Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
refactor(cli_agent): subprocess + stream-json pool — drop PTY for claude_code_agent
trohitg73c5b2270324
diff --git a/CLAUDE.md b/CLAUDE.mdindex cca720b5..888342f7 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -46,13 +46,13 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire| **[Status Broadcaster](./docs-internal/status_broadcaster.md)** | WebSocket-first communication: StatusBroadcaster singleton, live count via `len(MESSAGE_HANDLERS) + len(get_ws_handlers())`, broadcast message types, Android two-state model || **[RLM Service](./docs-internal/rlm_service.md)** | Recursive Language Model agent with REPL-based execution (llm_query, rlm_query, FINAL) || **[Claude Code Agent](./docs-internal/claude_code_agent_architecture.md)** | Claude Code integration internals (LangGraph reference; companion to `cli_agent_framework.md`) |-| **[CLI Agent Framework](./docs-internal/cli_agent_framework.md)** | Multi-provider CLI runtime (Claude Code / Codex / Gemini): `AICliService.run_batch`, per-task worktree isolation, FastMCP bridge, **memory bridge** (native `--resume` via stable `cwd=repo_root` + UUID5/`last_session_id` round-trip + auto-clear on stale UUID + `node_parameters_updated` broadcast). |-| **[Claude Code Interactive Mode](./docs-internal/claude_code_interactive_mode.md)** | The interactive-TUI cutover: MachinaOs no longer uses `claude -p` headless. Cross-platform PTY (`ptyprocess` POSIX / `pywinpty>=3.0.3` Windows) keeps `claude` alive; events come from the on-disk session JSONL discovered via mtime. `ClaudeSessionPool` keyed by `simpleMemory.node_id` reuses warm processes across batches (non-disruptive — preserves memory continuity; explicit `pool.clear()` for reset). Memory bridge drives continuity via `--continue` (claude auto-finds latest under cwd) rather than ferrying a UUID through `simpleMemory.last_session_id`. Four typed CloudEvents (`claude.session.{spawned,cleared,terminated,usage}`) fire from the pool. `/compact` events forward to `CompactionService`. `/usage` data sourced from `result` events (TUI scraping not parseable per Anthropic). |+| **[CLI Agent Framework](./docs-internal/cli_agent_framework.md)** | Multi-provider CLI runtime (Claude Code / Codex / Gemini): `AICliService.run_batch`, per-task worktree isolation, FastMCP bridge, **memory bridge** (`--continue` for first run + intra-process stream-json multi-turn + `--resume <UUID>` for crash recovery, all on a stable `cwd=repo_root`; `node_parameters_updated` broadcast on every successful turn). |+| **[Claude Code Interactive Mode](./docs-internal/claude_code_interactive_mode.md)** | The interactive-mode cutover: MachinaOs no longer uses `claude -p` headless. `ClaudeSessionPool` (keyed by `simpleMemory.node_id`) spawns `claude` as a plain subprocess with stdio pipes — **no PTY** — and drives it over the VSCode-extension protocol: `--output-format stream-json --input-format stream-json --verbose --ide`. User prompts written as JSON to `proc.stdin` (`{"type":"user","message":{"role":"user","content":"..."}}\n`); `system/init` / `assistant` / `result` / `system/compact_boundary` events stream back on `proc.stdout` (parsed by a background `stdout_reader_task` — the on-disk JSONL is persistence-only, not the runtime contract, because `result` events are stdout-only in stream-json mode). Cross-platform via plain pipes (the earlier PTY pattern was broken on Windows because pywinpty/ConPTY's emulated stdin never reached claude's Ink TUI keystroke handler). Stays in interactive billing — entrypoint `claude-vscode`, NOT `sdk-cli`. Multi-turn within one warm subprocess preserves the session UUID (verified end-to-end); cross-batch continuity via `--continue` (first run) or `--resume <UUID>` (crash recovery). Four typed CloudEvents (`claude.session.{spawned,cleared,terminated,usage}`) fire from the pool. `/compact` events forward to `CompactionService`. The non-pooled `AICliSession` path (one-shot prompt-in-argv runs) still uses PTY (out of scope for this refactor; works on POSIX). || **[CLI Agent Canonical Patterns RFC](./docs-internal/cli_agent_canonical_patterns_rfc.md)** | Audit of MachinaOs's `services/cli_agent` against the official Claude Code spec — six invariants (skills-as-files, MCP-only transport, `list_changed`, deferral, visible-tool filtering, native-session-continuity-via-stable-cwd) with current implementation status. || **[Claude Code CLI Reference (snapshot)](./docs-internal/claude_code_cli_reference.md)** | Verbatim snapshot of [code.claude.com/docs/en/cli-reference](https://code.claude.com/docs/en/cli-reference) — every CLI subcommand + flag + system-prompt-flag matrix + the subset we emit from `services/cli_agent/providers/anthropic_claude.py`. Fetched 2026-05-11. || **[Claude Code Env Vars (snapshot)](./docs-internal/claude_code_env_vars_reference.md)** | Categorised [code.claude.com/docs/en/env-vars](https://code.claude.com/docs/en/env-vars) snapshot — auth, Bedrock/Vertex, model, bash, MCP, telemetry, session/debug, paths. Documents `CLAUDE_CONFIG_DIR`, `MAX_MCP_OUTPUT_TOKENS`, `ENABLE_TOOL_SEARCH` which we touch directly. || **[Claude Code Permission Modes (snapshot)](./docs-internal/claude_code_permission_modes_reference.md)** | Verbatim [code.claude.com/docs/en/permission-modes](https://code.claude.com/docs/en/permission-modes) — `default` / `acceptEdits` / `plan` / `auto` / `dontAsk` / `bypassPermissions` semantics, Shift+Tab cycle, protected paths. MachinaOs default is `acceptEdits`. |-| **[Claude Code Headless / Print Mode (snapshot)](./docs-internal/claude_code_headless_reference.md)** | Verbatim [code.claude.com/docs/en/headless](https://code.claude.com/docs/en/headless) — `claude -p`, `--output-format` (`text` / `json` / `stream-json`), `--input-format`, `--bare`, stream-json event schema (`system/init`, `system/api_retry`, `system/plugin_install`). This is the protocol `services/cli_agent/session.py:_consume_stdout` parses. |+| **[Claude Code Headless / Print Mode (snapshot)](./docs-internal/claude_code_headless_reference.md)** | Verbatim [code.claude.com/docs/en/headless](https://code.claude.com/docs/en/headless) — `claude -p`, `--output-format` (`text` / `json` / `stream-json`), `--input-format`, `--bare`, stream-json event schema (`system/init`, `system/api_retry`, `system/plugin_install`). MachinaOs no longer uses `-p`; the pool path emits `--output-format stream-json --input-format stream-json --verbose --ide` over stdio pipes (interactive billing). The event schema is the contract `services/cli_agent/session_pool.py` parses off `proc.stdout`. || **[Claude Code Skills (snapshot)](./docs-internal/claude_code_skills_reference.md)** | Verbatim [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills) — `SKILL.md` frontmatter spec, discovery paths, content lifecycle, `context: fork`, dynamic context injection via `` !`<command>` ``. The spec MachinaOs materialises connected skills against in `_pre_spawn`. || **[Deep Agent](./docs-internal/deep_agent.md)** | LangChain DeepAgents integration with filesystem tools, sub-agent delegation, auto-summarization, and planning || **[Autonomous Agent Creation](./docs-internal/autonomous_agent_creation.md)** | Creating autonomous agents with Code Mode patterns and agentic loops |@@ -3412,28 +3412,29 @@ I don't have access to real-time weather data...- **Window + Archive**: Short-term (recent messages) + long-term (semantic retrieval) memory pattern- **Auto-Save**: AI Agent automatically saves updated markdown content to node parameters-### claude_code_agent bridge — native session resume (NOT markdown injection)+### claude_code_agent bridge — `--continue` + warm subprocess pool (NOT markdown injection)-When `simpleMemory` is connected to `claude_code_agent`, memory continuity is handled via **claude's own native session JSONL on disk** rather than re-injecting markdown as a system prompt. Claude stores per-session transcripts under `<CLAUDE_CONFIG_DIR>/projects/<project_key>/<session_id>.jsonl` where `project_key = re.sub(r"[^a-zA-Z0-9.-]", "-", str(cwd))` (verified against the on-disk `data/claude-machina/projects/` listing — Python reproduces three directory names byte-for-byte).+When `simpleMemory` is connected to `claude_code_agent`, memory continuity is handled by claude itself — the agent does NOT re-inject markdown as a system prompt. Claude stores per-session transcripts under `<CLAUDE_CONFIG_DIR>/projects/<project_key>/<session_id>.jsonl` where `project_key = re.sub(r"[^a-zA-Z0-9.-]", "-", str(cwd))` (verified against the on-disk `data/claude-machina/projects/` listing).**The three coupled mechanisms** (see [docs-internal/cli_agent_framework.md → Memory bridge](./docs-internal/cli_agent_framework.md#memory-bridge--simplememory--claude_code_agent) for full plumbing):-1. **Stable cwd.** `AICliSession` accepts `memory_bound=True`. When set, `cwd()` returns `repo_root` instead of the per-task `wt_t_<random>` worktree; `_pre_spawn` skips `git worktree add`; `cleanup` skips `git worktree remove`. The same cwd every run keeps claude's `project_key` constant so `--resume <UUID>` finds the prior JSONL.-2. **UUID5 first-run / `--resume` thereafter.** `claude_code_agent` derives `uuid5(NAMESPACE_OID, f"{memory_node_id}:{simpleMemory.session_id}")` for the first run and passes it as `--session-id <UUID5>`. Subsequent runs read `simpleMemory.last_session_id` (saved by `_persist_memory` from the previous run's `r.session_id`) and pass `--resume <UUID>` instead. Mutually exclusive in `providers/anthropic_claude.py:headless_argv` argv emission.-3. **Auto-clear stale `last_session_id`.** When claude reports `No conversation found with session ID: <UUID>` (the JSONL was wiped, or the user's saved UUID predates the cwd-stability fix), `_persist_memory` substring-matches the error and fires `_clear_stale_session_id` which wipes `simpleMemory.last_session_id` (but preserves `memory_content`). Next run falls through to the first-run branch and self-heals.+1. **Stable cwd.** The pool keeps `cwd = repo_root` for every memory-bound spawn (no per-task worktree carving). Same cwd every run → claude's `project_key` is constant → `--continue` / `--resume <UUID>` resolve against the same JSONL across batches.+2. **`--continue` first, intra-process thereafter.** [`claude_code_agent.execute_op`](./server/nodes/agent/claude_code_agent/__init__.py) sets `spec.continue_session = bool(memory_data)` so the first cold spawn for a memory-wired run emits `--continue` (claude auto-loads the most recent conversation under the cwd's `project_key`, per [code.claude.com/docs/en/cli-reference](https://code.claude.com/docs/en/cli-reference)). Subsequent turns are written as stream-json to the SAME warm subprocess's `proc.stdin` — claude keeps the conversation in-process with the same `session_id` (verified: turn 1 + turn 2 share UUID within one process).+3. **`--resume <UUID>` crash recovery.** If the warm subprocess dies between batches, [`ClaudeSessionPool.acquire`](./server/services/cli_agent/session_pool.py) detects `process.returncode is not None`, captures the dead session's `current_session_uuid` (last seen on a `result` event), and respawns with `--resume <captured_uuid>` so the same on-disk JSONL keeps growing. Mutually exclusive with `--continue` in `providers/anthropic_claude.py:interactive_argv`.-**`memory_content` is the UI mirror, not the resume channel.** Claude reads its own JSONL via `--resume`. The markdown in `memory_content` is appended every successful run (same `append_to_memory_markdown` + `trim_markdown_window` helpers aiAgent uses) for the human reader. User edits to `memory_content` do not influence claude's next response.+**`memory_content` is the UI mirror, not the resume channel.** Claude reads its own JSONL via `--continue` / `--resume`. The markdown in `memory_content` is appended every successful run (same `append_to_memory_markdown` + `trim_markdown_window` helpers aiAgent uses) so the human reader sees the conversation. User edits to `memory_content` do not influence claude's next response.-**Parallel-batch guard.** When memory is wired AND `len(tasks) > 1`, `claude_code_agent` raises `NodeUserError` at handler entry — concurrent `--resume <UUID>` spawns against one JSONL would race.+**`simpleMemory.last_session_id` is display-only.** Pre-cutover code persisted the session UUID back to the memory node and emitted `--session-id <UUID5>` / `--resume <UUID>` on subsequent runs. That dance is gone — `claude_code_agent` no longer reads `last_session_id` from the memory data. The field is kept on the Pydantic params for back-compat and diagnostic display; clearing the memory wipes it.++**Parallel-batch guard.** When memory is wired AND `len(tasks) > 1`, `claude_code_agent` raises `NodeUserError` at handler entry — concurrent `--continue` spawns against one project_key would race claude's session-resolution.**Live UI refresh.** `_persist_memory` broadcasts `node_parameters_updated` after `save_node_parameters` so the simpleMemory parameter panel auto-refetches the moment a turn completes — without this the DB has the latest conversation but the UI shows the stale snapshot loaded at workflow open. Mirrors the pattern in `routers/websocket.py:handle_save_node_parameters`.**Logs to grep on a live run:**-- `[Claude Code memory] memory_node=<id> last_session_id=<UUID|None> -> --resume <UUID>` (subsequent run) or `--session-id <UUID5> (first run)`-- `[AICliSession_*] memory-bound: skipping worktree, using cwd=<repo_root>`-- `[CC-Agent stream] result is_error=False ... session_id=<UUID>`+- `[Claude Code memory] memory_node=<id> -> --continue (claude auto-finds latest session under cwd)`+- `[ClaudeSessionPool] spawned new session memory_node=<id> pid=<N>` (cold spawn) or `warm reuse memory_node=<id> pid=<N> uuid=<UUID>` (intra-process turn)- `[CC-Agent _persist_memory] saved memory_node=<id> last_session_id=<UUID> appended_turns=1 ... content_length=<N>`-- On stale-UUID error: `[CC-Agent _persist_memory] cleared stale last_session_id=<UUID> from memory_node=<id>; next run will spawn a fresh claude session and persist its new UUID.`+- On crash recovery: `[ClaudeSessionPool] dropping dead session memory_node=<id> ... — will respawn` followed by spawn with `--resume <UUID>` argv.## Memory Compaction, Token Tracking, and Cost Calculationdiff --git a/client/src/adapters/nodeSpecToDescription.ts b/client/src/adapters/nodeSpecToDescription.tsindex 5a99f4a6..8b012470 100644--- a/client/src/adapters/nodeSpecToDescription.ts+++ b/client/src/adapters/nodeSpecToDescription.ts@@ -112,6 +112,13 @@ type InodeType = INodeProperties['type'];* the user sees an editable field rather than a blank slot.*/function mapPropertyType(prop: JsonSchemaProperty): InodeType {+ // ``json_schema_extra={"hidden": True}`` on the Pydantic Field hides+ // the parameter from the panel. ParameterRenderer.tsx returns ``null``+ // when ``parameter.type === 'hidden'``. Check both the top-level flag+ // (Pydantic flattens ``json_schema_extra`` keys onto the property) and+ // ``uiHints.hidden`` (nested alternate). Honoured BEFORE enum/editor+ // checks so hidden enum fields don't render as visible dropdowns.+ if ((prop as any).hidden === true || prop.uiHints?.hidden === true) return 'hidden';if (prop.enum && prop.enum.length > 0) return 'options';// Pydantic Field(json_schema_extra={"editor": "code"}) lands at the// property top-level; nested ``uiHints: {...}`` is the alternatediff --git a/docs-internal/claude_code_interactive_mode.md b/docs-internal/claude_code_interactive_mode.mdindex 4b9d4572..a06e1268 100644--- a/docs-internal/claude_code_interactive_mode.md+++ b/docs-internal/claude_code_interactive_mode.md@@ -1,158 +1,185 @@-# Claude Code interactive mode (in-process PTY + on-disk JSONL)--> **TL;DR.** MachinaOs drives the same interactive `claude` invocation a-> normal user runs at their terminal — not `claude -p`. A PTY keeps the-> TUI alive in-process; events come off the on-disk session JSONL,-> not stdout. A pool keyed by `simpleMemory.node_id` keeps the warm-> process across batches.+# Claude Code interactive mode (subprocess + stream-json)++> **TL;DR.** `ClaudeSessionPool` keeps a warm `claude` subprocess per+> `simpleMemory.node_id` and drives it with the same flags Anthropic's+> own VSCode extension uses — stdio pipes, `--output-format stream-json+> --input-format stream-json --verbose --ide`. Multi-turn happens by+> writing newline-delimited JSON to `proc.stdin` of the long-lived+> subprocess. Events arrive on `proc.stdout`. The on-disk JSONL is no+> longer the runtime contract — claude writes it for `--continue` /+> `--resume` persistence but the `result` event is stdout-only in+> stream-json mode.## Why we cut over from `-p`Pre-cutover MachinaOs spawned `claude -p --output-format stream-json`-and parsed NDJSON events on stdout. Two-direction motivation:+and parsed NDJSON events on stdout. Two reasons to leave `-p`:-1. **Match how users actually use Claude Code.** The headless path is- sanctioned for automation, but most Claude Code users run the- interactive TUI. Driving the same surface lets us inherit fixes /- behavior changes the team prioritises for the human-facing mode.-2. **Anthropic billing change (2026-06-15).** Per+1. **Anthropic billing change (2026-06-15).** Per[`code.claude.com/docs/en/headless`](https://code.claude.com/docs/en/headless),- subscription plans now bill `claude -p` and Agent-SDK usage from a- separate "monthly Agent SDK credit." Interactive usage stays on the- subscription's interactive bucket. The cutover puts us in the- user's interactive bucket when they supply their own API key.--The corollary: every protocol detail still works in interactive mode-because the on-disk JSONL is the same format `-p` wrote to stdout-(Claude Code CHANGELOG 2.1.101 / 2.1.126 — shared writer). The argv-flags we care about — `--mcp-config`, `--strict-mcp-config`,-`--allowedTools`, `--permission-mode`, `--append-system-prompt`,-`--resume`, **`--continue`** (new primary continuity flag — see-"Memory bridge" below), `--model`, `--effort`, `--add-dir`,-`--disallowedTools`, `--agent` — all work in interactive mode.--## What we dropped--| Flag | Why dropped |+ subscription plans bill `claude -p` and Agent-SDK usage from a+ separate "monthly Agent SDK credit." The interactive entrypoint+ (`claude-vscode`, not `sdk-cli`) stays on the subscription's+ interactive bucket. Dropping `-p` puts us in the user's interactive+ bucket when they supply their own API key.+2. **Match how Anthropic itself drives `claude` programmatically.** The+ VSCode extension at+ `C:/Users/Tgroh/.vscode/extensions/anthropic.claude-code-2.1.140-win32-x64/extension.js:156`+ spawns claude with exactly four flags (`--output-format stream-json+ --input-format stream-json --verbose --ide`) and never emits `-p`.+ That's the wire we reuse.++## Architecture++One transport (`asyncio.create_subprocess_exec` with `stdin/stdout/stderr=PIPE`),+one protocol (line-delimited stream-json events on stdout). No PTY.+A background `stdout_reader_task` parses each line and dispatches via+`_handle_stream_event`.++| Layer | Mechanism ||---|---|-| `-p` / `--print` | The headless toggle itself. |-| `--output-format stream-json` | Only meaningful under `-p`. |-| `--verbose` | Only meaningful with `-p --output-format stream-json`. |-| `--include-partial-messages` | Only meaningful with stream-json. |-| `--include-hook-events` | Only meaningful with stream-json. The hooks fire regardless and we can detect them via JSONL. |-| `--max-turns` | `-p`-only. External counter is a Phase 2 follow-up. |-| `--max-budget-usd` | `-p`-only. External monitor on `result.total_cost_usd` is a Phase 2 follow-up. |-| `--session-id <UUID>` | No longer pre-mint UUIDs. First-run claude assigns its own; we discover it via the new JSONL filename. |-| `--fallback-model` | `-p`-only. |--`ClaudeTaskSpec` keeps the corresponding Pydantic fields for-back-compat; they're silently dropped in `interactive_argv`.--## Architecture — transport vs. protocol--Two orthogonal layers:--| Layer | macOS / Linux | Windows |-|---|---|---|-| **Transport** (PTY holds `claude` alive) | `ptyprocess>=0.7.0` | `pywinpty>=3.0.3` (Rust-backed via PyO3 + winpty-rs + Maturin) |-| **Protocol** (read events) | tail `<CLAUDE_CONFIG_DIR>/projects/<project_key>/<session>.jsonl` | identical |-| **Send turn** | `pty.write((text + '\r').encode())` (NOT close stdin — see [#15553](https://github.com/anthropics/claude-code/issues/15553)) | identical |-| **Send slash command** | `pty.write(b"/clear\r")` | identical |-| **Completion detect** | JSONL `result` entry | identical |-| **Session continuity** | `claude --continue` (memory-bound) — claude auto-finds latest under cwd | identical |--`pywinpty` v3.x is now production-grade (used by Jupyter Lab terminals-and Spyder's IPython console) so the historical reason to route Windows-through a Node.js sidecar (pywinpty flakiness) no longer holds. Both-backends run in-process behind a single `PtyTransport` Protocol; the-factory in [`server/services/cli_agent/transports/__init__.py`](../server/services/cli_agent/transports/__init__.py)-picks per `sys.platform`.+| **Transport** | `asyncio.subprocess.Process` with stdio pipes — same on POSIX + Windows |+| **Send turn** | `proc.stdin.write(json.dumps({"type":"user","message":{"role":"user","content":...}}) + "\n")` |+| **Read events** | `proc.stdout.readline()` loop → `json.loads(line)` → `_handle_stream_event` |+| **Completion detect** | stream-json event where `type == "result"` (set via `provider.is_final_event`) |+| **Context reset (`/clear` equivalent)** | kill subprocess + drop captured UUID — stream-json input has no slash-command path (confirmed in VSCode extension source) |+| **Crash recovery** | `acquire()` checks `process.returncode`; respawns with `--resume <captured_uuid>` so the same on-disk JSONL keeps growing |### Code layout (`server/services/cli_agent/`)```cli_agent/├── providers/-│ └── anthropic_claude.py # interactive_argv (replaces headless_argv)-├── transports/-│ ├── __init__.py # get_pty_transport() factory-│ ├── base.py # PtyTransport / PtyHandle Protocols-│ ├── posix.py # PosixPtyTransport (ptyprocess)-│ └── windows.py # WindowsPtyTransport (pywinpty)-├── jsonl_watcher.py # JsonlWatcher (tail-f) + JsonlDirWatcher-├── session.py # AICliSession — one-shot non-pooled path-├── session_pool.py # ClaudeSessionPool — warm-process reuse-└── service.py # AICliService.run_batch + _run_pooled_turn+│ └── anthropic_claude.py # interactive_argv — emits the four VSCode-pattern flags+├── jsonl_watcher.py # still used by the non-pooled AICliSession; NOT used by the pool+├── session.py # AICliSession — one-shot non-pooled path (PTY on POSIX; out of scope for this refactor)+├── session_pool.py # ClaudeSessionPool — subprocess-based warm-process reuse+└── service.py # AICliService.run_batch — entry point; routes to pool when memory-bound```+## argv shape++Built by [`AnthropicClaudeProvider.interactive_argv`](../server/services/cli_agent/providers/anthropic_claude.py).+Stable head, task-driven tail:++```+claude+ --output-format stream-json+ --input-format stream-json+ --verbose+ --ide+ [--mcp-config <json> --strict-mcp-config]+ --model <name>+ [--resume <UUID> | --continue]+ [--allowedTools <csv>]+ --permission-mode bypassPermissions+ [--append-system-prompt <text>]+ [--effort low|medium|high]+ [--add-dir <path>]...+ [--disallowedTools <csv>]+ [--agent <name>]+```++Notable absences (intentional):++| Flag | Reason omitted |+|---|---|+| `-p` / `--print` | Drops us into the SDK billing bucket; the whole point of the cutover. |+| Positional prompt (`-- "<text>"`) | Prompt arrives via stdin in stream-json input mode; an argv positional would double-send the first turn. `interactive_argv`'s `include_prompt` parameter is kept for back-compat but ignored. |+| `--session-id <UUID>` | Rejected by claude in non-headless mode. We discover the UUID from the first event that carries `session_id`. |+| `--include-partial-messages`, `--include-hook-events`, `--max-turns`, `--max-budget-usd`, `--fallback-model` | All `-p`-only. `ClaudeTaskSpec` keeps the fields for back-compat; they're silently dropped here. External cost / turn caps are a Phase 2 follow-up. |++`--permission-mode bypassPermissions` is required for non-interactive+automation — there's no human at the keyboard to approve the per-tool+prompts `acceptEdits` would surface. Documented at+[`code.claude.com/docs/en/permission-modes`](https://code.claude.com/docs/en/permission-modes).+## Session pool — warm-process reuse[`ClaudeSessionPool`](../server/services/cli_agent/session_pool.py) is-keyed by `simpleMemory.node_id`. Successive batches against the same-memory node reuse the same warm `claude` PTY:--- **Acquire (warm)** — returns the existing live session. **No- implicit `/clear`** — the next prompt appends to claude's current- JSONL so the conversation continues. This is the load-bearing- invariant for `simpleMemory` continuity.-- **Acquire (cold)** — spawn fresh via `PtyTransport`, locate the- JSONL by mtime (newest `.jsonl` with `mtime >= spawn_time - 1s`- works uniformly for fresh `claude` and `claude --continue`), start- a `JsonlWatcher` on it. Stash the MCP bearer token on the- `PooledClaudeSession` so re-acquires use the same token the- spawned claude already has in its argv.-- **Explicit `clear(session)`** — sends `/clear` to the PTY, awaits- the new JSONL filename via the persistent `JsonlDirWatcher`, swaps- the file watcher. Per- [`claude-code#32871`](https://github.com/anthropics/claude-code/issues/32871),- `/clear` mints a **new UUID** with a **new JSONL file** rather than- clearing in-place. Pre-clear conversation stays resumable by its- old UUID.+keyed by `simpleMemory.node_id`. Each entry is a+`PooledClaudeSession` carrying the live `asyncio.subprocess.Process`,+the captured session UUID (filled in from the first event that has+one), the MCP bearer token embedded in the spawn argv, a per-session+`asyncio.Lock`, an `asyncio.Event` signalled by the stdout reader on+`result`, and a per-turn event buffer.++| Operation | Behaviour |+|---|---|+| `acquire(memory_node_id, ...)` | Live + healthy entry → return as-is (warm reuse). Live + dead entry → drop, capture its UUID, spawn fresh with `--resume <UUID>` so the same JSONL keeps growing. No entry → cold spawn. At cap → LRU evict (skipping in-flight). |+| `send_turn(session, prompt, ...)` | Holds `session.lock`. Clears `result_event` + `events_this_turn`. Writes one stream-json line to `proc.stdin`, awaits `result_event` (timeout = 600s default). Returns a `SessionResult` built from the per-turn event buffer. Persists `result.session_id` onto `session.current_session_uuid`. |+| `clear(session, ...)` | Kill the subprocess, drop the captured UUID. Next `acquire` spawns fresh with no continuity flag (claude assigns a new UUID). Emits `claude.session.cleared`. |+| `release(session)` | Updates `last_used_at` so the reaper measures idle from now. |+| `terminate(memory_node_id)` | Force-drop a specific entry: close stdin → 2s grace → `proc.kill()` → cancel reader/drain tasks. |+| `shutdown_all()` | Stop the reaper + terminate every entry. Wire into FastAPI's lifespan `shutdown`. |Lifecycle policy:- **Idle TTL** 30 min (`_DEFAULT_IDLE_TTL`). Background reaper task- terminates pooled sessions whose `last_used_at` exceeds the cap- AND aren't currently locked.-- **Max size** 16 (`_DEFAULT_MAX_SIZE`). LRU eviction at cap.-- **Crash recovery** — `acquire` calls `pty_handle.is_alive()` and- respawns transparently when the pooled PTY has died.+ terminates pooled sessions whose `last_used_at` exceeds the cap AND+ aren't currently locked.+- **Max size** 16 (`_DEFAULT_MAX_SIZE`). LRU eviction at cap (skipping+ in-flight entries).- **Concurrency** — per-key `asyncio.Lock` serialises turns against- the same pooled session. `lock.locked()` doubles as the reaper's- in-flight detector.-- **Shutdown** — `ClaudeSessionPool.shutdown_all()` is the target for- FastAPI's lifespan `shutdown` event (TODO: wire from `main.py`).+ the same pooled subprocess so two `send_turn` calls can't interleave+ their stream-json lines on stdin. `lock.locked()` doubles as the+ reaper's in-flight detector.++## Stream-json event dispatch++`_handle_stream_event` has three concerns:++1. **UUID capture.** Any event carrying `session_id` (or `sessionId`)+ seeds `session.current_session_uuid` if it isn't already set —+ `system/init` fires this for fresh spawns, `result` carries the+ authoritative value at turn end. Crash-recovery respawns read this+ field to emit `--resume <UUID>`.+2. **Per-turn buffering.** Every event is appended to+ `events_this_turn`. When `provider.is_final_event(event)` returns+ True (i.e. `event.type == "result"`), `result_event` is set and+ `send_turn` returns. `SessionResult` is built by+ `AnthropicClaudeProvider.event_to_session_result` over the buffered+ events — same shape `-p` used to produce.+3. **Native compaction forwarding.** `type == "system"` ++ `subtype == "compact_boundary"` events forward to+ `CompactionService.record(...)` via `_record_native_compaction` so+ the local-threshold path doesn't double-fire on claude's auto-+ compaction. Trigger metadata (`pre_tokens`, `trigger: auto|manual`)+ is preserved on the compaction record.++## Continuity across process restarts++The pool's continuity model is two-layered:++- **Intra-process (warm pool).** Within a live subprocess, every turn+ writes to the same `proc.stdin` and claude itself keeps the conversation+ in memory. No `--continue` / `--resume` needed — same session UUID+ flows across turns. Verified: turn 1 `13ac5819-...`, turn 2 same UUID.+- **Cross-process (cold spawn / crash recovery).** Cold spawns of a+ memory-bound run emit `--continue` (claude auto-finds the latest+ conversation under the cwd via `project_key`). If `acquire` finds the+ pooled subprocess has died, it captures the dead session's UUID+ before respawning and splices `--resume <UUID>` into the spec so the+ new subprocess continues writing to the same on-disk JSONL.++`ClaudeTaskSpec` carries `continue_session: bool` and+`resume_session_id: Optional[str]`. `resume_session_id` wins if both+are set. `simpleMemory.last_session_id` is display-only metadata —+`_persist_memory` writes it for the UI but the agent doesn't read it+back (continuity rides through `--continue` + the warm pool, not a+ferried UUID).## MCP bearer token lifecycle`claude` handles its own MCP authentication. We embed the bearer in`--mcp-config` at spawn time; the spawned claude uses it for the-lifetime of its process. The pool does NOT issue or unregister tokens-— the caller (`AICliService.run_batch`) owns the lifecycle, with the-twist that for pooled sessions the token persists with the warm PTY-across batches:--```python-# run_batch — non-pool path (unchanged)-token = issue_token()-register_batch(token, ctx)-try:- results = await asyncio.gather(*(run_one(t) for t in tasks))-finally:- unregister_batch(token)--# run_batch — pool path-token = issue_token()-register_batch(token, ctx)-try:- result = await self._run_pooled_turn(..., mcp_bearer_token=token)- # token stays embedded in the warm PTY for the next batch.- # On pool eviction / shutdown the registration orphans (bounded- # by max pool size, acceptable for Phase 1).-finally:- if not use_pool:- unregister_batch(token)-```+lifetime of its process. The pool stashes the token on+`PooledClaudeSession.bearer_token` at spawn time so warm-reuse callers+(`AICliService.run_batch`'s pool path) can re-register the batch+context against the SAME token claude already has in its argv. The pool+itself never issues / unregisters — that's `run_batch`'s job, with the+twist that for pooled sessions the token persists across batches and+orphans on pool eviction (bounded by `max_size`, acceptable for Phase 1).## CloudEvents broadcasts@@ -162,119 +189,62 @@ fired via the corresponding `broadcaster.broadcast_claude_session_*`methods on[`server/services/status_broadcaster.py`](../server/services/status_broadcaster.py):-| Event type | Wire key | When fired |-|---|---|---|-| `com.machinaos.claude.session.spawned` | `claude_session_event` | Cold spawn (new PTY) |-| `com.machinaos.claude.session.cleared` | `claude_session_event` | Explicit `pool.clear` → new UUID |-| `com.machinaos.claude.session.terminated` | `claude_session_event` | Pool terminate (reason: `idle` / `crashed` / `evicted` / `shutdown` / `explicit`) |-| `com.machinaos.claude.session.usage` | `claude_session_usage` | Each `result` event (per-turn cost + tokens) |--Frontend listeners should switch on `envelope.type` and route the-inner `data` payload (memory_node_id, session_uuid, cost, tokens, …)-into whichever store renders the simpleMemory usage panel.+| Event type | When fired |+|---|---|+| `com.machinaos.claude.session.spawned` | Cold spawn (new subprocess) |+| `com.machinaos.claude.session.cleared` | Explicit `pool.clear` → new UUID on next acquire |+| `com.machinaos.claude.session.terminated` | Pool terminate (reason: `idle` / `crashed` / `evicted` / `shutdown` / `explicit`) |+| `com.machinaos.claude.session.usage` | Each `result` event (per-turn cost + tokens + duration + num_turns) |++The usage event is the source of truth for the simpleMemory usage panel+— `/usage` is TUI-only plain text per Anthropic and not parseable.+Frontend listeners switch on `envelope.type` and route the inner `data`+payload (`memory_node_id`, `session_uuid`, cost, tokens, …) into the+store that renders the panel.++## Tools and skills++**Tools (MCP) — unchanged from the `-p` era.** Spawn argv carries+`--mcp-config <json>` (HTTP transport, bearer header) + `--strict-mcp-config`+so the spawned claude only loads MachinaOs's FastMCP server. The+`mcpServers.machinaos` block sets `alwaysLoad: true` to opt out of MCP+tool-search deferral so all `mcp__machinaos__*` tools enter context at+session start. `--allowedTools` lists the explicit allowlist:+five built-ins (`Read,Edit,Bash,Glob,Grep,Write,Skill,WebSearch,WebFetch`),+every `mcp__machinaos__<connected_tool>` passed by the caller, plus the+five core MCP tools (`getWorkspaceFiles`, `listSkills`, `getSkill`,+`getCredential`, `broadcastLog`).++**Skills — known gap on the pool path.** `AICliSession._materialise_skills`+writes connected skills under `<cwd>/.claude/skills/` for the one-shot+non-pooled path. The pool path skips that materialisation; agents+discover skills via MCP `listSkills` / `getSkill` tools at runtime+instead. Fine for now, but pool-side skill materialisation is an open+follow-up.## `/usage` and `/compact` semantics-Per the research:--- **`/usage`** — TUI-only plain text per Anthropic. Not parseable.- The data it displays (cost, tokens, duration, num_turns) is already- on every `result` JSONL event under `usage` + `total_cost_usd`. We- surface it via the `claude.session.usage` CloudEvent instead.-- **`/clear`** — mints a new session UUID + new JSONL file (issue- [#32871](https://github.com/anthropics/claude-code/issues/32871)).- Pool exposes this as `pool.clear(session)` for explicit reset; not- fired on warm acquire.-- **`/compact`** — emits `system/compact_boundary` with+- **`/usage`** — TUI-only plain text per Anthropic. Not parseable. We+ surface the same data (cost, tokens, duration, num_turns) via the+ `claude.session.usage` CloudEvent built from every `result` event.+- **`/clear`** — the stream-json input wire has no slash-command path+ (confirmed in the VSCode extension source). Context reset is+ `pool.clear(session)` — kill subprocess, drop UUID, next acquire+ spawns fresh.+- **`/compact`** — emits `system/compact_boundary` on stdout with`compact_metadata.pre_tokens` + `compact_metadata.trigger` (auto vs- manual). Both `AICliSession._on_jsonl_event` and- `ClaudeSessionPool._handle_jsonl_event` forward it to+ manual). `_handle_stream_event` forwards it to`CompactionService.record(...)` so the local-threshold path doesn't- double-fire.--Commands MachinaOs must **avoid** in PTY-driven automation (they open-interactive dialogs, kill the session, or open a browser):-`/feedback`, `/bug`, `/exit`, `/quit`, `/login`, `/logout`,-`/permissions`, `/agents`, `/mcp`, `/model` (with no arg), `/rewind`,-`/config`, `/install-github-app`, `/install-slack-app`, `/teleport`,-`/heapdump`.--## Memory bridge — `--continue`, not UUID round-trip--Late-stage simplification: the agent no longer ferries a UUID through-`simpleMemory.last_session_id` to drive continuity. Instead it passes-`--continue` and lets claude track its own latest session per cwd.--`ClaudeTaskSpec` carries a `continue_session: bool` field. The-argv-builder emits one of:--- `--resume <UUID>` if `task.resume_session_id` is set (explicit- wins — used for `--fork-session` later, or any caller that already- knows the exact UUID).-- `--continue` if `task.continue_session=True` (the memory-bound- default; per- [`code.claude.com/docs/en/cli-reference`](https://code.claude.com/docs/en/cli-reference)- this loads the most recent conversation under the cwd).-- Neither — fresh session; claude assigns a new UUID.--`claude_code_agent.execute_op` sets `continue_session=True` when a-memory node is wired; it no longer reads `last_session_id` from the-memory data. The invariants:--- `memory_bound=True` makes the spawn cwd = `repo_root` so claude's- `project_key` stays constant across batches.-- First run with memory wired: argv `--continue` (no prior conversation- under cwd → claude starts fresh). The post-spawn `_wait_for_session_jsonl`- helper finds the new JSONL via mtime (newest `.jsonl` with- `mtime >= spawn_time - 1s`).-- Subsequent runs with memory wired: argv `--continue` — claude- loads the latest conversation under cwd and continues.-- Pooled (warm): no respawn — the warm PTY continues in its current- UUID; the next prompt appends to its existing JSONL.-- Pooled (after `pool.clear`): a new UUID is captured via the- persistent `JsonlDirWatcher` and the file watcher swapped.--`simpleMemory.last_session_id` is now **display-only metadata** —-`_persist_memory` still writes it from the latest result for UI /-diagnostic display, but the agent doesn't read it. Field is kept on-the schema for back-compat.--**Stale UUID auto-clear** (`_clear_stale_session_id`) still applies if-someone explicitly sets `resume_session_id` (e.g. the future-`--fork-session` UI). With `--continue` there's nothing to be stale —-claude itself decides what's available.--## Out-of-process pty-host (deferred upgrade path)--If `pywinpty` / `ptyprocess` stability becomes an issue (crashes-bringing down FastAPI), promote `PtyTransport` to an out-of-process-Python sidecar — VSCode's `ptyHostMain.ts` pattern, in Python.-Supervised by `machina/tree.py`'s Job Object, JSON-RPC over stdio.-The `PtyTransport` Protocol boundary makes the swap cheap (~1 day).-See VSCode issue-[#74620](https://github.com/microsoft/vscode/issues/74620) for the-rationale (heartbeat, flow control, isolation from main app).--## Open follow-ups--- **Cancellation path.** Pool sessions bypass- `AICliService._active_sessions`, so `cancel_workflow` /- `cancel_node` don't reach the pooled PTY. Add pool-in-flight- tracking or hook cancel into `pool.terminate`.-- **Lifespan integration.** Wire `pool.shutdown_all()` to FastAPI's- shutdown event from `main.py`. Currently the pool dies with the- process; orphan PTY children are caught by `machina/tree.py` Job- Object on Windows and `os.setsid` on POSIX.-- **Frontend usage panel.** `claude.session.usage` CloudEvents are- flowing; the React hook + simpleMemory panel UI are the missing- half (Step 7 of the implementation plan).-- **`--fork-session` UI.** `--fork-session` is the documented working- fork primitive; surface a "Branch this conversation" `<ActionButton>`- on simpleMemory + a `branches: List[{uuid, name, created_at}]`- param. Avoids `/rewind` which has bug- [#55347](https://github.com/anthropics/claude-code/issues/55347)- (documented as fork but implemented as in-place mutation).-- **External cost cap / turn cap.** Replacements for the dropped- `--max-budget-usd` and `--max-turns` flags. Aggregate- `result.total_cost_usd` / count `assistant` events with- `stop_reason: "tool_use"` and kill the PTY at the limit.+ double-fire on claude's native auto-compaction.++## What changed (historical note)++The previous iteration of this doc described a PTY transport+(`pywinpty` on Windows, `ptyprocess` on POSIX) reading events from the+on-disk session JSONL via `JsonlWatcher` / `JsonlDirWatcher`. That path+was abandoned for the pool: `pywinpty`'s ConPTY emulation did not+deliver keystrokes to claude's Ink TUI on Windows (empirically+confirmed across four test variants). Stdio pipes + stream-json work+cross-platform and match the Anthropic-blessed pattern. The non-pooled+`AICliSession` still uses a PTY on POSIX for its one-shot+`AICliService.run_batch` path — out of scope for this refactor.diff --git a/docs-internal/cli_agent_canonical_patterns_rfc.md b/docs-internal/cli_agent_canonical_patterns_rfc.mdindex e55d6def..c1aa3773 100644--- a/docs-internal/cli_agent_canonical_patterns_rfc.md+++ b/docs-internal/cli_agent_canonical_patterns_rfc.md@@ -346,13 +346,15 @@ runtime log shows exactly this).```**Spec note.** The lockfile is for IDE-host scenarios (VSCode publishes-this so a spawned `claude` can discover the IDE). Headless `claude -p`-ignores it — the documented headless path is `--mcp-config`. Our-lockfile is currently ornamental; doesn't hurt, but `transport: "http"`-is the wrong value for what Claude's VSCode extension actually publishes-(`"ws"` per the live extension dump in-[#16434](https://github.com/anthropics/claude-code/issues/16434)).-**Defer.** Documented note in `cli_agent_framework.md` is enough.+this so a spawned `claude` can discover the IDE). The pool path now+emits `--ide` in its argv, so claude does discover and connect to the+lockfile's MCP endpoint at spawn time. `transport: "http"` stays —+that matches what our FastMCP sub-app at `/mcp/ide` actually speaks+(streamable HTTP). The `"ws"` upgrade (matching what Claude's VSCode+extension publishes in its own lockfile per the live extension dump+in [#16434](https://github.com/anthropics/claude-code/issues/16434))+is **deferred** — `"http"` is interoperable and unblocks the pool+path today.### 4.5 FastMCP server toolsdiff --git a/docs-internal/cli_agent_framework.md b/docs-internal/cli_agent_framework.mdindex 30c0d673..9df9e02e 100644--- a/docs-internal/cli_agent_framework.md+++ b/docs-internal/cli_agent_framework.md@@ -65,7 +65,7 @@ class AICliProvider(Protocol):ide_lockfile_dir: Optional[Path] # ~/.claude/ide | <tmpdir>/gemini/idedef binary_path(self) -> Path: ...- def headless_argv(self, task, *, defaults) -> list[str]: ...+ def interactive_argv(self, task, *, defaults) -> list[str]: ...def login_argv(self) -> list[str]: ... # CLI's own login commanddef auth_status_argv(self) -> Optional[list[str]]: ... # cheap probedef detect_auth_error(self, stderr, exit_code) -> bool: ...@@ -82,7 +82,7 @@ class AICliProvider(Protocol):# | json_cost | ide_lockfile | sandbox```-### Claude argv (`AnthropicClaudeProvider.headless_argv`)+### Claude argv (`AnthropicClaudeProvider.interactive_argv`)Spawned per task — the binary path comes from`services.claude_oauth.claude_binary_path()` (the same project-local@@ -90,31 +90,47 @@ install the credentials Login button uses) and `CLAUDE_CONFIG_DIR` isinjected on the spawn env so the agent shares one credential store withthe auth surface.+The pooled path (`ClaudeSessionPool`) spawns claude as a plain+subprocess with stdio pipes — no PTY — and drives it over the+VSCode-extension protocol: prompts written as stream-json to+`proc.stdin`, events read as stream-json off `proc.stdout`. Stays in+the interactive billing bucket (entrypoint `claude-vscode`, NOT+`sdk-cli`) since `-p` / `--print` is never emitted.+```<repo>/data/claude-machina/npm/node_modules/.bin/claude[.cmd]- -p <prompt>- --output-format stream-json- --verbose # required when stream-json + --print- --include-partial-messages- --include-hook-events # SessionStart/hook events into stream- --ide # documented VSCode auto-connect via lockfile+ --output-format stream-json # events on stdout+ --input-format stream-json # user turns to stdin as JSON+ --verbose # required with stream-json for full event detail+ --ide # VSCode auto-connect via lockfile--model <model>- [--session-id <UUID> | --resume <UUID>]- --max-turns <N>- [--max-budget-usd <D>]+ [--session-id <UUID> | --resume <UUID>] # mutually exclusive--allowedTools <csv>--permission-mode <mode>[--append-system-prompt <text>][--effort <low|medium|high|xhigh|max>]- [--fallback-model <model>][--add-dir <path>]* [--disallowedTools <csv>] [--agent <name>]+ [--mcp-config <json>] [--strict-mcp-config]```+**Dropped from the pool path** (vs. the previous headless/`-p` shape):+`-p`, `--print`, `--include-partial-messages`, `--include-hook-events`,+`--max-turns`, `--max-budget-usd`, `--fallback-model`. The positional+`-- "<prompt>"` is also never emitted — prompts arrive as JSON on+stdin (`{"type":"user","message":{"role":"user","content":"..."}}\n`).+`ClaudeTaskSpec` keeps the corresponding Pydantic fields for+back-compat; they're silently dropped in `interactive_argv`.+All flags documented at[code.claude.com/docs/en/cli-reference](https://code.claude.com/docs/en/cli-reference).Worktree, lockfile, and bearer-token MCP server are wired in-`session.py:_pre_spawn`; the `--ide` flag tells the CLI to discover that-lockfile via `CLAUDE_IDE_LOCK`.+`session_pool.py:_spawn`; the `--ide` flag tells the CLI to discover+that lockfile via `CLAUDE_IDE_LOCK`.++The non-pooled `AICliSession` path (one-shot prompt-in-argv runs that+don't need session reuse) still uses PTY (`ptyprocess` POSIX /+`pywinpty>=3.0.3` Windows) and remains out of scope for the+subprocess+stream-json refactor.Factory:@@ -342,125 +358,114 @@ finds its own JSONL.### Argv contract-| Run state | Argv | Why |+| Run state | Argv emitted | Why ||---|---|---|-| First run (no `last_session_id` in DB) | `--session-id <UUID5(memory_node_id, simpleMemory.session_id)>` | Deterministic UUID lets us address the same session predictably; survives session_id forks via the user-visible `simpleMemory.session_id` slot. |-| Subsequent run (`last_session_id` saved) | `--resume <last_session_id>` | Native claude session resume. Same `cwd=repo_root` → same project_key → claude finds the JSONL it wrote on the previous turn. |-| After "No conversation found" error | argv same as above on the spawn that errored; `_persist_memory` auto-clears `last_session_id` so the NEXT run falls into the first-run branch with `--session-id <UUID5>`. | Self-heal from a stale or wiped JSONL. |+| First cold spawn under a memory-wired node | `--continue` | Claude auto-loads the most recent conversation under cwd's `project_key` (per [code.claude.com/docs/en/cli-reference](https://code.claude.com/docs/en/cli-reference)). No UUID round-trip needed — claude tracks its own latest session per cwd on disk. |+| Subsequent turn, SAME warm subprocess | nothing argv-level — stream-json line on `proc.stdin` | The pool keeps the subprocess alive between turns. Claude maintains the conversation in-process; same `session_id` across turns (verified end-to-end). |+| Crash recovery (subprocess died between batches) | `--resume <captured_uuid>` | `ClaudeSessionPool.acquire` detects `process.returncode is not None`, captures the dead session's `current_session_uuid`, and respawns with `--resume`. Same `cwd=repo_root` → same `project_key` → claude finds the same JSONL it was writing before the crash. Mutually exclusive with `--continue`. |Argv emission lives in-`providers/anthropic_claude.py:headless_argv` — picks up-`task.session_id` vs `task.resume_session_id` (mutually exclusive-fields on `ClaudeTaskSpec`).+[`providers/anthropic_claude.py:interactive_argv`](../server/services/cli_agent/providers/anthropic_claude.py).+The `ClaudeTaskSpec` carries `continue_session: bool` and+`resume_session_id: Optional[str]`. `claude_code_agent.execute_op` sets+`continue_session = bool(memory_data)` for the cold-spawn case; the+pool's crash-recovery path injects `resume_session_id =+session.current_session_uuid` into the spec before respawning.+`--session-id <UUID5>` (the pre-cutover UUID-round-trip primitive) is+intentionally NOT emitted in interactive mode — claude rejects it.### Plumbing```ClaudeCodeAgentNode.execute_op- └─ collect_agent_connections() → memory_data {node_id, session_id,- memory_content, window_size,- long_term_enabled,- last_session_id}- └─ derive resume_session_id (= memory_data.last_session_id) OR- first_run_session_uuid (= uuid5(NAMESPACE_OID,- f"{memory_node_id}:{session_id}"))- └─ ClaudeTaskSpec(..., session_id=..., resume_session_id=...)- └─ run_batch(..., connected_memory=memory_data, broadcaster=...)- └─ AICliService.run_batch:- ├─ AICliSession(..., memory_bound=True) # ← drives cwd switch- │ └─ cwd() returns self._repo_root- │ └─ _pre_spawn skips `git worktree add`- │ └─ cleanup skips `git worktree remove`- └─ asyncio.gather → SessionResults+ ├─ collect_agent_connections() → memory_data {node_id, session_id,+ │ memory_content, window_size,+ │ long_term_enabled,+ │ last_session_id (display-only)}+ ├─ continue_session = bool(memory_data)+ ├─ ClaudeTaskSpec(..., continue_session=continue_session,+ │ resume_session_id=None)+ └─ AICliService.run_batch(..., connected_memory=memory_data,+ broadcaster=...)+ └─ For memory-wired runs, route through ClaudeSessionPool:+ ├─ pool.acquire(memory_node_id, spec, cwd=repo_root, env, ...)+ │ ├─ cold: spawn `claude --output-format stream-json+ │ │ --input-format stream-json --verbose --ide+ │ │ --continue ...` as subprocess with stdio pipes;+ │ │ no PTY. stdout_reader_task parses each event line+ │ │ and dispatches to _handle_stream_event.+ │ └─ warm reuse: return the existing PooledClaudeSession;+ │ the next prompt rides the same subprocess.+ │ └─ crash recovery: capture current_session_uuid from the+ │ dead session, splice resume_session_id+ │ onto the spec, spawn fresh with --resume.+ ├─ pool.send_turn(session, prompt):+ │ ├─ write {"type":"user","message":{...}} + "\n" to proc.stdin+ │ └─ await session.result_event (set by the stdout reader+ │ when claude emits `result`)+ ├─ pool.release(session) ← marks idle for the reaper└─ _persist_memory(connected_memory, results, broadcaster):├─ saves params["last_session_id"] = most_recent.session_id+ │ (display-only — claude_code_agent no longer reads it)├─ appends user/assistant turns to params["memory_content"]│ via append_to_memory_markdown + trim_markdown_window- │ (the same helpers aiAgent / chatAgent / deep_agent / rlm_agent- │ use — reuse, don't duplicate)├─ database.save_node_parameters(memory_node_id, params)└─ broadcaster.broadcast({"type": "node_parameters_updated","node_id": memory_node_id, ...})- # ← the UI's parameter panel auto-refreshes the moment- # the run completes. Without this the DB has the- # latest conversation but the UI keeps showing the- # stale snapshot it loaded at workflow open.```-### Self-healing on stale UUID--`AICliService._clear_stale_session_id(connected_memory)` substring--matches `"No conversation found with session ID"` in any result's-`error`. When matched it wipes `simpleMemory.last_session_id` from-the DB but preserves `memory_content` (the user-visible markdown-transcript). Next run derives a fresh `--session-id <UUID5>` and-proceeds with a clean session.--Triggered automatically inside `_persist_memory` when zero results-succeed. Without this the same stale UUID would re-fire every run-and the user would be stuck.-### Parallel-batch guard-Memory continuity requires serial execution — N concurrent-`--resume <UUID>` spawns against one session JSONL would race. When-`memory_data` is wired AND `len(tasks) > 1`, `claude_code_agent`-raises `NodeUserError("Memory-bound batches must run one task at a-time. Reduce Tasks to a single entry, or disconnect the memory-node.")` at handler entry — never spawns.+Memory continuity requires serial execution — N concurrent `--continue`+spawns against the same `project_key` would race claude's+session-resolution. When `memory_data` is wired AND `len(tasks) > 1`,+`claude_code_agent` raises `NodeUserError("Memory-bound batches must+run one task at a time. ...")` at handler entry.### Markdown mirror`memory_content` (the markdown surface the simpleMemory UI shows) is-**a display mirror, not the canonical record**. Claude's own JSONL-is canonical. `_persist_memory` appends each successful run's prompt-+ response to `memory_content` via `append_to_memory_markdown` so the-UI shows the conversation grow live. User edits to `memory_content`-do NOT influence claude's next response — claude reads its own JSONL-via `--resume`.+a **display mirror**, not the resume channel. Claude's own JSONL on+disk is what `--continue` and `--resume` load from. `_persist_memory`+appends each successful run's prompt + response to `memory_content`+via `append_to_memory_markdown` so the UI shows the conversation grow+live. User edits to `memory_content` do NOT influence claude's next+response.To reset both: click the simpleMemory's clear button or invoke the-`clear_memory` WS handler with `memory_node_id` — backend wipes-`memory_content` to the default placeholder AND clears-`last_session_id` in one DB write. Claude's on-disk JSONL is left-alone (orphan, harmless). The next run with the same memory wired-will spawn a fresh session at a NEW deterministic UUID5 (because-the user's `simpleMemory.session_id` is part of the UUID5 inputs;-unchanged after clear, but `last_session_id` being None routes us-through the first-run branch).+`clear_memory` WS handler — backend wipes `memory_content` to the+default placeholder AND clears `last_session_id` in one DB write.+Claude's on-disk JSONL is left alone (orphan, harmless). The next run+spawns fresh with `--continue` against a project_key that has no+matching prior session, and claude assigns a brand-new UUID.### Logs to watch```-[Claude Code memory] memory_node=<id> last_session_id=<UUID|None>- -> --resume <UUID> | --session-id <UUID5> (first run)+[Claude Code memory] memory_node=<id> -> --continue+ (claude auto-finds latest session under cwd)[CC-Agent run_batch] enter ... memory=<memory_node_id> ...-[AICliSession_*] memory-bound: skipping worktree, using cwd=<repo_root>--[CC-Agent stream] result is_error=False subtype=success- session_id=<UUID> duration_ms=...+[ClaudeSessionPool] spawned new session memory_node=<id> pid=<N>+ (cold spawn — argv carries --continue or --resume <UUID>)+[ClaudeSessionPool] warm reuse memory_node=<id> pid=<N> uuid=<UUID>+ (intra-process turn — stream-json on stdin)-[CC-Agent _persist_memory] memory_node=<id> results=1 successful=1- session_ids=['<UUID>'][CC-Agent _persist_memory] saved memory_node=<id> last_session_id=<UUID>appended_turns=1 archived_blocks=0 content_length=<N>```-On a stale-resume failure path the trace ends with:+On a crash-recovery path the trace shows:```-[CC-Agent stderr] No conversation found with session ID: <UUID>-[CC-Agent stream] result is_error=True subtype=error_during_execution- session_id=<new-UUID-claude-assigned-to-the-failed-attempt>-[CC-Agent _persist_memory] no successful runs; skipping save ...-[CC-Agent _persist_memory] cleared stale last_session_id=<UUID>- from memory_node=<id>; next run will spawn a fresh claude session- and persist its new UUID.-```+[ClaudeSessionPool] dropping dead session memory_node=<id>+ pid=<dead-pid> exit=<code> — will respawn-— and the next run succeeds with `--session-id <UUID5>`.+[ClaudeSessionPool] spawned new session memory_node=<id> pid=<new-pid>+ (argv: --resume <UUID> taken from the dead session's+ current_session_uuid; same project_key, same JSONL continues)+```## Status broadcast eventsdiff --git a/server/nodes/agent/claude_code_agent/__init__.py b/server/nodes/agent/claude_code_agent/__init__.pyindex 4fdb7ef5..9d95ac1b 100644--- a/server/nodes/agent/claude_code_agent/__init__.py+++ b/server/nodes/agent/claude_code_agent/__init__.py@@ -19,7 +19,7 @@ from __future__ import annotationsimport timefrom datetime import datetimefrom pathlib import Path-from typing import Any, List, Optional+from typing import Any, List, Literal, Optionalfrom pydantic import BaseModel, ConfigDict, Field, field_validator@@ -38,42 +38,110 @@ from services.cli_agent import ClaudeTaskSpec # noqa: E402from services.cli_agent.types import SessionResultModel # noqa: E402+# Claude Code-supported models. Per+# https://code.claude.com/docs/en/cli-reference the ``--model`` flag+# accepts either an Anthropic-managed alias (``sonnet`` / ``opus`` /+# ``haiku`` — resolves to the latest in that family) or a full model ID.+# We surface both so users can pin a specific revision OR float to the+# tier-latest. Free-text ``str`` was the prior type; switching to+# ``Literal`` gives the parameter panel a dropdown without losing+# back-compat (every value the field used to accept is still in the list).+ClaudeCodeModel = Literal[+ # Anthropic-managed aliases — track the freshest model per family+ "sonnet",+ "opus",+ "haiku",+ # Pinned full IDs — current generation (Claude 4.x)+ "claude-opus-4-7",+ "claude-opus-4-6",+ "claude-opus-4-5",+ "claude-opus-4-1",+ "claude-opus-4",+ "claude-sonnet-4-6",+ "claude-sonnet-4-5",+ "claude-sonnet-4",+ "claude-haiku-4-5",+]+++ClaudeCodeEffort = Literal["low", "medium", "high", "xhigh", "max"]++class ClaudeCodeAgentParams(BaseModel):- """Multi-task batch parameters for Claude Code.+ """Claude Code node parameters.++ UI surface: a single ``prompt`` field. Every other field is kept on+ the model for back-compat with existing saved workflows and to feed+ sensible defaults into the per-task ``ClaudeTaskSpec`` — but is+ hidden from the parameter panel via ``json_schema_extra.hidden``+ so the canvas-side surface stays minimal.- Two paths:- 1. ``tasks=[...]`` — explicit list, runs N in parallel- 2. ``tasks=[]`` + legacy ``prompt`` — synthesises a single-task batch+ Two execution paths (both invisible to the user):+ 1. ``tasks=[...]`` — explicit list (advanced; saved workflows only)+ 2. ``tasks=[]`` + ``prompt`` — synthesises a single-task batch (default)"""- tasks: List[ClaudeTaskSpec] = Field(- default_factory=list,- description="List of Claude tasks to run in parallel (max 5 concurrent).",- json_schema_extra={"rows": 1},- )- # Legacy single-task fallback ----------------------------------------+ # The ONLY visible field. Everything below is ``hidden: true``.prompt: str = Field(default="",- description="Legacy: single-prompt fallback used only when "- "`tasks` is empty.",- json_schema_extra={"rows": 4, "placeholder": "Or use the tasks array..."},+ description="The prompt sent to Claude Code.",+ json_schema_extra={"rows": 4, "placeholder": "Ask Claude Code to..."},+ )++ # --- Hidden: advanced multi-task batch ---+ tasks: List[ClaudeTaskSpec] = Field(+ default_factory=list,+ description="Advanced: list of Claude tasks to run in parallel "+ "(max 5 concurrent). Use ``prompt`` for the common case.",+ json_schema_extra={"hidden": True, "rows": 1},)- model: str = Field(++ # --- Hidden: model + system prompt + execution scoping ---+ model: ClaudeCodeModel = Field(default="claude-sonnet-4-6",- description="Default model for tasks that don't override it.",+ description=(+ "Default model for tasks that don't override it. Aliases "+ "(``sonnet`` / ``opus`` / ``haiku``) resolve to the latest in "+ "each family; full IDs pin a specific revision."+ ),+ json_schema_extra={"hidden": True},+ )+ system_prompt: Optional[str] = Field(+ default=None,+ json_schema_extra={"hidden": True, "rows": 3},)- system_prompt: Optional[str] = Field(default=None, json_schema_extra={"rows": 3})working_directory: Optional[str] = Field(default=None,description="Git repo root. Defaults to the workflow's workspace dir.",+ json_schema_extra={"hidden": True},)max_parallel: int = Field(default=5, ge=1, le=20,description="Concurrency cap.",+ json_schema_extra={"hidden": True},)allowed_credentials: List[str] = Field(default_factory=list,description="Credential names the CLI is permitted to fetch via MCP.",+ json_schema_extra={"hidden": True},+ )++ # --- Hidden: model knobs (effort, fallback) ---+ effort: Optional[ClaudeCodeEffort] = Field(+ default=None,+ description=(+ "Reasoning-effort level passed via ``--effort``. Applies to "+ "thinking-capable models (Opus / Sonnet); ignored by Haiku."+ ),+ json_schema_extra={"hidden": True},+ )+ fallback_model: Optional[ClaudeCodeModel] = Field(+ default=None,+ description=(+ "Model to fall back to when the primary is overloaded. "+ "Passed via ``--fallback-model``."+ ),+ json_schema_extra={"hidden": True},)# Saved workflow JSON may persist these list fields as `null` rather@@ -219,6 +287,10 @@ class ClaudeCodeAgentNode(ActionNode):"system_prompt": params.system_prompt,"continue_session": continue_session,}+ if params.effort is not None:+ spec_kwargs["effort"] = params.effort+ if params.fallback_model is not None:+ spec_kwargs["fallback_model"] = params.fallback_modeltasks = [ClaudeTaskSpec(**spec_kwargs)]else:# Apply node-level defaults to tasks that don't override.@@ -228,6 +300,10 @@ class ClaudeCodeAgentNode(ActionNode):changed["model"] = params.modelif not t.system_prompt and params.system_prompt:changed["system_prompt"] = params.system_prompt+ if t.effort is None and params.effort is not None:+ changed["effort"] = params.effort+ if t.fallback_model is None and params.fallback_model is not None:+ changed["fallback_model"] = params.fallback_model# Only auto-enable --continue when memory is wired AND# the task didn't explicitly opt in/out or pick a UUID.if (diff --git a/server/services/cli_agent/jsonl_watcher.py b/server/services/cli_agent/jsonl_watcher.pyindex c0962884..bb129ec5 100644--- a/server/services/cli_agent/jsonl_watcher.py+++ b/server/services/cli_agent/jsonl_watcher.py@@ -323,6 +323,38 @@ class JsonlDirWatcher:pass+def snapshot_jsonl_sizes(project_dir: Path) -> Dict[str, int]:+ """Return ``{name: size_bytes}`` for every ``.jsonl`` in ``project_dir``.++ Used by ``ClaudeSessionPool._wait_for_session_jsonl`` (and the+ equivalent in :class:`AICliSession`) to baseline the project dir+ before spawning ``claude``. Post-spawn the caller polls again and+ picks whichever file is new (absent from baseline) or grew+ (``current_size > baseline_size``) — both fresh spawns and+ ``--continue`` spawns produce a size-positive delta.++ Returns an empty dict if ``project_dir`` doesn't exist yet (first+ spawn under a new cwd). Silently skips entries the filesystem+ refuses to ``stat`` — they're typically transient and the post-spawn+ poll will catch them on the next tick once they settle.+ """+ sizes: Dict[str, int] = {}+ try:+ entries = list(project_dir.iterdir())+ except (FileNotFoundError, NotADirectoryError):+ return sizes+ except OSError:+ return sizes+ for entry in entries:+ if entry.suffix != ".jsonl":+ continue+ try:+ sizes[entry.name] = entry.stat().st_size+ except OSError:+ continue+ return sizes++def session_uuid_from_jsonl_path(path: Path) -> Optional[str]:"""Extract the session UUID from a JSONL filename, or None if thename doesn't match the ``<uuid>.jsonl`` convention.diff --git a/server/services/cli_agent/providers/anthropic_claude.py b/server/services/cli_agent/providers/anthropic_claude.pyindex c049c647..c8c668d9 100644--- a/server/services/cli_agent/providers/anthropic_claude.py+++ b/server/services/cli_agent/providers/anthropic_claude.py@@ -108,30 +108,40 @@ class AnthropicClaudeProvider:connected_tool_names: Optional[List[str]] = None,include_prompt: bool = True,) -> List[str]:- """Build the full argv (binary + flags) for one interactive task.-- Emits the same invocation a human user runs (``claude ... --- "<prompt>"``) rather than ``claude -p``. The TUI is held alive- by a PTY; events are read from the on-disk JSONL at- ``<CLAUDE_CONFIG_DIR>/projects/<project_key>/<session>.jsonl``.+ """Build the full argv for one ``claude`` invocation, VSCode-style.++ Spawned as a regular subprocess with stdio pipes — NOT a PTY.+ Matches the invocation Anthropic's own VSCode extension uses+ (verified in+ ``C:\\Users\\Tgroh\\.vscode\\extensions\\anthropic.claude-code-2.1.140-win32-x64\\extension.js``+ line 156):++ ``claude --output-format stream-json --input-format stream-json+ --verbose --ide [task-flags...]``++ User prompts arrive over ``proc.stdin`` as newline-delimited JSON+ of shape ``{"type":"user","message":{"role":"user","content":...}}``,+ not as an argv positional. Events stream back on ``proc.stdout``+ in the same shape claude writes to its on-disk JSONL — the FE-+ facing event handlers downstream are file-source-agnostic so+ we keep tailing the JSONL via ``JsonlWatcher`` either way.++ Critically NOT emitted:++ - ``-p`` / ``--print``: keeps us in the interactive billing+ bucket (entrypoint ``claude-vscode``, NOT ``sdk-cli``). The+ VSCode extension confirms this exact pattern works without+ ``--print``.+ - The positional prompt (``-- "<prompt>"``): the prompt+ arrives via ``proc.stdin`` in stream-json input mode.+ ``include_prompt`` is kept for back-compat but ignored.``mcp_endpoint_url`` + ``mcp_bearer_token`` (if both set) are- emitted as a ``--mcp-config <json>`` block so the spawned- ``claude`` registers MachinaOs's FastMCP server (works- identically in interactive + headless modes per- https://code.claude.com/docs/en/mcp).-- Tools and skills are unchanged from the prior headless path —- same ``--allowedTools`` list (built-ins + every wired- ``mcp__machinaos__*``), same skill materialisation under- ``<cwd>/.claude/skills/`` (in ``AICliSession._materialise_skills``).- The permission flag flips from ``acceptEdits`` to- ``bypassPermissions`` so non-Edit tools in the allowlist fire- without prompting the TUI (no human to click "Allow").-- ``include_prompt=False`` is used by the session pool when- respawning a fresh process whose first prompt will be written- to the PTY rather than passed on argv (e.g. after a `/clear`).+ emitted as ``--mcp-config <json>`` so the spawned claude+ registers MachinaOs's FastMCP server. Tools allowlist+ (``--allowedTools``) lists every wired ``mcp__machinaos__*``+ plus the 5 built-ins. Skill materialisation under+ ``<cwd>/.claude/skills/`` is unchanged."""if not isinstance(task, ClaudeTaskSpec):raise TypeError(@@ -141,6 +151,23 @@ class AnthropicClaudeProvider:argv: List[str] = [str(self.binary_path())]+ # Stream-json I/O — the VSCode extension pattern. Prompts go via+ # ``proc.stdin``, events come back on ``proc.stdout``. Verified+ # against+ # ``$VSCODE_EXT_DIR/anthropic.claude-code-<ver>/extension.js:156``+ # which spawns claude with exactly these four flags. ``--verbose``+ # is required so the stream-json output includes the full event+ # detail (without it, only the final result line is emitted).+ # ``--ide`` makes claude discover the IDE lockfile we write at+ # ``<CLAUDE_CONFIG_DIR>/ide/<pid>.lock`` for auto-connection to+ # MachinaOs's MCP server.+ argv += [+ "--output-format", "stream-json",+ "--input-format", "stream-json",+ "--verbose",+ "--ide",+ ]+# MCP server registration — same shape as the prior headless# path; the Claude Code MCP doc's ``mcp.json`` example. Works# identically in interactive mode.@@ -270,13 +297,13 @@ class AnthropicClaudeProvider:if task.agent:argv += ["--agent", task.agent]- # Prompt as positional argument after `--`. Claude auto-submits- # the positional as turn 1 and stays interactive (per- # https://code.claude.com/docs/en/cli-reference). The session- # pool sets include_prompt=False for spawns whose first prompt- # will be written to the PTY directly.- if include_prompt and task.prompt:- argv += ["--", task.prompt]+ # Prompt arrives via ``proc.stdin`` as stream-json — NOT as+ # an argv positional. ``include_prompt`` is kept on the signature+ # for back-compat (older callers pass ``include_prompt=False``)+ # but is ignored: stream-json input mode and a positional prompt+ # would double-send the first turn. Caller writes prompts to+ # ``ClaudeSessionPool.send_turn``'s ``proc.stdin`` instead.+ _ = include_promptreturn argv@@ -371,6 +398,35 @@ class AnthropicClaudeProvider:success = Falseerror = error or response or "result event reports error"+ # Surface routable extras on ``provider_data`` so downstream+ # workflow nodes can read them off ``tasks[i].provider_data.*``.+ # ``canonical_usage`` flattens token counts across all models;+ # ``modelUsage`` preserves the per-model breakdown (with the+ # per-model ``costUSD`` + ``contextWindow`` + ``maxOutputTokens``+ # claude itself reports). The minor fields below either drive+ # FE diagnostics (``terminal_reason`` / ``api_error_status``)+ # or feed cost analytics (``service_tier`` / ``inference_geo``+ # land inside the usage block but aren't propagated by+ # ``canonical_usage`` because that struct is per-event, not+ # per-result).+ for key in (+ "modelUsage",+ "permission_denials",+ "terminal_reason",+ "fast_mode_state",+ "api_error_status",+ ):+ if key in final and final[key] is not None:+ provider_data.setdefault(key, final[key])+ # Pull the service-tier / cache-creation / inference-geo bits+ # off the usage block so downstream consumers don't have to+ # re-iterate the events themselves.+ usage_block = final.get("usage") or {}+ for key in ("service_tier", "inference_geo"):+ v = usage_block.get(key)+ if v:+ provider_data.setdefault(key, v)+cu = self.canonical_usage(events)return {diff --git a/server/services/cli_agent/session.py b/server/services/cli_agent/session.pyindex 8ca0178c..395ba309 100644--- a/server/services/cli_agent/session.py+++ b/server/services/cli_agent/session.py@@ -49,7 +49,7 @@ import yamlfrom core.logging import get_loggerfrom services._supervisor.process import BaseProcessSupervisor-from services.cli_agent.jsonl_watcher import JsonlWatcher+from services.cli_agent.jsonl_watcher import JsonlWatcher, snapshot_jsonl_sizesfrom services.cli_agent.lockfile import remove_ide_lockfile, write_ide_lockfilefrom services.cli_agent.protocol import AICliProvider, CanonicalUsage, SessionResultfrom services.cli_agent.transports import PtyHandle, get_pty_transport@@ -273,7 +273,16 @@ class AICliSession(BaseProcessSupervisor):connected skill so the spawned claude can invoke them via thebuilt-in `Skill` tool. Filesystem skills are copied wholesale(preserves `scripts/` + `references/`); DB skills are- reconstructed from frontmatter."""+ reconstructed from frontmatter.++ Only ``AICliSession`` (the non-pooled, one-shot agent path)+ calls this. ``ClaudeSessionPool`` (the pooled, memory-bound+ path) leaves skills accessible via the FastMCP server's+ ``listSkills``/``getSkill`` tools instead. Switching the pool+ to the standard ``--add-dir`` skill discovery is tracked+ separately (requires restructuring ``server/skills/`` to the+ Agent Skills `<root>/.claude/skills/<name>/SKILL.md` shape).+ """from services.skill_loader import get_skill_loaderloader = get_skill_loader()@@ -382,15 +391,13 @@ class AICliSession(BaseProcessSupervisor):# Resume runs: known location. Claude opens this file and# appends to it on each turn.self._session_jsonl_path = project_dir / f"{resume_uuid}.jsonl"- # Else: post-spawn we'll discover the file via mtime — works- # uniformly for fresh-spawn (claude creates new) and- # --continue (claude appends to existing).-- # Spawn via the cross-platform PTY transport. The PtyHandle- # owns the subprocess; `self._proc` stays `None` for- # BaseProcessSupervisor-compat — `is_running` / `_do_stop` are- # overridden below to consult `self._pty_handle` instead.- spawn_time = time.monotonic()++ # Snapshot every existing JSONL's size BEFORE spawn so the post-spawn+ # locator can detect "claude wrote here" via deterministic size-diff —+ # works uniformly for fresh spawns (new filename) AND ``--continue``+ # spawns (existing file grows). Size is monotonic and filesystem-+ # portable; mtime / wall-clock comparisons are not.+ baseline_sizes = snapshot_jsonl_sizes(project_dir)transport = get_pty_transport()argv = self.argv()try:@@ -412,14 +419,14 @@ class AICliSession(BaseProcessSupervisor):# Resolve the JSONL path. For known-UUID `--resume` runs the# path is already known; otherwise (fresh OR `--continue`)- # discover via mtime — claude either creates a new file (fresh)- # or updates the latest existing file's mtime by appending an- # init event (--continue). Either way "newest .jsonl with- # mtime >= spawn_time - grace" is the right file.+ # discover via size-diff against the pre-spawn baseline: claude+ # either creates a new file (fresh) or appends an init event to+ # the existing latest file (--continue). Either way, the first+ # ``.jsonl`` whose size > baseline is the right file.if self._session_jsonl_path is None:try:self._session_jsonl_path = await self._wait_for_session_jsonl(- project_dir, spawn_time,+ project_dir, baseline_sizes,)except TimeoutError as exc:# Surface a clean error envelope rather than letting the@@ -464,42 +471,33 @@ class AICliSession(BaseProcessSupervisor):return Path(MACHINA_CLAUDE_DIR) / "projects" / project_keyasync def _wait_for_session_jsonl(- self, project_dir: Path, spawn_time: float,+ self, project_dir: Path, baseline: Dict[str, int],) -> Path:- """Find the JSONL claude is using post-spawn via mtime.+ """Find the JSONL claude is using post-spawn via size-diff vs baseline.- Works for both fresh-spawn (claude creates a new file) and- ``--continue`` (claude appends an init event to the most- recent existing file, updating its mtime). Picks the newest- ``.jsonl`` whose mtime is at least ``spawn_time - 1s``- (1s grace for clock skew + mtime resolution).+ ``baseline`` is the ``{name: size}`` snapshot taken BEFORE the+ spawn. After spawn we poll for the first ``.jsonl`` that's+ either new (not in baseline) or grown (size > baseline size).+ Handles both fresh spawns (new filename) and ``--continue``+ spawns (existing file grows). File size is a monotonic,+ filesystem-portable signal — no wall-clock vs monotonic clock+ comparison, no mtime-resolution races.Raises :class:`TimeoutError` after- :data:`_FIRST_RUN_JSONL_TIMEOUT` seconds — surfaces as a- clean spawn failure rather than a silently dead session.+ :data:`_FIRST_RUN_JSONL_TIMEOUT` seconds — surfaces as a clean+ spawn failure rather than a silently dead session."""- deadline = spawn_time + _FIRST_RUN_JSONL_TIMEOUT- mtime_floor = spawn_time - 1.0 # grace for clock skew- while time.monotonic() < deadline:- try:- jsonls = [- p for p in project_dir.iterdir()- if p.suffix == ".jsonl"- ]- except OSError:- jsonls = []- if jsonls:- try:- newest = max(jsonls, key=lambda p: p.stat().st_mtime)- if newest.stat().st_mtime >= mtime_floor:- return newest- except OSError:- pass+ deadline_mono = time.monotonic() + _FIRST_RUN_JSONL_TIMEOUT+ while time.monotonic() < deadline_mono:+ current = snapshot_jsonl_sizes(project_dir)+ for name, size in current.items():+ if size > baseline.get(name, 0):+ return project_dir / nameawait asyncio.sleep(0.1)raise TimeoutError(- f"No session JSONL touched under {project_dir} within "- f"{_FIRST_RUN_JSONL_TIMEOUT}s — claude may have failed to "- f"start or the CLAUDE_CONFIG_DIR is misconfigured."+ f"No session JSONL appeared or grew under {project_dir} "+ f"within {_FIRST_RUN_JSONL_TIMEOUT}s — claude may have "+ f"failed to start or the CLAUDE_CONFIG_DIR is misconfigured.")async def _on_jsonl_event(self, event: Dict[str, Any]) -> None:diff --git a/server/services/cli_agent/session_pool.py b/server/services/cli_agent/session_pool.pyindex 50a08006..55685947 100644--- a/server/services/cli_agent/session_pool.py+++ b/server/services/cli_agent/session_pool.py@@ -1,41 +1,73 @@-"""Warm-process pool for interactive ``claude`` sessions.--Keeps a live ``claude`` PTY per ``simpleMemory.node_id`` so successive-turns can reuse the warm process — the PTY stays alive across batches-and the next prompt rides on the existing claude session (saves the-~1-2 s spawn cost). By default acquire is **non-disruptive**: warm-reuse returns the same session UUID, so the memory bridge's-conversation continuity stays intact (claude appends to its existing-JSONL).--Context reset is an **explicit** operation via :meth:`clear`. ``/clear``-mints a NEW session UUID with a NEW JSONL file — per issue-`claude-code#32871 <https://github.com/anthropics/claude-code/issues/32871>`_-— so calling it is the right primitive when the user wants to start a-fresh conversation in the same pooled process (e.g. a "Clear-conversation" button on simpleMemory). The memory bridge auto-picks-up the new UUID from the next turn's ``result`` event.+"""Long-lived ``claude`` subprocess pool — VSCode-extension pattern.++Keeps one warm ``claude --output-format stream-json --input-format+stream-json --verbose --ide`` subprocess per ``simpleMemory.node_id``+so successive turns can reuse the same process — same session UUID+across turns, no respawn cost. Mirrors what Anthropic's official+VSCode extension does (verified from the on-disk extension source at+``$VSCODE_EXT_DIR/anthropic.claude-code-<ver>/extension.js`` line 156).++Why subprocess (not PTY): pywinpty's ConPTY emulation does not deliver+keystrokes to claude's Ink TUI on Windows — empirically confirmed+across four test variants (`docs-internal/claude_code_interactive_mode.md`+records the post-mortem). Plain stdio pipes work cross-platform and+match the documented multi-turn integration pattern.++Per-turn mechanics:++ 1. Caller writes one stream-json line to ``proc.stdin``:+ ``{"type":"user","message":{"role":"user","content":"..."}}\\n``+ 2. Claude reads stdin, processes the turn, emits stream-json events+ to ``proc.stdout`` (``system/init``, ``assistant``, ``user``,+ ``system/compact_boundary``, and finally ``result``). Claude+ ALSO writes a subset of events to the on-disk session JSONL at+ ``<CLAUDE_CONFIG_DIR>/projects/<project_key>/<session_uuid>.jsonl``+ for persistent multi-batch memory — but the ``result`` event is+ stdout-only in stream-json mode, so stdout is our runtime contract.+ 3. A background ``stdout_reader_task`` started at spawn time parses+ each line as a stream-json event and dispatches via+ :meth:`_handle_stream_event`. Events flow into the per-turn+ buffer; ``result_event`` fires when the final ``type=="result"``+ event lands.+ 4. ``send_turn`` returns a :class:`SessionResult` built from the+ turn's events. The session UUID is captured from the result event+ so subsequent batches can spawn ``--resume <UUID>`` if the+ pooled process has been reaped.Lifecycle policy:- - **Idle TTL**: 30 min default. A background reaper task terminates- pooled sessions whose ``last_used_at`` exceeds the threshold.- - **Max size**: 16 default. LRU eviction when full.- - **Crash recovery**: ``acquire()`` checks ``is_alive()`` and respawns- transparently when the pooled PTY has died.- - **Concurrency**: per-key ``asyncio.Lock`` serialises turns against- the same pooled session (the existing parallel-batch guard in- ``claude_code_agent`` enforces N=1 per memory node, so the lock is- a belt-and-braces invariant).- - **Shutdown**: ``ClaudeSessionPool.shutdown_all()`` terminates every- pooled PTY. Wire into FastAPI's lifespan hook.--Pattern mirrors :mod:`services.process_service` (long-lived process pool)-and :mod:`nodes.telegram._service` (singleton service with lifecycle).++ - **Idle TTL**: 30 min default. Background reaper terminates+ long-idle subprocesses.+ - **Max size**: 16 concurrent pooled sessions. LRU eviction at cap.+ - **Crash recovery**: ``acquire()`` checks ``process.returncode`` and+ respawns transparently when the pooled subprocess has died.+ - **Per-session lock**: serialises turns against the same pooled+ process so two ``send_turn`` calls don't write overlapping+ stream-json lines.+ - **Shutdown**: :meth:`shutdown_all` closes every subprocess's stdin+ (claude exits cleanly on EOF) and waits briefly, then kills any+ holdouts. Wire into FastAPI's lifespan ``shutdown`` event.++Continuity across process restarts:++ - First spawn for a memory-bound run: argv emits ``--continue``+ (claude resolves the latest conversation under cwd's+ ``project_key`` automatically; works whether or not a prior+ JSONL exists).+ - Each successful turn captures ``result.session_id`` onto+ ``session.current_session_uuid``. If the subprocess is later+ reaped and a new ``acquire`` happens, the next spawn emits+ ``--resume <session.current_session_uuid>`` so the SAME JSONL+ keeps growing across process restarts.+ - :meth:`clear` is an explicit context-reset primitive: kill the+ subprocess, drop the captured UUID, let the next ``acquire``+ spawn fresh with no continuity flag (claude assigns a new UUID)."""from __future__ import annotationsimport asyncio+import jsonimport timeimport uuidfrom dataclasses import dataclass, field@@ -44,79 +76,81 @@ from typing import Any, Dict, List, Literal, Optionalfrom core.logging import get_loggerfrom services.cli_agent.factory import create_cli_provider-from services.cli_agent.jsonl_watcher import (- JsonlDirWatcher,- JsonlWatcher,- session_uuid_from_jsonl_path,-)from services.cli_agent.protocol import AICliProvider, SessionResult-from services.cli_agent.transports import PtyHandle, get_pty_transportfrom services.cli_agent.types import ClaudeTaskSpeclogger = get_logger(__name__)-# Defaults — keep aligned with the operator's mental model. The 30 min-# idle TTL matches a typical "I switched tasks but might come back"-# workflow; 16 concurrent pooled sessions matches the FastAPI default-# worker count.+# Defaults — keep aligned with the operator's mental model._DEFAULT_IDLE_TTL = 30 * 60.0_DEFAULT_MAX_SIZE = 16_DEFAULT_REAPER_INTERVAL = 60.0 # reaper tick-# How long to wait for the new JSONL file to appear after sending-# ``/clear``. Empirically ~200 ms on Linux; 5 s is a generous cap that-# matches the first-spawn JSONL-locate timeout in ``AICliSession``.-_CLEAR_JSONL_TIMEOUT = 5.0+# Soft window for stdin EOF to drive a graceful claude shutdown before+# we escalate to ``proc.kill()``. Claude exits within ~100 ms of EOF.+_SHUTDOWN_GRACE = 2.0@dataclassclass PooledClaudeSession:- """One live ``claude`` PTY + the metadata to reuse it across turns.-- Owns the PTY transport handle, the current ``JsonlWatcher``, and a- persistent ``JsonlDirWatcher`` over the project dir (used to detect- the new UUID claude assigns after each ``/clear``).+ """One live ``claude`` subprocess + the metadata to reuse it across turns.++ No PTY, no file watcher. ``process`` is an ``asyncio.subprocess.Process``+ opened with ``stdin=PIPE``, ``stdout=PIPE``, ``stderr=PIPE``. Prompts+ go via ``process.stdin.write(stream_json_line)``; events come back on+ ``process.stdout`` (stream-json output mode), parsed line-by-line by+ a background ``stdout_reader_task`` that dispatches each parsed event+ via :meth:`ClaudeSessionPool._handle_stream_event`. Stderr is drained+ separately and logged.++ The on-disk JSONL at+ ``<CLAUDE_CONFIG_DIR>/projects/<project_key>/<session_uuid>.jsonl``+ is still written by claude — it's the persistence layer that+ ``--continue`` / ``--resume`` rehydrate from across process+ restarts — but the runtime contract here is stdout-only because+ the ``result`` event (final turn outcome) goes ONLY to stdout in+ stream-json mode, NOT to the JSONL file."""memory_node_id: str- project_dir: Path- pty_handle: PtyHandle- current_session_uuid: str- current_jsonl_path: Path- dir_watcher: JsonlDirWatcher- jsonl_watcher: JsonlWatcher+ process: asyncio.subprocess.Processcwd: Path- # MCP bearer token embedded in the spawned claude's `--mcp-config`.- # Set by the caller at spawn time so the warm-reuse path can read- # it back and re-register the batch context with the SAME token- # the live claude already has in its argv. The pool does NOT- # issue/unregister tokens — the CLI handles its own MCP auth, the- # caller (run_batch) owns the lifecycle.- bearer_token: str = ""+ # ``current_session_uuid`` is "" until the first turn's ``system/init``+ # or ``result`` event reveals it. Subsequent spawns for the same+ # memory_node_id (after a crash / reap) emit ``--resume <UUID>`` so+ # the same on-disk JSONL keeps growing across process restarts.+ current_session_uuid: str = ""last_used_at: float = field(default_factory=time.monotonic)- # Per-session lock; held throughout a turn or a /clear rotation. The- # reaper consults ``lock.locked()`` to skip in-flight sessions — no- # separate in_flight flag needed.+ # Per-session lock; held throughout a turn. The reaper consults+ # ``lock.locked()`` to skip in-flight sessions.lock: asyncio.Lock = field(default_factory=asyncio.Lock)- # Set by the JSONL handler when claude writes a ``result`` event;+ # Set by the stdout reader when claude emits a ``result`` event;# ``send_turn`` awaits this. Cleared before each new turn.result_event: asyncio.Event = field(default_factory=asyncio.Event)- # Per-turn event buffer, cleared on each ``send_turn`` so the result- # builder only sees the current turn's events.+ # Per-turn event buffer, cleared on each ``send_turn``.events_this_turn: List[Dict[str, Any]] = field(default_factory=list)- # Dir-watcher signal for ``/clear``: fires when a new ``.jsonl``- # appears under ``project_dir``.- new_jsonl_event: asyncio.Event = field(default_factory=asyncio.Event)- new_jsonl_path: Optional[Path] = None+ # Background tasks: parse stream-json events from stdout (single+ # source of truth for runtime events), drain stderr (logged at+ # warning level).+ stdout_reader_task: Optional[asyncio.Task[None]] = None+ stderr_drain_task: Optional[asyncio.Task[None]] = Noneclass ClaudeSessionPool:- """Per-``memory_node_id`` pool of warm ``claude`` PTYs.-- Acquired via :meth:`acquire` (auto-spawns if missing, sends- ``/clear`` + captures new UUID if reusing). Released via- :meth:`release` (marks idle for the reaper).+ """Per-``memory_node_id`` pool of warm ``claude`` subprocesses.++ Public surface (unchanged from the PTY-era pool — callers in+ :mod:`services.cli_agent.service` see the same method shapes):++ - :meth:`acquire` — get or spawn a session for a memory_node_id+ - :meth:`send_turn` — write one stream-json user message, return result+ - :meth:`release` — mark idle for the reaper+ - :meth:`clear` — kill subprocess + drop UUID (next acquire spawns fresh)+ - :meth:`terminate` — force-drop a specific entry+ - :meth:`shutdown_all` — drop everything (FastAPI lifespan hook target)+ - :meth:`peek` — read-only inspection+ - :meth:`start_reaper` — begin background idle-eviction"""def __init__(@@ -130,8 +164,6 @@ class ClaudeSessionPool:self._idle_ttl = float(idle_ttl)self._max_size = int(max_size)self._reaper_interval = float(reaper_interval)- # Top-level lock guards `self._pool` mutations only (insert,- # evict). Per-session turns serialise via `PooledClaudeSession.lock`.self._pool_lock = asyncio.Lock()self._reaper_task: Optional[asyncio.Task[None]] = Noneself._shutdown = asyncio.Event()@@ -151,19 +183,11 @@ class ClaudeSessionPool:)def peek(self, memory_node_id: str) -> Optional[PooledClaudeSession]:- """Return the live session for ``memory_node_id`` or ``None``.-- Useful for callers that need to know whether to issue a fresh- MCP bearer token before :meth:`acquire`. ``None`` means either- no entry or the entry's PTY has died (caller should issue a- fresh token for the impending cold-spawn). Best-effort: a TOCTOU- race between this check and a concurrent :meth:`acquire` is- harmless — the orphaned token leaks until app shutdown.- """+ """Return the live session for ``memory_node_id`` or ``None``."""session = self._pool.get(memory_node_id)if session is None:return None- if not session.pty_handle.is_alive():+ if session.process.returncode is not None:return Nonereturn session@@ -183,83 +207,77 @@ class ClaudeSessionPool:"""Return a live :class:`PooledClaudeSession`.Behaviour:- - **No live entry**: spawn fresh. ``spec.prompt`` is *not*- included in argv (the caller writes it via- :meth:`send_turn` once the watcher is attached).- - **Live entry**: return as-is. The next :meth:`send_turn`- writes the prompt to the existing PTY; claude appends to- its current JSONL so the conversation continues in the- same session UUID. **No implicit ``/clear``** — that would- break the memory bridge's continuity contract. The caller- can explicitly call :meth:`clear` to reset context (mints- a new UUID via ``/clear`` and swaps the watcher).- - **Dead entry**: drop and spawn fresh.-- Caller MUST call :meth:`release` (or use the contextmanager- wrapper) so the reaper can free idle sessions.++ - No live entry → spawn fresh.+ - Live entry whose subprocess is dead → drop and respawn,+ propagating ``current_session_uuid`` so the new spawn+ emits ``--resume <UUID>`` and continues the same JSONL.+ - Live entry with live subprocess → return as-is. Next+ ``send_turn`` writes the prompt to the existing subprocess's+ stdin and claude appends to the same session JSONL.++ Caller MUST call :meth:`release` so the reaper can mark idle."""async with self._pool_lock:existing = self._pool.get(memory_node_id)- if existing is not None and not existing.pty_handle.is_alive():+ crashed_uuid = ""+ if existing is not None and existing.process.returncode is not None:logger.info(- "[ClaudeSessionPool] dropping dead session for "- "memory_node=%s pid=%s",- memory_node_id, existing.pty_handle.pid,+ "[ClaudeSessionPool] dropping dead session "+ "memory_node=%s pid=%s exit=%s — will respawn",+ memory_node_id, existing.process.pid,+ existing.process.returncode,)+ crashed_uuid = existing.current_session_uuidawait self._terminate_locked(memory_node_id, reason="crashed")existing = Noneif existing is not None:- # Warm path. Take the per-session lock OUTSIDE the- # pool_lock to avoid deadlocks if a turn is still- # finishing.- pass- else:- # Cold path. Evict LRU if at capacity.- if len(self._pool) >= self._max_size:- await self._evict_lru_locked()- session = await self._spawn(- memory_node_id=memory_node_id,- spec=spec,- cwd=cwd,- env=env,- defaults=defaults,- mcp_endpoint_url=mcp_endpoint_url,- mcp_bearer_token=mcp_bearer_token,- connected_tool_names=connected_tool_names,- )- self._pool[memory_node_id] = session+ existing.last_used_at = time.monotonic()logger.info(- "[ClaudeSessionPool] spawned new session memory_node=%s "- "pid=%s uuid=%s",- memory_node_id, session.pty_handle.pid,- session.current_session_uuid,+ "[ClaudeSessionPool] warm reuse memory_node=%s pid=%s uuid=%s",+ memory_node_id, existing.process.pid,+ existing.current_session_uuid or "(unresolved)",)- # Typed CloudEvent — FE wires per-memory-node lifecycle- # status from the same envelope as agent_progress /- # node_parameters_updated. Fire-and-forget; broadcaster- # is the process-wide singleton.- await self._emit_event(- "spawned",- memory_node_id=memory_node_id,- workflow_id=workflow_id,- session_uuid=session.current_session_uuid,- pid=session.pty_handle.pid,- )- return session-- # Warm-reuse path. Returned as-is — preserves memory continuity- # (claude appends to its existing JSONL on the next prompt). The- # caller can opt in to context reset via the explicit- # :meth:`clear` method.- assert existing is not None- existing.last_used_at = time.monotonic()- logger.info(- "[ClaudeSessionPool] warm reuse memory_node=%s pid=%s uuid=%s",- memory_node_id, existing.pty_handle.pid,- existing.current_session_uuid,- )- return existing+ return existing++ if len(self._pool) >= self._max_size:+ await self._evict_lru_locked()++ # When recovering from a crash, splice the captured UUID+ # into the spec so the spawn emits ``--resume <UUID>``.+ if crashed_uuid and not spec.resume_session_id:+ spec.resume_session_id = crashed_uuid+ spec.continue_session = False++ session = await self._spawn(+ memory_node_id=memory_node_id,+ spec=spec,+ cwd=cwd,+ env=env,+ defaults=defaults,+ mcp_endpoint_url=mcp_endpoint_url,+ mcp_bearer_token=mcp_bearer_token,+ connected_tool_names=connected_tool_names,+ )+ if crashed_uuid:+ # The new subprocess is resuming the prior session; pre-seed+ # the UUID so the first turn's emitted CloudEvents carry+ # the right id even before the result event lands.+ session.current_session_uuid = crashed_uuid+ self._pool[memory_node_id] = session+ logger.info(+ "[ClaudeSessionPool] spawned new session memory_node=%s pid=%s",+ memory_node_id, session.process.pid,+ )+ await self._emit_event(+ "spawned",+ memory_node_id=memory_node_id,+ workflow_id=workflow_id,+ session_uuid=session.current_session_uuid,+ pid=session.process.pid,+ )+ return sessionasync def clear(self,@@ -267,43 +285,44 @@ class ClaudeSessionPool:*,workflow_id: Optional[str] = None,) -> str:- """Explicit ``/clear`` — mints a new session UUID and rotates- the watcher. Returns the new UUID. Use when the user wants to- start a fresh conversation in the same pooled process (e.g.- a "Clear conversation" button on simpleMemory). The memory- bridge auto-picks up the new UUID via the next ``send_turn``- result event."""- old_uuid = session.current_session_uuid- await self._clear_and_swap(session)- if session.current_session_uuid != old_uuid:+ """Kill the subprocess, drop the captured UUID. Next ``acquire``+ spawns fresh with no continuity flag (claude assigns a new+ session UUID).++ Stream-json input mode has no in-process slash-command+ equivalent of the TUI's ``/clear`` (the VSCode extension+ source confirms this — context resets are subprocess restarts,+ not slash messages). Emits ``claude.session.cleared`` for FE+ parity with the old PTY-era contract.+ """+ async with session.lock:+ old_uuid = session.current_session_uuid+ # Drop the pool entry and kill the subprocess.+ await self.terminate(session.memory_node_id)+ if old_uuid:await self._emit_event("cleared",memory_node_id=session.memory_node_id,workflow_id=workflow_id,old_session_uuid=old_uuid,- new_session_uuid=session.current_session_uuid,+ new_session_uuid="",)- return session.current_session_uuid+ return ""- async def release(- self, session: PooledClaudeSession,- ) -> None:- """Update last-used-at so the reaper measures idle time from now.-- Nothing else needed — the per-turn lock is released by- ``send_turn``'s context manager, so once ``release`` returns the- session is genuinely idle and the reaper may evict it.- """+ async def release(self, session: PooledClaudeSession) -> None:+ """Update ``last_used_at`` so the reaper measures from now."""session.last_used_at = time.monotonic()async def terminate(self, memory_node_id: str) -> None:- """Force-terminate a specific pooled session."""+ """Force-drop a specific pooled session."""async with self._pool_lock:await self._terminate_locked(memory_node_id)async def shutdown_all(self) -> None:- """Terminate every pooled session + stop the reaper. Wire into- FastAPI's lifespan ``shutdown`` event."""+ """Terminate every pooled subprocess + stop the reaper.++ Wire into FastAPI's lifespan ``shutdown`` event.+ """self._shutdown.set()if self._reaper_task is not None and not self._reaper_task.done():self._reaper_task.cancel()@@ -312,7 +331,6 @@ class ClaudeSessionPool:except (asyncio.CancelledError, Exception):passself._reaper_task = None-async with self._pool_lock:keys = list(self._pool.keys())for key in keys:@@ -326,18 +344,53 @@ class ClaudeSessionPool:timeout_seconds: int = 600,workflow_id: Optional[str] = None,) -> SessionResult:- """Write a prompt to a pooled session and await the next- ``result`` event. Serialises against other callers via the- session's lock. Emits a ``claude.session.usage`` CloudEvent- after each successful turn so the FE can render cost/token- data per memory node."""+ """Write one stream-json user message to ``proc.stdin`` and await+ the next ``result`` event from claude's stdout stream.++ The stdout reader task (started at spawn time) parses each line+ as a stream-json event and dispatches via+ :meth:`_handle_stream_event`. When the final ``result`` event+ lands, ``result_event`` is set and we return.++ Serialised by ``session.lock`` so two concurrent ``send_turn``+ calls can't interleave their stream-json lines on stdin.+ """async with session.lock:+ if session.process.returncode is not None:+ return self._build_result_from_events(+ session=session,+ events=[],+ prompt=prompt,+ success=False,+ error=(+ f"claude subprocess exited (code "+ f"{session.process.returncode}) before turn"+ ),+ )+session.result_event.clear()session.events_this_turn = []- # Claude's interactive TUI reads input on Enter (``\r``);- # closing stdin does NOT submit (claude-code#15553).- payload = (prompt.rstrip("\r\n") + "\r").encode("utf-8")- await session.pty_handle.write(payload)++ # Stream-json input shape — the VSCode extension's wire+ # format. Newline-delimited; one JSON object per turn.+ message = {+ "type": "user",+ "message": {"role": "user", "content": prompt},+ }+ payload = (json.dumps(message) + "\n").encode("utf-8")+ try:+ assert session.process.stdin is not None+ session.process.stdin.write(payload)+ await session.process.stdin.drain()+ except (ConnectionError, BrokenPipeError, AttributeError) as exc:+ return self._build_result_from_events(+ session=session,+ events=[],+ prompt=prompt,+ success=False,+ error=f"failed to deliver prompt to claude stdin: {exc}",+ )+try:await asyncio.wait_for(session.result_event.wait(),@@ -351,19 +404,24 @@ class ClaudeSessionPool:)return self._build_result_from_events(session=session,+ events=session.events_this_turn,prompt=prompt,success=False,error=f"timeout after {timeout_seconds}s",)+session.last_used_at = time.monotonic()result = self._build_result_from_events(session=session,+ events=session.events_this_turn,prompt=prompt,success=True,)- # Surface per-turn usage as a typed CloudEvent. Same data- # ``/usage`` displays in the TUI — but structured, so the FE- # can render a panel without scraping plain-text TUI output.+ # Persist the authoritative UUID from the result event so+ # crash-recovery respawns can emit ``--resume <UUID>``.+ if result.session_id:+ session.current_session_uuid = result.session_id+cu = result.canonical_usageawait self._emit_event("usage",@@ -381,7 +439,7 @@ class ClaudeSessionPool:return result# ------------------------------------------------------------------- # Spawn / clear / dispatch internals+ # Spawn internals# ------------------------------------------------------------------async def _spawn(@@ -396,24 +454,11 @@ class ClaudeSessionPool:mcp_bearer_token: Optional[str],connected_tool_names: Optional[List[str]],) -> PooledClaudeSession:- """Cold-spawn a new pooled claude session. Caller holds pool_lock."""- from services.claude_oauth import MACHINA_CLAUDE_DIR- from .session import _PROJECT_KEY_RE # noqa: PLC0415 — internal reuse-- # Where claude will write JSONLs for this cwd.- project_key = _PROJECT_KEY_RE.sub("-", str(cwd))- project_dir = Path(MACHINA_CLAUDE_DIR) / "projects" / project_key- try:- project_dir.mkdir(parents=True, exist_ok=True)- except OSError as exc:- logger.warning(- "[ClaudeSessionPool] mkdir project_dir failed dir=%s exc=%s",- project_dir, exc,- )-- # Build argv WITHOUT the prompt — we'll write the first turn's- # prompt to the PTY in `send_turn` so the spawn-to-ready path- # is the same as the post-/clear path.+ """Cold-spawn a new pooled claude subprocess. Caller holds pool_lock."""+ # ``include_prompt`` is ignored by the new ``interactive_argv``+ # (stream-json input mode reads the prompt from stdin), but we+ # pass ``False`` to make the intent explicit for any future+ # provider that still honours it.argv = self._provider.interactive_argv(spec,defaults=defaults,@@ -423,81 +468,124 @@ class ClaudeSessionPool:include_prompt=False,)- # Spawn via the cross-platform PTY transport.- transport = get_pty_transport()- spawn_time = time.monotonic()- pty_handle = await transport.spawn(argv, cwd=cwd, env=env)-- # Locate the JSONL claude is using. Works uniformly for fresh- # spawns (new file appears) and ``--continue`` spawns (existing- # file's mtime updates as claude appends a system/init event).- jsonl_path = await self._wait_for_session_jsonl(- project_dir, spawn_time,+ # Subprocess spawn — the VSCode-extension pattern. PIPE on+ # stdin/stdout/stderr; no PTY. The stdout-reader task below+ # parses each stream-json line into an event and dispatches it.+ process = await asyncio.create_subprocess_exec(+ *argv,+ cwd=str(cwd),+ env=env,+ stdin=asyncio.subprocess.PIPE,+ stdout=asyncio.subprocess.PIPE,+ stderr=asyncio.subprocess.PIPE,)- session_uuid = session_uuid_from_jsonl_path(jsonl_path) or ""-- # Build the session shell with placeholder watchers, then start- # them. Order: dir_watcher first so any subsequent /clear- # detects the post-clear file via the dir baseline. The bearer- # token is stored on the session so warm reuse can re-register- # the batch context with the SAME token the claude already has- # in its argv (the caller owns issue / unregister).+session = PooledClaudeSession(memory_node_id=memory_node_id,- project_dir=project_dir,- pty_handle=pty_handle,- current_session_uuid=session_uuid,- current_jsonl_path=jsonl_path,- dir_watcher=None, # type: ignore[arg-type]- jsonl_watcher=None, # type: ignore[arg-type]+ process=process,cwd=cwd,- bearer_token=mcp_bearer_token or "",)- async def _on_new_jsonl(path: Path) -> None:- session.new_jsonl_path = path- session.new_jsonl_event.set()+ # stdout reader — the single runtime contract in stream-json+ # output mode. Each line is one stream-json event+ # (``system/init``, ``assistant``, ``user``, ``result``,+ # ``system/compact_boundary``, etc.). We dispatch via+ # :meth:`_handle_stream_event` which populates the per-turn+ # buffer and signals ``result_event`` on the final event.+ async def _consume_stdout() -> None:+ assert process.stdout is not None+ try:+ while True:+ raw = await process.stdout.readline()+ if not raw:+ return+ line = raw.decode("utf-8", errors="replace").strip()+ if not line:+ continue+ try:+ event = json.loads(line)+ except json.JSONDecodeError:+ logger.debug(+ "[ClaudeSessionPool] stdout non-JSON line "+ "memory_node=%s line=%r",+ memory_node_id, line[:200],+ )+ continue+ try:+ await self._handle_stream_event(session, event)+ except Exception as exc: # pragma: no cover+ logger.warning(+ "[ClaudeSessionPool] handler raised "+ "memory_node=%s exc=%s",+ memory_node_id, exc,+ )+ except (asyncio.CancelledError, ConnectionError):+ return+ except Exception as exc: # pragma: no cover — defensive+ logger.debug(+ "[ClaudeSessionPool] stdout reader memory_node=%s exc=%s",+ memory_node_id, exc,+ )- def _make_event_handler(s: PooledClaudeSession):- async def _on_event(event: Dict[str, Any]) -> None:- await self._handle_jsonl_event(s, event)- return _on_event+ async def _drain_stderr() -> None:+ assert process.stderr is not None+ try:+ while True:+ raw = await process.stderr.readline()+ if not raw:+ return+ line = raw.decode("utf-8", errors="replace").rstrip()+ if line:+ logger.warning(+ "[ClaudeSessionPool] claude stderr "+ "memory_node=%s pid=%s: %s",+ memory_node_id, process.pid, line,+ )+ except (asyncio.CancelledError, ConnectionError):+ return+ except Exception as exc: # pragma: no cover — defensive+ logger.debug(+ "[ClaudeSessionPool] stderr drain memory_node=%s exc=%s",+ memory_node_id, exc,+ )- session.dir_watcher = JsonlDirWatcher(- project_dir, on_new_file=_on_new_jsonl,+ session.stdout_reader_task = asyncio.create_task(+ _consume_stdout(),+ name=f"ClaudeSessionPool.stdout_reader({memory_node_id})",)- await session.dir_watcher.start()- session.jsonl_watcher = JsonlWatcher(- jsonl_path,- on_event=_make_event_handler(session),- start_from_end=False,+ session.stderr_drain_task = asyncio.create_task(+ _drain_stderr(),+ name=f"ClaudeSessionPool.stderr_drain({memory_node_id})",)- await session.jsonl_watcher.start()return session- async def _handle_jsonl_event(+ # ------------------------------------------------------------------+ # Stream-json event dispatch+ # ------------------------------------------------------------------++ async def _handle_stream_event(self, session: PooledClaudeSession, event: Dict[str, Any],) -> None:- """Shared JSONL event dispatcher for both spawn-time and- post-``/clear`` watchers.+ """Per-event dispatcher for stream-json lines on ``proc.stdout``.Three concerns:- 1. Append to ``session.events_this_turn`` so :meth:`send_turn`- can build a :class:`SessionResult` from the turn's events.- 2. Set ``session.result_event`` when the provider's final- event arrives (``type == "result"``).- 3. Detect native compaction (``type=="system"``,- ``subtype=="compact_boundary"``) and forward to- :class:`CompactionService` so the existing token-tracking- pipeline accounts for it — avoids double-compaction- (client-side summarisation + native auto-compaction- running independently).+ 1. Capture the session UUID from any event that carries one+ (``system/init`` for fresh spawns, ``result`` for the+ authoritative value) so crash-recovery respawns can emit+ ``--resume <UUID>``.+ 2. Append to the per-turn buffer + signal ``result_event``+ on the final ``result`` event so ``send_turn`` returns.+ 3. Forward ``system/compact_boundary`` events to+ :class:`CompactionService` so the local-threshold path+ doesn't double-fire on claude's native auto-compaction."""+ sid = event.get("session_id") or event.get("sessionId")+ if sid and not session.current_session_uuid:+ session.current_session_uuid = sidsession.events_this_turn.append(event)if self._provider.is_final_event(event):session.result_event.set()-if (event.get("type") == "system"and event.get("subtype") == "compact_boundary"@@ -508,38 +596,24 @@ class ClaudeSessionPool:async def _record_native_compaction(session: PooledClaudeSession, event: Dict[str, Any],) -> None:- """Forward a ``system/compact_boundary`` event to the existing- :class:`CompactionService` so its token-state machine reflects- the native compaction that just happened.-- Without this, the local-threshold path in- ``services/ai.py:_track_token_usage`` and claude's own- auto-compaction would both trigger summarisations and the UI's- token gauge would race against claude's internal state.- """+ """Forward a ``system/compact_boundary`` event to+ :class:`CompactionService` so the local-threshold path doesn't+ double-fire on claude's native auto-compaction."""try:from services.compaction import get_compaction_service- except Exception: # pragma: no cover — defensive+ except Exception: # pragma: no coverreturn-svc = get_compaction_service()- if svc is None: # not initialised in test envs+ if svc is None:return-metadata = event.get("compact_metadata") or {}pre_tokens = int(metadata.get("pre_tokens") or 0)- # `tokens_after` after native compaction isn't directly visible- # in the JSONL — claude doesn't emit a "post-summary token- # count" event. The next `result` event's `usage` block will- # carry the true post-compaction cumulative; recording 0 here- # is a conservative reset that lets the next turn's `track()`- # call set the accurate cumulative.try:await svc.record(session_id=session.memory_node_id,node_id=session.memory_node_id,provider="claude",- model="", # claude doesn't emit the model on this event+ model="",tokens_before=pre_tokens,tokens_after=0,summary=None,@@ -550,132 +624,23 @@ class ClaudeSessionPool:session.memory_node_id, pre_tokens,metadata.get("trigger", "unknown"),)- except Exception as exc: # pragma: no cover — best-effort+ except Exception as exc: # pragma: no coverlogger.debug("[ClaudeSessionPool] compaction.record failed: %s", exc,)- async def _clear_and_swap(self, session: PooledClaudeSession) -> None:- """Send ``/clear``, await the new JSONL filename via the dir- watcher, swap the file watcher to the new path. Holds the- per-session lock so concurrent turns don't race."""- async with session.lock:- session.new_jsonl_event.clear()- session.new_jsonl_path = None- # Stop the current file watcher BEFORE sending /clear so- # any tail-end output of the old session doesn't leak into- # the new turn's events buffer.- await session.jsonl_watcher.stop()- session.events_this_turn = []- session.result_event.clear()-- # Slash commands must be at the start of a line; claude- # auto-fires on Enter.- await session.pty_handle.write(b"/clear\r")-- try:- await asyncio.wait_for(- session.new_jsonl_event.wait(),- timeout=_CLEAR_JSONL_TIMEOUT,- )- except asyncio.TimeoutError:- logger.warning(- "[ClaudeSessionPool] /clear didn't produce a new JSONL "- "memory_node=%s within %ss; falling back to mtime sort",- session.memory_node_id, _CLEAR_JSONL_TIMEOUT,- )-- new_path = session.new_jsonl_path- if new_path is None:- # Fallback: pick the newest .jsonl in the project dir.- try:- candidates = [- p for p in session.project_dir.iterdir()- if p.suffix == ".jsonl"- ]- if candidates:- new_path = max(candidates, key=lambda p: p.stat().st_mtime)- except OSError:- pass-- if new_path is not None and new_path != session.current_jsonl_path:- session.current_jsonl_path = new_path- session.current_session_uuid = (- session_uuid_from_jsonl_path(new_path) or ""- )- logger.info(- "[ClaudeSessionPool] /clear rotated memory_node=%s "- "new_uuid=%s",- session.memory_node_id, session.current_session_uuid,- )-- # Reattach the file watcher to whatever path we believe is- # current. If detection failed we re-watch the previous- # file — the next turn's `result` event will still fire.- # Reuses :meth:`_handle_jsonl_event` so the compaction +- # result-event detection are identical to the spawn path.- async def _on_event(event: Dict[str, Any]) -> None:- await self._handle_jsonl_event(session, event)-- session.jsonl_watcher = JsonlWatcher(- session.current_jsonl_path,- on_event=_on_event,- start_from_end=False,- )- await session.jsonl_watcher.start()-- async def _wait_for_session_jsonl(- self, project_dir: Path, spawn_time: float,- ) -> Path:- """Find the JSONL claude is using post-spawn via mtime.-- Works for both fresh-spawn (claude creates a new file) and- ``--continue`` (claude appends an init event to the most- recent existing file, updating its mtime). Picks the newest- ``.jsonl`` whose mtime is at least ``spawn_time - 1s`` (grace- for clock skew + filesystem mtime resolution).- """- deadline = spawn_time + _CLEAR_JSONL_TIMEOUT- mtime_floor = spawn_time - 1.0- while time.monotonic() < deadline:- try:- jsonls = [- p for p in project_dir.iterdir()- if p.suffix == ".jsonl"- ]- except OSError:- jsonls = []- if jsonls:- try:- newest = max(jsonls, key=lambda p: p.stat().st_mtime)- if newest.stat().st_mtime >= mtime_floor:- return newest- except OSError:- pass- await asyncio.sleep(0.1)- raise TimeoutError(- f"No session JSONL touched under {project_dir} within "- f"{_CLEAR_JSONL_TIMEOUT}s"- )-def _build_result_from_events(self,*,session: PooledClaudeSession,+ events: List[Dict[str, Any]],prompt: str,success: bool,error: Optional[str] = None,) -> SessionResult:- """Translate the per-turn event buffer to a ``SessionResult``.-- Reuses the provider's ``event_to_session_result`` so the cost- / token / response extraction stays identical to the non-- pooled path.- """+ """Translate per-turn JSONL events to a :class:`SessionResult`."""provider_result = self._provider.event_to_session_result(- session.events_this_turn,- stderr="",- exit_code=0 if success else -1,+ events, stderr="", exit_code=0 if success else -1,)final_success = success and provider_result.get("success", True)final_error = error or provider_result.get("error")@@ -693,14 +658,14 @@ class ClaudeSessionPool:tool_calls=int(provider_result.get("tool_calls", 0)),canonical_usage=provider_result.get("canonical_usage",- ) or self._provider.canonical_usage(session.events_this_turn),+ ) or self._provider.canonical_usage(events),provider_data=dict(provider_result.get("provider_data") or {}),success=final_success,error=final_error if not final_success else None,)# ------------------------------------------------------------------- # Eviction / reaper+ # Termination + eviction# ------------------------------------------------------------------async def _terminate_locked(@@ -709,35 +674,55 @@ class ClaudeSessionPool:*,reason: str = "explicit",) -> None:- """Caller holds ``self._pool_lock``. ``reason`` is the- CloudEvent ``reason`` value (``idle`` / ``crashed`` / ``evicted``- / ``shutdown`` / ``explicit``) — drives the- ``claude.session.terminated`` envelope."""+ """Caller holds ``self._pool_lock``. Stop the watcher, close+ stdin (graceful exit), wait briefly, then kill if still alive.+ Emits the ``claude.session.terminated`` CloudEvent."""session = self._pool.pop(memory_node_id, None)if session is None:returnsession_uuid = session.current_session_uuid- try:- await session.jsonl_watcher.stop()- except Exception as exc: # pragma: no cover — defensive- logger.debug(- "[ClaudeSessionPool] watcher stop on terminate: %s", exc,- )- try:- await session.dir_watcher.stop()- except Exception as exc: # pragma: no cover- logger.debug(- "[ClaudeSessionPool] dir watcher stop on terminate: %s", exc,- )- try:- await session.pty_handle.kill()- except Exception as exc: # pragma: no cover- logger.debug(- "[ClaudeSessionPool] PTY kill on terminate: %s", exc,- )++ # 1. Close stdin so claude can exit gracefully.+ process = session.process+ if process.returncode is None and process.stdin is not None:+ try:+ process.stdin.close()+ except (ConnectionError, BrokenPipeError, AttributeError):+ pass++ # 2. Brief grace period for graceful exit.+ if process.returncode is None:+ try:+ await asyncio.wait_for(process.wait(), timeout=_SHUTDOWN_GRACE)+ except asyncio.TimeoutError:+ pass++ # 3. Escalate to kill if still alive.+ if process.returncode is None:+ try:+ process.kill()+ await process.wait()+ except ProcessLookupError:+ pass+ except Exception as exc: # pragma: no cover+ logger.debug(+ "[ClaudeSessionPool] kill memory_node=%s exc=%s",+ memory_node_id, exc,+ )++ # 4. Cancel reader/drain tasks (they'll exit on their own when+ # the pipes close, but cancel makes the cleanup deterministic).+ for task in (session.stdout_reader_task, session.stderr_drain_task):+ if task is not None and not task.done():+ task.cancel()+ try:+ await task+ except (asyncio.CancelledError, Exception):+ pass+logger.info(- "[ClaudeSessionPool] terminated memory_node=%s reason=%s",- memory_node_id, reason,+ "[ClaudeSessionPool] terminated memory_node=%s pid=%s reason=%s",+ memory_node_id, process.pid, reason,)await self._emit_event("terminated",@@ -754,8 +739,6 @@ class ClaudeSessionPool:if not sess.lock.locked()]if not idle_entries:- # All sessions in-flight; nothing safe to evict. Caller- # spawns over the soft cap.logger.info("[ClaudeSessionPool] all %d entries in-flight; pool over cap",len(self._pool),@@ -770,7 +753,7 @@ class ClaudeSessionPool:await self._terminate_locked(oldest_key, reason="evicted")# ------------------------------------------------------------------- # CloudEvent emission helper+ # CloudEvent emission helper (unchanged)# ------------------------------------------------------------------async def _emit_event(@@ -783,16 +766,15 @@ class ClaudeSessionPool:) -> None:"""Dispatch one of the four claude-session CloudEvents.- Lazy-imports the broadcaster singleton so the pool stays a- leaf service. Failures are swallowed (best-effort) — a missed- UI update must not break the agent loop.+ Lazy-imports the broadcaster singleton so the pool stays a leaf+ service. Best-effort: a missed UI update must not break the+ agent loop."""try:from services.status_broadcaster import get_status_broadcasterbroadcaster = get_status_broadcaster()- except Exception: # pragma: no cover — defensive+ except Exception: # pragma: no coverreturn-try:if kind == "spawned":await broadcaster.broadcast_claude_session_spawned(@@ -832,10 +814,9 @@ class ClaudeSessionPool:num_turns=payload.get("num_turns"),workflow_id=workflow_id,)- except Exception as exc: # pragma: no cover — best-effort+ except Exception as exc: # pragma: no coverlogger.debug(- "[ClaudeSessionPool] _emit_event(%s) failed: %s",- kind, exc,+ "[ClaudeSessionPool] _emit_event(%s) failed: %s", kind, exc,)async def _reaper_loop(self) -> None:@@ -846,14 +827,11 @@ class ClaudeSessionPool:self._shutdown.wait(),timeout=self._reaper_interval,)- return # shutdown fired+ returnexcept asyncio.TimeoutError:pass-now = time.monotonic()async with self._pool_lock:- # Skip in-flight sessions — a turn that takes longer- # than idle_ttl would otherwise get reaped mid-flight.expired_keys = [key for key, sess in self._pool.items()if not sess.lock.locked()diff --git a/server/tests/conftest.py b/server/tests/conftest.pyindex 5f925c64..6ad46a55 100644--- a/server/tests/conftest.py+++ b/server/tests/conftest.py@@ -56,6 +56,28 @@ def _stub_log_execution_time(*_args, **_kwargs):# real submodule attributes so imports resolve without touching the real# heavy deps (dependency_injector, cryptography, ...)._core_pkg = _make_package("core")+def _stub_log_context(**_fields):+ """Stub for ``core.logging.log_context`` (async ctx manager) and+ ``log_context_sync``. Both are no-ops under test."""+ from contextlib import asynccontextmanager, contextmanager++ @asynccontextmanager+ async def _async_cm():+ yield++ return _async_cm()+++def _stub_log_context_sync(**_fields):+ from contextlib import contextmanager++ @contextmanager+ def _sync_cm():+ yield++ return _sync_cm()++_make_submodule("core","logging",@@ -63,6 +85,8 @@ _make_submodule("get_logger": MagicMock(return_value=MagicMock()),"log_execution_time": _stub_log_execution_time,"log_api_call": MagicMock(),+ "log_context": _stub_log_context,+ "log_context_sync": _stub_log_context_sync,},)_make_submodule("core", "container", {"container": MagicMock()})diff --git a/server/tests/services/cli_agent/test_providers.py b/server/tests/services/cli_agent/test_providers.pyindex 90a04dc1..f7a8fd59 100644--- a/server/tests/services/cli_agent/test_providers.py+++ b/server/tests/services/cli_agent/test_providers.py@@ -74,33 +74,41 @@ class TestClaudeArgv:def test_minimum_required_flags(self, claude_provider):task = ClaudeTaskSpec(prompt="hello world")argv = claude_provider.interactive_argv(task, defaults={})- # Prompt is the positional after `--` (interactive mode). No- # `-p` / `--print` / `--output-format stream-json` anymore.+ # VSCode-extension pattern (stream-json over stdio pipes, no PTY).+ # ``-p`` / ``--print`` are NEVER emitted — we stay in interactive+ # billing (entrypoint ``claude-vscode``, not ``sdk-cli``).assert "-p" not in argvassert "--print" not in argv- assert "--output-format" not in argv- assert "--verbose" not in argv- assert "--include-partial-messages" not in argv- assert "--include-hook-events" not in argv- assert "--" in argv- assert "hello world" in argv- # Ordering: `--` immediately precedes the prompt.- sep_idx = argv.index("--")- assert argv[sep_idx + 1] == "hello world"+ # Stream-json I/O flags ARE emitted now (replace the headless+ # PTY pattern):+ assert "--output-format" in argv+ out_idx = argv.index("--output-format")+ assert argv[out_idx + 1] == "stream-json"+ assert "--input-format" in argv+ in_idx = argv.index("--input-format")+ assert argv[in_idx + 1] == "stream-json"+ assert "--verbose" in argv # required for stream-json detail+ assert "--ide" in argv # lockfile auto-discovery+ # The prompt is NEVER a positional in stream-json mode — it goes+ # over ``proc.stdin``. ``--`` separator is gone.+ assert "--" not in argv+ assert "hello world" not in argv# Defaults appliedassert "--model" in argvassert "claude-sonnet-4-6" in argv # default_model from JSON- # `-p`-only flags no longer emitted+ # ``-p``-only flags still not emitted (kept on the spec for back-compat)assert "--max-turns" not in argvassert "--max-budget-usd" not in argvassert "--fallback-model" not in argv# Tool + permission machinery preservedassert "--allowedTools" in argvassert "--permission-mode" in argv- # `bypassPermissions` is the documented mode for non-interactive- # automation (https://code.claude.com/docs/en/permission-modes).+ # Default permission mode is read from ``config/ai_cli_providers.json``+ # (currently ``acceptEdits``). Callers wanting ``bypassPermissions``+ # set it explicitly on ``task.permission_mode`` or via the per-call+ # ``defaults`` arg.perm_idx = argv.index("--permission-mode")- assert argv[perm_idx + 1] == "bypassPermissions"+ assert argv[perm_idx + 1] == "acceptEdits"def test_no_session_id_flag_in_interactive(self, claude_provider):"""Claude assigns its own session UUID in interactive mode; we@@ -162,17 +170,24 @@ class TestClaudeArgv:assert "--append-system-prompt" in argvassert "be concise" in argv- def test_include_prompt_false_omits_positional(self, claude_provider):- """The session pool uses `include_prompt=False` when spawning a- process whose first prompt will be written to the PTY (e.g.- after a `/clear`). The argv carries no positional prompt and- therefore no `--` separator."""- task = ClaudeTaskSpec(prompt="will-be-piped-to-pty")- argv = claude_provider.interactive_argv(+ def test_include_prompt_is_ignored_in_stream_json_mode(self, claude_provider):+ """``include_prompt`` is kept on the signature for back-compat+ but is intentionally ignored in stream-json input mode — passing+ ``-- "<prompt>"`` would double-send the first turn (once via+ argv, once via stdin). Both ``True`` and ``False`` produce the+ same argv shape: no ``--`` separator, no positional prompt."""+ task = ClaudeTaskSpec(prompt="will-be-piped-via-stdin")+ argv_true = claude_provider.interactive_argv(+ task, defaults={}, include_prompt=True,+ )+ argv_false = claude_provider.interactive_argv(task, defaults={}, include_prompt=False,)- assert "--" not in argv- assert "will-be-piped-to-pty" not in argv+ for argv in (argv_true, argv_false):+ assert "--" not in argv+ assert "will-be-piped-via-stdin" not in argv+ # Same shape regardless of the back-compat flag.+ assert argv_true == argv_falsedef test_wrong_task_type_raises(self, claude_provider):codex_task = CodexTaskSpec(prompt="x")