CAP protocol both directions: agent speak plus orchestrator drivers (1.39.0)

- Agent side: --cap-manifest plus --cap-speak stream-json binding with
  transcript-diff frames, diff/transcript artifacts, session config
- Orchestrator: PTY driver (settle heuristics on PtyProc/TuiVtScreen),
  stream-json, ACP-stdio (permission/elicit/fs/terminal serving) and
  A2A drivers (dual draft/current spelling, SSE mapping)
- Sessions, fleets: worktrees, master plans, mediated routing,
  budget refusal, audit log, research auto-answerer, --cap CLI
- cap.md contract with drift tests; research/cap-protocol archive
- Suites 1119 + 16 green

.gitignore

@@ -11,6 +11,7 @@
 *.md
 !research/**/*.md
 !uiflow.md
+!cap.md
 
 # Backup files
 *.bak

AGENTS.md

@@ -10,6 +10,7 @@
 - The grr terminal client (`tai.py --tui`, the `Grr*` classes) is specified in [grrtui.md](grrtui.md): read it before touching any `Grr*` code, and keep its screen, key and cap tables in step with the code (`GrrSpecTests` fails when they drift). It is a client of the grr server and shows what the server's `/api/spec` and `/locales.json` say; never copy a string, color or limit of the server into `tai.py`. `tests/grr_tui.py` drives the real binary against a real grr server (sibling `../grr`, `GRR_DIR` to move it) and a real model.
 - The terminal multiplexer (`Mplex*` classes, `tai.py --mplex`, `~/.tai/mplex.toml`) is specified in [mplex.md](mplex.md): read it before touching any `Mplex*` code, and keep its option, command and key tables in step with the code (`MplexSpecTests` fails when they drift).
 - Interactive UI flows (`plexer_show`, `PlexerFlow`, `PlexerController.ask`, the `show`/`result`/`cancel` control commands) are specified in [uiflow.md](uiflow.md): read it before touching any flow code, and keep its contract and cap tables in step with the code (`UiflowDocTests` fails when they drift).
+- CAP protocol support (`Cap*` classes, `--cap-manifest`, `--cap-speak`, orchestrator drivers) is specified in [cap.md](cap.md): read it before touching any `Cap*` code, and keep its event, error and manifest tables in step with the code (`CapDocTests` fails when they drift).
 
 ## Testing
 

cap.md

