threadkeeper 0.19.0__tar.gz → 0.20.0__tar.gz

{threadkeeper-0.19.0/threadkeeper.egg-info → threadkeeper-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: threadkeeper
-Version: 0.19.0
+Version: 0.20.0
 Summary: Multi-agent shared brain across Claude Code/Desktop, Codex, Antigravity CLI, Copilot, and VS Code. Cross-session memory, self-improving skill loops, inter-agent signaling — one local MCP server.
 Author: thread-keeper contributors
 License: MIT
@@ -22,7 +22,7 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: mcp<3,>=2.2.0
+Requires-Dist: mcp<3,>=2.3.0
 Requires-Dist: pydantic>=2.13.4
 Requires-Dist: pydantic-settings>=2.14.2
 Requires-Dist: pyyaml>=6.0.3
@@ -35,6 +35,9 @@ Provides-Extra: semantic-st
 Requires-Dist: sentence-transformers>=2.2.0; extra == "semantic-st"
 Requires-Dist: numpy>=1.24.0; extra == "semantic-st"
 Requires-Dist: sqlite-vec>=0.1.9; extra == "semantic-st"
+Provides-Extra: encrypted
+Requires-Dist: keyring>=25.0; extra == "encrypted"
+Requires-Dist: sqlcipher3-wheels>=0.5.7; extra == "encrypted"
 Provides-Extra: dev
 Requires-Dist: pytest>=9.1.1; extra == "dev"
 Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
@@ -150,6 +153,12 @@ managed instructions block and call `brief()` / `context()` before answering, or
 `memory://brief` resource the host attaches automatically (see
 [MCP primitives](#mcp-primitives-tools-resources-prompts)).
 
+The MCP initialization response also carries concise, static lifecycle guidance:
+load the brief/context, open/note/close substantive threads, prefer read-only
+resources for host-attached context, and use dry-run plus confirmation before
+destructive maintenance. Hooks and the managed files remain reinforcement for
+clients that do not surface server instructions.
+
 ### Alternative installs
 
 If you don't have `pipx` and don't want to install it:
@@ -219,12 +228,12 @@ the `CLIAdapter` contract. See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ### Python MCP SDK surface
 
-thread-keeper requires MCP Python SDK 2.2 or later (`mcp>=2.2.0,<3`). Its
-stable Skills extension uses the MCP 2026-07-28 extension surface, while tools,
+thread-keeper requires MCP Python SDK 2.3 or later (`mcp>=2.3.0,<3`). Its
+stable Skills and durable Tasks extensions use the MCP 2026-07-28 extension surface, while tools,
 resources, prompts, annotations, structured content, elicitation, and stdio
 continue to use the same `MCPServer` instance.
 
-### MCP primitives (tools, resources, prompts, elicitation)
+### MCP primitives (tools, resources, prompts, Apps, elicitation)
 
 MCP has three server primitives. thread-keeper uses all three, mapped to the
 read/act split, plus MCP elicitation for host-native confirmations:
@@ -232,8 +241,9 @@ read/act split, plus MCP elicitation for host-native confirmations:
 | Primitive | Control | What thread-keeper exposes | When to use |
 |---|---|---|---|
 | **Tools** | model-controlled (may act) | the full surface — `brief`, `note`, `spawn`, `search`, `curator_review`, `wikilink_health`, … | the agent decides to call them |
-| **Resources** | application-controlled, read-only | `memory://brief`, `memory://context`, `memory://dashboard`, `memory://agent-status` | the **host** attaches/pulls them automatically |
+| **Resources** | application-controlled, read-only | `memory://brief`, `memory://context`, `memory://dashboard`, `memory://agent-status` | the **host** attaches/pulls them automatically; capable hosts may subscribe |
 | **Prompts** | user-controlled templates | `review_recent_threads`, `run_library_curation`, `audit_threadkeeper` | the user runs them (Claude Code: `/mcp__thread-keeper__<name>`) |
+| **MCP App** | host-rendered, display-only | `open_dashboard` → `ui://thread-keeper/dashboard` | a host that advertises MCP Apps opens the sandboxed dashboard |
 
 **Resources** back the genuinely read-only memory views with the same render
 functions as the matching tools, so the content is identical — `memory://brief`
@@ -247,6 +257,24 @@ so an automatic host pull is **side-effect-free**.
 **Prompts** turn the curation / audit / review flows into discoverable,
 parameterized commands; each just drives the existing tools.
 
+**Portable dashboard App.** `open_dashboard` is a read-only progressive
+enhancement over the existing status data. In an MCP Apps-capable host it opens
+`ui://thread-keeper/dashboard` in a sandboxed iframe and shows autonomous
+loops, running children, budget state, task history, recent failures, and
+recent materializations. It never sends prompts, transcripts, task-log text,
+credentials, child identifiers, or local paths to the iframe. Loading and the
+App's Refresh button only open the existing database in SQLite read-only mode;
+they never bootstrap a session, reconcile tasks, start daemons, refresh process
+RSS, or write telemetry.
+
+This is portable across macOS, Windows, and Linux because it uses the existing
+stdio server registration in the table above — no native app installation is
+needed. If the host does not advertise the `io.modelcontextprotocol/ui`
+extension with `text/html;profile=mcp-app`, `open_dashboard` returns a short
+text fallback; use `agent_status(json_output=True)` or `mp_dashboard()` as the
+tested fallback. The macOS menu-bar app remains an optional native frontend
+over the same status data, not a requirement for this dashboard.
+
 **Elicitation** is a client feature, not a server primitive. When a host
 advertises form-mode elicitation, high-stakes mutations can pause for a
 structured user choice instead of relying on an ignorable text nudge. The first
@@ -256,7 +284,8 @@ the previous immediate tool behavior.
 
 Everything here is **additive and capability-gated**: a host that advertises the
 `resources` / `prompts` capabilities sees those primitives; one that advertises
-`elicitation.form` gets structured confirmations for covered high-stakes writes.
+MCP Apps gets the dashboard iframe; and one that advertises `elicitation.form`
+gets structured confirmations for covered high-stakes writes.
 Hosts without a capability fall back to the SessionStart hook plus the `brief()`
 / `context()` tools and the existing write behavior — same content, no
 regression. Static URIs only for now (resource *templates* with `{param}` are
@@ -285,6 +314,23 @@ activate it, approve its tools, record use telemetry, or approve supporting
 files. Activation and any user approval remain responsibilities of the host's
 skill-loading path.
 
+### MCP Tasks for headless spawn
+
+Clients using MCP 2026-07-28 that advertise the
+`io.modelcontextprotocol/tasks` extension can call `spawn(..., visible=False)`
+as a durable asynchronous operation. The response is an opaque public task
+handle; poll it with `tasks/get` and request cooperative cancellation with
+`tasks/cancel`. Handles are bound to the authenticated caller (or the local OS
+user for stdio), survive a host reconnect, and never expose the short internal
+spawn ID. The server suggests a five-second polling interval.
+
+Only headless `spawn` is task-eligible: visible Terminal.app work has no stable
+process-group handle. `tournament`, `tasks`, `task_logs`, and the legacy custom
+spawn lifecycle stay unchanged. Clients that do not advertise the extension
+receive the existing synchronous `spawn` response, including on older protocol
+versions. `spawn` does not pause for approval, so it deliberately does not
+implement `tasks/update` or task enumeration.
+
 ### Memory egress (cross-provider privacy)
 
 thread-keeper is "one user model … shared across CLIs," and that sharing is by
@@ -322,6 +368,32 @@ override wins over `.env`):
 THREADKEEPER_MEMORY_EGRESS=same-vendor
 ```
 
+### Project memory boundaries
+
+Memory is also isolated by repository. thread-keeper derives a path-free
+`prj_…` namespace from the repository remote (or, when no remote exists, its
+Git history), so ordinary moves and Git worktrees retain one identity without
+storing a local path. New project memory is scoped to that namespace; portable
+memory must be explicitly written as `global` or `shared`.
+
+`brief()`, `search()`, `dialog_search()`, resources, and learning-loop inputs
+read the current project plus explicit global/shared rows. Set
+`cross_project=True` on `search` or `dialog_search` only for deliberate
+cross-project recall. Those results show `scope=`/`project=` provenance and
+write a `cross_project_recall` audit event. The `memory_scope_status()` tool
+shows the current namespace and the migration accounting.
+
+Existing databases keep their memory recallable: legacy rows without reliable
+repository provenance become `global`, as all memory effectively was before
+namespaces, while tasks whose working directory still resolves are scoped to
+their project; new memory is scoped from then on. The migration report records
+the counts. A database that was already at schema v5 before namespaces existed
+gets the namespace columns and this one-time backfill on its next start. Rows
+explicitly marked `unresolved` stay excluded from automatic recall. This
+boundary controls *which local memory is recalled*; it is separate from
+`THREADKEEPER_MEMORY_EGRESS`, which controls whether personal memory may be
+sent to another model provider.
+
 ---
 
 ## Core systems
@@ -666,9 +738,23 @@ can correct one unique substring without reserializing a lesson. Shadow-origin
 though an existing same-slug long lesson may be corrected without increasing
 its body size; near-duplicate slugs are blocked, and semantic body matches are
 routed to the incumbent lesson or surfaced for curation instead of minting a
-sibling lesson. A clear new directive or debunk also flags older permissive
-lessons on the same concrete practice for patch, cross-link, or supersession
-review.
+sibling lesson. The same slug and semantic gates apply to every writer,
+foreground sessions included: a foreground near-duplicate is refused with the
+neighbour's slug, and the author either extends it with `lesson_patch` or, after
+reading it, passes `new_despite=<slug>` (comma-separated when the gates name
+several neighbours) to keep a deliberately separate rule. Loop writers are
+recognized by their write origin, so a loop child cannot opt out by passing a
+foreground-looking `source`. A same-slug rewrite is never folded into a
+different lesson, and the Curator verifier writes the umbrella of a verified
+consolidation without the gates.
+A new lesson that debunks a near-duplicate is refused too: correct the existing
+lesson instead of adding a conflicting one. Refusals are recorded as
+`lesson_refused` events so the gate's hit rate stays measurable. Replacing a
+lesson by its exact title keeps the creator's `origin` (and, for a
+human-authored lesson, its `source` too), and each new Curator
+pass first backfills legacy or mislabeled origin markers (loop sources such as
+`shadow` and `curator` can never count as human-authored), keeping the
+original file as `lessons.md.pre-origin-backfill`.
 Before a genuinely new fallback lesson is written,
 `lesson_neighbors(title, body, summary, k=3)` shows the nearest existing lesson
 slugs (semantic, with a lexical fallback). Shadow and candidate reviewers use
@@ -764,22 +850,60 @@ for semantic review. System and installed-plugin sources are resolved from
 their read-only caches rather than misreported as missing mirrors; telemetry
 rows with no real `SKILL.md` remain explicit orphans. The same inventory also
 flags a dense lesson subtopic when at least
-`THREADKEEPER_CURATOR_PROMOTION_MIN_LESSONS` lessons (default 3) share a pair
-of meaningful title terms. A non-protected candidate must become one validated,
-checklist-style canonical skill before its source lessons are retired; protected
-clusters are left for human review. A read-only research child reads every
-complete skill and relevant support file, performs current web research against
-official docs and comparable public skills, then writes a bounded
-`RESEARCH-<pass>-batch-NNN-of-MMM.json` handoff through a destination-scoped
-tool. A separate web-free evaluator receives that handoff as fenced, untrusted
-data and writes numbered per-skill verdicts to
+`THREADKEEPER_CURATOR_PROMOTION_MIN_LESSONS` lessons (default 3) share two
+concrete title terms and a non-generic body mechanism. Generic joins and
+domain-wide/high-document-frequency title words cannot form a candidate. The
+inventory and `curator_review_status()` report emitted/rejected counts and
+rejection reasons, so the rule can be tuned from production data. Every
+candidate, protected members included, becomes a PROMOTE proposal: the
+verifier creates or patches one validated, checklist-style canonical skill
+before it retires the source lessons. The evaluator reads every complete skill and relevant support
+file, but has no web tools. External research is off by default. With explicit
+`THREADKEEPER_CURATOR_WEB_RESEARCH=1`, a separate Claude-only researcher gets
+only fixed public compatibility queries, `WebSearch`, `WebFetch`, and one
+parent-authorized handoff writer; it cannot read local memory or the
+repository. The evaluator receives that handoff as fenced, untrusted data and
+writes numbered per-skill verdicts to
 `~/.threadkeeper/curator/REPORT-<isodate>.md` for a one-batch pass or
 `REPORT-<isodate>-batch-NNN-of-MMM.md` for a multi-batch pass: KEEP / REPAIR /
-UPDATE / MERGE / SPLIT / DEPRECATE / DELETE / CROSS_LINK / HUMAN_REVIEW.
-Similar names and cosine scores are only candidates; merge/delete decisions
-compare intent, workflow, inputs, outcomes, and unique details. Pinned and
-foreground-authored entries are marked `[PROTECTED]`, and delete-class tools
-enforce the same boundary server-side. The pass is
+UPDATE / MERGE / SPLIT / DEPRECATE / DELETE / CROSS_LINK / DEFER. DEFER means
+the evidence is insufficient for now and a later pass re-examines the entry;
+no verdict waits for a person. Similar names and cosine scores are only
+candidates; merge/delete decisions compare intent, workflow, inputs, outcomes,
+and unique details. Pinned entries are marked `[PINNED]` (keep only), and
+foreground-authored or legacy entries `[PROTECTED]`; the mutating tools enforce
+both boundaries server-side.
+
+Destructive decisions are settled by a second agent, not by a person. The
+evaluator applies only in-place edits that remove nothing (lesson and skill
+patches, repairs, cross-links, concept curation) to entries that are neither
+`[PROTECTED]` nor `[PINNED]`. Every removal, consolidation, merge, split and
+promotion, and every change to a `[PROTECTED]` entry, goes into a
+`VERIFY_PROPOSALS` block at the end of its report. When that block holds at
+least one numbered proposal, the batch gets a third child: an independent
+verifier that re-reads every lesson and skill a proposal touches, tries to
+refute it (a merge that would lose a distinct rule, a removal whose "covered
+by" claim is only partly true, a promotion that is not one procedure), and
+applies only the confirmed or corrected proposals inside the pass snapshot. It
+patches missing residue into a covering skill before removing a lesson,
+records `keep_both` merge verdicts for the pairs it refutes, and writes a
+provenanced `VERIFY-<pass>[-batch-NNN-of-MMM].md` report ending with
+`CURATOR_VERIFY_COMPLETE`. A pass is endorsed only after every batch's
+verification is complete or has used its three attempts. Server-side,
+`lesson_remove` and `skill_manage(action='delete')` refuse the evaluator
+outright, and `lesson_patch` / same-slug `lesson_append` refuse it on protected
+lessons; only the verifier phase, inside a pass carrying both pass-id and
+snapshot-dir context, may change protected entries, and no curator phase may
+touch a pinned one. The verifier is also scoped: the parent records every name
+its batch's proposals mention under the pass snapshot
+(`verify_scope/batch-NNN.json`), and the server refuses a verifier change to
+any lesson or skill outside that list. The batch inventory and the proposals
+reach it as fenced, untrusted data. The Evolve report applier never removes
+anything: it may patch, and the server refuses its `lesson_remove` and skill
+deletes. The parent records the mode each evaluator actually ran in, so a batch
+whose research failed (and was evaluated without mutation tools) never reaches
+the verifier. Report destinations are authorized by exact pass and name, so a
+long pass cannot age them out. The pass is
 single-flight across processes — a non-blocking `fcntl.flock` pidfile
 (`<db dir>/curator.lock`) plus a running-children check serialize it, so
 multiple MCP server instances can't run overlapping (now destructive) passes
@@ -841,11 +965,13 @@ SHA-256 as provenance. Research and evaluation are two phases of each batch
 inside the durable pass: the web-free evaluator for a batch starts only after
 that batch's handoff validates. A researcher that fails or leaves a missing,
 malformed, swapped, or mismatched handoff is retried (three attempts); after
-that the batch gets a non-mutating evaluator that records `HUMAN_REVIEW` for
-decisions that depend on current external facts. A destructive pass takes its
+that the batch gets a non-mutating evaluator that marks `DEFER` for decisions
+that depend on current external facts, so a later pass re-examines them. A destructive pass takes its
 recovery snapshot right before its first mutating evaluator.
 `THREADKEEPER_CURATOR_WEB_RESEARCH=0` skips the research phase entirely (and
 its token cost); the evaluator then judges currency from local evidence only.
+A batch that holds no skills never gets a researcher: the fixed research topics
+only concern skills, so its evaluator starts at once.
 Each report path is then
 authorized in the existing parent-authored `curator_pass` event;
 `curator_report_write` records its SHA-256 in `curator_report_provenance`.
@@ -853,34 +979,39 @@ This makes the report directory an untrusted transport: a stray or forged
 `REPORT-*.md` file cannot acquire the provenance needed by the applier.
 
 The web-enabled researcher never receives lesson, skill, or concept mutation
-tools. The evaluator never receives web tools. Curator applies its own PATCH /
-PRUNE / CONSOLIDATE directly by default (the evaluator writes the REPORT first,
-then mutates — `lesson_remove` is in its toolset so it can actually prune and
-consolidate duplicate lessons). Set
+tools. The evaluator never receives web tools. By default the evaluator applies
+its own in-place edits directly after writing the REPORT, and the verifier
+applies the confirmed destructive proposals; neither the evaluator's toolset
+nor the server lets the evaluator remove anything. Set
 `THREADKEEPER_CURATOR_DESTRUCTIVE=0` for advisory REPORT-only. Pinned and
-untracked skills remain protected. Foreground-authored skills are protected by
-default; set `THREADKEEPER_CURATOR_MANAGE_FOREGROUND_SKILLS=1` to grant the
-Curator explicit snapshot-scoped authority to repair, merge, and delete those
-skills too. The opt-in never overrides pins and is accepted only inside a real
-Curator pass carrying both pass-id and snapshot-dir context. Lessons are
+untracked skills remain protected. Foreground-authored skills are `[PROTECTED]`
+by default, so only the verifier changes them;
+`THREADKEEPER_CURATOR_MANAGE_FOREGROUND_SKILLS=1` (which does not limit the
+verifier) additionally lets the
+evaluator make in-place repairs to them. Lessons are
 stamped with an explicit `origin=<THREADKEEPER_WRITE_ORIGIN>` marker when
 appended; missing, legacy, or unknown lesson provenance is protected by
 default. `lesson_remove` and `skill_manage(action='delete')` refuse protected
 foreground/unknown-origin entries unless `force=True` is called from a
-foreground writer; curator/spawned children cannot elevate themselves with
-`force`. Before a destructive child is spawned, thread-keeper writes
+foreground writer or the caller is the Curator verifier phase; curator/spawned
+children cannot elevate themselves with `force`. Before a destructive child is spawned, thread-keeper writes
 a recoverable snapshot under
 `<reports_dir>/snapshots/<pass-id>/` (default
 `~/.threadkeeper/curator/snapshots/<pass-id>/`). The snapshot contains
 `lessons.md`, copied in-scope skill dirs, a `manifest.json`, and per-action
 tombstones for curator prunes/deletes. Retention is bounded by
-`THREADKEEPER_CURATOR_SNAPSHOT_RETENTION` (default 10, current pass always kept).
+`THREADKEEPER_CURATOR_SNAPSHOT_RETENTION` (default 10) for legacy/direct
+snapshots. Daemon-owned snapshots instead follow the coordinated workflow
+retention policy, so their pass, report, manifest, and recovery archive cannot
+age out on different schedules; active work and an endorsed report that has not
+been applied always keep recovery material.
 Use `curator_restore(pass_id, lesson_slug="...")` or
 `curator_restore(pass_id, skill_name="...")` to restore an item from a snapshot.
 As a prevention layer before recovery is needed, a destructive Curator pass
 has one server-side shared admission budget for `lesson_remove` and
 `skill_manage(action='delete')`, including across bounded child batches.
-`THREADKEEPER_CURATOR_MAX_DESTRUCTIVE_PER_PASS` defaults to 10; set it to 0 to
+`THREADKEEPER_CURATOR_MAX_DESTRUCTIVE_PER_PASS` defaults to 30 (only verified
+proposals delete anything); set it to 0 to
 disable those autonomous deletes. The pass ID makes the count durable and
 cross-process, while foreground/human deletes are unaffected. `mp_dashboard`
 shows admitted and refused operations with `status=HIT` when the Curator reaches
@@ -914,9 +1045,21 @@ The shared lesson file has its own write serialization: `lesson_append`,
 `lessons.md.lock` around file creation/read/mutate/write, so foreground calls
 and learning-loop children cannot last-writer-win over each other's sections.
 
+`lesson_list(k=20, query="")` lists the newest lessons, or with `query` (the
+managed instructions pass the opening request) the most relevant ones with a
+relevance score: semantic when embeddings are available, otherwise the share
+of query words (any script) a lesson contains. Lesson vectors are stored in the
+`lesson_vectors` table keyed by body hash and embedding fingerprint, so each
+body is encoded once per install. Missing vectors are encoded in chunks of 32
+within an 8-second budget per call; a call that runs out falls back to the
+lexical ranking and the next call resumes. Each line shows the lesson's summary. Without a query a session
+would only ever see the newest few lessons, whatever the task.
+
 Lesson access is tracked the same way skill access is: `lesson_list` increments
 `lesson_usage.view_count` for displayed rows and `lesson_get` increments
-`lesson_usage.use_count` for the returned lesson. Curator dry runs include a
+`lesson_usage.use_count` for the returned lesson. Only foreground reads count:
+the curator and other loops read every lesson they audit, and counting those
+reads would make every lesson look recently useful. Curator dry runs include a
 ranked `STALE LESSONS (dry-run decay ranking)` section computed as
 `access_frequency × exp(-days_since_access / tau)`, filtered to unprotected
 lessons with no recent access and low pull-count. That decay list is advisory
@@ -1011,15 +1154,27 @@ with that name instead of minting overlapping roadmap PRs.
 
 The Evolve applier is the downstream implementer. `evolve_apply_roadmap_issue()`
 picks one open GitHub issue at a time (`roadmap` label first, then FIFO), but
-the automatic pass first scans already-open same-repo applier PRs for GitHub
-merge conflicts. A conflicted `roadmap/…` or `evolve/…` PR is repaired before
-any new issue/report/evolve work is started; if the PR sweep itself cannot read
-GitHub state, the pass fails closed instead of taking fresh work blind. The
-conflict-repair child checks out the existing PR branch, merges the current
-base branch, resolves conflicts, runs the full suite, and pushes back to the
-same branch. It then waits for GitHub checks on the pushed PR head and runs
-`gh pr merge --squash --delete-branch`, so GitHub lands the repaired PR into
-`main` through branch protection rather than a raw local `git push origin main`.
+the automatic pass first sweeps the open PRs authored by the account
+thread-keeper's `gh` acts as — yours: applier, reviewer, and hand-made PRs
+alike. A PR from any other account (a collaborator, a bot, a fork) is never
+updated, repaired, or merged. If the PR sweep itself cannot read GitHub state
+or the `gh` account, the pass fails closed instead of taking fresh work blind.
+The sweep squash-merges the oldest non-draft PR GitHub reports `CLEAN` (up to
+date, required checks green) through the protected merge API, pinned to the
+head SHA it saw green, and then asks GitHub to update the oldest `BEHIND` one —
+the "Update branch" button — so CI reruns against the new base. Open
+work in progress as a draft: drafts are never merged. Strict branch
+protection lets only one PR merge per base commit, so PRs land one at a time,
+oldest first. Between full passes the daemon repeats only this cheap landing
+sweep every 15 minutes, so a green PR lands minutes after its checks finish;
+it skips while any reviewer/applier git writer runs. A conflicted applier PR
+(`roadmap/…` or `evolve/…` head branch in this repository) is repaired before
+any new issue/report/evolve work is started: the conflict-repair child checks
+out the existing PR branch, merges the current base branch, resolves
+conflicts, runs the full suite, and pushes back to the same branch, then
+stops; the landing sweep merges it once it is green. A hand-made PR with
+conflicts, and red or otherwise blocked PRs, wait for a human. Set
+`THREADKEEPER_EVOLVE_AUTOLAND=0` to leave every merge to a human.
 The roadmap issue child skips issues carrying denylisted human-gate labels,
 skips issues with an active Evolve claim comment, posts its own claim comment
 before spawning, and advances to the next issue when an issue-local dispatch
@@ -1054,9 +1209,13 @@ task’s tree. This prevents unrelated unfinished tests from blocking every PR
 repair. Ignored files (including `.venv`) and explicit operator checkouts stay
 in place; live writers prevent recovery, and backup failures block dispatch.
 Each managed-checkout child fetches the
-configured branch only to retrieve the configured immutable commit, then
-prepares or resumes its deterministic local/remote feature branch from
-`THREADKEEPER_EVOLVE_REPO_COMMIT`, never from the branch's moving tip. Retries
+configured branch, prepares or resumes its deterministic local/remote feature
+branch from the freshly fetched `origin/<THREADKEEPER_EVOLVE_REPO_BRANCH>` tip,
+rebases onto it, and re-syncs the managed venv to that branch's declared
+dependencies. `THREADKEEPER_EVOLVE_REPO_COMMIT` bounds only what the parent
+provisions and parks the checkout at; it is never a branch base, because a base
+that never moves cut every applier PR from one stale commit and each PR was
+born conflicted with `main`. Retries
 therefore validate prior branch work instead of discovering a branch-name
 collision after changing the base checkout. A shared git-writer running-task
 check prevents the privileged reviewer audit and code/PR applier from
@@ -1066,8 +1225,9 @@ If a killed child leaves an unresolved merge or plain tracked WIP in the default
 auto-managed checkout, the next code-producing pass archives the diff before
 recovering it. Merge recovery remains limited to `roadmap/…`/`evolve/…`
 branches whose exact PR is confirmed open or merged. For an open PR, the parent
-archives the interrupted merge, aborts it, refreshes the disposable checkout,
-and lets the normal conflict-repair sweep retry that same PR. A merged PR's
+archives the interrupted merge (including edits the child made after staging
+a resolution), resets it, refreshes the disposable checkout, and lets the
+normal conflict-repair sweep retry that same PR. A merged PR's
 leftover merge is discarded as stale. Plain abandoned WIP is recoverable on
 those applier branches when PR state is readable, and also on the configured
 base branch: the disposable base can contain orphaned edits when an older child
@@ -1160,6 +1320,11 @@ daily deterministic `docs/roadmap-audit-YYYY-MM-DD` branch so repeated audit
 passes update or skip the existing roadmap PR rather than opening a second one.
 Automatic apply passes respect the configured interval so multiple foreground
 MCP server startups do not repeatedly spawn workers for the same open issue.
+That interval is consumed only by a real child launch or a completed empty
+check. A busy applier, checkout/GitHub/claim/race error, or refused spawn keeps
+the prior cursor and retries on a bounded short cadence; repeated identical
+blockers are recorded once until the blocker changes. `evolve_apply_status()`
+shows the last attempt, last successful dispatch, and any pending retry time.
 Manual tools such as `evolve_apply_conflicted_pr()` and
 `evolve_apply_roadmap_issue()` dispatch immediately. If no conflicted applier PR
 or roadmap issue is startable, the pass falls back to Curator reports and then
@@ -1337,8 +1502,45 @@ Adding a new language is a two-file PR — see [CONTRIBUTING.md](CONTRIBUTING.md
 
 The most-used env knobs (full list in `threadkeeper/config.py`):
 
+### MCP tool profiles
+
+The server can advertise a role-sized MCP tool surface instead of its full
+catalog. Set `THREADKEEPER_TOOL_PROFILE` before server startup, then restart
+the host after changing it:
+
+| Profile | Intended surface |
+| --- | --- |
+| `core` | daily session memory: `brief`, `context`, threads, notes, search, and peer coordination |
+| `coordination` | `core` plus child spawning, task status, pickup, and delegated search |
+| `memory-admin` | `core` plus durable memory, concepts, lessons, graph links, and explicit erasure |
+| `learning-loops` | `core` plus extraction, validation, skills, Curator, probes, and dialectic workflows |
+| `full` | every registered tool; the compatibility default when no profile is configured |
+
+New `thread-keeper-setup` registrations use `core`. Existing server entries
+without the setting retain `full` until you opt in. Add exact, comma-separated
+tool names with `THREADKEEPER_TOOL_INCLUDE`, or remove names with
+`THREADKEEPER_TOOL_EXCLUDE`; unknown names and contradictory overrides stop the
+server rather than exposing an unintended surface.
+
+Spawned children default to `core`; archival, Curator, candidate-review,
+shadow-review, probe-runner, and dialectic-validator roles use
+`learning-loops`, while Evolve roles request `full`. The server receives the
+parent’s resolved allowlist and intersects it with the child profile, so a
+child cannot regain a tool its parent did not expose.
+`THREADKEEPER_CHILD_TOOL_PROFILE` explicitly selects a different child profile,
+still under that parent constraint.
+
+Every non-full profile includes read-only `capability_search(query)`. It returns
+at most six matching capability *families* with a summary and the profile that
+would expose them. It does not list hidden concrete tools or enable any action;
+use it as the fallback on hosts that lack native deferred tool discovery.
+
 | Knob | Default | Purpose |
 |---|---|---|
+| `THREADKEEPER_TOOL_PROFILE` | `full` | MCP registry profile: `core`, `coordination`, `memory-admin`, `learning-loops`, or `full`; read at server start |
+| `THREADKEEPER_TOOL_INCLUDE` | "" | exact comma-separated tool names to add to the selected profile; unknown names fail closed |
+| `THREADKEEPER_TOOL_EXCLUDE` | "" | exact comma-separated tool names to remove from the selected profile; unknown or overlapping names fail closed |
+| `THREADKEEPER_CHILD_TOOL_PROFILE` | role default | spawned-child profile override; always intersected with the parent’s resolved tool surface |
 | `THREADKEEPER_DB` | `~/.threadkeeper/db.sqlite` | SQLite file |
 | `THREADKEEPER_TASK_LOG_DIR` | `~/.threadkeeper/tasks` | owner-only task spool for spawn logs, stdin prompts, command scripts, and small runtime logs |
 | `THREADKEEPER_RETENTION_INTERVAL_S` | 0 (off) | SQLite retention/compaction daemon tick; 0 disables the daemon |
@@ -1349,7 +1551,13 @@ The most-used env knobs (full list in `threadkeeper/config.py`):
 | `THREADKEEPER_PROBE_RESULT_RETENTION_DAYS` | 0 | prune old `probe_results` and refresh reliability aggregates; 0 keeps forever |
 | `THREADKEEPER_RETENTION_WAL_CHECKPOINT` | false | run `PRAGMA wal_checkpoint(TRUNCATE)` during retention passes |
 | `THREADKEEPER_RETENTION_VACUUM_AFTER_ROWS` | 0 | run `VACUUM` after a pass deletes at least this many rows; 0 disables VACUUM |
+| `THREADKEEPER_WORKFLOW_RETENTION_DAYS` | 30 | age protection for terminal Curator passes and consumed Evolve research handoffs; `0` disables the age bound |
+| `THREADKEEPER_WORKFLOW_RETENTION_COUNT` | 100 | newest terminal Curator passes and research handoffs protected by count; `0` disables the count bound |
 | `THREADKEEPER_MEMORY_EGRESS` | `all` | cross-provider scope for personal-class memory (verbatim quotes + dialectic user-model) in `brief()`. `all` = current behavior, egress to whichever vendor backs the consuming CLI. `same-vendor` = personal renders only for Claude/Anthropic, omitted for OpenAI/Google/Microsoft CLIs. `work-only` = personal never rendered, any vendor. See [Memory egress](#memory-egress-cross-provider-privacy) |
+| `THREADKEEPER_OTEL_ENABLED` | false | enable privacy-safe OTLP tracing only when an endpoint is also configured |
+| `THREADKEEPER_OTEL_ENDPOINT` | "" | OTLP/HTTP collector trace endpoint, normally `https://collector.example/v1/traces` |
+| `THREADKEEPER_OTEL_EXPORT_TIMEOUT_S` | 2 | collector request timeout; export happens outside the local workflow |
+| `THREADKEEPER_OTEL_EXPORT_QUEUE_SIZE` | 256 | bounded per-process span queue (1–2048); oldest queued spans are dropped under pressure |
 | `THREADKEEPER_AUTO_REVIEW` | "" (off) | auto-review on `close_thread` |
 | `THREADKEEPER_AUTO_UPDATE_INTERVAL_S` | 86400 | MCP self-update check interval; 0 disables |
 | `THREADKEEPER_AUTO_UPDATE_RESTART` | "1" | exit MCP process after an update passes setup/import smoke checks so the host restarts on new code |
@@ -1381,11 +1589,11 @@ The most-used env knobs (full list in `threadkeeper/config.py`):
 | `THREADKEEPER_CANDIDATE_REVIEW_BATCH_SIZE` | 40 | most pending candidates (oldest first) one reviewer child receives; the rest stay pending for the next pass |
 | `THREADKEEPER_LEARNING_LOOP_SKILL_CREATE_LIMIT` | 2 | max new skills one autonomous learning-loop child (`candidate_review`, `shadow_review`, or `background_review`) may create in its session; foreground creation is unaffected |
 | `THREADKEEPER_CURATOR_INTERVAL_S` | 259200 | deep curator audit every three days; set `0` to disable |
-| `THREADKEEPER_CURATOR_MANAGE_FOREGROUND_SKILLS` | 0 | allow snapshot-scoped Curator repair/merge/delete of foreground skills; pinned/untracked skills remain protected |
+| `THREADKEEPER_CURATOR_MANAGE_FOREGROUND_SKILLS` | 0 | let the Curator evaluator make in-place repairs to foreground skills; the verifier changes foreground skills its proposals name regardless, and pinned skills stay protected |
 | `THREADKEEPER_CURATOR_MIN_LESSONS` | 3 | min lessons before curator engages |
-| `THREADKEEPER_CURATOR_WEB_RESEARCH` | `1` (on) | run a read-only web research child per batch before the web-free evaluator; `0` skips research (the evaluator uses local evidence only) |
+| `THREADKEEPER_CURATOR_WEB_RESEARCH` | `0` (off) | explicit consent for the isolated Curator web researcher; it receives only fixed public compatibility queries, and decisions that need facts the handoff lacks are marked `DEFER` for a later pass |
 | `THREADKEEPER_CURATOR_DESTRUCTIVE` | `1` (on) | curator child writes its REPORT then applies its own PATCH/PRUNE/CONSOLIDATE directly (incl. `lesson_remove` for prune/consolidate); set `0` for advisory REPORT-only. `[PROTECTED]` entries are refused server-side |
-| `THREADKEEPER_CURATOR_MAX_DESTRUCTIVE_PER_PASS` | 10 | shared server-side ceiling for one destructive Curator pass across `lesson_remove` and `skill_manage(action='delete')`; `0` disables autonomous deletes and foreground deletes bypass it |
+| `THREADKEEPER_CURATOR_MAX_DESTRUCTIVE_PER_PASS` | 30 | shared server-side ceiling for one destructive Curator pass across `lesson_remove` and `skill_manage(action='delete')`; `0` disables autonomous deletes and foreground deletes bypass it |
 | `THREADKEEPER_CURATOR_SNAPSHOT_RETENTION` | 10 | number of destructive curator pre-mutation snapshots to retain under `<reports_dir>/snapshots`; current pass is always retained |
 | `THREADKEEPER_CURATOR_TRASH_TTL_DAYS` | 30 | days to retain recovery artifacts under `<db dir>/curator/trash` for `lesson_remove` and `skill_manage(action='delete')`; expired artifacts are swept on new trash writes |
 | `THREADKEEPER_PROBE_INTERVAL_S` | 0 (off) | probe daemon tick (s); 1800 = 30 min recommended so finished probe answers are graded promptly |
@@ -1427,12 +1635,17 @@ The most-used env knobs (full list in `threadkeeper/config.py`):
 | `THREADKEEPER_SKILL_NUDGE_INTERVAL` | 10 | events between `skill_hint` nudges |
 | `THREADKEEPER_DIALECTIC_MINE_INTERVAL_S` | 0 (off) | dialectic_miner daemon tick (s); 0 disables mechanical observation capture |
 | `THREADKEEPER_DIALECTIC_VALIDATE_INTERVAL_S` | 0 (off) | dialectic_validator daemon tick (s); 0 disables LLM-driven claim synthesis |
+| `THREADKEEPER_MODEL_ROUTER_INTERVAL_S` | 604800 (weekly) | model-router pass interval (s); 0 disables it and `auto` follows the active CLI |
+| `THREADKEEPER_MODEL_ROUTER_FALLBACK_CLI` | codex | CLI for the router's fallback run |
+| `THREADKEEPER_MODEL_ROUTER_FALLBACK_MODEL` | gpt-6.1-sol | model for the router's fallback run |
+| `THREADKEEPER_MODEL_ROUTER_FALLBACK_EFFORT` | xhigh | effort for the router's fallback run |
 | `THREADKEEPER_DIALECTIC_VALIDATE_MIN` | 5 | min buffered observations before validator engages |
 | `THREADKEEPER_DIALECTIC_VALIDATE_FLUSH_AGE_S` | 259200 | age-flush: an undersized observation buffer is still validated once its oldest eligible row is this old (0 = threshold only) |
 | `THREADKEEPER_DIALECTIC_VALIDATE_BATCH_SIZE` | 50 | max observations sent to one validator child; prevents oversized prompts and drains large queues incrementally |
 | `THREADKEEPER_EVOLVE_REVIEW_INTERVAL_S` | 0 (off) | evolve-reviewer daemon tick (s); audits thread-keeper for safety/leaks/optimization/new ideas, updates roadmap/issues, and includes legacy evolve suggestions as input. Runs as two alternating phases — read-only web research, then a privileged web-free audit that consumes the fenced research digest (#79) — so a full cycle spans two ticks |
 | `THREADKEEPER_EVOLVE_REVIEW_BACKLOG_MAX` | 25 | max open, not-yet-applied `roadmap`-label issues before the issue-creating audit is skipped and records `backlog_saturated`; skip-labelled and untrusted-author roadmap issues still count; `0` disables the cap |
 | `THREADKEEPER_EVOLVE_APPLY_INTERVAL_S` | 0 (off) | evolve-applier daemon tick (s); implements one open GitHub issue at a time, then falls back to Curator reports and promoted legacy evolve suggestions. Empty checks are throttled between intervals; actionable work and manual apply tools still dispatch |
+| `THREADKEEPER_EVOLVE_AUTOLAND` | true | land open non-draft PRs authored by the account `gh` acts as: squash-merge one once GitHub reports it up to date with required checks green, and update one that fell behind the base. Other accounts' PRs are never touched. `0`/`false` leaves every merge to a human |
 | `THREADKEEPER_EVOLVE_REPO_ROOT` | (auto) | absolute path to the thread-keeper git checkout the evolve reviewer/applier branch, test, and open PRs against. When empty, the repo is resolved automatically: the package's parent dir for an editable `install.sh`, else a managed checkout under the DB dir that is auto-cloned on first use. Set this to pin an explicit checkout |
 | `THREADKEEPER_EVOLVE_AUTO_CLONE` | true | auto-provision a managed checkout that runs remote `pip install -e` and tests; set `0`/`false` on shared or multi-user hosts unless that remote-code-execution boundary is explicitly accepted |
 | `THREADKEEPER_EVOLVE_REPO_URL` | upstream repo | HTTPS `github.com` source for the managed clone; restart-only, and other hosts/schemes are refused |
@@ -1492,7 +1705,7 @@ THREADKEEPER_SPAWN__DEFAULT=claude
 # supported CLI keys: claude, codex, antigravity (agy executable), copilot
 THREADKEEPER_SPAWN__LOOP__SHADOW_OBSERVER=claude   # heaviest reasoning → keep on Claude
 THREADKEEPER_SPAWN__LOOP__CURATOR=codex            # weekly audit → Codex is fine
-THREADKEEPER_SPAWN__LOOP__CANDIDATE_REVIEWER=auto  # "auto" = follow active CLI
+THREADKEEPER_SPAWN__LOOP__CANDIDATE_REVIEWER=auto  # "auto" = model router decides (active CLI until it has)
 # model pin per CLI or per role:  THREADKEEPER_SPAWN__MODEL__<KEY>=<model>
 THREADKEEPER_SPAWN__MODEL__CLAUDE=opus
 THREADKEEPER_SPAWN__MODEL__CODEX=gpt-5.5
@@ -1505,7 +1718,8 @@ THREADKEEPER_SPAWN__EFFORT__CURATOR=xhigh
 ```
 
 Resolution per role: `SPAWN__LOOP__<role>` → `SPAWN__DEFAULT` → active CLI →
-`claude`; `"auto"` (or unset) defers to the active CLI. Real environment
+`claude`; unset defers to the active CLI, and `"auto"` does too until the model
+router (below) has decided for that role. Real environment
 variables override the `.env`. Force host detection with
 `THREADKEEPER_ACTIVE_CLI=claude` (or `codex`, `antigravity`/`agy`,
 `copilot`). `agy` is normalized to `antigravity`. See `.env.example`
@@ -1513,6 +1727,28 @@ for the full knob list. `spawn_status()` includes warnings when a configured
 spawn CLI is unsupported or a model key does not match a supported CLI/startup
 role, while keeping the same fallback resolution.
 
+### Model router (`auto` roles)
+
+Set a role's CLI to `auto` to let the weekly **model router** choose its CLI,
+model and effort:
+
+```bash
+THREADKEEPER_SPAWN__LOOP__SHADOW_OBSERVER=auto
+```
+
+The router reviews the last 30 days of that role's spawns (success rate,
+failures such as provider capacity errors, run time, tokens, recent outcomes)
+plus the local model catalog, and records one decision per `auto` role with a
+reason. Until it has decided, `auto` keeps its old meaning and follows the
+active CLI. While a role is routed, its `SPAWN__MODEL__<ROLE>` and
+`SPAWN__EFFORT__<ROLE>` pins are ignored and `spawn_status()` warns about them.
+
+The router runs on `claude` / `opus` / `max` (override with the usual
+`SPAWN__LOOP|MODEL|EFFORT__MODEL_ROUTER` keys). If that run fails, the same pass
+reruns on the fallback below; a pass that fails twice retries after 6 hours.
+`model_router_status()` shows current decisions and `model_router_run()` runs a
+pass now. Set `THREADKEEPER_MODEL_ROUTER_INTERVAL_S=0` to disable the router.
+
 Adapters without headless support (Claude Desktop, VS Code) can't be
 spawn targets — `spawn_status()` reports them as "no adapter" and any
 override pointing at them falls back to the next priority level.
@@ -1562,6 +1798,38 @@ Three tools keep the memory tidy. `consolidate()` and `forget()` default to
 
 ## Telemetry
 
+### Privacy-safe OTLP traces
+
+OTLP export is **off by default**. To opt in, set both
+`THREADKEEPER_OTEL_ENABLED=1` and `THREADKEEPER_OTEL_ENDPOINT` to an
+OTLP/HTTP `/v1/traces` endpoint. ThreadKeeper sends OTLP JSON asynchronously;
+collector failure, timeout, or a full queue never delays a local MCP call,
+spawn, watchdog action, or SQLite write.
+
+One spawned workflow is linked as `MCP spawn → workflow → agent → child MCP
+operation`. The W3C trace context is saved with the task and passed only in the
+private child environment (and its slim MCP config), never in a prompt or CLI
+argument. A watchdog continuation uses the prior agent span as its parent, so
+retries remain in the same trace.
+
+The exporter has a fixed allowlist: operation/tool identifier, latency and
+queue wait, provider/model identifiers, input/output/total tokens, USD cost,
+retry count, and terminal outcome. Operation names are fixed; tool/provider
+identifiers are limited to 64 safe characters, model identifiers to 96, and a
+process exports at most 64 distinct model values (later values become
+`unknown`).
+Everything else is excluded by construction: prompts, MCP arguments/results,
+memory bodies, user quotes, credentials, paths, task logs, and SQLite event
+summaries are never span attributes.
+
+The local SQLite event ledger remains the source of truth. It retains only the
+opaque trace linkage beside a task row, so its existing task-retention policy
+also removes that linkage. Configure collector retention at the collector; no
+trace payload is persisted locally. If traces do not arrive, first verify the
+endpoint includes `/v1/traces`; then inspect collector connectivity. A full
+queue intentionally drops its oldest pending spans rather than growing memory
+or blocking the workflow.
+
 - **`mp_dashboard(window_days=7)`** — one-call rollup of the whole
   system, read-only. Three sections: **stores** (threads by state,
   notes/dialog/distill/concepts counts, skills + claims by tier,
@@ -1634,7 +1902,9 @@ that keeps a write transaction open for a minute or more.
 
 Schema migration uses SQLite `PRAGMA user_version`: a current database skips
 legacy `ALTER TABLE` work, while an old or fresh v0 database migrates once
-under a writer transaction and records the current version. Duplicate-column
+under a writer transaction and records the current version. Every startup
+also replays the idempotent baseline `CREATE ... IF NOT EXISTS` schema, so a
+table added after the last version bump still reaches existing databases. Duplicate-column
 migrations are the only expected no-op; other DDL errors are logged and raised.
 
 On POSIX systems, startup and `get_db()` harden the default local store
@@ -1642,9 +1912,10 @@ best-effort: `~/.threadkeeper` is `0700`, while `db.sqlite`, SQLite
 `-wal`/`-shm` sidecars, `~/.threadkeeper/.env`, curator `REPORT-*.md`
 files, and headless spawn logs are owner-only (`0600`).
 
-Use `tk-backup` for disaster recovery. It uses SQLite `VACUUM INTO`, so
-committed frames still living in the live `-wal` sidecar are included in a
-compacted snapshot without quiescing background writers:
+Use `tk-backup` for disaster recovery. In the default SQLite profile it uses
+`VACUUM INTO`; the encrypted profile uses SQLCipher's online backup API into a
+new encrypted destination. Both paths include committed frames still living in
+the live `-wal` sidecar without quiescing background writers:
 
 ```bash
 tk-backup create ~/threadkeeper-backup.sqlite
@@ -1667,6 +1938,73 @@ first and copy `db.sqlite`, `db.sqlite-wal`, and `db.sqlite-shm` together. To
 wipe memory, also stop thread-keeper first, then remove the main DB and both
 sidecars.
 
+### Opt-in encrypted storage (experimental)
+
+The default `sqlite` profile is unchanged. For sensitive memory at rest, the
+optional `sqlcipher` profile encrypts the main database, WAL/rollback-journal
+pages, and profile-aware snapshots with SQLCipher. SQLCipher temporary
+structures are kept in memory with cipher memory security enabled. Install it
+explicitly and initialize a new store before starting any MCP server:
+
+```bash
+pip install 'threadkeeper[encrypted]'
+tk-storage init --db ~/.threadkeeper/secure.sqlite
+export THREADKEEPER_DB=~/.threadkeeper/secure.sqlite
+export THREADKEEPER_STORAGE_PROFILE=sqlcipher
+```
+
+The profile name may live in normal configuration; the encryption key never
+does. Thread-keeper generates a random key and retrieves it from the operating
+system secret store through `keyring`. It never accepts a key in an environment
+variable, config file, command argument, event, log, or telemetry. If the
+secret store, SQLCipher backend, or key is unavailable, opening the encrypted
+profile fails closed. A wrong key cannot initialize or replace an existing
+database.
+
+Use the normal backup command after enabling the profile; it recognizes the
+profile and creates an encrypted destination with its own OS-secret-store key:
+
+```bash
+tk-backup create ~/threadkeeper-secure-backup.sqlite
+tk-backup restore ~/threadkeeper-secure-backup.sqlite --yes
+tk-storage integrity-check --db ~/.threadkeeper/secure.sqlite
+tk-storage rekey --db ~/.threadkeeper/secure.sqlite
+```
+
+Stop all MCP servers, the daemon host, and CLI sessions before a restore or
+rekey. If a machine loses power during rekey, normal opens intentionally stop;
+run `tk-storage recover-rekey --db …` to have the OS secret store validate and
+finish the pending rotation without printing either key. Back up the operating
+system account and its secret store according to your platform's recovery
+procedure. Thread-keeper deliberately has no key-export command: exporting a
+raw database key into a shell history or ordinary file defeats this profile.
+
+Move an existing store through a separately validated output path. The source
+is never replaced, so it remains available until the new store has been
+verified:
+
+```bash
+tk-storage migrate ~/.threadkeeper/db.sqlite ~/.threadkeeper/secure.sqlite \
+  --from-profile sqlite --to-profile sqlcipher
+tk-storage migrate ~/.threadkeeper/secure.sqlite ~/.threadkeeper/plain.sqlite \
+  --from-profile sqlcipher --to-profile sqlite
+```
+
+Only switch `THREADKEEPER_DB` and `THREADKEEPER_STORAGE_PROFILE` after the
+destination passes `tk-storage integrity-check` (for SQLCipher) or
+`sqlite3 <path> 'PRAGMA integrity_check'` (for ordinary SQLite). The migration
+checks integrity plus table/index/trigger coverage before the destination is
+atomically published.
+
+This is an at-rest database profile, not full-device encryption. It does not
+encrypt task logs, curator reports/snapshots, exported briefs, source CLI
+transcripts, skills, `node.id`, or sync traffic. Put the whole state directory
+on full-disk encryption, use the existing owner-only permissions, set retention
+for logs/reports, and use TLS/private networking for sync. The profile is
+experimental: automated SQLCipher coverage currently runs on Linux; validate
+the OS keyring integration on macOS or Windows before relying on it for a
+recovery-sensitive deployment.
+
 ### Selective Erasure
 
 For one regretted or sensitive conversation, use targeted erasure instead of
@@ -1702,6 +2040,19 @@ the high-volume tables (`dialog_messages`, `dialog_fts`, `dialog_vec`,
 `signals`, `events`, `tasks`, `probe_results`) so growth is visible before it
 becomes a problem.
 
+Terminal Curator passes own their frozen batch text, `REPORT-*`, `AUDIT-*`, and
+destructive snapshot; Evolve handoffs own their `RESEARCH-*` digest. The
+retention daemon keeps active/retryable work, recovery material, and endorsed
+but unapplied reports. After both enabled workflow bounds expire, it first
+compacts batch/research bodies to a SHA-256 plus a 512-character summary and
+removes only owned files. A later pass removes the compacted rows. File removal
+is path-contained to the configured Curator or Evolve directory, rejects
+symlinks, and is journaled so an interrupted delete retries safely. Use
+`workflow_retention_preview()` for the dry-run counts/bytes and oldest terminal
+pass; `mp_dashboard()` shows its latest outcome. A selective `forget()` that
+matches a frozen workflow body compacts it immediately, including active work;
+the normal report/lesson review guidance still applies to generalized content.
+
 `db_compact()` is the opt-in disk-reclaim tool: `VACUUM` + a mandatory
 `dialog_fts` rebuild (schema v2 keys the FTS index on `dialog_messages`
 rowids, which `VACUUM` is permitted to renumber — the rebuild is what
@@ -1868,9 +2219,9 @@ reusable verdict logic lives in `threadkeeper/verify_ingest.py`.
 ## Memory-quality evaluation
 
 The ingest verifier above answers *"did we capture the data?"*. The
-memory-quality harness answers the harder question — *"when we retrieve it,
-do we recall the right fact, and do we **refuse** to answer about things that
-never happened?"* It's modeled on
+memory-quality harness answers two separate questions: *"did we retrieve the
+right evidence?"* and *"does an agent produce the right final answer from
+that evidence?"* It's modeled on
 [LongMemEval](https://arxiv.org/pdf/2410.10813) (ICLR 2025) plus mem0's 2026
 [tokens-per-retrieval](https://mem0.ai/blog/ai-memory-benchmarks-in-2026)
 cost axis, and runs the **real** `search()` / `dialog_search()` / `brief()`
@@ -1881,24 +2232,34 @@ python scripts/memory_eval/run.py                 # bundled demo corpus, lexical
 python scripts/memory_eval/run.py --json          # machine-readable report
 python scripts/memory_eval/run.py --db snap.sqlite --ground-truth my_labels.json
 python scripts/memory_eval/run.py --semantic      # use embeddings if installed
-python scripts/memory_eval/run.py --judge llm      # LLM-graded (needs ANTHROPIC_API_KEY)
+python scripts/memory_eval/run.py --matrix --strict # FTS/hybrid migration gate
+age -d holdout.json.age | python scripts/memory_eval/run.py \
+  --ground-truth /dev/stdin --private-holdout       # no per-case output
 ```
 
-It reports four headline groups over a fixed ground-truth set:
+It reports these headline groups over a fixed ground-truth set:
 
-- **accuracy** — fraction of questions whose retrieval recalled the gold
-  fact, broken out per the five LongMemEval axes (information extraction,
-  multi-session reasoning, temporal reasoning, knowledge updates, abstention).
+- **evidence recall** and **final-answer correctness** — separate scores, both
+  per axis. The final answer comes from a deterministic replay responder that
+  may emit only facts found in the returned context; it gives CI a stable
+  boundary between retrieval and reasoning failures.
 - **abstention rate** — of the *never-happened* questions, the fraction the
-  system correctly refused. This is the highest-payoff axis: it directly
-  measures whether the auto-injected `brief()` context fabricates or surfaces
-  stale facts.
+  system correctly refused. Retention/curation removals and egress-blocked
+  personal memory are also required to end in a refusal.
 - **tokens-per-retrieval** — mean / median / max tokens of what each query
-  returned, so recall is never read apart from cost (a wider window that
-  recalls more also costs more).
+  returned, plus equivalent final-answer token totals.
 - **retrieval latency** — mean / p50 / p95 / max wall-clock milliseconds. With
   `--semantic`, the backend is reported as `hybrid`, because dense candidates
   augment rather than replace FTS.
+- **outcome classification** — retrieval failure, reasoning failure,
+  stale-memory use, removed-memory use, and privacy-policy violation.
+
+`--matrix` runs every public-fixture case through the FTS and hybrid backends,
+three fixture states (`baseline`, `retained`, `curated`), and every personal
+memory egress policy (`all`, `same-vendor`, `work-only`). A hybrid row is marked
+unavailable when the optional semantic extra is not installed. `--strict`
+requires the versioned fixture thresholds and zero safety violations, making
+the same command suitable for retrieval/model migration gates.
 
 For DB concurrency, run the reproducible local gate:
 
@@ -1910,18 +2271,20 @@ The JSON result includes expected/actual writes, throughput, p50/p95/p99/max
 write latency, worker errors, elapsed time, and `PRAGMA quick_check`; a non-zero
 exit means a lost write, worker failure, or integrity failure.
 
-With no `--db` the harness builds the bundled fixture
-(`scripts/memory_eval/ground_truth.json` — a fictional "billing service" told
-across three sessions) into a throwaway DB; it's a **golden baseline** where a
-faithful retrieval scores 100%, so a regression in the retrieval tools drops
-the number. `--db` runs **read-only**: the snapshot is copied to a temp file
-and the original is never opened for writing. The default judge is **lexical**
-(deterministic, offline, no API key, no embeddings) so the command is
-reproducible and CI-safe; `--judge llm` grades answer *reasoning* (not just
-retrieval recall) with an Anthropic model when a key is set — the intended
-optimization target for lesson-decay tuning (#27) and bi-temporal claims (#28)
-work. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for how the
-axes map onto thread-keeper's retrieval surface.
+With no `--db` the harness builds the bundled, versioned public synthetic
+fixture (`scripts/memory_eval/ground_truth.json` — a fictional "billing
+service") into a throwaway DB. Bump its `version` whenever cases, labels, or
+thresholds change; CI uses the checked-in version and its stable thresholds.
+`--db` runs **read-only**: the snapshot is copied to a temp file and the
+original is never opened for writing.
+
+For a private holdout, keep the corpus encrypted or outside the repository and
+pass it with `--private-holdout`. The runner does not decrypt data itself; it
+accepts a locally decrypted file or stdin and deletes its temporary DB on exit.
+Private mode emits aggregate metrics only — no case rows, failure details,
+retrieved context, or replayed answer is written to stdout, artifacts, or the
+repository. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the corpus
+contract and migration-gate interpretation.
 
 ## Evaluating learning-loop decision quality
 
@@ -2023,7 +2386,9 @@ threadkeeper/
 so `tools/list` carries MCP 2025-06-18 `ToolAnnotations` for every
 registered tool: `readOnlyHint=True` for pure reads (`brief`, `context`, `search`,
 `dialog_search`, the status tools, …) and `readOnlyHint=False`
-for mutations. `lesson_list` / `lesson_get` are classified as non-destructive
+for mutations. Advertised reads use query-only database connections and never
+bootstrap a session, start daemon work, refresh process data, or mutate
+lifecycle state. `lesson_list` / `lesson_get` are classified as non-destructive
 writes because they bump lesson access counters. Delete/overwrite/kill tools
 carry `destructiveHint=True` (`compost` is read-only — it only surfaces idle
 threads). A confirmation/elicitation host reads this to decide which calls
@@ -2038,6 +2403,15 @@ capability before prompting, uses only a flat primitive schema, and leaves
 unsupported clients on the existing text/tool fallback path. The first protected
 write is `dialectic_supersede`.
 
+**Protocol compatibility (#344).** The stdio server supports the
+`2025-11-25` initialize-handshake era and the `2026-07-28` request-envelope
+era. Legacy hosts retain the existing tools, resources, and prompts. Modern
+calls derive identity and capabilities from every request, static discovery
+catalogs advertise public cache freshness, and replaying a completed write with
+the same caller-bound JSON-RPC id returns the original result instead of
+committing a second mutation. Sealed continuation state expires after five
+minutes; an interrupted write with no terminal result is rejected on replay.
+
 Detailed map in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
 Open work in [docs/ROADMAP.md](docs/ROADMAP.md) and the
 [Issues tab](https://github.com/po4erk91/thread-keeper/issues).