feat: deployment hardening for notification bridge

[ShunmeiCho]

Context

E2E testing on venus (2026-04-02) exposed several deployment friction points. The notification bridge works end-to-end but requires manual steps that should be automated.

Issues Found During E2E

P0: Stale sshd RemoteForward port cleanup

• Old SSH sessions leave sshd child processes in CLOSE_WAIT holding port 18339
• New SSH connections' RemoteForward silently fails
• cc-clip connect should detect and offer to clean up stale processes on remote
• At minimum: fail-fast with actionable error message instead of silent failure

P1: cc-clip doctor diagnostic command

• One-command diagnosis of entire notification chain
• Check: daemon running, tunnel alive, shim installed, hook script version, nonce registered, Claude Code hooks configured, Codex notify configured
• Offer auto-fix for detected issues

P2: Daemon binary version consistency

• After rebuild, old daemon must be restarted manually
• cc-clip serve should detect version mismatch and warn/auto-restart
• Consider cc-clip service upgrade for launchd-managed daemon

P3: SSH LocalCommand for automatic port cleanup (docs only)

• Document optional SSH config with PermitLocalCommand + LocalCommand for users who prefer plain ssh over cc-clip connect
• Not a default recommendation, just a documented option

Relates to

• chore: notification bridge follow-up cleanups (I1-I5) #20 (code quality follow-ups)
• feat: clipboard preview notification + SSH notification bridge #17 (merged: notification bridge)

[ShunmeiCho]

Additional: --install-claude-hooks opt-in flag

From E2E testing discussion: add an explicit opt-in flag to cc-clip connect:

cc-clip connect <host> --install-claude-hooks

When set:

• Modify remote ~/.claude/settings.json to add cc-clip-hook to Stop + Notification
• Use cc-clip-managed guard blocks (same pattern as PATH/DISPLAY markers)
• Backup original file before modification
• Idempotent merge: don't overwrite existing hooks, only append
• Without this flag: continue to print config snippet only (current behavior)

Priority: P2 (after stale port cleanup and doctor command)

[ShunmeiCho]

Status Update (2026-04-03)

Progress check against codebase:

Item	Status	Evidence
P0: Stale sshd port cleanup	Partial — documented	Manual fix in docs/troubleshooting.md (lines 55-80). Auto-detection in connect not yet implemented.
P1: cc-clip doctor	Done	internal/doctor/{local,remote}.go — checks daemon, tunnel, shim, token, deploy state, PATH priority, image probe
P2: Daemon version mismatch	Open	serve command has no version check logic
P3: SSH LocalCommand docs	Open	No PermitLocalCommand documentation added yet

[ShunmeiCho]

Status refresh (2026-05-20)

Refreshed after the v0.7.2-v0.7.4 hardening releases.

Item	Status	Evidence
P0 stale sshd RemoteForward cleanup	Partial	Manual troubleshooting is documented in docs/troubleshooting.md; automatic connect detection / cleanup is still open.
P1 doctor diagnostic command	Done	cc-clip doctor --host ... exists and covers local/remote tunnel and deployment checks.
P2 daemon binary version consistency	Open	No automatic local daemon vs deployed wrapper/binary version mismatch detection yet.
P3 SSH LocalCommand docs	Open	No dedicated PermitLocalCommand / LocalCommand setup docs found.
--install-claude-hooks opt-in	Open / needs design	Current wrapper behavior deserves a separate design PR: either explicit opt-in, or clearer documentation of current auto-injection behavior and its boundaries.