feat(service): harden defaults — env, crash-loop guard, persistent logs

[JD2005L]

What

Three orthogonal install-hardening items that each stand on their own:

1. Inject HOME and TERM explicitly into both systemd unit and launchd plist.
2. Crash-loop guard on systemd via StartLimitIntervalSec=300 + StartLimitBurst=5.
3. Persistent default log path — /tmp/clawcode-<slug>.log → ~/.clawcode/logs/<slug>.log, with install plan creating the dir.

Why

1. Explicit HOME + TERM

systemd user services and launchd both start with a largely empty environment. Anything in Claude Code or a plugin that reads \$HOME (resolving ~), or probes \$TERM (color output, TUI detection, several Node libraries), behaves unpredictably when those are unset. Some combinations fail loudly; more often they fail subtly — e.g. a skill that works interactively and then no-ops under the service with no clear error. Setting them at the unit/plist level is cheap and universally safe.

2. Crash-loop guard

With Restart=always and RestartSec=10, a deterministic boot-time error (bad config, missing binary, malformed extraArgs) churns forever at 10 s intervals, flooding logs and journald. StartLimitIntervalSec=300 + StartLimitBurst=5 tells systemd to give up after 5 restarts in 5 minutes so the failure surfaces in systemctl status instead of hiding in noise. No change on healthy services.

macOS launchd already has its own throttling (ThrottleInterval, ExitTimeOut), so no plist change is needed for this item.

3. Persistent log path

/tmp is wiped on reboot, so a service that auto-restarts through a reboot loses the log that explains why it was failing in the first place. Moving to ~/.clawcode/logs/ keeps logs available for post-mortem and matches where the rest of the agent's per-user state sits.

systemd's append: and launchd's StandardOutPath do NOT create missing parent dirs and the service will silently refuse to start without them, so the install plan now includes a "Create log directory" command up front.

Changes

lib/service-generator.ts

• defaultLogPath now returns ~/.clawcode/logs/<slug>.log (was /tmp/clawcode-<slug>.log).
• generateSystemdUnit emits Environment=HOME=..., Environment=TERM=xterm-256color, StartLimitIntervalSec=300, StartLimitBurst=5.
• generatePlist emits EnvironmentVariables with HOME and TERM.
• buildPlan install action prepends a "Create log directory" command.

docs/service.md

• Example systemd unit and plist updated.
• Logs section reflects new default + explains why the log dir is created at install.
• Restart-loop troubleshooting row points at the new log location and mentions StartLimitBurst so users know to check systemctl status when systemd has given up.

Verification

bun -e on the generator directly:

--- unit ---
[Unit]
Description=ClawCode Agent (claude)
After=network.target

[Service]
Type=simple
WorkingDirectory=/home/claude
Environment=HOME=/home/claude
Environment=TERM=xterm-256color
ExecStartPre=-/usr/bin/pkill -f \"claude.*--dangerously-skip-permissions\"
ExecStart=/usr/local/bin/claude --dangerously-skip-permissions
Restart=always
RestartSec=10
# Crash-loop guard: stop restarting after 5 failures within 5 minutes
# so a deterministic boot-time error doesn't churn forever.
StartLimitIntervalSec=300
StartLimitBurst=5
StandardOutput=append:/home/claude/.clawcode/logs/claude.log
StandardError=append:/home/claude/.clawcode/logs/claude.log

--- commands ---
  Create log directory: mkdir -p \"/home/claude/.clawcode/logs\"
  Create systemd user directory: mkdir -p \"/home/claude/.config/systemd/user\"
  Reload systemd: systemctl --user daemon-reload
  Enable + start the service: systemctl --user enable --now clawcode-claude.service

Plist output similarly verified — EnvironmentVariables dict with HOME and TERM, persistent StandardOutPath.

Not changed (explicitly)

• ExecStartPre=-/usr/bin/pkill ... from v1.3.0 left alone — it's the right answer for the multi-instance race.
• Restart=always and RestartSec=10 kept. These are opinionated and the current defaults are reasonable; crash-loop guard is the right fix for their only real downside.
• No script(1)-wrap of ExecStart. I run this locally and it's arguably helpful for some skills that expect a PTY, but the value is niche enough that it doesn't belong in a default.

Relationship to other PRs

• Independent of fix: resolve WORKSPACE to user project dir, not plugin dir (#5) #6 (fix: resolve WORKSPACE ...) — no overlap.
• Independent of feat(service): emit resume-on-restart wrapper alongside service unit #7 (feat(service): resume-on-restart wrapper) — no file overlap; both PRs can land in either order. If they both land, the wrapper PR's extraFiles writing happens in the same install flow as this PR's Create log directory command.