@@ -0,0 +1,294 @@
+# CAP support in tai (`Cap*`)
+
+Tai speaks the CLI Agent Protocol both directions: as an agent
+(`--cap-manifest`, `--cap-speak`) and as an orchestrator driving
+other CLI agents. Normative upstream: CAP Core v1 plus the coding
+profile; research archive is `research/cap-protocol/`.
+Protocol id `CAP_VERSION`, manifest schema
+`CAP_MANIFEST_SCHEMA`, coding profile id `CAP_PROFILE_CODING`,
+shipped manifest revision `CAP_MANIFEST_REVISION`.
+
+## Conformance claim
+
+- Agent: CLI-invokable, publishes `TAI_CAP_MANIFEST` via
+  `--cap-manifest`, matches the PTY contract and speaks
+  stream-json via `--cap-speak`. Claims the `coding` profile.
+- Orchestrator: reads manifests via `CapRegistry`, implements PTY
+  plus stream-json plus ACP-stdio plus A2A bindings (gRPC
+  excluded, see Deviations), honors the §10 rules below, and
+  serves the reverse RPC it advertises.
+
+## Phases
+
+1. Events, errors, manifest registry, `--cap-manifest`. DONE.
+2. Agent `--cap-speak` stream-json binding, coding artifacts. DONE.
+3. Orchestrator PTY driver (`CapPtyDriver` on `PtyProc` plus
+   `TuiVtScreen`, parse). DONE.
+4. Orchestrator stream-json driver plus §10 orchestration
+   (`CapSession`, `CapFleet`, worktrees, budget). DONE.
+5. ACP-stdio and A2A drivers, reverse RPC serving, research
+   auto-answerer (`CapAnswerer`). DONE.
+
+## Core events (`CapEvent`)
+
+Kinds in `CapEvent.KINDS`:
+
+Agent to orchestrator: `cap.session.ready`, `cap.text_chunk`,
+`cap.tool_call.start`, `cap.tool_call.delta`, `cap.tool_call.end`,
+`cap.plan`, `cap.thought`, `cap.ask_user`, `cap.permission.request`,
+`cap.usage`, `cap.error`, `cap.artifact`, `cap.fs.change`,
+`cap.pty.raw_bytes`.
+Orchestrator to agent: `cap.user_input.inject`, `cap.cancel`,
+`cap.session.config`, plus answers `cap.ask_user.answer` and
+`cap.permission.response`. Directions live in
+`CapEvent.DIRECTIONS`, required fields in `CapEvent.REQUIRED`.
+
+Enum vocab: `channel` is `assistant`, `thought` or `system`;
+`status` is `pending`, `in_progress`, `completed`, `cancelled` or
+`blocked`; `priority` is `urgent`, `high`, `medium` or `low`;
+`scope` (cancel) is `current_turn` or `session`;
+`risk_level` is `low`, `medium` or `high`; `decision` is
+`allow_once`, `allow_always` or `deny`; `permission_mode` is
+`none`, `confirm` or `interactive`; `stop_reason` is `end_turn`,
+`max_tokens`, `tool_use`, `stop_sequence`, `cancelled` or `error`.
+
+## Errors
+
+`CAP_ERROR_CODES` maps numerics to symbols, `CAP_ERROR_SYMBOLS`
+maps back. Core: `-32001 cap_manifest_missing`, `-32002
+cap_session_config_missing`, `-32003 cap_unsupported_capability`,
+`-32004 cap_budget_exceeded`, `-32005 cap_invalid_answer`,
+`-32006 cap_unknown_permission`, `-32007
+cap_queued_input_unsupported`, `-32008 cap_cancel_unsupported`,
+`-32009 cap_binding_unavailable`, `-32010 cap_profile_unsupported`.
+Coding: `-32020 cap_scope_violation`, `-32021 cap_path_not_found`,
+`-32022 cap_io_error`, `-32023 cap_terminal_unavailable`,
+`-32024 cap_terminal_killed`.
+
+`CAP_ERROR_STRINGS` holds the `cap.error` string codes: core
+`rate_limit`, `auth_error`, `tool_timeout`, `context_overflow`,
+`model_unavailable`, `pty_died`, `parse_failed`; coding
+`git_dirty`, `test_failed`, `merge_conflict`,
+`language_server_down`. Wire failures raise `CapError`.
+
+## Manifests (`CapManifest`, `CapRegistry`)
+
+Required (§5.2): `agent.name`, `agent.binary`,
+`agent.profiles`, `startup.command`, `startup.ready_when`,
+`pty.cols`, `pty.rows`, `capabilities.streaming_output`.
+Defaults (§5.3) in `CapManifest.DEFAULTS`:
+`pty.bracketed_paste` false, `pty.sigint_cancels_turn` hard,
+`pty.queued_input_supported` false, `capabilities.multi_session`
+false, `capabilities.ask_user.*` all false,
+`capabilities.streaming_tool_output` false, `cost.metered` false,
+`parse.idle` the `>`/`❯` pair, all other `parse.*` unset,
+`parse.error_lines` empty.
+
+Resolution order in `CapRegistry`: binary sibling
+`cap-agent.toml`, user-local `~/.config/cap/agents/`,
+system-wide `/usr/share/cap-agents/`, probe
+`<binary> --cap-manifest` with timeout `CAP_PROBE_TIMEOUT`
+seconds. Override dirs via constructor args in tests.
+
+## Bindings (`CapBinding`)
+
+Priority `CapBinding.ORDER`: `grpc`, `stream_json`, `acp_stdio`,
+`a2a`, `pty`. `CapBinding.UNSUPPORTED` is `grpc` only (stdlib
+has no HTTP/2 or protobuf); selection falls through past it.
+Manifest booleans `false` and absent fields mean the same:
+not supported. A2A tries draft endpoints first
+(`POST /message/send`, `/tasks/cancel`), then current A2A
+(`POST /message:send`, `POST /tasks/{id}:cancel`). The ACP
+server argv is out-of-band (fleet `argv`, chat `--argv`):
+the manifest carries no ACP command. Pipe drivers share
+`CapPipeReader` (non-blocking NDJSON, `CAP_STREAM_LINE_MAX`
+shared cap), `cap_stderr_drain`, `cap_proc_kill` and
+`cap_proc_reap`.
+
+## Reverse RPC served by the orchestrator
+
+Core: `cap.user_io.show`, `cap.user_io.input`, `cap.notify`.
+Coding fs: `cap.fs.read`, `cap.fs.write`, `cap.fs.list`,
+`cap.fs.exists`, `cap.fs.delete`, `cap.fs.watch`. Coding
+terminal: `cap.terminal.create`, `cap.terminal.output`,
+`cap.terminal.wait`, `cap.terminal.kill`, `cap.terminal.release`.
+Scope enforcement: `workspace_only` is the session `cwd`
+subtree, `project_root` the VCS-root ancestor subtree,
+`unrestricted` nothing (discouraged); symlinks resolve before
+the check and MUST NOT escape.
+
+`CapAcpDriver` speaks ACP v1 (`CAP_ACP_VERSION`) over stdio:
+initialize handshake, `session/new`, prompt turns with the
+C.3 update mapping (message/thought chunks, tool calls,
+plan, usage deltas). It serves `fs/read_text_file` and
+`fs/write_text_file` (line windows, `CAP_ACP_FS_MAX` bytes),
+`terminal/*` (grants, `CAP_ACP_TERMINALS_MAX` concurrent,
+`CAP_ACP_TERM_BUF` retention, `CAP_ACP_TERM_WAIT_MAX` wait
+cap), form `elicitation/create` (URL declined), and tai
+`_cap/*` extensions for `fs.list`/`exists`/`delete` plus
+`user_io.show`/`input` and `notify`. Permission, elicitation
+and input answers flow through the unified `open_asks` stash.
+
+`CapA2aDriver` refuses cards without the `cap-protocol/v1`
+extension, posts messages (flavor sticky after discovery),
+and maps SSE payloads: raw `cap.*` events, `_meta.cap.kind`
+data parts, text parts, task states (input-required opens
+an ask, terminal states end the turn), plain artifacts.
+Answers return as marked data parts. HTTP timeout
+`CAP_A2A_TIMEOUT` (30). Tai does not expose sessions over
+A2A (server side unbuilt).
+
+## Orchestration (§10)
+
+Sessions get `cap://` URNs stable per orchestrator. Master
+plans carry `_meta.cap.assigned_to` and `_meta.cap.depends_on`;
+sub-agents never talk directly, every `@cap://` directive
+routes through the orchestrator into the audit log. Coding
+sub-agents get git worktrees under `.cap-worktrees/`, merged
+by the orchestrator. Usage aggregates across the fleet and the
+orchestrator hard-cancels past budget. Interruption is
+cooperative: cancel the turn, keep partial text, resend with
+the correction.
+
+`CapSession` pumps one driver on its own thread, queues
+events, and blocks per turn in `ask` with `CAP_TURN_TIMEOUT`
+(600); `CapTurnResult` carries the turn events, end state,
+usage delta and joined text. `CapFleet` provisions git
+worktrees per coding session (plain dirs outside git, both
+tracked and removed on close), publishes validated master
+plans, routes `@cap://` mentions (`CAP_MENTION_RE`) through
+per-session pending queues (`CAP_ROUTE_QUEUE_MAX`, 16,
+idle-only delivery), refuses new turns past `budget_usd`,
+and keeps every mediation in the audit log.
+`collect_diffs` reports bounded per-worktree diffs
+(`CAP_FLEET_DIFF_MAX`, 65536); merging stays the operator's
+call. Poll cadence `CAP_SESSION_POLL` (0.1), worktree root
+`CAP_WORKTREE_DIR`.
+
+`CapFleet.set_answerer` installs a `CapAnswerer`: open asks
+and permission requests each get one daemon research thread
+(deduped, counted busy by `wait_idle`, audited). Policy
+first (deny list, allow list, `max_risk` over
+`CAP_ANSWER_RISKS`), then an isolated tai one-shot
+(`--auto`, own vault under `cap-research`) bounded by
+`CAP_ANSWER_TIMEOUT` (300) and `CAP_ANSWER_PARALLEL` (4);
+the value comes from the last `CAP_ANSWER_MARKER` line.
+Failures fall back safe (deny, False, unknown). CLI:
+`--auto-answer`, `--allow-tool`, `--deny-tool`, `--max-risk`
+(`cap_answer_flags`, `cap_build_answerer`); fleet file
+`auto_answer`, `allow_tools`, `deny_tools`, `max_risk`.
+
+## Stream driver (`CapStreamDriver`)
+
+NDJSON over pipes with the C.1 mapping (init to ready,
+assistant blocks to chunk/thought/tool start, tool results
+to tool end, result to usage or error, tai `artifact`
+frames to `cap.artifact`, unknown lines counted in
+`ignored_frames`). stdout is non-blocking with a manual
+line buffer capped at `CAP_STREAM_LINE_MAX` (1048576);
+stderr drains on a daemon thread into the last
+`CAP_STREAM_STDERR_KEEP` (50) lines, quoted on unexpected
+exit. Turn cancel kills the one-shot process and the next
+send respawns lazily.
+
+## PTY heuristics (`CapPtyDriver`)
+
+`CapDriver` is the shared base (identity, event queue, id
+sequences, send guards, spawn-then-ready start). States in
+`CapDriver.STATES`: starting, ready, working,
+input_required, done, failed, closed. `done` ends the turn
+with the session alive; `closed` and `failed` are terminal.
+
+Spawns under `PtyProc`, renders through `TuiVtScreen`
+(`text_lines`), writes terminal replies back. Settle window
+`CAP_PTY_SETTLE_MS` (800), prompt gate (no Done before the
+first real prompt), bounded resubmits
+`CAP_PTY_RESUBMITS_MAX` (3), wait-for-ready before the first
+prompt, 150ms text-to-Enter gap `CAP_PTY_SUBMIT_GAP_MS`,
+scrollback `CAP_PTY_SCROLLBACK` (10000), raw-bytes stream
+opt-in only via `raw_sink`. Idle is the idle regex on the
+last line plus 200ms silence `CAP_PTY_IDLE_MS`; boot ready
+needs the marker plus the same silence. Boot timeout
+`CAP_PTY_INIT_TIMEOUT` (60) when the manifest sets none.
+
+Line events from fresh rendered rows, first match wins:
+error lines to `cap.error` (`rate_limit`/`auth_error` by
+substring, else `error`), tool start/end pairing by call
+id, ask patterns to `cap.ask_user` (answered via
+`CapPtyDriver.answer`), plan/thought markers to `cap.plan`
+/ `cap.thought`. Identical line events suppress repeats
+per turn. Cancel consults `capabilities.mid_turn_cancel`
+over `pty.sigint_cancels_turn` over hard; queued input
+consults `capabilities.queued_input` over
+`pty.queued_input_supported` over false.
+
+## CLI surface
+
+- `--cap-manifest`: print `TAI_CAP_MANIFEST` and exit 0. No
+  vault, no network, no boot. Phase 1.
+- `--cap-speak`: stream-json over stdio (agent side). Bulk
+  session config via `CAP_SESSION_CONFIG` (JSON
+  `cap.session.config`); `--cap-cwd`, `--cap-model`,
+  `--cap-permission-mode`, `--cap-max-turns` override single
+  fields. Phase 2.
+- `cap` orchestrator commands via `--cap` (`cap_cli_main`,
+  `cap_cli_help`): `resolve` (`cap_resolve_main`), `chat`
+  (`cap_chat_main`, task once plus tty REPL, `--argv` for
+  ACP servers), `run` (`cap_run_main` over a `fleet.toml`
+  validated by `cap_fleet_plan`). Results print via
+  `cap_print_result`. Phase 4.
+
+`fleet.toml` schema: `[fleet]` with `start` (a session URN),
+`task`, optional `budget_usd`, `auto_answer`, `allow_tools`,
+`deny_tools`, `max_risk`; `[[sessions]]` with `name`,
+`agent` (registry key), optional `cwd`/`model`/`argv`;
+`[[routes]]` with `when` (source URN, `.done` suffix
+allowed) and `route_to`. Routes run statically in order,
+each feeding the source's last text into the target.
+
+## Speak path (`CapSpeakSession`)
+
+`CapSessionConfig` parses env plus flags; `CapStreamJson`
+builds Claude-compatible frames and parses inbound user
+frames; `CapSpeakSession` runs each turn through
+`Agent.run_turn` with stdout parked on stderr and emits the
+transcript diff (assistant frames, grouped tool results,
+result frame) plus a `diff` artifact when the tree changed.
+`CAP_SPEAK_MAX_TURNS` (50) caps turns when unset;
+`CAP_SPEAK_DIFF_MAX` (65536) caps inline diff bytes.
+
+Permission mapping: `none` boots yolo, `confirm` and
+`interactive` boot auto (research instead of asking); stdin
+is never read for prompts. Artifacts travel as tai
+`artifact` frames (receivers ignore unknown types); the
+`transcript` artifact is a `file://` URI under
+`cap-transcripts/`, written at session end. Constants
+`CAP_SESSION_CONFIG_ENV`, `CAP_SPEAK_MAX_TURNS`,
+`CAP_SPEAK_DIFF_MAX`; entry `cap_speak_main`; cancel via
+`cap_interrupt` (SIGTERM acts like Ctrl-C, emits an error
+result, exits 130).
+
+## Deviations from upstream
+
+- gRPC binding not implemented (stdlib).
+- Regex flavor: tai accepts Python named groups `(?P<>)`
+  (every shipped example uses them) and rejects only
+  lookaround and backreferences, against the letter of §5.4.
+- No fs/terminal mediation on the agent speak path: reverse
+  RPC framing over stream-json is unspecified upstream.
+- A2A dual spelling (draft first, current fallback).
+- Worktrees under `.cap-worktrees/` per the profile text, not
+  the reference CLI's `.cap/`.
+- PTY submit sends CR, not the spec's LF: CR is Enter in both
+  canonical and raw terminal modes.
+- Idle/prompt rows never emit `cap.text_chunk`; no usage
+  events on the PTY path (agents report none).
+- Tool end output is empty (PTY shows no result payload);
+  plan entries carry the marker line as content.
+- A2A expose (serving tai sessions over A2A) is not built;
+  tai drives A2A agents but does not serve them.
+- ACP `terminal/wait_for_exit` is capped at 600s and reports
+  null exit codes when still running; v2 renames deferred.
+- `_cap/fs.list`/`exists`/`delete` and `_cap/user_io.*`
+  shapes are tai-defined (the profile fixes methods, not
+  JSON shapes).

