threadkeeper 0.19.1__tar.gz → 0.20.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: threadkeeper
-Version: 0.19.1
+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:
@@ -234,6 +243,7 @@ read/act split, plus MCP elicitation for host-native confirmations:
 | **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; 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
@@ -337,9 +383,13 @@ 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 are migrated conservatively: rows without reliable
-repository provenance are marked `unresolved`, excluded from automatic recall,
-and listed in the migration report until an operator classifies them. This
+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.
@@ -688,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
@@ -790,10 +854,10 @@ flags a dense lesson subtopic when at least
 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. 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. The evaluator reads every complete skill and relevant support
+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
@@ -802,11 +866,44 @@ 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
@@ -868,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`.
@@ -880,22 +979,22 @@ 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
@@ -911,7 +1010,8 @@ Use `curator_restore(pass_id, lesson_slug="...")` or
 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
@@ -945,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
@@ -1113,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
@@ -1207,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
@@ -1384,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 |
@@ -1434,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` | `0` (off) | explicit consent for the isolated Curator web researcher; it receives only fixed public compatibility queries, while foreground/private/unclassified entries use `HUMAN_REVIEW` |
+| `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 |
@@ -1480,6 +1635,10 @@ 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 |
@@ -1546,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
@@ -1559,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`
@@ -1567,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.
@@ -1720,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
@@ -1728,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
@@ -1753,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