threadkeeper 0.8.1__tar.gz → 0.9.1__tar.gz

{threadkeeper-0.8.1 → threadkeeper-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: threadkeeper
-Version: 0.8.1
+Version: 0.9.1
 Summary: Multi-agent shared brain across Claude Code/Desktop, Codex, Gemini, Copilot, VS Code. Cross-session memory, self-improving skill loops, inter-agent signaling — one local MCP server.
 Author: thread-keeper contributors
 License: MIT
@@ -23,6 +23,8 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2
+Requires-Dist: pydantic-settings>=2
 Provides-Extra: semantic
 Requires-Dist: fastembed>=0.3; extra == "semantic"
 Requires-Dist: numpy>=1.24.0; extra == "semantic"
@@ -198,6 +200,36 @@ 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.
 
+`tk-agent-status` exposes autonomous learning loop status as structured JSON
+or compact text for external monitors:
+
+```sh
+tk-agent-status
+tk-agent-status --json
+```
+
+`apps/macos-agent-status/` contains a small macOS menu-bar app that polls this
+command every 5 seconds and shows every autonomous learning loop: enabled/off,
+running/idle/ready, last pass, backlog, and active child RSS when that loop has
+spawned a worker. Active loops are sorted first (`running`, then `ready`), so
+background work stays at the top of the panel. The app also requests macOS
+notification permission and sends a notification when a newly completed
+autonomous child task produces a useful result in `recent_results`; the first
+poll only marks existing results as seen, so old completions do not spam
+notifications. Probe backlog is due objective probes only, not every registered
+probe, so a healthy cooldown shows `0 due probes` instead of looking stuck. On
+macOS, `python -m threadkeeper.server` automatically installs and launches it
+on MCP startup. Set `THREADKEEPER_MENUBAR_AUTO_LAUNCH=0` to disable that
+behavior.
+
+Manual fallback:
+
+```sh
+cd apps/macos-agent-status
+./build.sh
+open build/ThreadKeeperAgentStatus.app
+```
+
 ### Learning loops
 
 Five loops turn raw agent dialog into a curated, multi-CLI-mirrored
@@ -252,7 +284,9 @@ 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 (advisory) or direct PATCH/PRUNE/CONSOLIDATE |
+| 5 | Curator daemon | every 7 days (env knob) | every existing lesson + recently-touched skill | REPORT-`<date>`.md; Evolve applier applies the latest complete report |
+| 6 | dialectic_miner daemon | configurable (env knob; 0=off) | recent `dialog_messages` — user replies + preceding-assistant context | `dialectic_observations` buffer |
+| 7 | dialectic_validator daemon | configurable (env knob; 0=off) | buffered `dialectic_observations` | dialectic claims + evidence (support / contradict / supersede) via spawned opus child |
 
 All five write into the universal Skill format (`SKILL.md` under each
 known/configured skills root — `~/.claude/skills/`, `~/.codex/skills/`,
@@ -291,6 +325,10 @@ marked as spawned/background processes, so they cannot start their own shadow
 daemon even if a CLI drops the no-embeddings env. Idempotent through
 `events.kind='shadow_review_pass'`.
 
+Before writing memory, the observer now checks existing lessons/skills and
+prefers patching broad skills. Shadow-origin `lesson_append` is a compact
+fallback only: oversized bodies and near-duplicate slugs are rejected.
+
 #### 3. Extract daemon
 
 Every `THREADKEEPER_EXTRACT_INTERVAL_S` seconds (default off, 600 =
@@ -327,7 +365,10 @@ Hard limits: max 2 new skills per pass, `[PROTECTED]` (pinned +
 foreground-authored) skills off-limits. Closes the gap between
 heuristic harvest and SKILL.md materialization — previously pending
 candidates accumulated indefinitely waiting for an agent to call
-`accept_candidate()` manually.
+`accept_candidate()` manually. The loop is machine-wide single-flight:
+while one reviewer child is running, other foreground servers/ticks report
+`candidate_review_running` instead of spawning another child for the same
+queue.
 
 #### 5. Autonomous Curator
 
@@ -339,9 +380,57 @@ CONSOLIDATE / PRUNE recommendations. Pinned and foreground-authored
 entries are marked `[PROTECTED]` in the inventory so the curator
 never proposes destructive changes against them.
 
-Phase 1 is advisory-only (REPORT only); flip
-`THREADKEEPER_CURATOR_DESTRUCTIVE=1` once trust builds to let the
-child apply its own recommendations directly.
+Curator itself stays advisory-only by default. The existing Evolve applier is
+the apply worker: on its next pass it first looks for the latest complete
+Curator report (`CURATOR_PASS_COMPLETE`) that has not been marked applied, then
+spawns an `evolve_applier` child to apply only safe, still-current memory
+maintenance through `lesson_append` / `lesson_remove` / `skill_manage`. It never
+touches `[PROTECTED]`, foreground/user, pinned, or validated entries. Only after
+the child finishes does it call `evolve_mark_curator_report_applied(...)`, which
+prevents replaying the same report.
+
+#### 6. Evolve applier — code evolution + curator report apply
+
+The brief format is not fixed: any session can file a change to it with
+`evolve_format(suggestion, rationale)`. The `evolve_reviewer` daemon triages
+the queue and **promotes** the good ones — promoted suggestions surface in the
+brief with a ★. Until now that's where it stopped: a human had to hand-edit
+`render_brief` in `brief.py`.
+
+`evolve_apply(evolve_id)` closes the loop. It spawns an `evolve_applier` child
+(resolved through the normal spawn role/model config — recommend opus, it
+writes code) that:
+
+1. edits `render_brief()` to implement the suggestion;
+2. adds/extends a **golden brief test** asserting both that the new
+   behavior/field appears *and* that the existing brief sections still render —
+   a format change can't silently break the brief;
+3. runs the full suite (`.venv/bin/python -m pytest -q`) until green;
+4. opens a **pull request** on a feature branch via `gh`, body quoting the
+   suggestion + rationale. The generated commit and PR title use the repo's
+   allowed Conventional Commit types (`feat:`/`fix:` etc.), never the internal
+   `evolve:` label.
+
+**Autonomy is the PR gate, nothing more.** The child never pushes or commits to
+`main` (which has branch protection); a human reviews and merges. On a
+successful PR the child calls `evolve_mark_applied(evolve_id, pr_url)`, which
+sets `applied=1` so the suggestion stops resurfacing. Validation inside the
+child (golden render_brief test + full suite green) is the objective gate the
+loop otherwise lacks.
+
+The same applier role also drains Curator reports. `evolve_apply_curator_report`
+manually applies the latest complete report, or a specific report path. This
+path does **not** edit code or open a PR; it uses memory MCP tools only and
+marks the report applied with `evolve_mark_curator_report_applied(...)`.
+
+Manual: `evolve_apply(#id)` (get ids from `evolve_review()`). Optional daemon:
+set `THREADKEEPER_EVOLVE_APPLY_INTERVAL_S>0` (default 0 = off) to periodically
+apply the latest complete Curator report first, then implement the oldest
+promoted+unapplied suggestion. Pin the agent/model with
+`THREADKEEPER_SPAWN__LOOP__EVOLVE_APPLIER` /
+`THREADKEEPER_SPAWN__MODEL__EVOLVE_APPLIER`. Single-flight (one applier child at
+a time, enforced by a short dispatch file lock plus running-task detection)
+keeps code edits and memory maintenance from colliding.
 
 #### Honest take
 
@@ -430,7 +519,10 @@ The most-used env knobs (full list in `threadkeeper/config.py`):
 | `THREADKEEPER_CURATOR_INTERVAL_S` | 0 (off) | curator daemon tick (s); 604800 = 7d recommended |
 | `THREADKEEPER_CURATOR_MIN_LESSONS` | 3 | min lessons before curator engages |
 | `THREADKEEPER_CURATOR_DESTRUCTIVE` | "" (advisory) | when "1": curator child applies its own PATCH/PRUNE/CONSOLIDATE directly instead of writing advisory REPORT only |
+| `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_MENUBAR_AUTO_LAUNCH` | true | macOS: auto install/launch status menu-bar app on MCP startup |
 | `THREADKEEPER_MEMORY_GUARD_POLL_S` | 30 | server RSS guard tick (s); 0 disables |
 | `THREADKEEPER_MEMORY_GUARD_WARN_MB` | 1536 | notify/log when a server crosses this RSS |
 | `THREADKEEPER_MEMORY_GUARD_KILL_MB` | 3072 | SIGTERM server above this RSS; 0 disables killing |
@@ -447,9 +539,17 @@ The most-used env knobs (full list in `threadkeeper/config.py`):
 | `THREADKEEPER_EMBED_MODEL` | `paraphrase-multilingual-MiniLM-L12-v2` | 384-dim cross-lingual embedding model |
 | `THREADKEEPER_SPAWNED_CHILD` | "" | spawn-internal marker; disables autonomous daemons in children |
 | `THREADKEEPER_SKILL_NUDGE_INTERVAL` | 10 | events between `skill_hint` nudges |
-
-Persist them via `~/.claude/settings.json`'s `env` block (Claude Code) or
-the equivalent env section in each CLI's config. Hot-config reload is
+| `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_DIALECTIC_VALIDATE_MIN` | 5 | min buffered observations before validator engages |
+| `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); triages the format-evolution queue (promote/dismiss) |
+| `THREADKEEPER_EVOLVE_APPLY_INTERVAL_S` | 0 (off) | evolve-applier daemon tick (s); applies latest complete Curator report first, then oldest promoted+unapplied suggestion behind a PR. Manual `evolve_apply` / `evolve_apply_curator_report` work regardless |
+| `THREADKEEPER_DIALECTIC_MAX_NEW_CLAIMS` | 3 | max new dialectic claims the validator may create per pass |
+
+Persist them in `~/.threadkeeper/.env` (copy from `.env.example`) — one file,
+read via pydantic-settings; real environment variables still override it.
+Hot-config reload is
 [tracked](https://github.com/po4erk91/thread-keeper/issues/2).
 
 ### Per-loop agent dispatch
@@ -460,36 +560,27 @@ Codex spawn, etc. Detection: process-tree walk at startup, cached for
 the server lifetime. The MCP tool `spawn_status()` shows the live
 resolution table.
 
-Override per role via `~/.threadkeeper/spawn.toml`:
-
-```toml
-[default]
-agent = "auto"     # "auto" = use active CLI (default)
-
-[loops]
-# Force specific roles to specific CLIs regardless of active host
-shadow_observer    = "claude"   # heaviest reasoning → keep on Claude
-curator            = "codex"    # weekly audit → Codex is fine
-candidate_reviewer = "auto"     # follow active CLI
-archivist          = "claude"   # close_thread auto-review
-extract            = "auto"     # this one is local (no spawn)
-
-[models]
-# Optional per-CLI model pin — overrides each CLI's own default
-claude = "opus"
-codex  = "gpt-5.4"
-gemini = "gemini-2.5-pro"
-```
-
-Or via env (highest priority, overrides the TOML):
+Override per role in `~/.threadkeeper/.env` (there is no longer a `spawn.toml` —
+all config lives in the one `.env`). Spawn routing uses nested `__` keys; dict
+keys are lowercased:
 
 ```bash
-export THREADKEEPER_SPAWN_DEFAULT=codex                 # global default
-export THREADKEEPER_SPAWN_LOOP_CURATOR=gemini           # per-role
-export THREADKEEPER_SPAWN_MODEL_CLAUDE=opus             # per-CLI model
-export THREADKEEPER_ACTIVE_CLI=claude                   # force detection
+# default agent for roles with no explicit pin ("" / unset = use the active CLI)
+THREADKEEPER_SPAWN__DEFAULT=claude
+# per-role CLI:  THREADKEEPER_SPAWN__LOOP__<ROLE>=<cli>
+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
+# model pin per CLI or per role:  THREADKEEPER_SPAWN__MODEL__<KEY>=<model>
+THREADKEEPER_SPAWN__MODEL__CLAUDE=opus
+THREADKEEPER_SPAWN__MODEL__DIALECTIC_VALIDATOR=opus
 ```
 
+Resolution per role: `SPAWN__LOOP__<role>` → `SPAWN__DEFAULT` → active CLI →
+`claude`; `"auto"` (or unset) defers to the active CLI. Real environment
+variables override the `.env`. Force host detection with
+`THREADKEEPER_ACTIVE_CLI=claude`. See `.env.example` for the full knob list.
+
 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.
@@ -534,6 +625,13 @@ them with `dry_run=False` to apply:
   a loop firing constantly while its outcomes stay flat, or a queue
   backing up. Complements the per-loop `*_status` tools (`mp_health`,
   `spawn_budget_status`, `shadow_review_status`).
+- **`agent_status(json_output=False, refresh=True)`** — autonomous learning
+  loop status, shaped for UI clients. Shows every loop's enabled/running/ready
+  state, last pass, backlog, and active spawned-child RSS; running child agents
+  are included as detail rows in the JSON. The JSON also includes
+  `recent_results` for useful completed loop tasks, which the macOS menu-bar app
+  uses for notifications. The `tk-agent-status` console command and macOS
+  menu-bar app use the same underlying snapshot.
 
 ---
 

{threadkeeper-0.8.1 → threadkeeper-0.9.1}/README.md

@@ -159,6 +159,36 @@ 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.
 
+`tk-agent-status` exposes autonomous learning loop status as structured JSON
+or compact text for external monitors:
+
+```sh
+tk-agent-status
+tk-agent-status --json
+```
+
+`apps/macos-agent-status/` contains a small macOS menu-bar app that polls this
+command every 5 seconds and shows every autonomous learning loop: enabled/off,
+running/idle/ready, last pass, backlog, and active child RSS when that loop has
+spawned a worker. Active loops are sorted first (`running`, then `ready`), so
+background work stays at the top of the panel. The app also requests macOS
+notification permission and sends a notification when a newly completed
+autonomous child task produces a useful result in `recent_results`; the first
+poll only marks existing results as seen, so old completions do not spam
+notifications. Probe backlog is due objective probes only, not every registered
+probe, so a healthy cooldown shows `0 due probes` instead of looking stuck. On
+macOS, `python -m threadkeeper.server` automatically installs and launches it
+on MCP startup. Set `THREADKEEPER_MENUBAR_AUTO_LAUNCH=0` to disable that
+behavior.
+
+Manual fallback:
+
+```sh
+cd apps/macos-agent-status
+./build.sh
+open build/ThreadKeeperAgentStatus.app
+```
+
 ### Learning loops
 
 Five loops turn raw agent dialog into a curated, multi-CLI-mirrored
@@ -213,7 +243,9 @@ 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 (advisory) or direct PATCH/PRUNE/CONSOLIDATE |
+| 5 | Curator daemon | every 7 days (env knob) | every existing lesson + recently-touched skill | REPORT-`<date>`.md; Evolve applier applies the latest complete report |
+| 6 | dialectic_miner daemon | configurable (env knob; 0=off) | recent `dialog_messages` — user replies + preceding-assistant context | `dialectic_observations` buffer |
+| 7 | dialectic_validator daemon | configurable (env knob; 0=off) | buffered `dialectic_observations` | dialectic claims + evidence (support / contradict / supersede) via spawned opus child |
 
 All five write into the universal Skill format (`SKILL.md` under each
 known/configured skills root — `~/.claude/skills/`, `~/.codex/skills/`,
@@ -252,6 +284,10 @@ marked as spawned/background processes, so they cannot start their own shadow
 daemon even if a CLI drops the no-embeddings env. Idempotent through
 `events.kind='shadow_review_pass'`.
 
+Before writing memory, the observer now checks existing lessons/skills and
+prefers patching broad skills. Shadow-origin `lesson_append` is a compact
+fallback only: oversized bodies and near-duplicate slugs are rejected.
+
 #### 3. Extract daemon
 
 Every `THREADKEEPER_EXTRACT_INTERVAL_S` seconds (default off, 600 =
@@ -288,7 +324,10 @@ Hard limits: max 2 new skills per pass, `[PROTECTED]` (pinned +
 foreground-authored) skills off-limits. Closes the gap between
 heuristic harvest and SKILL.md materialization — previously pending
 candidates accumulated indefinitely waiting for an agent to call
-`accept_candidate()` manually.
+`accept_candidate()` manually. The loop is machine-wide single-flight:
+while one reviewer child is running, other foreground servers/ticks report
+`candidate_review_running` instead of spawning another child for the same
+queue.
 
 #### 5. Autonomous Curator
 
@@ -300,9 +339,57 @@ CONSOLIDATE / PRUNE recommendations. Pinned and foreground-authored
 entries are marked `[PROTECTED]` in the inventory so the curator
 never proposes destructive changes against them.
 
-Phase 1 is advisory-only (REPORT only); flip
-`THREADKEEPER_CURATOR_DESTRUCTIVE=1` once trust builds to let the
-child apply its own recommendations directly.
+Curator itself stays advisory-only by default. The existing Evolve applier is
+the apply worker: on its next pass it first looks for the latest complete
+Curator report (`CURATOR_PASS_COMPLETE`) that has not been marked applied, then
+spawns an `evolve_applier` child to apply only safe, still-current memory
+maintenance through `lesson_append` / `lesson_remove` / `skill_manage`. It never
+touches `[PROTECTED]`, foreground/user, pinned, or validated entries. Only after
+the child finishes does it call `evolve_mark_curator_report_applied(...)`, which
+prevents replaying the same report.
+
+#### 6. Evolve applier — code evolution + curator report apply
+
+The brief format is not fixed: any session can file a change to it with
+`evolve_format(suggestion, rationale)`. The `evolve_reviewer` daemon triages
+the queue and **promotes** the good ones — promoted suggestions surface in the
+brief with a ★. Until now that's where it stopped: a human had to hand-edit
+`render_brief` in `brief.py`.
+
+`evolve_apply(evolve_id)` closes the loop. It spawns an `evolve_applier` child
+(resolved through the normal spawn role/model config — recommend opus, it
+writes code) that:
+
+1. edits `render_brief()` to implement the suggestion;
+2. adds/extends a **golden brief test** asserting both that the new
+   behavior/field appears *and* that the existing brief sections still render —
+   a format change can't silently break the brief;
+3. runs the full suite (`.venv/bin/python -m pytest -q`) until green;
+4. opens a **pull request** on a feature branch via `gh`, body quoting the
+   suggestion + rationale. The generated commit and PR title use the repo's
+   allowed Conventional Commit types (`feat:`/`fix:` etc.), never the internal
+   `evolve:` label.
+
+**Autonomy is the PR gate, nothing more.** The child never pushes or commits to
+`main` (which has branch protection); a human reviews and merges. On a
+successful PR the child calls `evolve_mark_applied(evolve_id, pr_url)`, which
+sets `applied=1` so the suggestion stops resurfacing. Validation inside the
+child (golden render_brief test + full suite green) is the objective gate the
+loop otherwise lacks.
+
+The same applier role also drains Curator reports. `evolve_apply_curator_report`
+manually applies the latest complete report, or a specific report path. This
+path does **not** edit code or open a PR; it uses memory MCP tools only and
+marks the report applied with `evolve_mark_curator_report_applied(...)`.
+
+Manual: `evolve_apply(#id)` (get ids from `evolve_review()`). Optional daemon:
+set `THREADKEEPER_EVOLVE_APPLY_INTERVAL_S>0` (default 0 = off) to periodically
+apply the latest complete Curator report first, then implement the oldest
+promoted+unapplied suggestion. Pin the agent/model with
+`THREADKEEPER_SPAWN__LOOP__EVOLVE_APPLIER` /
+`THREADKEEPER_SPAWN__MODEL__EVOLVE_APPLIER`. Single-flight (one applier child at
+a time, enforced by a short dispatch file lock plus running-task detection)
+keeps code edits and memory maintenance from colliding.
 
 #### Honest take
 
@@ -391,7 +478,10 @@ The most-used env knobs (full list in `threadkeeper/config.py`):
 | `THREADKEEPER_CURATOR_INTERVAL_S` | 0 (off) | curator daemon tick (s); 604800 = 7d recommended |
 | `THREADKEEPER_CURATOR_MIN_LESSONS` | 3 | min lessons before curator engages |
 | `THREADKEEPER_CURATOR_DESTRUCTIVE` | "" (advisory) | when "1": curator child applies its own PATCH/PRUNE/CONSOLIDATE directly instead of writing advisory REPORT only |
+| `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_MENUBAR_AUTO_LAUNCH` | true | macOS: auto install/launch status menu-bar app on MCP startup |
 | `THREADKEEPER_MEMORY_GUARD_POLL_S` | 30 | server RSS guard tick (s); 0 disables |
 | `THREADKEEPER_MEMORY_GUARD_WARN_MB` | 1536 | notify/log when a server crosses this RSS |
 | `THREADKEEPER_MEMORY_GUARD_KILL_MB` | 3072 | SIGTERM server above this RSS; 0 disables killing |
@@ -408,9 +498,17 @@ The most-used env knobs (full list in `threadkeeper/config.py`):
 | `THREADKEEPER_EMBED_MODEL` | `paraphrase-multilingual-MiniLM-L12-v2` | 384-dim cross-lingual embedding model |
 | `THREADKEEPER_SPAWNED_CHILD` | "" | spawn-internal marker; disables autonomous daemons in children |
 | `THREADKEEPER_SKILL_NUDGE_INTERVAL` | 10 | events between `skill_hint` nudges |
-
-Persist them via `~/.claude/settings.json`'s `env` block (Claude Code) or
-the equivalent env section in each CLI's config. Hot-config reload is
+| `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_DIALECTIC_VALIDATE_MIN` | 5 | min buffered observations before validator engages |
+| `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); triages the format-evolution queue (promote/dismiss) |
+| `THREADKEEPER_EVOLVE_APPLY_INTERVAL_S` | 0 (off) | evolve-applier daemon tick (s); applies latest complete Curator report first, then oldest promoted+unapplied suggestion behind a PR. Manual `evolve_apply` / `evolve_apply_curator_report` work regardless |
+| `THREADKEEPER_DIALECTIC_MAX_NEW_CLAIMS` | 3 | max new dialectic claims the validator may create per pass |
+
+Persist them in `~/.threadkeeper/.env` (copy from `.env.example`) — one file,
+read via pydantic-settings; real environment variables still override it.
+Hot-config reload is
 [tracked](https://github.com/po4erk91/thread-keeper/issues/2).
 
 ### Per-loop agent dispatch
@@ -421,36 +519,27 @@ Codex spawn, etc. Detection: process-tree walk at startup, cached for
 the server lifetime. The MCP tool `spawn_status()` shows the live
 resolution table.
 
-Override per role via `~/.threadkeeper/spawn.toml`:
-
-```toml
-[default]
-agent = "auto"     # "auto" = use active CLI (default)
-
-[loops]
-# Force specific roles to specific CLIs regardless of active host
-shadow_observer    = "claude"   # heaviest reasoning → keep on Claude
-curator            = "codex"    # weekly audit → Codex is fine
-candidate_reviewer = "auto"     # follow active CLI
-archivist          = "claude"   # close_thread auto-review
-extract            = "auto"     # this one is local (no spawn)
-
-[models]
-# Optional per-CLI model pin — overrides each CLI's own default
-claude = "opus"
-codex  = "gpt-5.4"
-gemini = "gemini-2.5-pro"
-```
-
-Or via env (highest priority, overrides the TOML):
+Override per role in `~/.threadkeeper/.env` (there is no longer a `spawn.toml` —
+all config lives in the one `.env`). Spawn routing uses nested `__` keys; dict
+keys are lowercased:
 
 ```bash
-export THREADKEEPER_SPAWN_DEFAULT=codex                 # global default
-export THREADKEEPER_SPAWN_LOOP_CURATOR=gemini           # per-role
-export THREADKEEPER_SPAWN_MODEL_CLAUDE=opus             # per-CLI model
-export THREADKEEPER_ACTIVE_CLI=claude                   # force detection
+# default agent for roles with no explicit pin ("" / unset = use the active CLI)
+THREADKEEPER_SPAWN__DEFAULT=claude
+# per-role CLI:  THREADKEEPER_SPAWN__LOOP__<ROLE>=<cli>
+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
+# model pin per CLI or per role:  THREADKEEPER_SPAWN__MODEL__<KEY>=<model>
+THREADKEEPER_SPAWN__MODEL__CLAUDE=opus
+THREADKEEPER_SPAWN__MODEL__DIALECTIC_VALIDATOR=opus
 ```
 
+Resolution per role: `SPAWN__LOOP__<role>` → `SPAWN__DEFAULT` → active CLI →
+`claude`; `"auto"` (or unset) defers to the active CLI. Real environment
+variables override the `.env`. Force host detection with
+`THREADKEEPER_ACTIVE_CLI=claude`. See `.env.example` for the full knob list.
+
 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.
@@ -495,6 +584,13 @@ them with `dry_run=False` to apply:
   a loop firing constantly while its outcomes stay flat, or a queue
   backing up. Complements the per-loop `*_status` tools (`mp_health`,
   `spawn_budget_status`, `shadow_review_status`).
+- **`agent_status(json_output=False, refresh=True)`** — autonomous learning
+  loop status, shaped for UI clients. Shows every loop's enabled/running/ready
+  state, last pass, backlog, and active spawned-child RSS; running child agents
+  are included as detail rows in the JSON. The JSON also includes
+  `recent_results` for useful completed loop tasks, which the macOS menu-bar app
+  uses for notifications. The `tk-agent-status` console command and macOS
+  menu-bar app use the same underlying snapshot.
 
 ---
 

{threadkeeper-0.8.1 → threadkeeper-0.9.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "threadkeeper"
-version = "0.8.1"
+version = "0.9.1"
 description = "Multi-agent shared brain across Claude Code/Desktop, Codex, Gemini, Copilot, VS Code. Cross-session memory, self-improving skill loops, inter-agent signaling — one local MCP server."
 requires-python = ">=3.11"
 authors = [{ name = "thread-keeper contributors" }]
@@ -27,6 +27,8 @@ classifiers = [
 ]
 dependencies = [
     "mcp>=1.0.0",
+    "pydantic>=2",
+    "pydantic-settings>=2",
 ]
 
 [project.optional-dependencies]
@@ -69,6 +71,8 @@ thread-keeper-setup = "threadkeeper._setup:main"
 # Recompute stored embeddings with the active backend (e.g. after switching to
 # the ONNX default). Equivalent to `python -m threadkeeper.migrate_embeddings`.
 tk-migrate-embeddings = "threadkeeper.migrate_embeddings:main"
+# JSON/text status feed for menu-bar widgets and terminal monitors.
+tk-agent-status = "threadkeeper.agent_status:main"
 
 [tool.setuptools.packages.find]
 include = ["threadkeeper*"]

{threadkeeper-0.8.1 → threadkeeper-0.9.1}/tests/test_adapters.py

@@ -324,6 +324,10 @@ def test_codex_register_mcp_writes_toml(tmp_path, monkeypatch):
     assert '"/opt/python"' in body
     assert "[mcp_servers.thread-keeper.env]" in body
     assert '"/repo"' in body
+    assert "[mcp_servers.thread-keeper.tools.dialectic_claim]" in body
+    assert "[mcp_servers.thread-keeper.tools.dialectic_observation_resolve]" in body
+    assert "[mcp_servers.thread-keeper.tools.accept_candidate]" in body
+    assert 'approval_mode = "approve"' in body
 
 
 def test_codex_iter_messages_filters_developer_turns(tmp_path, monkeypatch):
@@ -350,6 +354,63 @@ def test_codex_iter_messages_filters_developer_turns(tmp_path, monkeypatch):
     assert msgs[1].content == "hello"
 
 
+def test_codex_iter_messages_uses_forced_child_cid_from_spawn_preamble(
+    tmp_path, monkeypatch,
+):
+    pkg = _bootstrap(tmp_path, monkeypatch)
+    fp = tmp_path / "rollout-2026-06-11T10-00-00.jsonl"
+    forced_cid = "af389b3f-8e17-46b5-87f1-402769a74e58"
+    fp.write_text("\n".join([
+        json.dumps({
+            "timestamp": "2026-06-11T10:00:00Z",
+            "type": "session_meta",
+            "payload": {"id": "019eb5d0-6753-7c31-bce6-b887761090c6", "cwd": "/x"},
+        }),
+        json.dumps({
+            "timestamp": "2026-06-11T10:00:01Z",
+            "type": "response_item",
+            "payload": {
+                "type": "message",
+                "role": "user",
+                "id": "u-agents",
+                "content": [{"type": "input_text", "text": "# AGENTS.md instructions"}],
+            },
+        }),
+        json.dumps({
+            "timestamp": "2026-06-11T10:00:02Z",
+            "type": "response_item",
+            "payload": {
+                "type": "message",
+                "role": "user",
+                "id": "u-spawn",
+                "content": [{
+                    "type": "input_text",
+                    "text": (
+                        "You were spawned in the background by parent conversation "
+                        "8877cab4-1f45-4d05-9a1c-09c6ab28adf1. "
+                        f"Your own cid is {forced_cid} (forced via --session-id "
+                        "and THREADKEEPER_FORCE_CID env)."
+                    ),
+                }],
+            },
+        }),
+        json.dumps({
+            "timestamp": "2026-06-11T10:00:03Z",
+            "type": "response_item",
+            "payload": {
+                "type": "message",
+                "role": "assistant",
+                "id": "a-1",
+                "content": [{"type": "output_text", "text": "processed"}],
+            },
+        }),
+    ]) + "\n")
+
+    msgs = list(pkg["codex"].iter_messages(fp))
+    assert [m.uuid for m in msgs] == ["u-agents", "u-spawn", "a-1"]
+    assert {m.session_id for m in msgs} == {forced_cid}
+
+
 # ---------------------------------------------------------------------
 # Gemini
 # ---------------------------------------------------------------------