research/INDEX.md

@@ -6,11 +6,11 @@
 
 | Metric | Value |
 |---|---|
-| Subjects | 12 |
-| Total source documents | 667 |
-| — Tier 1 (Source Dossier, independently analyzed) | 193 |
-| — Tier 2 (Source Citation Card, listed only) | 474 |
-| Total conclusion documents | 27 |
+| Subjects | 13 |
+| Total source documents | 691 |
+| — Tier 1 (Source Dossier, independently analyzed) | 216 |
+| — Tier 2 (Source Citation Card, listed only) | 475 |
+| Total conclusion documents | 29 |
 | Archive opened | 2026-10-09 |
 | Last updated | 2026-10-18 |
 
@@ -30,6 +30,7 @@
 | [`prompt-context-scaling`](prompt-context-scaling/) | 34 (10 / 24) | 3 | 2026-10-18 | 2026-10-18 | Scaling prompts past the context window and reusing RAG/graph for more; tai already matches the converged arsenal, giant prompts should spill to retrievable records (specified, not built), full GraphRAG and memory vendors rejected |
 | [`background-work-limits`](background-work-limits/) | 10 (4 / 6) | 2 | 2026-10-18 | 2026-10-18 | Bounding parallel subagents and hardening the scheduler; parallel cap 8 with reject-loud, per-tick fires 4, one live run per schedule via lease, stated misfire policy; implemented same day |
 | [`sandbox-resource-caps`](sandbox-resource-caps/) | 21 (3 / 18) | 1 | 2026-10-18 | 2026-10-18 | Capping the agent sandbox box CPU/memory/pids after the coverage audit found it uncapped; static trio 2g/2.0/256 at create, best-effort update for existing boxes, pids via recreation; implemented same day |
+| [`cap-protocol`](cap-protocol/) | 24 (23 / 1) | 2 | 2026-10-18 | 2026-10-18 | Supporting CAP (CLI Agent Protocol) as agent and orchestrator: full read of core + coding profile, quickstart, STATUS, all 5 manifests; selective A2A/ACP wire reads; decided phased rollout without gRPC plus dual A2A spelling |
 
 ## Recent activity log
 
@@ -57,6 +58,7 @@
 | 2026-10-18 | `sqlite-rag-hybrid-search` | Extended with 28 sources (7 Tier 1 / 21 Tier 2) + 2 conclusions (`conclusions/standing-retrieval-eval.md`, `conclusions/lexical-tuning-roadmap.md`), closing the original conclusion's open risk on unmeasured retrieval quality: rank metrics (Hit@K/MRR/nDCG/Context Precision), goldens generalized from the fingerprint method, implicit search-then-read preferences, query logging gap, and an ordered tuning backlog (column weights, OR-fallback, prefix) with HyDE/RM3/embeddings rejected. Counts verified directly against the written files via `research/audit.py` (PASS). |
 | 2026-10-18 | `background-work-limits` | New subject: 10 sources (4 Tier 1 / 6 Tier 2) + 2 conclusions, covering supervisor bounds (OTP intensity, semaphore reject-loud) and scheduler policies (APScheduler max_instances/coalesce, Temporal Skip, cron) after a feature-coverage audit found orchestration and scheduling unresearched. Decisions implemented same day: AGENTS_MAX_PARALLEL 8 with AgentsFull refusal, 64-record retention with oldest-collected purge, 4 fires per tick, one live run per schedule via last_status lease, stated misfire policy, no auto-retry. Counts verified directly against the written files via `research/audit.py` (PASS). |
 | 2026-10-18 | `sandbox-resource-caps` | New subject: 21 sources (3 Tier 1 / 18 Tier 2) + 1 conclusion, covering container resource caps (Docker limits reference, podman-run flag parity, podman-update create-only pids gap) plus snippet corroboration of the memory/cpus/pids trio after the coverage audit found the sandbox box fully uncapped. Decision implemented same day: static `--memory=2g --cpus=2.0 --pids-limit=256` at box create for both engines, one best-effort `update` (memory plus cpus) per process for existing boxes, concrete `rm -f` recovery pointer on failure. Counts verified directly against the written files via `research/audit.py` (PASS). |
+| 2026-10-18 | `cap-protocol` | New subject: 24 sources (23 Tier 1 / 1 Tier 2) + 2 conclusions, covering CAP core v1 and the coding profile read in full, quickstart, STATUS, all 5 example manifests, A2A spec + proto (selective), 10 ACP pages (selective), and the reference A2A driver (grepped). Decisions: implement all bindings except gRPC in 5 phases (manifest/events, agent speak, PTY driver, stream-json + orchestration, ACP/A2A + auto-answer); try draft then current A2A endpoint spellings. Counts verified directly against the written files via `research/audit.py` (PASS). |
 
 ## How to use this index
 

research/cap-protocol/a2a-proto.md

@@ -0,0 +1,50 @@
+# A2A a2a.proto (wire shapes)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | cap-protocol |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | A2A specification/a2a.proto |
+| Source URL | https://github.com/a2aproject/A2A/blob/main/specification/a2a.proto |
+| Source type | schema |
+| Source date (published) | Unknown, not stated (living file) |
+| Date researched | 2026-10-18 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct raw-file fetch, read selectively (TaskState, TaskStatus, Part, TaskStatusUpdateEvent, AgentExtension) |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+The machine-readable A2A schema behind the template-generated spec tables: 9-state TaskState enum, TaskStatus (state + message + timestamp), Part oneof (text/raw/url/data + metadata + filename + media_type), status/artifact update events, AgentExtension (uri/description/required/params).
+
+## Key findings
+
+- `TASK_STATE_INPUT_REQUIRED = 6` exists, validating CAP's C.4 mapping row; JSON form is lowercase (`working`, `input-required`, ...).
+- Parts are a oneof: exactly one of text/raw/url/data, with media_type on all variants; CAP's TextPart/DataPart map to the text/data arms.
+- TaskStatusUpdateEvent carries task_id + context_id + full TaskStatus; artifact updates are separate events, matching CAP's split mapping.
+- context_id is REQUIRED on updates: multi-turn correlation key tai's driver must persist per session.
+
+## Pros / strengths
+
+- Unambiguous field shapes with presence/required annotations; no prose interpretation needed.
+- Confirms CAP's event mapping (C.4) is implementable against real A2A frames.
+
+## Cons / limitations / caveats
+
+- Read selectively (5 messages of ~40); security/push/video-part messages not reviewed.
+- Proto is the schema, not the JSON mapping; JSON enum casing confirmed only via the reference driver's test fixtures.
+
+## Relevance to tai
+
+Schema source for tai's A2A driver frame parsing and expose-server synthesis.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-18 | Initial dossier created. |

research/cap-protocol/a2a-specification.md

@@ -0,0 +1,52 @@
+# A2A protocol specification (current)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | cap-protocol |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Agent2Agent (A2A) Protocol Specification |
+| Source URL | https://github.com/a2aproject/A2A/blob/main/docs/specification.md |
+| Source type | specification |
+| Source date (published) | Unknown, not stated (living LF doc) |
+| Date researched | 2026-10-18 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct raw-file fetch, read selectively: full outline, §3.1 ops, §5.3 method mapping, §5.4 errors, discovery sections via grep |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+Current A2A: JSON-RPC PascalCase methods (`SendMessage`, `SendStreamingMessage`, `CancelTask`...) or colon-REST equivalents (`POST /message:send`), AgentCard at `/.well-known/agent-card.json`, cursor-paginated task listing, extension declarations with required flags. Critically, its method names do NOT match what CAP v1 cites (`message/send`, `tasks/cancel`).
+
+## Key findings
+
+- Method mapping (§5.3): JSON-RPC `SendMessage` / REST `POST /message:send`; streaming `SendStreamingMessage` / `POST /message:stream`; cancel `CancelTask` / `POST /tasks/{id}:cancel`. CAP's slash-forms match the pre-1.0 A2A draft, not current A2A.
+- Stream patterns: message-only (exactly one Message then close) or task-lifecycle (Task first, then status/artifact updates, close at terminal state).
+- Terminal states: completed/failed/canceled/rejected; interrupted: input-required (6), auth-required (8).
+- AgentCard discovery via well-known URI; extensions carry uri/description/required/params, matching CAP's `cap-protocol/v1` extension check.
+- A2A error codes (-32001..-32009) collide numerically with CAP's registry but with different meanings; bindings must not mix the two registries.
+
+## Pros / strengths
+
+- Normative LF spec with explicit binding-equivalence rules, giving tai a stable target for the A2A driver and expose-server.
+- The extension mechanism is exactly what CAP's compatibility check needs.
+
+## Cons / limitations / caveats
+
+- Markdown tables are template-generated (`proto_to_table`), so the .md alone omits field shapes; the .proto file is the real schema.
+- Large surface (push notifications, OAuth flows, mTLS) far beyond what CAP's binding needs; tai implements the message/stream/cancel/card subset only.
+- Read selectively (operations, mappings, discovery); auth and push sections not read.
+
+## Relevance to tai
+
+Forces the dual-spelling decision in the naming-drift conclusion: tai's A2A driver must speak CAP-literal draft endpoints to CAP peers and current endpoints to real A2A agents.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-18 | Initial dossier created. |

