threadkeeper 0.19.0__tar.gz → 0.19.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: threadkeeper
-Version: 0.19.0
+Version: 0.19.1
 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
@@ -232,7 +232,7 @@ 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>`) |
 
 **Resources** back the genuinely read-only memory views with the same render
@@ -322,6 +322,28 @@ 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 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
+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
@@ -764,15 +786,20 @@ 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. 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
+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.
@@ -874,7 +901,11 @@ a recoverable snapshot under
 `~/.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
@@ -1011,15 +1042,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 +1097,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
@@ -1349,7 +1396,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 |
@@ -1383,7 +1436,7 @@ The most-used env knobs (full list in `threadkeeper/config.py`):
 | `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_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, while foreground/private/unclassified entries use `HUMAN_REVIEW` |
 | `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_SNAPSHOT_RETENTION` | 10 | number of destructive curator pre-mutation snapshots to retain under `<reports_dir>/snapshots`; current pass is always retained |
@@ -1433,6 +1486,7 @@ The most-used env knobs (full list in `threadkeeper/config.py`):
 | `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 |
@@ -1562,6 +1616,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,
@@ -1702,6 +1788,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 +1967,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 +1980,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 +2019,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 +2134,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 +2151,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).