threadkeeper 0.17.7__tar.gz → 0.18.0__tar.gz

{threadkeeper-0.17.7 → threadkeeper-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: threadkeeper
-Version: 0.17.7
+Version: 0.18.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<2,>=1.10.0
+Requires-Dist: mcp<3,>=1.10.0
 Requires-Dist: pydantic>=2.13.4
 Requires-Dist: pydantic-settings>=2.14.2
 Requires-Dist: pyyaml>=6.0.3
@@ -108,6 +108,8 @@ Integrity API provenance from the expected GitHub Trusted Publisher. Dirty or
 diverged git checkouts are skipped rather than overwritten. Restarts are gated
 on install/setup success plus a subprocess import smoke check, so a broken or
 unverified update is recorded but the current server keeps running.
+Interpreters without pip (uv-created or pipx venvs) install through
+`uv pip install --python <interpreter>` when `uv` is available.
 Upstream PyPI publishing is intentionally gated: green merge-to-main builds are
 auto-tagged, but every upload pauses for a human approval on the protected
 `pypi` GitHub Environment (a maintainer-signed annotated `v*` tag remains the
@@ -193,17 +195,19 @@ thread-keeper-setup --dry-run
 | Claude Code | `~/.claude.json` `mcpServers` | `~/.claude/CLAUDE.md` | `~/.claude/settings.json` `hooks` | `~/.claude/projects/**/*.jsonl` |
 | Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` `mcpServers` (macOS); `%APPDATA%\Claude\…` (Win); `~/.config/Claude/…` (Linux) | none (GUI-only) | not supported by the app | none — chats live in Electron IndexedDB |
 | Codex (CLI + desktop) | `~/.codex/config.toml` `[mcp_servers]` (shared between CLI and `Codex.app`) | `~/.codex/AGENTS.md` | not supported | `~/.codex/sessions/**/rollout-*.jsonl` |
-| Antigravity CLI (`agy`) | `~/.gemini/config/mcp_config.json` `mcpServers` | `~/.gemini/config/AGENTS.md` | not wired yet | not yet parsed — sqlite/protobuf under `~/.gemini/antigravity-cli/conversations/*.db` |
+| Antigravity CLI (`agy`) | `~/.gemini/config/mcp_config.json` `mcpServers` | `~/.gemini/config/AGENTS.md` | not wired yet | `~/.gemini/antigravity-cli/conversations/*.db` (sqlite/protobuf, read-only: user prompts and final answers) |
 | Copilot | `~/.copilot/mcp-config.json` `mcpServers` | `~/.copilot/copilot-instructions.md` | `~/.copilot/hooks.json` | `~/.copilot/session-store.db` (sqlite) |
 | VS Code | `~/Library/Application Support/Code/User/mcp.json` `servers` (macOS); `%APPDATA%\Code\User\mcp.json` (Win); `~/.config/Code/User/mcp.json` (Linux) | none (per-workspace only) | not supported | none — extensions own their history |
 
 Every CLI that produces parseable transcripts feeds the same
 `dialog_messages` table with a `source` tag, so `dialog_search()` finds
-matches regardless of where the conversation happened. Claude Desktop,
-Antigravity CLI, and the VS Code adapter are the exceptions — MCP registration
-only; their chats don't reach the table for now (Electron IndexedDB on the
-Claude Desktop side; sqlite/protobuf on the Antigravity side; per-extension
-stores on the VS Code side).
+matches regardless of where the conversation happened. Claude Desktop and
+the VS Code adapter are the exceptions — MCP registration only; their chats
+don't reach the table for now (Electron IndexedDB on the Claude Desktop side;
+per-extension stores on the VS Code side). Antigravity keeps one SQLite file
+per conversation with protobuf step payloads; thread-keeper opens it read-only
+(never creating WAL sidecars next to it) and keeps only user prompts and final
+model answers, skipping tool calls and thinking.
 
 VS Code's user-level `mcp.json` is the central host that **every
 MCP-aware VS Code extension** consumes — GitHub Copilot Chat, the
@@ -213,6 +217,14 @@ Cline, … — so a single registration there reaches all of them at once.
 Adding a new CLI = one file under `threadkeeper/adapters/` implementing
 the `CLIAdapter` contract. See [CONTRIBUTING.md](CONTRIBUTING.md).
 
+### Python MCP SDK compatibility
+
+thread-keeper supports MCP Python SDK 1.x and 2.x (`mcp>=1.10.0,<3`). Fresh
+installs resolve 2.x. A small internal adapter uses the SDK 2.x `MCPServer`
+name and falls back to its SDK 1.x `FastMCP` predecessor, so tools, resources,
+prompts, annotations, structured content, elicitation, and stdio behavior keep
+the same public contract across both supported SDK majors.
+
 ### MCP primitives (tools, resources, prompts, elicitation)
 
 MCP has three server primitives. thread-keeper uses all three, mapped to the
@@ -309,9 +321,10 @@ task row so dead children stop counting against the cap. Admission control
 refuses a new spawn that would exceed `THREADKEEPER_SPAWN_BUDGET_MB`
 (3 GB default). Slim children that need semantic search delegate to the parent
 via `search_via_parent` — no per-child copy of the embedding model. Admission
-uses a SQLite `BEGIN IMMEDIATE` reservation: `spawn()` re-checks the budget and
-inserts the child task row with its RSS estimate before `Popen`, so two
-concurrent spawns cannot both squeeze through the cap.
+uses a short SQLite `BEGIN IMMEDIATE` reservation: `spawn()` re-checks the
+budget and commits the child task row with its RSS estimate before `Popen`, so
+two concurrent spawns cannot both squeeze through the cap, and no write lock is
+held while the child launches.
 
 When `cwd` is inside a Git checkout, `spawn()` also requires the source
 checkout's tracked files to be clean, then starts the child from a unique
@@ -319,6 +332,15 @@ branch/worktree under `THREADKEEPER_TASK_LOG_DIR/worktrees/`. Parallel children
 therefore never share a mutable checkout or Git index. Non-Git directories keep
 their existing behavior; a dirty Git checkout is refused before a child starts.
 
+Learning-loop children that name no `cwd` (Curator, shadow review, candidate
+and dialectic review, probes, panels, the archivist) start in the owner-only
+`<db dir>/workspace` directory instead of the spawning process's working
+directory. The daemon host keeps the directory of whichever session started it,
+so these children used to run inside an unrelated user project, and a dirty Git
+checkout there refused every loop spawn. Foreground spawns keep the caller's
+directory, and callers that pass `cwd` (the Evolve reviewer and applier) are
+unchanged.
+
 The spawn wrapper also records each completed child's `duration_s`,
 `tokens_in`, `tokens_out`, `tokens_total`, and `cost_usd` when the underlying
 CLI emits a recognizable usage trailer. Optional daily ceilings
@@ -535,7 +557,7 @@ shows agents focused on their primary task rarely do).
 | 2 | shadow_review daemon | every 15 min (env knob) | recent `dialog_messages` window | SKILL.md, lessons.md |
 | 3 | extract daemon | every 10 min (env knob) | recent `dialog_messages` window | `extract_candidates` pending queue |
 | 4 | candidate-reviewer daemon | every 1 h (env knob) | pending candidates queue | SKILL.md (create/patch) / notes / verbatim / reject |
-| 5 | Curator daemon | every 7 days (env knob) | every existing lesson + recently-touched skill | `REPORT-<date>.md`; Evolve applier applies it after roadmap issues |
+| 5 | Curator daemon | every 7 days (env knob) | every existing lesson + recently-touched skill | pass-scoped research handoffs and `REPORT-<date>.md`; Evolve applier applies reports after roadmap issues |
 | 6 | evolve_reviewer daemon | configurable (env knob; 0=off) | code/docs/issues; web research in a separate read-only phase (#79) | roadmap updates + GitHub issues |
 | 7 | evolve_applier daemon | configurable (env knob; 0=off) | open GitHub issues, Curator reports, legacy promoted evolve suggestions | PRs + applied markers |
 | 8 | dialectic_miner daemon | configurable (env knob; 0=off) | recent `dialog_messages` — user replies + preceding-assistant context | `dialectic_observations` buffer |
@@ -626,6 +648,15 @@ slugs (semantic, with a lexical fallback). Shadow and candidate reviewers use
 that preflight to patch/consolidate an incumbent or add a `[[slug]]` cross-link
 to a related, distinct lesson while its body is still editable.
 
+When the dialog shows a rule being broken again although a lesson already
+covers it, the reviewers call `lesson_violation(slug, evidence)` instead of
+writing a duplicate. One conversation counts once per lesson per day; at
+`THREADKEEPER_LESSON_VIOLATION_THRESHOLD` (3) violations inside
+`THREADKEEPER_LESSON_VIOLATION_WINDOW_DAYS` (90) the lesson is
+memory-insufficient: `mp_dashboard` lists it and the Curator inventory marks it
+`[MEMORY-INSUFFICIENT]` and recommends escalating the rule to a PreToolUse-style
+hook or other hard guard.
+
 #### 3. Extract daemon
 
 Every `THREADKEEPER_EXTRACT_INTERVAL_S` seconds (default off, 600 =
@@ -709,10 +740,12 @@ 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. The child reads every
+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 numbered per-skill verdicts to
+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/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.
@@ -744,25 +777,59 @@ have increased its patch counter. Patches are maintenance activity, not proof
 that a foreground user or agent consulted the skill.
 
 Before spawning, the scheduler hashes lessons, concepts, skill bodies, support
-trees, validators, and mirror state. Repeated manual calls over identical bytes
-return `unchanged_inventory`; the scheduled three-day pass still runs because
-CLI behavior, official guidance, and external alternatives can change without
-local file changes. `curator_review_status()` shows the inventory hash plus the
-latest report, deterministic audit manifest, recovery snapshot, last endorsed
-`inventory_sha256`, and the current inventory hash. Spawned pass events record
-`entries`, `batches`, `batch_entries`, and `max_batch_chars`, making partial or
-large reviews visible in the normal `curator_pass` trail.
-
-Each report path is explicitly authorized in a parent-authored `curator_pass`
-event before its child is launched. `curator_report_write` only accepts that
-exact path from the spawned Curator carrying the matching pass ID, then records
-the persisted report's SHA-256 in `curator_report_provenance`. This makes the
-report directory an untrusted transport: a stray or forged `REPORT-*.md` file
-cannot acquire the provenance needed by the applier.
-
-Curator applies its own PATCH / PRUNE / CONSOLIDATE directly by default (it
-writes the REPORT first, then mutates — `lesson_remove` is in its toolset so it
-can actually prune and consolidate duplicate lessons). Set
+trees, validators, and mirror state. It then persists a pass manifest with the
+expected reports and the rendered text of every batch before launching any
+child. A dispatch is not completion: every batch must exit successfully and
+have a final, matching provenance record before the inventory is endorsed.
+Repeated manual calls over identical bytes return `unchanged_inventory` only
+after that endorsement; scheduled passes still run because CLI behavior,
+official guidance, and external alternatives can change without local file
+changes. Every required inventory source (lessons, skill telemetry, skill
+files, and concepts) must read successfully before a pass is created; a
+successfully empty source remains valid, while a failed one records
+`inventory_error source=<source> error=<type>` without authorizing a report,
+creating a recovery snapshot, or launching a child.
+
+A pass keeps reviewing the batches it froze even when the live inventory
+changes, and resuming it never re-reads the inventory. Failed and timed-out
+batches are retried without redispatching completed work, up to three launched
+attempts per batch; a spawn memory or spend-budget refusal leaves the batch
+waiting without using an attempt (a spend-cap refusal also alerts). A pass
+whose batch exhausts its attempts, or that outlives two Curator intervals
+(at least six hours), is abandoned so the next due tick starts fresh.
+`THREADKEEPER_CURATOR_MAX_CONCURRENT_BATCHES` (default `1`) bounds one pass's
+live children while normal spawn admission still enforces the shared RSS
+budget. While a pass is active, the daemon polls it every
+`THREADKEEPER_CURATOR_BATCH_POLL_S` seconds (default `60`) instead of waiting
+for the next full Curator interval. `curator_review_status()` and the Curator
+row in `agent_status` expose expected, running, failed, complete, and
+unapplied batch counts alongside the inventory hash, reports, audit manifest,
+and recovery snapshot.
+
+Each research handoff path is explicitly authorized for one pass, inventory
+fingerprint, manifest digest, and batch before its web-enabled child is
+launched. `curator_research_write` accepts only that destination from a spawned
+`curator_researcher` child carrying the matching pass ID, and records the final
+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
+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.
+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`.
+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
 `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
@@ -803,11 +870,13 @@ or `skill_manage(action='restore', name=...)`. Trash retention is bounded by
 `THREADKEEPER_CURATOR_TRASH_TTL_DAYS` (30 days by default) and swept on new
 trash writes. Advisory mode does not write snapshots. The existing Evolve
 applier is
-also the Curator apply worker: after the roadmap issue queue is empty, it looks
-for the latest complete Curator report (`CURATOR_PASS_COMPLETE`) whose path and
-current SHA-256 match an unapplied `curator_report_provenance` event, then
-spawns an `evolve_applier` child to apply only safe, still-current memory
-maintenance through `lesson_append` / `lesson_patch` / `lesson_remove` / `skill_manage` /
+also the Curator apply worker: after the roadmap issue queue is empty, it
+enumerates every complete, unapplied report in the oldest endorsed Curator pass
+(`CURATOR_PASS_COMPLETE`) whose path and current SHA-256 match an unapplied
+`curator_report_provenance` event, then spawns an `evolve_applier` child to
+apply only safe, still-current memory
+maintenance through `lesson_append` / `lesson_patch` / `lesson_remove` /
+`skill_manage` /
 `concept_manage`. It never touches `[PROTECTED]`,
 foreground/user, pinned, or validated entries. Only after the child finishes
 does it call `evolve_mark_curator_report_applied(...)` with the verified hash;
@@ -889,8 +958,18 @@ shell/`bypassPermissions` to the same child:
 
 A full research → audit cycle therefore spans two due passes.
 
-Before a privileged audit can create more issues, the parent counts open,
-not-yet-applied roadmap work with a paginated GitHub REST read. At
+Privileged reviewer and applier launches use private server-owned launchers.
+The public `spawn()` tool refuses `permission_mode="bypassPermissions"` even if
+a caller supplies Evolve-looking role or provenance metadata; only the explicit
+`THREADKEEPER_ALLOW_BYPASS_PERMISSIONS_SPAWN=1` operator override opens that
+mode for public calls.
+
+Before a privileged audit can create more issues, the parent counts only open,
+not-yet-applied issues carrying the deliberate `roadmap` label with a paginated
+GitHub REST read. Issues without that label do not consume the reviewer cap.
+Roadmap issues with an applier skip label or an untrusted author still count:
+those gates stop autonomous pickup, not the reviewer's view of intended roadmap
+work. At
 `THREADKEEPER_EVOLVE_REVIEW_BACKLOG_MAX` (default 25), it withholds that audit
 and records `backlog_saturated open=<n> cap=<max>` on the
 `evolve_review_pass` event; set the knob to `0` to opt out. The read-only
@@ -1014,19 +1093,24 @@ which bypasses the gate as explicit promotion. This removes the untrusted input
 at the boundary and complements the in-prompt data-fencing of #22/#76. The
 public claim comment also carries only an opaque per-host token (a 6-char hash
 of the hostname), never the raw hostname/PID/git-rev; the full host identity is
-recorded in the local event log for multi-host triage.
-
-**Privilege + public-body guard (#22).** Stored evolve suggestions and external
+recorded in the local event log for multi-host triage. A visible claim marker is
+also not a bearer token: the claim lock accepts it only when the comment's
+GitHub `author_association` is in that trusted association set, or when its
+author login is listed in `THREADKEEPER_EVOLVE_CLAIM_AUTOMATION_ACTORS`. Missing
+author metadata and untrusted marker comments remain visible on GitHub but do
+not block roadmap work or affect claim-race resolution.
+
+**Privilege + public-body guard.** Stored evolve suggestions and external
 GitHub issue bodies are wrapped in explicit data fences before a privileged
-child sees them. The exposed `spawn()` tool refuses
-`permission_mode="bypassPermissions"` unless the request comes from the evolve
-daemon role/write-origin pairs (`evolve_reviewer`/`evolve`,
-`evolve_applier`/`evolve_apply`) or the operator explicitly opts in with
-`THREADKEEPER_ALLOW_BYPASS_PERMISSIONS_SPAWN=1`. Privileged evolve children also
-get a PATH-prepended `gh` wrapper that scrubs `gh issue create`, `gh issue
-comment`, and `gh pr create` bodies before the real GitHub CLI sees them:
-home-directory paths and common token shapes are redacted, and a body is
-refused if a known unsafe pattern remains.
+child sees them. The public `spawn()` tool refuses
+`permission_mode="bypassPermissions"` regardless of caller-supplied role or
+provenance metadata; privileged Evolve launches use private server-owned
+capabilities, and public calls need the explicit
+`THREADKEEPER_ALLOW_BYPASS_PERMISSIONS_SPAWN=1` operator override. Privileged
+Evolve children also get a PATH-prepended `gh` wrapper that scrubs `gh issue
+create`, `gh issue comment`, and `gh pr create` bodies before the real GitHub
+CLI sees them: home-directory paths and common token shapes are redacted, and a
+body is refused if a known unsafe pattern remains.
 
 Fallback/manual paths remain:
 
@@ -1090,7 +1174,9 @@ Three detection sources per tick:
 
 1. **Admission failures / terminal timeouts** — a `<loop>_pass` event whose
    summary is a spawn/budget failure (e.g. `token_budget_exceeded`,
-   `claude_cli_not_found`), plus `spawn_timeout_retry_failed`.
+   `claude_cli_not_found`), plus `spawn_timeout_retry_failed`. A budget
+   refusal names the local cap that refused the child — the spawn memory
+   budget or the daily token/cost budget — not the CLI subscription.
 2. **Dead children** — a `tasks` row that ended with a non-zero, non-timeout
    return code. This is the important one: `spawn()` returns `ok task=…` at
    *launch*, so a `*_pass` summary is a false success when a child later dies
@@ -1140,7 +1226,11 @@ category off silences the banner without hiding the history. Each materializatio
 uses its own skill or lesson toggle; generic task reports are history-only.
 Foreground writes appear too, without waiting for a background child to finish.
 A pathless skill mark only silences its reminder and has no materialization
-banner. Enabling a toggle never replays backlog.
+banner. Enabling a toggle never replays backlog. Child-log excerpts and spawn
+error reasons in both lists are bounded sanitized summaries: credential-shaped
+values and private home paths are redacted before they reach the MCP status
+response, menu, or notification; raw logs remain available only through
+`task_logs`.
 
 **Settings in the app.** The menu-bar app's **Settings ▸ Notifications** tab
 edits these same `THREADKEEPER_NOTIFY_*` keys visually — switches for the
@@ -1197,9 +1287,9 @@ claim earned trust. Thresholds:
 
 All multilingual regex and prompt fragments live in
 `threadkeeper/i18n.py` — the rest of the codebase stays English-only.
-Currently ships ten locales: **English, Mandarin Chinese, Hindi,
-Spanish, Portuguese, French, German, Arabic, Russian, Japanese**
-(~82 % of the world's speakers).
+Currently ships twelve locales: **English, Mandarin Chinese, Hindi,
+Spanish, Portuguese (Brazilian and European), French, German, Arabic,
+Russian, Japanese, Korean, Bengali**.
 
 Adding a new language is a two-file PR — see [CONTRIBUTING.md](CONTRIBUTING.md).
 
@@ -1248,10 +1338,14 @@ The most-used env knobs (full list in `threadkeeper/config.py`):
 | `THREADKEEPER_CANDIDATE_REVIEW_INTERVAL_S` | 0 (off) | candidate-reviewer daemon tick (s), restart-throttled by the last `candidate_review_pass`; 3600 = 1h recommended |
 | `THREADKEEPER_CANDIDATE_REVIEW_MIN` | 3 | min pending candidates before reviewer engages |
 | `THREADKEEPER_CANDIDATE_REVIEW_FLUSH_AGE_S` | 259200 | age-flush: an undersized pending queue is still reviewed once its oldest candidate is this old (0 = threshold only) |
+| `THREADKEEPER_LESSON_VIOLATION_THRESHOLD` | 3 | violations of one lesson inside the window that make it memory-insufficient (recommend a hook) |
+| `THREADKEEPER_LESSON_VIOLATION_WINDOW_DAYS` | 90 | window for counting `lesson_violation` records |
+| `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_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_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 |
@@ -1259,7 +1353,7 @@ The most-used env knobs (full list in `threadkeeper/config.py`):
 | `THREADKEEPER_PROBE_INTERVAL_S` | 0 (off) | probe daemon tick (s); 1800 = 30 min recommended so finished probe answers are graded promptly |
 | `THREADKEEPER_PROBE_COOLDOWN_S` | 604800 | per-category probe cooldown; 86400 = 1d recommended for active reliability tracking |
 | `THREADKEEPER_SPAWN_BUDGET_MB` | 3072 | combined child RSS cap (MB); 0 disables |
-| `THREADKEEPER_ALLOW_BYPASS_PERMISSIONS_SPAWN` | "" (off) | explicit override that lets ordinary `spawn()` calls request `permission_mode="bypassPermissions"`; default off means only evolve daemon role/write-origin pairs can use the dangerous mode |
+| `THREADKEEPER_ALLOW_BYPASS_PERMISSIONS_SPAWN` | "" (off) | explicit operator override that lets public `spawn()` calls request `permission_mode="bypassPermissions"`; otherwise only private server-owned Evolve launchers can use it |
 | `THREADKEEPER_SPAWN_TOKEN_BUDGET` | 0 | recorded 24h spawned-child token ceiling; 0 disables |
 | `THREADKEEPER_SPAWN_COST_BUDGET_USD` | 0 | recorded 24h spawned-child dollar ceiling; 0 disables |
 | `THREADKEEPER_SPAWN_MAX_RUNTIME_S` | 3600 | wall-clock lifetime cap (s) for a spawned child; over-cap live children are SIGTERM→SIGKILL'd and closed with `return_code` 124; 0 disables |
@@ -1296,7 +1390,7 @@ The most-used env knobs (full list in `threadkeeper/config.py`):
 | `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 issues before the issue-creating audit is skipped and records `backlog_saturated`; `0` disables the cap |
+| `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_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 |
@@ -1307,6 +1401,7 @@ The most-used env knobs (full list in `threadkeeper/config.py`):
 | `THREADKEEPER_EVOLVE_REPO_PROVISION_LOCK_TIMEOUT_S` | 5 | maximum seconds to wait for another clone/venv provisioning operation before returning `ERR evolve_repo_provisioning_in_progress retry_later=1`; `0` is immediate |
 | `THREADKEEPER_EVOLVE_APPLY_SKIP_LABELS` | `blocked,needs-design,wontfix,question,discussion,help wanted` | comma-separated labels that exclude GitHub issues from autonomous Evolve applier pickup. Exact-number apply returns `skipped: label X`; set to `off` to clear |
 | `THREADKEEPER_EVOLVE_TRUSTED_AUTHOR_ASSOCIATIONS` | `OWNER,MEMBER,COLLABORATOR` | comma-separated GitHub author associations eligible for **autonomous** issue pickup on this public repo; issues from other authors are skipped unless promoted (trust label or exact-number invocation) |
+| `THREADKEEPER_EVOLVE_CLAIM_AUTOMATION_ACTORS` | (empty) | comma-separated GitHub logins allowed to own visible Evolve claim comments without a trusted repository association; all other marker comments are advisory text only |
 | `THREADKEEPER_EVOLVE_TRUST_LABELS` | (empty) | comma-separated labels that promote an untrusted-author issue into the autonomous queue; on a public repo only collaborators can apply labels, so a trust label is a maintainer endorsement |
 | `THREADKEEPER_ROADMAP_ISSUE_MAX_ATTEMPTS` | 3 | poison-issue dead-letter cap: after this many implementer spawns for a roadmap issue with no resulting PR, the issue gets a `blocked` label + one summary comment and is excluded from the auto-drain until a human intervenes. A manual `evolve_apply_roadmap_issue(issue_number=N)` bypasses the cap, but the default skip-label gate still refuses the `blocked` label until it is removed or reconfigured |
 | `THREADKEEPER_ROADMAP_ISSUE_BACKOFF_BASE_S` | 172800 (2d) | base failure-backoff window for a roadmap issue; doubles per attempt (`base * 2^(attempts-1)`, capped at 30d). Defers re-selection of a repeatedly-aborting issue beyond the fixed 24h claim TTL |
@@ -1491,8 +1586,10 @@ hardening, WAL/schema migration, and vec-table setup once per process.
 `PRAGMA query_only=ON`, so retrieval cannot accidentally migrate, heartbeat,
 or write. `run_write()` opens a fresh connection, acquires `BEGIN IMMEDIATE`,
 runs a DB-only callback, and closes it; only `SQLITE_BUSY`/`SQLITE_LOCKED` are
-retried with bounded jitter. `get_db()` remains a compatibility API for older
-low-level call sites.
+retried with bounded jitter, including a lock hit while the connection is being
+set up. `get_db()` remains a compatibility API for older low-level call sites;
+its connections are tracked, and the daemon host logs the call site of any
+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
@@ -1827,8 +1924,8 @@ pip install -e '.[semantic,dev]'
 python -m pytest
 ```
 
-869 tests passing on Python 3.11 / 3.12 / 3.13 (1 skipped). CI runs
-the suite and a resolved-dependency `pip-audit` gate on every push and PR.
+The suite runs on Python 3.11 / 3.12 / 3.13. CI runs it, together with a
+resolved-dependency `pip-audit` gate, on every push and PR.
 CodeQL scans the Python source on those changes and weekly; see
 [SECURITY.md](SECURITY.md#continuous-security-scanning) for the exception
 process and reporting policy.
@@ -1840,7 +1937,7 @@ process and reporting policy.
 ```
 threadkeeper/
 ├── server.py             # MCP entry: python -m threadkeeper.server
-├── _mcp.py               # FastMCP singleton + read_tool()/write_tool() annotation wrappers
+├── _mcp.py               # MCPServer singleton + read_tool()/write_tool() annotation wrappers
 ├── tool_schemas.py       # typed outputSchema models for the structured status tools
 ├── _setup.py             # `thread-keeper-setup` installer
 ├── config.py             # env-driven defaults
@@ -1851,7 +1948,7 @@ threadkeeper/
 ├── eval/                 # offline learning-loop decision-quality harness (python -m threadkeeper.eval)
 ├── brief.py              # render_brief / render_context
 ├── shadow_review.py      # autonomous learning observer
-├── i18n.py               # 10 locales of regex + prompt bundles
+├── i18n.py               # 12 locales of regex + prompt bundles
 ├── adapters/             # one file per supported CLI
 │   ├── claude_code.py
 │   ├── claude_desktop.py
@@ -1859,7 +1956,7 @@ threadkeeper/
 │   ├── antigravity.py
 │   ├── copilot.py
 │   └── vscode.py
-└── tools/                # @read_tool()/@write_tool() entries — 120 of them
+└── tools/                # registered @read_tool()/@write_tool() entries
     ├── threads.py
     ├── peers.py
     ├── spawn.py
@@ -1871,14 +1968,14 @@ threadkeeper/
 
 **Tool annotation contract (#67).** Every tool registers through
 `@read_tool()` or `@write_tool(destructive=…, idempotent=…)` (in `_mcp.py`),
-so `tools/list` carries MCP 2025-06-18 `ToolAnnotations` for all 113 tools:
-`readOnlyHint=True` for pure reads (`brief`, `context`, `search`,
+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
-writes because they bump lesson access counters. The ten 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
-warrant a prompt. The five status tools (`context`, `spawn_budget_status`,
+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
+warrant a prompt. The status tools (`context`, `spawn_budget_status`,
 `spawn_status`, `mp_health`, `agent_status`) additionally advertise an
 `outputSchema` and return `structuredContent` alongside the legacy text
 block. The contract is enforced by `tests/test_tool_annotations.py`.