research/cap-protocol/acp-cancellation.md

@@ -0,0 +1,47 @@
+# ACP cancellation ($/cancel_request, -32800)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | cap-protocol |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | ACP Cancellation |
+| Source URL | https://agentclientprotocol.com/protocol/v1/cancellation.md |
+| Source type | specification |
+| Source date (published) | Unknown, not stated (living docs) |
+| Date researched | 2026-10-18 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch, read in full (75 lines) |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+`$/cancel_request` notification cancels any JSON-RPC request; the callee MUST answer the original request (valid response or `-32800` Request Cancelled). Prompt turns ALSO have `session/cancel`, under which the client MUST answer pending permission requests with `cancelled` and the agent MUST end the prompt with stop reason `cancelled`.
+
+## Key findings
+
+- Two-level cancel: generic `$/cancel_request` for any request, plus turn-scoped `session/cancel` with stricter MUSTs; tai's driver needs both (turn cancel maps from `cap.cancel` scope current_turn).
+- Cascading cancel is illustrated but explicitly optional: no automatic propagation guarantee.
+- Internal cancellation (either side) SHOULD surface as the same `-32800`, keeping one code path.
+
+## Pros / strengths
+
+- Clean separation of generic vs turn cancel; the worked cascade example removes sequencing doubt.
+
+## Cons / limitations / caveats
+
+- `$/cancel_request` support is optional per implementation; tai must handle agents that ignore it (timeout + kill).
+
+## Relevance to tai
+
+Cancel mapping for the ACP driver: `cap.cancel` to `session/cancel` (+ `$/cancel_request` for in-flight requests), with timeout fallback.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-18 | Initial dossier created. |

research/cap-protocol/acp-elicitation.md

@@ -0,0 +1,48 @@
+# ACP elicitation (form and URL modes)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | cap-protocol |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | ACP Elicitation |
+| Source URL | https://agentclientprotocol.com/protocol/v1/elicitation.md |
+| Source type | specification |
+| Source date (published) | Unknown, not stated (living docs) |
+| Date researched | 2026-10-18 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch, read in full (199 lines) |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+Elicitation via `elicitation/create` with explicit `mode` (no MCP-style default): form mode (flat object schema, primitives plus enums, never secrets) and URL mode (out-of-band, `elicitationId` plus `elicitation/complete` notification). Responses are accept/decline/cancel with optional content; unadvertised modes get JSON-RPC -32602. Clients advertise per-mode support explicitly (`{}` means NO modes).
+
+## Key findings
+
+- Form mode is the ACP counterpart of CAP `cap.ask_user` (CAP cites the same JSON-Schema-subset convention); tai's driver maps form elicitations to ask_user events.
+- Explicit per-mode advertisement means tai can offer form-only and stay compliant while declining URL flows.
+- MCP-compatibility trap documented in-spec: empty object does NOT mean form-only here, unlike MCP's release candidate.
+
+## Pros / strengths
+
+- Gives ask_user a structured cross-protocol lineage (MCP elicitation to ACP to CAP), so tai's auto-answerer targets one shape.
+
+## Cons / limitations / caveats
+
+- URL mode is out of scope for tai (no browser/redirect handler); tai answers URL elicitations with decline, per the spec's safe-fallback rule.
+- Secrets policy is agent-side; tai-as-client cannot verify an agent obeys the no-secrets-in-form rule.
+
+## Relevance to tai
+
+Shapes the ask_user mapping and the research auto-answerer input contract (restricted JSON Schema form).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-18 | Initial dossier created. |

research/cap-protocol/acp-file-system.md

@@ -0,0 +1,48 @@
+# ACP file-system methods
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | cap-protocol |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | ACP File System |
+| Source URL | https://agentclientprotocol.com/protocol/v1/file-system.md |
+| Source type | specification |
+| Source date (published) | Unknown, not stated (living docs) |
+| Date researched | 2026-10-18 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch, method inventory via grep plus surrounding prose (capability gating, read/write shapes) |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+Two client-hosted methods: `fs/read_text_file` (path + optional line/limit, returns content) and `fs/write_text_file` (path + content), both capability-gated per method; agents MUST NOT call unadvertised methods. No list/exists/delete, confirming the coding profile's `_cap/<rpc>` extension gap.
+
+## Key findings
+
+- Read supports line/limit windowing, which CAP's `cap.fs.read` lacks; the bridge must either emulate (read-all then slice) or pass through as an extension param.
+- Absolute paths required, matching CAP's fs contract; unsaved-editor-state access is the rationale (N/A to tai, which reads disk).
+- Per-method capability flags give tai's driver a truthful advertisement surface (offer read/write only when the coding profile grants them).
+
+## Pros / strengths
+
+- Minimal surface with strict gating: exactly the two methods a code agent needs most.
+
+## Cons / limitations / caveats
+
+- Inventory-level reading (grep + prose); error shapes and write atomicity unspecified in what was read.
+- No list/exists/delete forces the `_cap` extension path for full coding-profile parity.
+
+## Relevance to tai
+
+Confirms the §9 bridge table: fs.read/write map natively, the rest need `_cap` extensions the driver must implement.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-18 | Initial dossier created. |

research/cap-protocol/acp-initialization.md

@@ -0,0 +1,49 @@
+# ACP initialization (initialize, session/new baseline)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | cap-protocol |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | ACP Initialization |
+| Source URL | https://agentclientprotocol.com/protocol/v1/initialization.md |
+| Source type | specification |
+| Source date (published) | Unknown, not stated (living docs) |
+| Date researched | 2026-10-18 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch, read in full (initialization handshake, version negotiation, client capabilities) plus session-setup page for session/new |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+Connection baseline: `initialize` handshake negotiates client/agent capabilities (prompt content types, fs methods, terminals, elicitation modes, notices, compaction), and all agents MUST support `session/new`, `session/prompt`, `session/cancel`, `session/update`.
+
+## Key findings
+
+- The four-method MUST baseline is the liveness contract tai's ACP driver can rely on for any agent.
+- Capability negotiation is where tai declines surface (notices, compaction, URL elicitation) and advertises coding-profile grants (fs, terminals); initialize carries `protocolVersion: 1`, `clientCapabilities`, and `clientInfo`.
+- Version negotiation: agent answers with the same version or its latest; tai speaks v1 only and closes on anything else.
+- `session/new` takes `{cwd, mcpServers}` and returns `{sessionId}` (see the session-setup dossier).
+
+## Pros / strengths
+
+- Explicit baseline + negotiation keeps a minimal driver compliant by construction.
+
+## Cons / limitations / caveats
+
+- v1 only; v2 migration (method renames) deferred until an agent requires it.
+- Auth methods and MCP server passing are out of scope for tai's driver.
+
+## Relevance to tai
+
+Handshake design for the ACP driver: capability set tai advertises and the baseline it requires.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-18 | Initial dossier created. |

research/cap-protocol/acp-introduction.md

@@ -0,0 +1,46 @@
+# ACP introduction and architecture
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | cap-protocol |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | ACP Introduction |
+| Source URL | https://agentclientprotocol.com/get-started/introduction.md |
+| Source type | documentation |
+| Source date (published) | Unknown, not stated (living docs) |
+| Date researched | 2026-10-18 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch, read in full |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+ACP standardizes editor-to-agent communication (LSP analogy): local agents run as editor subprocesses over JSON-RPC stdio; remote agents over HTTP/WebSocket (remote support still in progress). Reuses MCP JSON shapes where possible; user text defaults to Markdown.
+
+## Key findings
+
+- Local = subprocess + JSON-RPC over stdio is the stable, specified path; remote is explicitly work-in-progress, so tai's ACP binding targets stdio only.
+- Markdown as the default user-text format aligns with tai's TUI rendering.
+
+## Pros / strengths
+
+- Confirms stdio as the SHOULD-support transport, matching CAP's ACP-stdio binding exactly.
+
+## Cons / limitations / caveats
+
+- Positioning page only; no wire detail (covered by the sibling dossiers).
+
+## Relevance to tai
+
+Scopes tai's ACP binding to local stdio and records why remote ACP is out of scope.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-18 | Initial dossier created. |

research/cap-protocol/acp-llms-index.md

@@ -0,0 +1,46 @@
+# ACP documentation index (llms.txt)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | cap-protocol |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | ACP llms.txt documentation index |
+| Source URL | https://agentclientprotocol.com/llms.txt |
+| Source type | documentation index |
+| Source date (published) | Unknown, not stated (living docs) |
+| Date researched | 2026-10-18 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch; v1 page list read in full, v2 list partially (fetch truncated past session-delete) |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+The ACP doc map: v1 covers overview, initialization, auth, session setup/list/delete, prompt turn, content, tool calls, elicitation, file system, cancellation, terminals, plan, modes, config options, slash commands, extensibility, transports, schema; v2 exists with a migration guide.
+
+## Key findings
+
+- v1 already includes elicitation and extensibility pages, so CAP's "(v2)" annotations on elicit/cancel are about method renames, not feature existence.
+- The index drove selective fetching: transports, prompt-turn, tool-calls, elicitation, file-system, cancellation, terminals, agent-plan, content.
+
+## Pros / strengths
+
+- Complete map in one fetch; every binding-relevant page identified without crawling.
+
+## Cons / limitations / caveats
+
+- v2 section only partially seen; v2 migration details deferred to the ACP-driver phase.
+
+## Relevance to tai
+
+Research roadmap for the ACP binding; v2 migration page is queued reading for Phase 5.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-18 | Initial dossier created. |

