@jeffober/thatch 0.1.28 → 0.1.30

package/docs/dev/features/prediction-engine.md

@@ -0,0 +1,253 @@
+# Prediction Engine (User Decision Model)
+
+A statistical model of the user's decision-making preferences. Captures "when
+X, the user tends to Y." The agent queries the model when facing judgment
+calls and updates it based on user feedback.
+
+## What it does
+
+- Four tools: `prediction_query`, `prediction_update`, `prediction_list`,
+  `prediction_delete`. All defined in `src/tool-defs.ts`.
+- Auto-fires at every user message: embeds the prompt, cosine-matches against
+  matchers, injects scored predictions as a synthetic nudge part.
+- Bayesian confidence model — a graded score that is reinforced or weakened
+  over time, not binary like memory.
+- Matcher-prediction edges: many-to-many with weights. The same matcher can
+  produce different predictions in different contexts.
+- Ambiguity surfacing: strong predictions are followed silently; ambiguous or
+  competing predictions are surfaced to the user.
+- No wall-clock decay: confidence moves only when tested (user feedback);
+  untested predictions stay at the prior.
+
+## How it works
+
+### Data model: matchers, predictions, edges, provenance
+
+Four tables in SQLite, mirroring the behavior engine's shape:
+
+- **Matchers** — context patterns (situation descriptions). Embedded,
+  cosine-matched at `chat.message`. Capture "when" — describes the situation.
+- **Predictions** — user preference statements with graded confidence.
+  Capture "what" — the user's tendency.
+- **Edges** — weighted matcher-to-prediction links. Many-to-many. The same
+  matcher can produce different predictions in different contexts (the weight
+  encodes context-dependency). The same prediction can be reached by multiple
+  matchers.
+- **Provenance** — audit trail of every signal applied to a prediction
+  (`confirm` / `disconfirm` / `soft` / `create`) with detail and timestamp.
+
+### Confidence model (Bayesian posterior)
+
+```text
+confidence = (confirm_count + K * P0) / (confirm_count + disconfirm_count + K)
+```
+
+- K = 5 (shrinkage parameter)
+- P0 = 0.5 (prior)
+- Soft signal weight: 0.25 — a soft disconfirm counts as one-quarter of a
+  full disconfirm.
+- `effective_confidence = confidence`. The shrinkage handles thin evidence: a
+  single confirm is plausible, not reliable.
+- No wall-clock decay. Confidence is relevance-gated: being tested
+  (encountered + user feedback) is what moves it. Untested predictions stay at
+  P0.
+
+### Scoring at query time
+
+```text
+score = cosine(user_text, matcher.embedding) × edge.weight × prediction.effective_confidence
+```
+
+Returns all predictions from matching matchers so the LLM can read conflicts.
+The LLM is the conflict detector. Prompt instruction: "if competing
+predictions offer conflicting guidance, surface to the user."
+
+### Query (`prediction_query` tool)
+
+- Embeds the context string.
+- Finds the top 5 matchers by cosine.
+- Filters to cosine >= 0.60 (`PREDICTION_QUERY_THRESHOLD`, matching the
+  auto-fire threshold).
+- Follows edges to predictions, scores them.
+- Returns one line per prediction: `[conf, N tests] When {matcher}: {verb}
+  {statement}`.
+- Verb reflects evidence count: "you may prefer" (0 evidence) vs "you tend to"
+  (has evidence).
+- Read-only. Embeds the context.
+
+### Update (`prediction_update` tool)
+
+Parameters: `matcher` (situation description), `prediction` (preference
+statement), `signal` (`confirm` / `disconfirm` / `soft` / `create`),
+`rationale` (why).
+
+Runs in a single DB transaction:
+
+1. **Matcher dedup** — finds an existing matcher above cosine 0.85, else
+   creates one.
+2. **Prediction dedup** — store-wide search for a near-identical prediction
+   (cosine >= 0.85). If found, links this matcher to it via an edge rather than
+   creating a duplicate row.
+3. **New prediction with a non-create signal** — applies the signal
+   immediately so the first confirm/disconfirm is not lost.
+4. **`create` on an existing prediction** — links the edge and records
+   provenance but does NOT adjust confidence. `create` is confidence-neutral.
+5. **`confirm` / `disconfirm` / `soft`** — maps to `adjustConfidence` and
+   records provenance.
+
+Returns a status line with final confidence and confirm/disconfirm counts.
+Embeds both the matcher and prediction text.
+
+### Auto-fire (opencode: `chat.message` hook)
+
+- Reuses the prompt embedding already computed for the recall nudge — no extra
+  model call.
+- Calls `db.scorePredictionNudge([repo, "global"], embedding,
+  PREDICTION_THRESHOLD)`.
+- Threshold: 0.60 (env: `THATCH_PREDICTION_THRESHOLD`). Higher than recall
+  (0.55) because surfacing a preference nudge is more disruptive.
+- Injects `predictionNudge(items)` as a separate synthetic text part with a
+  `[thatch] User decision model` header.
+- 0-evidence predictions use "you may prefer"; predictions with evidence use
+  "you tend to".
+- Independent try/catch — a prediction failure does not block recall or
+  behavior.
+- Toast: `[thatch] N predictions surfaced`.
+
+### Auto-fire (MCP: sideband)
+
+- `flush-tools` fires the prediction query via the sideband socket's
+  `predictions` method, in parallel with recall and behavior.
+- The same `scorePredictionNudge` entry point prevents scoring drift between
+  host paths.
+- Sideband failure returns `null`; the caller skips the prediction nudge
+  gracefully.
+
+### System prompt injection
+
+The auto-fire block looks like:
+
+```text
+## User decision model
+- [0.72 conf, 4 tests] When {matcher}: you tend to {prediction}
+- [0.61 conf, 2 tests] When {matcher2}: you may prefer {prediction2}
+```
+
+Prompt instructions: follow strong predictions silently, surface weak or
+competing predictions to the user, update the model when the user responds.
+
+### Ambiguity surfacing
+
+The killer feature. Three regimes:
+
+- **Strong prediction** (high confidence + evidence) — the agent follows
+  silently, does not interrupt.
+- **No prediction** — the agent asks the user (same as today).
+- **Ambiguous or competing predictions** — the agent surfaces naturally:
+  "I think you usually prefer X, but I'm not sure here — what do you want?"
+
+When the user responds to a surfaced prediction, the agent calls
+`prediction_update` to reinforce or weaken. The value is fewer interruptions,
+not more.
+
+### Firewall principle
+
+The model that uses predictions cannot grade its own predictions. The user's
+feedback is the signal. The query is mechanical (a statistical model). The
+formation and evaluation are agent-driven (via tools, guided by prompt
+instructions). This separation prevents the agent from reinforcing its own
+biases.
+
+### Relevance-gated decay
+
+Confidence does not decay by wall-clock time. It moves only when tested — when
+the user encounters a situation matching the matcher and provides feedback.
+Untested predictions stay at P0 (0.5). A prediction that was strongly confirmed
+a year ago but never tested since retains its confidence. The design assumes
+that user preferences are stable, not time-sensitive.
+
+## Interactions with other features
+
+- **Nudge pipeline** ([nudge-pipeline.md](nudge-pipeline.md)): prediction
+  auto-fire is tier 3. Shares the prompt embedding with recall (tier 2) and
+  behavior (tier 4).
+- **Behavior engine** ([behavior-engine.md](behavior-engine.md)): same
+  four-table data model, same Bayesian confidence, same scoring engine.
+  Different semantics — predictions model user preferences; behaviors model
+  LLM discipline.
+- **Scoring engine**: `src/scoring-engine.ts` provides the generic four-table
+  scoring base. `PredictionEngine` (`src/prediction.ts`) is a thin wrapper with
+  prediction-specific table names.
+- **Memory store** ([memory-store.md](memory-store.md)): same embedding model
+  (BGE-small-en-v1.5), same SQLite DB, different tables.
+- **Sideband IPC** ([sideband.md](sideband.md)): MCP hosts query predictions
+  via the sideband socket's `predictions` method.
+
+## Source files
+
+| File | Role |
+|------|------|
+| `src/prediction.ts` | Thin wrapper around `ScoringEngine` with prediction-specific table names |
+| `src/scoring-engine.ts` | Generic four-table scoring engine with Bayesian confidence (shared base for prediction and behavior) |
+| `src/db.ts` | Prediction tables, `scorePredictionNudge` |
+| `src/tool-defs.ts` | Four prediction tools (`query`, `update`, `list`, `delete`) |
+| `src/prompts.ts` | `predictionNudge` formatting, verb selection |
+| `src/sideband.ts` | `predictions` method for the MCP path |
+
+## Database tables
+
+```sql
+prediction_matchers(
+    id          TEXT PRIMARY KEY,
+    store       TEXT,
+    description TEXT,
+    embedding   BLOB,
+    model       TEXT,
+    created_at  TEXT,
+    updated_at  TEXT
+)
+
+predictions(
+    id               TEXT PRIMARY KEY,
+    store            TEXT,
+    statement        TEXT,
+    rationale        TEXT,
+    embedding        BLOB,
+    model            TEXT,
+    confidence       REAL,
+    confirm_count    REAL,
+    disconfirm_count REAL,
+    created_at       TEXT,
+    updated_at       TEXT
+)
+
+prediction_edges(
+    matcher_id   INTEGER,
+    prediction_id INTEGER,
+    weight       REAL,
+    PRIMARY KEY (matcher_id, prediction_id),
+    FOREIGN KEY (matcher_id)    REFERENCES prediction_matchers(id) ON DELETE CASCADE,
+    FOREIGN KEY (prediction_id) REFERENCES predictions(id)         ON DELETE CASCADE
+)
+
+prediction_provenance(
+    id           TEXT PRIMARY KEY,
+    prediction_id INTEGER,
+    signal       TEXT,
+    detail       TEXT,
+    created_at   TEXT,
+    FOREIGN KEY (prediction_id) REFERENCES predictions(id) ON DELETE CASCADE
+)
+```
+
+## Key invariants
+
+1. **The firewall principle.** The model that uses predictions cannot grade
+   them. User feedback is the only signal.
+2. **No wall-clock decay.** Confidence is relevance-gated — being tested moves
+   it, not the passage of time.
+3. **Dedup at creation.** Cosine >= 0.85 for both matchers and predictions.
+4. **Same `scorePredictionNudge` entry point** in both host paths (opencode
+   `chat.message` hook and MCP sideband) prevents scoring drift.
+5. **Matcher text is embedded raw.** No header prepend — unlike
+   `memory_remember`, which prepends `# label\n\n` before embedding.

