feat(cli): front door offers capture install + plugin SessionStart setup nudge - #28

What

Two front-door reliability improvements to the published backthread CLI + its Claude Code plugin. Both reduce the "installed but capture never actually wired" failure mode.

Part 1 — CLI front door detects the agent and offers to wire capture inline

In runStart step (4a), the bare-terminal door used to just print capture guidance. Now it does detect → offer → install:

• Inside Claude Code (CLAUDECODE=1): unchanged — still recommends the plugin. The CLI can't install a CC plugin itself, and must never hand-write the fragile npx settings.json hook (the ARP-680 worktree-freeze path), so it never auto-installs here.
• Bare terminal: detect the user's installed agent by user-global config-dir presence (~/.codex / ~/.cursor / ~/.gemini, new pure detectAgents.ts). When exactly one is found and the session is interactive, prompt Detected <Agent> — wire capture for it now? [Y/n] (empty = Yes). On yes, run the same per-agent writer as backthread install --agent <x> (auth already happened earlier in the wizard, so no re-auth and no backfill — matches the existing per-agent install leg). On no, fall back to the printed capture command.
• Ambiguous or non-interactive (zero detected, multiple detected, or no TTY): fall back to the printed guidance. It never guesses between agents and never hangs on stdin without a terminal.
• New prompt.ts (promptYesNo) carries the load-bearing TTY guard (no interactive terminal → resolve the default without reading stdin). New StartDeps seams (detectAgentsImpl / promptYesNoImpl / installAgentImpl / home) keep it unit-testable with no real fs/stdin.

Part 2 — plugin SessionStart "finish setup" nudge

New internal setup-check subcommand (not listed in USAGE, like capture --from-hook) + new setupCheck.ts. When the plugin is installed but setup is incomplete (not onboarded OR no device token), it prints a SessionStart additionalContext line so Claude can relay "run /backthread:start to finish setup". Once set up, it prints nothing (silent forever). Registered as a SessionStart hook (matcher startup) in hooks.json.

Why additionalContext + exit 0, not exit 2: a setup nudge must be non-blocking — exit 2 would block/disrupt session startup. Matcher startup (not resume) so it doesn't nag on every resume. Two cheap file reads, never throws (any error → silence).

Notes / deviations

• Version bumped 0.4.0 → 0.4.1, not 0.3.2. main had already advanced to 0.4.0 (with installAgent.ts changes from ARP-689/692) since this task was written, so I branched off origin/main and patch-bumped from there to avoid a regressive/conflicting PR. Lockstep applied across all 4 manifests (cli/package.json, cli/.claude-plugin/plugin.json, extensions/gemini/gemini-extension.json, extensions/codex/plugins/backthread/plugin.json) so the plugin/gemini/codex lockstep tests stay green.
• Committed the regenerated cli/dist-bundle/backthread.js (CI sync-checks it).
• The root package-lock.json had a pre-existing unrelated dirty diff; left it out of this commit.

Tests

npm run typecheck and npm test both pass — 439 tests, 0 fail. New focused tests for detectAgents, prompt (incl. the TTY guard), setupCheck, the firstRun offer path (single+yes / single+no / zero / multiple / inside-CC / version-warning / writer-throw), the plugin SessionStart hook structure, and the setup-check bin dispatch.

Release

This needs review before a release is cut — no npm publish and no v* tag were created.

🤖 Generated with Claude Code