research/cap-protocol/acp-prompt-turn.md

@@ -0,0 +1,51 @@
+# ACP prompt turn (session/update variants, stop reasons)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | cap-protocol |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | ACP Prompt Turn |
+| Source URL | https://agentclientprotocol.com/protocol/v1/prompt-turn.md |
+| Source type | specification |
+| Source date (published) | Unknown, not stated (living docs) |
+| Date researched | 2026-10-18 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch, read in full (590 lines) |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+The prompt-turn lifecycle: `session/prompt` request, `session/update` notification variants (message/thought chunks, tool_call, tool_call_update, plan, usage_update, notice, compaction...), permission interleaving, cancel semantics, and the `session/prompt` response carrying the stop reason. Turn boundary = prompt RESPONSE, not a notification.
+
+## Key findings
+
+- Update variants map 1:1 onto CAP C.3 rows (agent_message_chunk, agent_thought_chunk, tool_call, tool_call_update, plan) plus extras tai can ignore or log (notices, compaction, slash commands).
+- `messageId` groups chunks into messages (opaque, agent-chosen); a changed id means a new message.
+- Clients MUST restrict prompt content types to negotiated prompt capabilities.
+- notice/compaction updates are capability-gated (absent capability means MUST NOT send); tai's driver advertises neither, keeping agents on plain messages.
+- Cancel: client sends `session/cancel`, MUST answer pending permission requests with `cancelled` outcome, agent MUST reply to the original prompt with stop reason `cancelled`.
+
+## Pros / strengths
+
+- Precise turn-boundary rule (response, not notification) eliminates the PTY-style guessing for ACP agents.
+- Capability gating lets a minimal driver stay minimal without breaking agents.
+
+## Cons / limitations / caveats
+
+- Long page with heavy component markup; schema-level field types live on the schema page (not fetched).
+- Compaction/notice semantics add client-side state tai deliberately declines via capabilities.
+
+## Relevance to tai
+
+The C.3 mapping source for the ACP driver: update-variant to core-event table plus the prompt-response turn boundary.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-18 | Initial dossier created. |

research/cap-protocol/acp-session-setup.md

@@ -0,0 +1,47 @@
+# ACP session setup (session/new)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | cap-protocol |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | ACP Session Setup |
+| Source URL | https://agentclientprotocol.com/protocol/v1/session-setup.md |
+| Source type | specification |
+| Source date (published) | Unknown, not stated (living docs) |
+| Date researched | 2026-10-18 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch, targeted read (session/new request/response; load-session section skimmed) |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+Session creation: `session/new` with `{cwd, mcpServers: []}` returns `{sessionId}`; agents advertising `loadSession` also accept `session/load` for resume. Tai needs only the create path.
+
+## Key findings
+
+- `session/new` params are exactly `{cwd, mcpServers}` (servers carry name/command/args/env); tai sends an empty server list.
+- Result carries only `sessionId`, the correlation key for every later call.
+- Resume via `session/load` exists but tai sessions are single-connection; not implemented.
+
+## Pros / strengths
+
+- Trivial handshake; no negotiation beyond initialize.
+
+## Cons / limitations / caveats
+
+- Targeted read; auth and load-session details not synthesized.
+
+## Relevance to tai
+
+Exact `session/new` shapes for the ACP driver handshake.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-18 | Initial dossier created. |

research/cap-protocol/acp-terminals.md

@@ -0,0 +1,48 @@
+# ACP terminal methods
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | cap-protocol |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | ACP Terminals |
+| Source URL | https://agentclientprotocol.com/protocol/v1/terminals.md |
+| Source type | specification |
+| Source date (published) | Unknown, not stated (living docs) |
+| Date researched | 2026-10-18 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch, read in full (284 lines) |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+Client-hosted terminals: capability-gated in `initialize`, then `terminal/create` (command/args/env-list/cwd/outputByteLimit, truncation at char boundary), `terminal/output` (full output plus truncated flag plus exitStatus when exited, no offset param), `terminal/wait_for_exit`, `terminal/kill` (terminal stays valid), `terminal/release` (kills plus invalidates the id), mirroring the coding profile's terminal methods with `wait` vs `wait_for_exit` the only name difference.
+
+## Key findings
+
+- Near-perfect method correspondence with `cap.terminal.*` makes the ACP bridge for terminals a rename-only adapter.
+- Capability gating in initialize matches CAP's `terminal.enabled` advertisement; a disabled terminal is a refused capability, not an error path.
+- `session/update` notifications interleave with terminal management (per the method list), so output streaming shares the turn channel.
+
+## Pros / strengths
+
+- The 1:1 mapping de-risks the terminal half of the ACP bridge to near-zero design work.
+
+## Cons / limitations / caveats
+
+- No output paging: `terminal/output` returns the whole retained buffer every call, so tai must set outputByteLimit-aware retention itself.
+- Buffer-retention semantics differ from CAP's 60s rule: release invalidates the ACP terminal id immediately.
+
+## Relevance to tai
+
+Terminal bridge is rename-only; full param shapes queued for Phase 5 reading.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-18 | Initial dossier created. |

research/cap-protocol/acp-tool-calls.md

@@ -0,0 +1,48 @@
+# ACP tool calls and permission flow
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | cap-protocol |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | ACP Tool Calls |
+| Source URL | https://agentclientprotocol.com/protocol/v1/tool-calls.md |
+| Source type | specification |
+| Source date (published) | Unknown, not stated (living docs) |
+| Date researched | 2026-10-18 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch, read selectively (permission request/response, option kinds, statuses; content-block sections skimmed) |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+Tool-call reporting (`tool_call` + `tool_call_update` keyed by `toolCallId`, statuses pending/in_progress/completed/failed) and the `session/request_permission` flow: agent offers options with kinds (allow_once/allow_always/reject_once/reject_always), client answers `selected` + optionId or `cancelled`.
+
+## Key findings
+
+- Permission option kinds map directly onto CAP's `allow_once`/`allow_always`/`deny` decisions (reject kinds collapse to deny).
+- Client MAY auto-allow/reject per user settings: tai's orchestrator auto-answer policy has a spec-sanctioned hook here.
+- Tool statuses are a 4-state lifecycle with no streaming-output state; output arrives via content on updates.
+
+## Pros / strengths
+
+- Small, closed vocabulary (4 kinds, 4 statuses, 2 outcomes) that translates to CAP events without loss.
+
+## Cons / limitations / caveats
+
+- Read selectively; diff/image/audio content-block variants skimmed, not synthesized.
+- No risk-level concept: tai must derive CAP `risk_level` from tool identity/args heuristically.
+
+## Relevance to tai
+
+Permission/response translation table for the ACP driver and the auto-approval hook for research-driven answers.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-18 | Initial dossier created. |

research/cap-protocol/acp-transports.md

@@ -0,0 +1,47 @@
+# ACP transports (JSON-RPC stdio)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | cap-protocol |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | ACP Transports |
+| Source URL | https://agentclientprotocol.com/protocol/v1/transports.md |
+| Source type | specification |
+| Source date (published) | Unknown, not stated (living docs) |
+| Date researched | 2026-10-18 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch, read in full (57 lines) |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+ACP stdio: client launches agent subprocess, NDJSON JSON-RPC both ways (no embedded newlines), UTF-8, agent logs on stderr only, stdout carries nothing but ACP messages, teardown is close-stdin plus terminate.
+
+## Key findings
+
+- Newline-delimited JSON-RPC with no embedded newlines: tai's stdlib json + pipes implementation needs no framing layer beyond line splitting.
+- stderr is log-only and MAY be ignored: tai's driver can capture it for diagnostics without protocol risk.
+- Streamable HTTP is draft-only; custom transports MUST preserve JSON-RPC message format and lifecycle.
+
+## Pros / strengths
+
+- Minimal transport contract; a few dozen lines of stdlib implement it fully.
+
+## Cons / limitations / caveats
+
+- No heartbeat/keepalive specified; hung agents are detected only via timeouts tai must choose itself.
+
+## Relevance to tai
+
+The exact transport contract for the Phase 5 ACP-stdio driver (and its tests: NDJSON framing, stderr tolerance, close-stdin teardown).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-18 | Initial dossier created. |

research/cap-protocol/cap-core-v1.md