package/docs/dev/features/qa-system.md

@@ -0,0 +1,205 @@
+# QA System
+
+Thatch ships 93 QA use cases that verify end-to-end behavior. Each use case is
+a `bun:test` file that runs in an isolated environment — a temp-directory copy
+of the repo, not the working tree itself. Use cases are split into
+**automatable** (no LLM, fast) and **live** (spawns opencode, costs model
+tokens).
+
+## What it does
+
+- 93 use cases: 73 automatable + 20 live
+- Automatable use cases run without an LLM — they test CLI behavior, hooks, DB
+  operations, and tool execution directly via bun assertions
+- Live use cases spawn real opencode sessions — they test the full
+  nudge/extraction/skill pipeline with a real model
+- `mise` tasks for running subsets: `qa` (all), `qa-auto` (fast), `qa-live`
+  (model), `qa-dry-run` (list only)
+- Each use case follows a structured format: preconditions, steps, expected
+  results
+
+## How it works
+
+### Use case structure
+
+Each use case file (`tests/qa/auto/uc-NNN-name.ts` or
+`tests/qa/live/uc-NNN-name.ts`) imports `registerUseCase` and `UseCase` from
+`../runner`, defines the scenario with `preconditions`, `steps`, and `expected`
+as string arrays joined by newlines, then calls `registerUseCase(useCase)`.
+
+Most use cases use the default `runViaOpencode` (no custom `run`). Automatable
+use cases override `run` with direct CLI/bun assertions. Manual-only use cases
+set `manualOnly: true`.
+
+Individual use case files are `.ts` (not `.test.ts`) so bun does not discover
+them as standalone test files. Each directory has an `index.test.ts` **barrel
+file** that imports all use case modules. Bun's `--concurrent` flag
+parallelizes tests within a single file, not across files. The barrel pattern
+registers all use cases in one suite, enabling `--concurrent
+--max-concurrency 5` to run 5 use cases at once (33s vs 88s sequential for the
+auto suite).
+
+### Automatable use cases (73)
+
+Run without an LLM. Test CLI behavior, hooks, DB operations, and tool
+execution directly via bun assertions. These are fast and run in parallel.
+
+| UC | Name | What it tests |
+|----|------|---------------|
+| UC-004 | cli-inspection | `stores`, `list`, `show`, `forget`, `search` subcommands |
+| UC-005 | setup-install | setup installs correct files for Claude Code and Cursor |
+| UC-008 | hygiene-heartbeat | hygiene report at session start (duplicates, stale, orphaned) |
+| UC-009 | flush-tools-tiers | three priority tiers: extraction, recall, write nudge |
+| UC-011 | write-time-similarity-warning | `memory_remember` warns about near-duplicates |
+| UC-012 | model-migration | switching `THATCH_MODEL` makes old entries invisible |
+| UC-014 | skill-install-drift | `installSkills` overwrites drifted content |
+| UC-015 | env-override-matrix | `THATCH_RECALL_THRESHOLD`, `THATCH_PREDICTION_THRESHOLD`, `THATCH_BEHAVIOR_THRESHOLD` |
+| UC-016 | concurrent-session-isolation | sessions don't interfere with each other |
+| UC-017 | buffer-tool-vs-buffer-batch | Cursor per-tool vs Claude Code batch queueing |
+| UC-018 | mcp-startup-setup-detection | `checkSetup` at MCP server startup |
+| UC-021 | prediction-autofire | prediction nudge fires at `chat.message` |
+| UC-022 | prediction-dedup | cosine >= 0.85 dedup for matchers and predictions |
+| UC-023 | prediction-confidence-model | Bayesian posterior with confirm/disconfirm/soft |
+| UC-024 | prediction-delete | semantic-match deletion with cascade |
+| UC-025 | behavior-autofire | behavior nudge fires at `chat.message` |
+| UC-026 | behavior-dedup | cosine >= 0.85 dedup for matchers and behaviors |
+| UC-027 | behavior-confidence-model | ham/spam adjusts Bayesian confidence |
+| UC-028 | behavior-delete | semantic-match deletion with cascade |
+
+### Live use cases (20)
+
+Spawn real opencode sessions. Test the full pipeline with a real model. These
+cost model tokens and have a 20-minute per-use-case timeout. All 20 are marked
+`manualOnly: true` — the opencode binary is not available in CI, and three
+(UC-006, UC-010, UC-013) are manual-only for fundamental reasons (Cursor hook
+lifecycle, nested opencode session timeout, compaction trigger). Run them
+locally with `mise run qa-live`.
+
+| UC | Name | What it tests |
+|----|------|---------------|
+| UC-001 | memory-roundtrip | remember -> recall -> show -> forget |
+| UC-002 | dedup-cycle | `find_duplicates` -> classify -> merge -> `mark_checked` |
+| UC-003 | extraction-nudge | tool use -> buffer -> nudge -> `extraction_done` |
+| UC-006 | cursor-hook-lifecycle | Cursor hooks: `sessionStart`, `postToolUse`, `beforeSubmitPrompt` |
+| UC-007 | recall-nudge | prompt-aware recall at `chat.message` |
+| UC-010 | prime | `thatch prime` runs the project-primer skill |
+| UC-013 | compaction-context | compaction hook injects context |
+| UC-019 | archived-memory-lifecycle | archive -> search excludes -> unarchive -> search includes |
+| UC-020 | extraction-escalation | polite -> insistent -> ALL-CAPS over missed nudges |
+
+### mise tasks
+
+| Task | Command | Purpose |
+|------|---------|---------|
+| `qa` | `bun test tests/qa/auto/index.test.ts --concurrent --max-concurrency 5 && bun test tests/qa/live/index.test.ts` | Run all QA (auto first, then live) |
+| `qa-dry-run` | `QA_DRY_RUN=1 bun test tests/qa/auto/index.test.ts tests/qa/live/index.test.ts --concurrent --max-concurrency 5` | List use cases without spawning sessions |
+| `qa-auto` | `bin/qa-run auto` | Run automatable only (fast, no LLM). Pass UC names as args to select a subset. |
+| `qa-live` | `bin/qa-run live` | Run live only (spawns opencode, costs tokens). Pass UC names as args to select a subset. |
+
+The `qa` task runs auto first via `&&`. Auto failures stop before live runs.
+The `qa-live` task does not use `--concurrent` — live sessions are
+resource-heavy and benefit from sequential execution.
+
+### Runner architecture
+
+`tests/qa/runner.ts` provides the `registerUseCase` function and the `UseCase`
+type. The runner index files (`tests/qa/auto/index.test.ts` and
+`tests/qa/live/index.test.ts`) import all use case files in their directory,
+which self-register via `registerUseCase`. The runner then executes each use
+case.
+
+The `QA_DRY_RUN=1` environment variable causes the runner to print use case
+names and descriptions without executing them. This is useful for CI and for
+reviewing coverage without spawning sessions.
+
+### Isolation model
+
+The runner creates a **master copy** of the repo at `/tmp/thatch-qa/master/`
+via `git archive HEAD` (tracked files only — no `.git`, no `node_modules`, no
+untracked artifacts). `node_modules` is symlinked from the real repo to share
+deps including the HF embedding model cache. opencode's own npm deps
+(`~/.config/opencode/node_modules/`) are copied into the master so each use
+case has them without a warm-up session.
+
+Each use case gets a per-use-case copy of the master via `createFixture(name)`,
+with isolated `HOME`, `XDG_CONFIG_HOME`, `THATCH_DB_PATH`, and
+`THATCH_QUEUE_DIR` environment variables. The repo is read-only during QA —
+sessions run inside `/tmp/thatch-qa/<uc-name>/` copies.
+
+The `thatch-qa` skill (`.opencode/skills/thatch-qa/SKILL.md`) instructs the
+LLM on how to execute a single use case in the isolated directory. The skill's
+safety contract is intentionally fixed text — do not paraphrase it.
+
+### Execution modes
+
+1. **Live session** (default): no custom `run` function → `runViaOpencode`
+   spawns `opencode run --dir <ctx.dir> --model <MODEL> --auto` with the use
+   case content as prompt. Requires `VENICE_API_KEY`. Default model:
+   `venice/zai-org-glm-5-2` (override with `QA_MODEL` env var). Uses
+   `Bun.spawn()` (not `Bun.$`) so the process can be killed on timeout (590s
+   SIGTERM, SIGKILL in finally). The 20-minute per-test timeout is the
+   wall-clock budget for a complete LLM-driven agent session — do not reduce
+   it.
+2. **Automatable**: custom `run(ctx)` function with direct CLI/bun assertions.
+   No opencode session, no API key.
+3. **Manual-only**: `manualOnly: true` → test is skipped, prints `[MANUAL]`.
+
+### Relationship to the quality gate
+
+`mise run check` uses a flat glob (`tests/*.test.ts`) that excludes
+`tests/qa/`. QA tests spawn opencode sessions and cannot run in the normal
+quality gate. The QA files are typechecked by `tsconfig.check.json` (which
+includes all of `tests/`), just not executed during `check`. See
+[cicd.md](cicd.md) for the full CI pipeline.
+
+## Interactions with other features
+
+- **All features**: QA use cases verify end-to-end behavior of every feature
+- [cicd.md](cicd.md): `mise run check` uses a flat glob (`tests/*.test.ts`)
+  that excludes `tests/qa/`; CI runs `bun test` which includes the QA barrels;
+  `mise run qa` runs the full QA suite separately
+- [setup.md](setup.md): UC-005 and UC-018 test setup installation and detection
+- [nudge-pipeline.md](nudge-pipeline.md): UC-007, UC-009, UC-021, UC-025 test
+  nudge tiers
+- [extraction.md](extraction.md): UC-003, UC-020 test extraction nudge and
+  escalation
+- [hygiene.md](hygiene.md): UC-008 tests the hygiene heartbeat
+- [memory-store.md](memory-store.md): UC-001, UC-004, UC-011, UC-012, UC-019
+  test memory CRUD, search, warnings, migration, archival
+- [deduplication.md](deduplication.md): UC-002 tests the dedup cycle
+- [prediction-engine.md](prediction-engine.md): UC-021 through UC-024 test
+  auto-fire, dedup, confidence, delete
+- [behavior-engine.md](behavior-engine.md): UC-025 through UC-028 test
+  auto-fire, dedup, confidence, delete
+- [../skills.md](../skills.md): UC-014 tests skill drift detection
+- [multi-host.md](multi-host.md): UC-006, UC-017 test Cursor hooks and
+  buffer-tool vs buffer-batch
+
+## Source files
+
+| File | Role |
+|------|------|
+| `tests/qa/runner.ts` | `registerUseCase`, `UseCase` type, `ensureMaster`, `createFixture`, `runViaOpencode`, execution logic |
+| `tests/qa/auto/index.test.ts` | Automatable use case barrel — imports all auto use case modules |
+| `tests/qa/live/index.test.ts` | Live use case barrel — imports all live use case modules |
+| `tests/qa/auto/uc-NNN-*.ts` | 73 automatable use case files |
+| `tests/qa/live/uc-NNN-*.ts` | 20 live use case files |
+
+No separate QA docs directory exists. QA use cases live in `tests/qa/` as executable tests, not docs.
+
+## Key invariants
+
+1. **Automatable use cases never spawn an LLM.** They test CLI, hooks, DB, and
+   tool execution directly.
+2. **Live use cases spawn real opencode sessions and cost model tokens.** All
+   20 are marked `manualOnly` — the opencode binary is not available in CI.
+3. **`QA_DRY_RUN=1` lists use cases without executing.** Use this for CI and
+   coverage review.
+4. **Each use case follows the structured format**: preconditions, steps,
+   expected.
+5. **Use cases self-register via `registerUseCase`** — no central registry to
+   maintain. Add a new `.ts` file and import it from the barrel.
+6. **The repo is read-only during QA.** Sessions run inside
+   `/tmp/thatch-qa/<uc-name>/` copies created from `git archive HEAD`.
+7. **The 20-minute test timeout is the agent-session budget, not test
+   execution time.** Reducing it will cause live use cases to time out.

