feat(sensor): Zuhn-native session-capture hook (Option A)

[gorajing]

Summary

A Claude Code SessionEnd hook that captures the session transcript as a Zuhn session source. Mechanical only — no LLM in the hook. Insight extraction stays the deliberate, gated npm run autoknowledge step, so Phase 8's "no auto-extraction" still holds — only capture is automated.

Why this path: claude-mem (the alternative) digests via a paid LLM API (no key set + interactive install). Zuhn's own autoknowledge already uses the authenticated claude CLI — so this is zero new credentials, zero extra cost, no background daemon.

What it does

Claude Code SessionEnd
  └─ .claude/hooks/session-capture.sh   (bash, exit 0 always, errors → ~/.claude/session-capture.log)
        └─ scripts/capture-session.ts   (reads hook JSON from stdin; never throws)
              └─ lib/transcript.ts      (parse JSONL → drop noise → user/assistant turns → digest)
                    └─ writes one "session" source to sources/session/<slug>.md
                          │
                          │  later (manual / scheduled):
                          ▼
       ZUHN_GATE_BLOCKING_CHECKS=stance_present,stance_directional npm run autoknowledge
                          │
                          ▼
                       claude-CLI extraction → the gate → KB

Safety design

• Hook never breaks the session. try/catch around every I/O in capture-session.ts; bash wrapper always exit 0; process.stdin.isTTY guard prevents blocking on manual runs.
• Errors are LOGGED, not silenced. ~/.claude/session-capture.log (was a real bug-shaped design when I had 2>/dev/null; fixed).
• Idempotent. Slug/id salted by session_id and date-independent → same session always maps to the same file; existsSync short-circuits re-captures.
• Aggressive noise-stripping. Drops isSidechain (subagent), tool_use/tool_result, assistant thinking, attachment/system/custom-title lines, and framework-injection user turns (<system-reminder>/<command-*>).

Records a deliberate design supersession

docs/session-pipeline-setup.md updated: Phase 8's "explicit intent only / no passive scraping" existed because there was no automatic quality control. The gate now provides it, so passive transcript capture is safe. Capture is automated; extraction (and quality enforcement) stay gated.

Test plan

• 8 parser tests (noise-stripping edge cases, cap/tail, idempotency, null on empty)
• Full suite green (578 passed / 3 skipped) at commit time
• Typecheck clean
• Verified on the real 38 MB session transcript (→ 8,831-word clean digest, correct title)
• Verified on bogus input (graceful no-op, no stray write)
• Verified end-to-end via the logged hook chain with a synthetic transcript + temp KB (log shows fire + success; source written; exit 0)
• CI

Note on review

Local codex exec review stalled twice (the harness backgrounds long commands; codex exec hangs on stdin/tty in that mode). Killed both. Relying on the GitHub codex App for PR review, plus the test coverage above.

🤖 Generated with Claude Code