@@ -0,0 +1,56 @@
+# CAP Core v1 specification
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | cap-protocol |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | CAP CLI Agent Protocol (Core v1) |
+| Source URL | https://github.com/rsclaw-ai/cap-protocol/blob/main/docs/cap-v1.md |
+| Source type | specification |
+| Source date (published) | 2026-05-18 (draft, public review) |
+| Date researched | 2026-10-18 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct raw-file fetch, read in full (1036 lines) |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+The normative core: PTY is the REQUIRED universal binding, four OPTIONAL fast-paths (stream-json, gRPC, ACP-stdio, A2A), 14 core event kinds, 3 core reverse-RPC methods, a lifecycle starting with `cap.session.config` then `cap.session.ready`, first-class multi-agent orchestration (§10), A2A interop both directions (§11), and a dual numeric/string error registry (§14.2).
+
+## Key findings
+
+- Agent conformance = CLI-invokable + publishes Manifest + matches one binding contract; orchestrator conformance = reads manifests + PTY binding + §10 semantics + required reverse RPC.
+- Manifest resolution order: in-package, user-local (`~/.config/cap/agents/`), system-wide (`/usr/share/cap-agents/`), `--cap-manifest` probe.
+- Parse regexes use a POSIX ERE subset (no backrefs/lookaround); drivers MUST reject richer patterns. Note: the spec's own examples use `(?P<tool>...)` named groups, which are NOT in that subset.
+- PTY details: ANSI/VT100 screen buffer, regexes against rendered text on line boundaries, idle = idle-regex on last line + 200ms silence, bracketed paste over 1KB, cancel graceful/hard/none, 10k scrollback SHOULD, `pty_died` error on unexpected exit.
+- Orchestration: `cap://` URNs, master plan with `_meta.cap.assigned_to`, no direct sub-agent contact (all mediated + audited), git worktrees SHOULD, orchestrator MUST aggregate usage and hard-cancel over budget, cooperative interruption pattern (cancel + preserve + resend).
+- Reverse RPC has no defined wire encoding for stream-json/gRPC bindings; only the ACP binding gives it a native transport (JSON-RPC methods).
+- Error registry: -32001..-32010 with string twins; `cap.error` string codes include `rate_limit`, `pty_died`, `parse_failed`, `context_overflow`.
+
+## Pros / strengths
+
+- Complete contract in one file: events, lifecycle, orchestration, errors, and informative binding mappings (C.1-C.4) sufficient to implement drivers without guessing.
+- PTY-required/fast-path-optional layering matches tai's stdlib-only reality: full conformance is reachable without gRPC or any dependency.
+- The §10 orchestration semantics (URNs, mediated routing, budget aggregation) map directly onto tai's existing subagent + scheduler machinery.
+
+## Cons / limitations / caveats
+
+- Draft status with real drift risk: A2A method names in §6.5/C.4 (`message/send`, `tasks/cancel`) do not match current A2A (PascalCase / colon-REST); see the naming-drift conclusion.
+- Self-contradiction on regex flavor (§5.4 ERE-only vs `(?P<>)` in §5.1 examples); tai must decide what to accept.
+- Reverse RPC over stream-json is unspecified, so tai-as-agent cannot offer fs/terminal mediation on its speak path without inventing framing.
+- No conformance test suite ships with the spec; interop is validated against the reference Rust implementation only.
+
+## Relevance to tai
+
+The build blueprint for both directions: tai-as-agent implements §3.1 via `--cap-manifest` + stream-json speak; tai-as-orchestrator implements §3.2 minus gRPC. The §7 event table and §14.2 error table become `cap.md` drift tables.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-18 | Initial dossier created. |

research/cap-protocol/cap-homepage.md

@@ -0,0 +1,51 @@
+# CAP homepage (cap-protocol.org)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | cap-protocol |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | CAP CLI Agent Protocol (homepage) |
+| Source URL | https://cap-protocol.org/ |
+| Source type | project page |
+| Source date (published) | Unknown, not stated (living page; draft 2026-05-18 banner) |
+| Date researched | 2026-10-18 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch, read in full via saved output |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+Positioning page: the protocol-stack table (MCP/ACP/A2A/CAP layers), the PTY-substrate plus fast-paths plus orchestration pitch, a manifest example, the two normative doc links, the reserved-profile table, status timeline, and FAQ (ACP/A2A differences, binding optionality, cooperative interruption pointer to §10.6).
+
+## Key findings
+
+- Layer claim: CAP is orch-to-CLI-agent at fleet scale; one agent may speak all four protocols at once.
+- Only PTY is required; "most agents implement at most one fast-path" (FAQ) sets the interop expectation tai should design to.
+- Reserved profiles: devops, data, security, research, content, sysadmin, network. Only coding is defined.
+- Governance: rsclaw maintainers transitional; LF proposal once 3+ independent implementations exist. Tai would count toward that bar.
+- Spec text CC BY 4.0, reference code MIT.
+
+## Pros / strengths
+
+- Fastest correct mental model of where CAP sits; the FAQ preempts the ACP/A2A confusion directly.
+- Confirms fast-path optionality as the norm, which justifies tai's phased binding rollout.
+
+## Cons / limitations / caveats
+
+- Marketing surface, not normative; the manifest example on the page trims fields the spec requires (e.g. no `capabilities.streaming_output`).
+- Status timeline may lag the repo (page says reference impl "in progress", repo STATUS says the driver matrix is done).
+
+## Relevance to tai
+
+Justifies phased conformance (PTY + one fast-path first) and records the licensing and governance facts the implementation conclusion relies on.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-18 | Initial dossier created. |

research/cap-protocol/cap-profile-coding-v1.md

@@ -0,0 +1,56 @@
+# CAP Profile Coding v1 specification
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | cap-protocol |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | CAP Profile: Coding (v1, draft) |
+| Source URL | https://github.com/rsclaw-ai/cap-protocol/blob/main/docs/cap-profile-coding-v1.md |
+| Source type | specification |
+| Source date (published) | 2026-05-18 (draft) |
+| Date researched | 2026-10-18 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct raw-file fetch, read in full (446 lines) |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+The first vertical: `[capabilities.coding]` manifest section, 6 fs reverse-RPC methods (watch optional with `cap.fs.change` events), 5 terminal methods (create/output/wait/kill/release with a 60s buffer-retention rule), 6 artifact MIME types, scope enforcement (`workspace_only`/`project_root`/`unrestricted`), permission-mode-gated terminal vetting, and profile error codes -32020..-32024.
+
+## Key findings
+
+- Only `fs.scope` (when any fs is true) and `tool_permission` are required in the manifest section; everything else optional.
+- `cap.fs.read` MUST reject out-of-scope paths without revealing existence; symlink resolution happens BEFORE the scope check and escaping symlinks MUST NOT be followed.
+- Terminal defaults: kill signal SIGTERM escalating to SIGKILL after 5s; release keeps the buffer queryable 60s; wait with null timeout waits indefinitely.
+- `tool_permission = interactive` means EVERY terminal.create surfaces as a permission request; `confirm` allows allow-list auto-approve; `none` logs everything but users MUST be warned prominently.
+- Artifacts: diff (unified, one file RECOMMENDED), pr_link, test_result (output truncated to 64KB), commit, plan_doc, transcript (RECOMMENDED for audit/replay).
+- ACP bridge table (§9): fs.list/exists/delete have NO ACP counterpart and go over `_cap/<rpc>` extension methods.
+- Multi-agent worktree naming suggestion: `<repo>/.cap-worktrees/<sub-agent-urn>/` (the reference CLI instead uses `.cap/<session>/`).
+
+## Pros / strengths
+
+- Tight, implementable RPC surface: every method has params/result/errors, and the scope table leaves no enforcement ambiguity.
+- The transcript artifact type gives tai's orchestrator audit log a standard export shape for free.
+- tai already has the enforcement primitives (approval tiers, sandbox box, git) that §7 requires of an orchestrator.
+
+## Cons / limitations / caveats
+
+- `fs.watch` has no unsubscribe method defined; subscriptions presumably live for the session.
+- `cap.terminal.create` takes a single command string plus args array, but quoting/escaping rules between them are unspecified.
+- Worktree path suggestion conflicts with the reference implementation's actual `.cap/<session>/` layout; either is compliant (suggestion only).
+- No binary-file story for fs.read/write beyond a base64 encoding flag; large-file chunking is unaddressed.
+
+## Relevance to tai
+
+Defines tai's coding-profile surface both ways: orchestrator MUST implement the fs/terminal reverse RPC it advertises, agent SHOULD emit diff/test_result/transcript artifacts. The scope table becomes a `cap.md` drift table.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-18 | Initial dossier created. |

research/cap-protocol/cap-quickstart.md