package/docs/dev/features/session-lifecycle.md

@@ -0,0 +1,110 @@
+# Session Lifecycle Management (opencode)
+
+opencode emits bus events for session lifecycle changes. Thatch subscribes to these events to manage the extraction pipeline, send session-start reminders, and handle child session cleanup.
+
+## What it does
+
+- Session-start reminder + hygiene heartbeat for top-level sessions
+- Child session tracking (`childToParent` map, `parentSnapshots`)
+- Direct extraction: trigger child session when parent goes idle with pending buffer
+- Extraction child lifecycle: created on parent idle, drains parent's snapshot on completion, deleted after
+- Sub-agent lifecycle: task-dispatched sub-agents complete accepted entries but are not deleted
+- Session error recovery: child errors requeue parent's accepted entries
+- Session deletion recovery: child deletion requeues; parent deletion completes accepted entries
+
+## How it works
+
+### Event handler (`src/index.ts`, event hook)
+
+Subscribes to all session bus events. Dispatches based on `event.type`.
+
+### session.created with parentID (child session)
+
+1. Record `childToParent.set(childID, parentID)`
+2. Snapshot the parent's current pending buffer: `parentSnapshots.set(childID, [...extraction.peek(parentID)])`
+3. Return early -- child sessions don't get the session-start reminder
+
+This snapshot is used by `consumeSnapshot` for snapshot-aware drain: when the child writes memories, only the snapshot entries are removed from the parent's buffer, preserving interleaved-turn entries that were added after the snapshot was taken.
+
+### session.created without parentID (top-level session)
+
+- Send session-start reminder via `client.session.prompt` with `noReply: true` and `synthetic: true`
+- The reminder includes the hygiene heartbeat (pending dedup pairs, stale count, orphaned branch memories) when any signal is non-zero
+- See [hygiene.md](hygiene.md)
+
+### session.status idle -- extraction child
+
+When a child created by `triggerExtraction` goes idle:
+
+1. Drain the parent's snapshot from pending buffer via `consumeSnapshot` (if still present -- a no-save run's entries need draining so they don't replay; a save run already drained them via `tool.execute.after`)
+2. Never drains the entire buffer -- interleaved-turn entries survive
+3. Fire a toast with extraction metrics (new/updated/deleted counts) -- only if memories were actually written
+4. `completeAccepted(parentID)`, reset `missedNudges`
+5. Clean up all maps: `extracting`, `childToParent`, `parentSnapshots`, `childMetrics`, `extractionChildren`
+6. `consume(childID)` -- drain child's own buffer
+7. Delete the child session via `client.session.delete`
+
+### session.status idle -- task-dispatched sub-agent
+
+When a task-dispatched sub-agent (not created by `triggerExtraction`) goes idle:
+
+- `completeAccepted(parentID)` -- complete the parent's accepted entries (from the nudge-path `extraction_done` accept)
+- Reset `missedNudges`
+- Does NOT drain the buffer or delete the session -- the task tool that dispatched the sub-agent needs to read its output
+
+### session.status idle -- parent session
+
+When a parent session (no parentID) goes idle:
+
+- If not compacting, not already extracting, and buffer has pending interactions: `triggerExtraction(sessionID)`
+- On failure: log error, clear `extracting` flag (nudge path takes over as fallback on next chat.message)
+
+### session.error (child session)
+
+- `requeueAccepted(parentID)` -- move parent's accepted entries back to pending (the extractor never processed them)
+- Clean up all maps for the child
+
+### session.deleted -- child
+
+- `requeueAccepted(parentID)` -- entries go back to pending (never processed)
+- Clean up all maps for the child
+
+### session.deleted -- parent
+
+- `completeAccepted(id)` -- a deleted parent takes its accepted entries with it
+- Clear `extracting` for the parent
+
+### session.compacted
+
+- Clear the `compacting` flag so chat.message nudges resume
+- See [compaction-recovery.md](compaction-recovery.md)
+
+### Internal state maps
+
+- **childToParent**: `Map<childID, parentID>` -- maps child sessions to their parents
+- **parentSnapshots**: `Map<childID, Interaction[]>` -- snapshot of parent's buffer at child creation time
+- **childMetrics**: `Map<childID, {new, updated, deleted}>` -- extraction metrics per child
+- **extracting**: `Set<parentID>` -- parent IDs with an active direct-extraction child (suppresses nudge)
+- **extractionChildren**: `Set<childID>` -- distinguishes extraction children from task-dispatched sub-agents
+- **compacting**: `Set<sessionID>` -- sessions currently being compacted (suppresses nudges)
+- **missedNudges**: `Map<sessionID, number>` -- extraction nudge escalation counter
+
+## Interactions with other features
+
+- Extraction pipeline ([extraction.md](extraction.md)): direct extraction is triggered by `session.status idle`; child lifecycle managed here
+- Nudge pipeline ([nudge-pipeline.md](nudge-pipeline.md)): `extracting` set suppresses tier 1; `compacting` set suppresses all tiers
+- Hygiene ([hygiene.md](hygiene.md)): hygiene report runs at `session.created` for top-level sessions
+- Compaction recovery ([compaction-recovery.md](compaction-recovery.md)): `session.compacted` event clears the compacting flag
+- Memory store ([memory-store.md](memory-store.md)): child sessions write memories via `memory_remember`, which triggers drain via `tool.execute.after`
+
+## Source files
+
+- `src/index.ts` -- event handler (all session events), `triggerExtraction`, `cleanupChild`, internal state maps
+
+## Key invariants
+
+- Child sessions don't get the session-start reminder (early return in `session.created` with parentID).
+- `consumeSnapshot` is snapshot-aware: removes only entries captured at dispatch time, preserving interleaved-turn entries.
+- Extraction children are deleted after going idle; task-dispatched sub-agents are NOT deleted (task tool reads output).
+- Child errors requeue the parent's accepted entries (never processed). Child deletion also requeues.
+- Parent deletion completes accepted entries (takes them with it).