@@ -0,0 +1,51 @@
+# CAP quickstart (cap run/chat CLI)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | cap-protocol |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | CAP Quickstart |
+| Source URL | https://github.com/rsclaw-ai/cap-protocol/blob/main/docs/quickstart.md |
+| Source type | documentation |
+| Source date (published) | Unknown, not stated (repo living doc) |
+| Date researched | 2026-10-18 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct raw-file fetch, read in full (142 lines) |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+Operator view of the reference orchestrator: `fleet.yaml` sessions/routes, `cap run` with static/llm/hybrid routing, `cap chat` interactive multi-agent talk, `cap manifest validate/resolve`, `cap list-drivers`, and the driver matrix (`claude`, `openclaude`, `codex`, `opencode`, `aider`, `a2a:<url>`, `acp:<cmd>`, `grpc:<addr>`, `pty:<cmd>`).
+
+## Key findings
+
+- Fleet patterns: pipeline, fan-out+join, parallel+human-collect, by-subtask split via a ` ```cap-subtasks ` fence convention (convention, not spec).
+- Routing strategies: static (routes block verbatim), llm (model picks next session), hybrid.
+- `cap manifest validate/resolve` confirms manifest tooling is expected orchestrator surface, not just internal plumbing.
+- Worktree isolation path in practice: `.cap/<session>/`, cleaned up at fleet end (differs from the profile's `.cap-worktrees` suggestion).
+- `--bypass` auto-approves all permissions at the fleet level.
+
+## Pros / strengths
+
+- Shows what "orchestrator" means operationally beyond the spec's MUSTs; directly reusable as tai's `cap` CLI command sketch.
+- The `driver:` URI scheme (`a2a:`, `acp:`, `grpc:`, `pty:`) is a compact dispatch design tai can borrow.
+
+## Cons / limitations / caveats
+
+- Reference-implementation surface, not spec; fleet.yaml schema and fence conventions are rsclaw inventions.
+- NoFleet error semantics or exit codes documented here.
+
+## Relevance to tai
+
+Shapes tai's orchestrator UX (manifest validate/resolve, driver URIs, chat/run split) and confirms worktree cleanup as expected behavior.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-18 | Initial dossier created. |

research/cap-protocol/cap-rs-a2a-driver.md

@@ -0,0 +1,28 @@
+# CAP reference A2A driver (cap-rs a2a.rs)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | cap-protocol |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | crates/cap-rs/src/driver/a2a.rs |
+| Source URL | https://github.com/rsclaw-ai/cap-protocol/blob/main/crates/cap-rs/src/driver/a2a.rs |
+| Source type | reference implementation |
+| Date researched | 2026-10-18 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct raw-file fetch, grepped for endpoint strings, request bodies, and the event-mapping core (not read in full) |
+| Confidence | High |
+| Status | Active |
+
+## Why it's here
+
+Grepped to settle which A2A spelling the reference driver actually uses: `POST {endpoint}/message/send` with `{message: {role, parts: [{kind: text, text}]}}` and `POST {endpoint}/tasks/cancel` with no body (draft-style), card at `/.well-known/agent-card.json` refused without the `cap-protocol/v1` extension. The event mapper accepts raw `cap.*` JSON, data parts unwrapped via `_meta.cap.kind` (from message, task-status and artifact parts alike), text parts (kind or type `text`, id from messageId/message_id), and failed task states; outbound answers travel as data parts with the `_meta.cap.kind` marker. Control flow around the mapper was not reviewed.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-18 | Logged as consulted-but-not-analyzed. |

research/cap-protocol/cap-status.md

@@ -0,0 +1,51 @@
+# CAP repo STATUS (implementation reality)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | cap-protocol |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | cap-protocol status (docs/STATUS.md) |
+| Source URL | https://github.com/rsclaw-ai/cap-protocol/blob/main/docs/STATUS.md |
+| Source type | project notes |
+| Source date (published) | 2026-06-01 working snapshot |
+| Date researched | 2026-10-18 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct raw-file fetch, read in full (first 120 lines carry the state; rest is prior-session log, skimmed) |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+What actually works against real agents: full driver matrix done, CAP core v1 conformance claimed, A2A driver validated against a real endpoint, `cap chat`, LLM/hybrid routing, aider PTY driver, codex defaulting to stream-json. The PTY floor section documents the turn-boundary heuristics that make TUI agents reliable: idle-settle + ready-marker + prompt-sent gate, submit verification with bounded resubmits, wait-for-ready, 150ms text-to-Enter gap.
+
+## Key findings
+
+- Agent fidelity tiers in practice: claude/codex stream-json, opencode ACP (`opencode acp` v1.14 wire-verified), aider/codex-TUI PTY fallback. "PTY screen-scraping is the universal floor, not the goal."
+- PTY turn boundary = byte-silence ~800ms AND prompt glyph at rendered-screen bottom; first settle is Ready, post-prompt settles are Done; trailing prompt lines stripped from boundary chunks.
+- Three reliability fixes: prompt gate (no Done before first real prompt), submit verification (re-send Enter if prompt text still in input box, bounded MAX_RESUBMITS), wait-for-ready (hold first prompt until Ready).
+- codex app-server websocket transport was REMOVED as unreliable; stream-json supersedes it. Dead-end warning for tai: do not build a codex websocket driver.
+- Test gate: 54 + 25 + 6 + 2 green, clippy/fmt clean; live-validated codex-to-claude fleet run.
+
+## Pros / strengths
+
+- The only source of ground truth on what the spec costs in practice (heuristics, resubmits, timing constants).
+- Explicit dead-end marking (app-server removal) saves tai from the same mistake.
+
+## Cons / limitations / caveats
+
+- Explicitly non-normative and overwritten each session; facts may be stale relative to main.
+- Timing constants (800ms, 150ms) are tuned to the authors' machines, not portable guarantees.
+
+## Relevance to tai
+
+Directly specifies tai's PTY driver heuristics (settle window, prompt gate, resubmit bound) and the per-agent binding preference order.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-18 | Initial dossier created. |

research/cap-protocol/conclusions/a2a-naming-drift.md

@@ -0,0 +1,55 @@
+# Speak both A2A spellings, CAP-literal first
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | cap-protocol |
+| Document type | Conclusion Document |
+| Decided | 2026-10-18 |
+| Decided by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | A2A spec method-mapping table vs CAP spec text vs grep of reference driver's endpoint strings |
+| Confidence | High |
+| Status | Active |
+
+## Question / problem statement
+
+CAP v1 cites A2A methods (`message/send`, `tasks/cancel`) that current A2A does not define (it uses `SendMessage`/`POST /message:send`, `CancelTask`/`POST /tasks/{id}:cancel`). Which spelling does tai's A2A driver and expose-server use?
+
+## Conclusion
+
+Both, CAP-literal first: the driver tries draft-style endpoints (`POST /message/send`, `/tasks/cancel`) first since that is what CAP peers and the reference implementation speak (validated against a real endpoint), then falls back to current A2A (`POST /message:send`, `/tasks/{id}:cancel`, PascalCase JSON-RPC). The expose-server accepts both spellings. Error registries stay separate: A2A -32001..-32009 mean different things than CAP -32001..-32010 and MUST NOT be mixed.
+
+## Supporting sources
+
+- [A2A specification](../a2a-specification.md): current method mapping table (§5.3) and error-code table (§5.4).
+- [Reference A2A driver](../cap-rs-a2a-driver.md): proves the CAP ecosystem speaks draft-style endpoints in practice.
+- [CAP Core v1](../cap-core-v1.md): §6.5/§7.8/C.4 as the CAP-literal requirements.
+- [A2A proto](../a2a-proto.md): state enum and update events both spellings share.
+
+## Alternatives considered and rejected
+
+- CAP-literal only: rejected, real (non-CAP) A2A agents would be undrivable.
+- Current-A2A only: rejected, breaks interop with CAP peers and the reference implementation, the primary interop target.
+- Content-negotiate via AgentCard version: rejected, no standard version signal exists on the card for this; try/fallback is simpler and observable.
+
+## Risks / open questions
+
+- Double-spelling doubles the test matrix for the A2A driver; keep the fallback behind one helper so tests cover both through the same path.
+- If the spec finalizes on current-A2A spellings, flip the order (revisit condition).
+
+## Action taken
+
+Recorded as the A2A driver contract for Phase 5; no code yet.
+
+## Revisit when
+
+- CAP leaves draft with a stated A2A version pin (adopt it, drop the other spelling).
+- Draft endpoints vanish from the wild.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-18 | Conclusion recorded. |

research/cap-protocol/conclusions/scope-and-phasing.md

@@ -0,0 +1,60 @@
+# Tai implements CAP both directions, phased, without gRPC
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | cap-protocol |
+| Document type | Conclusion Document |
+| Decided | 2026-10-18 |
+| Decided by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | full read of CAP core + coding profile, quickstart, STATUS, all 5 example manifests; selective first-hand read of A2A spec + proto and 10 ACP pages; grep of reference A2A driver |
+| Confidence | High |
+| Status | Active |
+
+## Question / problem statement
+
+How does tai support "the literal whole protocol" as both agent (speaking CAP under a startup flag) and orchestrator (driving claude/codex/grok-class CLI agents, auto-answering their questions via research) while staying a single stdlib-only file?
+
+## Conclusion
+
+Implement every binding except gRPC, in five phases: (1) events/errors/manifest registry plus `--cap-manifest`; (2) agent-side `--cap-speak` stream-json binding with coding artifacts; (3) orchestrator PTY driver on the reference heuristics; (4) stream-json driver plus §10 orchestration (URNs, mediated routing, worktrees, budget); (5) ACP-stdio and A2A drivers, reverse-RPC serving, and the research auto-answerer. gRPC is rejected: stdlib has no HTTP/2 or protobuf, and hand-rolling both for one optional binding fails the boring-technology rule. A bare `grpc = true` manifest still parses; binding selection falls through to PTY.
+
+## Supporting sources
+
+- [CAP Core v1](../cap-core-v1.md): PTY-required/fast-path-optional layering makes full conformance reachable without gRPC; §7/§10/§14.2 are the build tables.
+- [CAP coding profile](../cap-profile-coding-v1.md): reverse-RPC surface and scope table for the orchestrator side.
+- [STATUS](../cap-status.md): PTY heuristics (800ms settle, prompt gate, resubmit bound) and the codex-websocket dead-end warning.
+- [openclaude manifest](../manifest-openclaude.md): `grpc = true` carries no address, so the flag alone is undrivable anyway.
+- [ACP transports](../acp-transports.md) + [prompt turn](../acp-prompt-turn.md): stdio NDJSON JSON-RPC is a few dozen stdlib lines; turn boundary is the prompt response.
+- [A2A specification](../a2a-specification.md): message/stream/cancel/card subset is stdlib-feasible (http.client, SSE parse, http.server for expose).
+
+## Alternatives considered and rejected
+
+- Full gRPC via hand-rolled HTTP/2 + protobuf: rejected, thousands of lines of bug surface for an optional binding whose own manifest example omits the server address.
+- PTY-only orchestrator (skip all fast-paths): rejected, the reference fidelity tiers show structured paths are strictly more reliable, and stream-json is cheap once PTY exists.
+- Separate package for CAP: rejected, the single-file stdlib-only constraint is load-bearing for tai distribution; CAP fits in `Cap*` classes plus a `cap.md` mapping doc.
+
+## Risks / open questions
+
+- Regex flavor: spec says ERE-only but all examples use `(?P<>)`; tai accepts Python-compatible patterns and rejects only backrefs/lookaround, flagged as a deliberate deviation.
+- Reverse RPC over stream-json is unspecified; tai-as-agent offers no fs/terminal mediation on the speak path until the spec defines framing.
+- ACP v2 migration and full terminal/fs param shapes still queued for Phase 5 reading.
+- Research auto-answerer quality depends on verdict/judge reliability already flagged as unmeasured.
+
+## Action taken
+
+Phases tracked as session todos; Phase 1 (events, errors, manifest registry, `--cap-manifest`, `cap.md`, tests) implemented same session. Later phases scheduled as follow-up turns.
+
+## Revisit when
+
+- The spec leaves draft (breaking changes possible; watch revision field).
+- A CAP conformance suite ships (adopt it as the integration gate).
+- A2A draft endpoints disappear from the wild (drop the draft spelling).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-18 | Conclusion recorded. |

research/cap-protocol/manifest-aider.md

@@ -0,0 +1,47 @@
+# Example manifest: aider
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | cap-protocol |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | CAP agent manifest for aider |
+| Source URL | https://github.com/rsclaw-ai/cap-protocol/blob/main/examples/aider.toml |
+| Source type | example config |
+| Source date (published) | Unknown, not stated (repo living file) |
+| Date researched | 2026-10-18 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct raw-file fetch, read in full (51 lines) |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+PTY-only REPL agent: startup command carries agent-specific flags (`--no-auto-commits`, `--no-suggest-shell-commands`), `^>$` idle, `/run` tool-call prefix, `multi_session = false`, unmetered cost.
+
+## Key findings
+
+- Startup commands embed policy flags; drivers append model/session args to this prefix rather than replacing it.
+- `multi_session = false` is the only false in the set: orchestrators MUST serialize aider sessions.
+- `metered = false`: no `cap.usage` expected; budget enforcement for aider is wall-clock/turn-count only.
+
+## Pros / strengths
+
+- The serial/unmetered corner that tai's orchestrator caps must respect.
+
+## Cons / limitations / caveats
+
+- `/run`-prefixed tool-call pattern is thin; PTY tool events for aider will be sparse by design.
+
+## Relevance to tai
+
+Orchestrator fixture for single-session agents and unmetered budget handling.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-18 | Initial dossier created. |

research/cap-protocol/manifest-claude-code.md

@@ -0,0 +1,47 @@
+# Example manifest: claude-code
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | cap-protocol |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | CAP agent manifest for claude-code |
+| Source URL | https://github.com/rsclaw-ai/cap-protocol/blob/main/examples/claude-code.toml |
+| Source type | example config |
+| Source date (published) | Unknown, not stated (repo living file) |
+| Date researched | 2026-10-18 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct raw-file fetch, read in full (57 lines) |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+The canonical full manifest: probe via `--version`, stream-json fast-path, PTY fallback with `❯`/`>` idle patterns, `◉ tool(args)` tool-call patterns, yes/no + select prompts, error lines, full capabilities, metered cost.
+
+## Key findings
+
+- `stream_json = ["claude", "-p", "--input-format=stream-json", "--output-format=stream-json"]` is the reference fast-path shape tai's stream-json driver must spawn.
+- Uses `(?P<tool>...)` named groups in tool patterns, again contradicting the §5.4 ERE-only rule (third occurrence: spec example, claude manifest, openclaude manifest).
+- `cost.metered = true`: drivers MUST surface `cap.usage` for this agent.
+
+## Pros / strengths
+
+- The one manifest exercising every section; ideal fixture for tai's manifest parser tests.
+
+## Cons / limitations / caveats
+
+- Example, not normative; `version_match`/`probe` shapes may not match real claude releases.
+
+## Relevance to tai
+
+Becomes a parser test fixture and the template for tai's own `--cap-manifest` output shape.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-18 | Initial dossier created. |

research/cap-protocol/manifest-codex.md

@@ -0,0 +1,47 @@
+# Example manifest: codex
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | cap-protocol |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | CAP agent manifest for codex |
+| Source URL | https://github.com/rsclaw-ai/cap-protocol/blob/main/examples/codex.toml |
+| Source type | example config |
+| Source date (published) | Unknown, not stated (repo living file) |
+| Date researched | 2026-10-18 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct raw-file fetch, read in full (51 lines) |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+PTY-first manifest for codex: all fast-paths false, `›` idle glyph, `✗` error prefix, 120s init timeout, metered cost.
+
+## Key findings
+
+- Shows the all-false fast-path form explicitly rather than omitting the section; tai's parser must treat false and absent identically.
+- The `›` (U+203A) prompt glyph is the live-captured turn-boundary marker the STATUS doc references.
+- `init_timeout_seconds = 120` doubles the claude value: slow-booting TUI agents need per-manifest patience.
+
+## Pros / strengths
+
+- Minimal-but-valid shape that pins down which fields a PTY-only agent can omit.
+
+## Cons / limitations / caveats
+
+- Contradicts STATUS.md, which says codex defaults to stream-json; the example file lags the implementation.
+
+## Relevance to tai
+
+Second parser fixture (the sparse PTY-only shape) and the binding-preference test case (all false means PTY).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-18 | Initial dossier created. |

research/cap-protocol/manifest-openclaude.md

@@ -0,0 +1,47 @@
+# Example manifest: openclaude
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | cap-protocol |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | CAP agent manifest for openclaude |
+| Source URL | https://github.com/rsclaw-ai/cap-protocol/blob/main/examples/openclaude.toml |
+| Source type | example config |
+| Source date (published) | Unknown, not stated (repo living file) |
+| Date researched | 2026-10-18 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct raw-file fetch, read in full (50 lines) |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+The gRPC-first manifest: `grpc = true` with stream-json/ACP/A2A false, PTY fallback fully specified (`◉` tool patterns again), metered cost.
+
+## Key findings
+
+- `grpc = true` is a bare boolean, not an address: the address presumably comes from out-of-band config (the quickstart's `grpc:<addr>` driver URI), a gap between manifest schema and CLI.
+- Third use of `(?P<>)` named groups in shipped examples, confirming the ERE-subset rule is aspirational; tai's parser should accept Python-compatible named groups and only reject backrefs/lookaround.
+- Otherwise structurally identical to claude-code, confirming one parser handles all five.
+
+## Pros / strengths
+
+- Documents the grpc-true shape tai must parse even though tai will not implement the gRPC binding (stdlib has no HTTP/2 or protobuf).
+
+## Cons / limitations / caveats
+
+- No address in the manifest makes the grpc flag alone undrivable; resolution rules are unspecified.
+
+## Relevance to tai
+
+Sets the binding-selection test case (grpc preferred but unavailable in tai means fall through to PTY) and settles the regex-flavor decision.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-18 | Initial dossier created. |

research/cap-protocol/manifest-opencode.md

@@ -0,0 +1,47 @@
+# Example manifest: opencode
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | cap-protocol |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | CAP agent manifest for opencode |
+| Source URL | https://github.com/rsclaw-ai/cap-protocol/blob/main/examples/opencode.toml |
+| Source type | example config |
+| Source date (published) | Unknown, not stated (repo living file) |
+| Date researched | 2026-10-18 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct raw-file fetch, read in full (52 lines) |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+PTY-shape manifest for opencode with `❯`/`›` idle alternatives and `^Error:` error lines; notably `ask_user` all-false except free_text, and no model_arg.
+
+## Key findings
+
+- No `model_arg`: drivers must cope with agents that accept no model flag (config `model` then has nowhere to go; warn, not fail).
+- Idle alternatives (`❯`, `›`) show the idle list is OR-matched across glyphs, matching multiple TUI states.
+- Like codex, lags STATUS.md, which routes opencode over ACP in practice.
+
+## Pros / strengths
+
+- Pins the no-model-arg and multi-glyph-idle cases tai's driver must handle.
+
+## Cons / limitations / caveats
+
+- Stale relative to the implementation (ACP is the real opencode path).
+
+## Relevance to tai
+
+Parser/driver fixture for the no-model-arg case and multi-pattern idle matching.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-18 | Initial dossier created. |