@gajae-code/coding-agent 0.17.6 → 0.17.7

package/src/internal-urls/docs-index.generated.ts

@@ -1,7 +1,7 @@
 // Auto-generated by scripts/generate-docs-index.ts - DO NOT EDIT
 Reflect.set(globalThis, Symbol.for("gjc.docs-index.generated.loaded"), true);
 
-export const EMBEDDED_DOC_FILENAMES: readonly string[] = ["ERRATA-GPT5-HARMONY.md","REBRANDING_PLAN_260525.md","acp-local-development.md","adr-abort-sdk-terminal-turn-owned.md","adr-inline-selection-gate.md","adr-overlay-component-seam.md","adr-sessions-dashboard.md","ai-schema-normalize.md","alibaba-token-plan-pro-profile-benchmark.md","analyze-me-with-gjc.md","aside-integration.md","auth-broker-gateway.md","bash-tool-runtime.md","blob-artifact-architecture.md","bot-integration.md","brand-assets.md","clipboard-transport.md","code-mode-evaluation-5770.md","codebase-overview.md","codegraph-custom-tool.md","compaction.md","composer-codex-parity.md","computer-use/README.md","concepts/context-compaction.md","crash-reporting.md","cursor-composer-profile-tiers.md","custom-providers-and-multi-account.md","customization.md","design/model-profile-ownership.md","devin-provider.md","discord-onboarding.md","doctor.md","environment-variables.md","examples/gjc-hooks/pre/README.md","external-control-readiness.md","extragoal-skill-template.md","fs-scan-cache-architecture.md","geobench.md","git-daemon.md","gjc-dogfood-skill-template.md","gjc-plugins.md","gjc-session-clawhip-routing.md","gpt-5.6-codex-preset-benchmark.md","grok-build-provider-design.md","handoff-generation-pipeline.md","hermes-mcp-bridge.md","hooks.md","hotspot-map-successor.md","install.md","keybindings.md","lsp-config.md","macos-option-key.md","managed-task-dag.md","memory.md","models.md","multi-vendor-profiles.md","native-ffi-optimization-policy.md","natives-addon-loader-runtime.md","natives-architecture.md","natives-binding-contract.md","natives-build-release-debugging.md","natives-media-system-utils.md","natives-rust-task-cancellation.md","natives-shell-pty-process.md","natives-text-search-pipeline.md","non-compaction-retry-policy.md","notebook-tool-runtime.md","onboarding-packet.md","onboarding-receipt.md","ooo-bridge-extension-contract.md","perf-profiling-corpus.md","porting-from-pi-mono.md","porting-to-natives.md","prompt-architect-reports/README.md","prompt-architect-reports/recovered-context/0-ToolPrompts.recovered.md","prompt-architect-reports/recovered-context/1-SystemPrompts.recovered.md","prompt-architect-reports/recovered-context/3-SkillMiscPrompts.recovered.md","prompt-architect-reports/recovery-summary.md","prompt-architect-reports/system-prompts.raw.md","prompt-architect-reports/tool-prompts.raw.md","provider-streaming-internals.md","python-repl.md","release-0.13.3-integration.md","release-0.14.2-handoff.md","render-mermaid.md","research-plan-ledger.md","research/unlazy-evaluation/REPORT.md","resolve-tool-runtime.md","rulebook-matching-pipeline.md","sdk-app-guide.md","sdk-embedding.md","sdk-owned-session-lifecycle-handoff.md","sdk-rpc-parity-audit.md","sdk-session-cli.md","sdk.md","secrets.md","session-import.md","session-operations-export-share-fork-resume.md","session-switching-and-recent-listing.md","session-tree-plan.md","session.md","skills.md","slack-onboarding.md","speech-to-text.md","standalone-mcp.md","streamdeck-integration-guide-with-cmux.md","telegram-onboarding.md","telemetry.md","terminal-app-integrations.md","theme.md","tools/ask.md","tools/ast-edit.md","tools/ast-grep.md","tools/bash.md","tools/bisect.md","tools/browser.md","tools/calc.md","tools/checkpoint.md","tools/computer.md","tools/cron.md","tools/debug.md","tools/edit.md","tools/eval.md","tools/find.md","tools/github.md","tools/irc.md","tools/job.md","tools/lsp.md","tools/monitor.md","tools/python.md","tools/read.md","tools/recipe.md","tools/render_mermaid.md","tools/resolve.md","tools/rewind.md","tools/search.md","tools/search_tool_bm25.md","tools/ssh.md","tools/task.md","tools/todo_write.md","tools/web_search.md","tools/write.md","tree.md","ttsr-injection-lifecycle.md","tui-lowrisk-ux-handoff.md","tui-runtime-internals.md","ui-design-visual-qa.md","ui-language.md","workflow-recovery-and-risk-proportional-validation.md"];
+export const EMBEDDED_DOC_FILENAMES: readonly string[] = ["ERRATA-GPT5-HARMONY.md","REBRANDING_PLAN_260525.md","acp-local-development.md","adr-abort-sdk-terminal-turn-owned.md","adr-inline-selection-gate.md","adr-overlay-component-seam.md","adr-sessions-dashboard.md","ai-schema-normalize.md","alibaba-token-plan-pro-profile-benchmark.md","analyze-me-with-gjc.md","aside-integration.md","auth-broker-gateway.md","bash-tool-runtime.md","blob-artifact-architecture.md","bot-integration.md","brand-assets.md","clipboard-transport.md","code-mode-evaluation-5770.md","codebase-overview.md","codegraph-custom-tool.md","compaction.md","composer-codex-parity.md","computer-use/README.md","concepts/context-compaction.md","crash-reporting.md","cursor-composer-profile-tiers.md","custom-providers-and-multi-account.md","customization.md","design/model-profile-ownership.md","devin-provider.md","discord-onboarding.md","doctor.md","environment-variables.md","examples/gjc-hooks/pre/README.md","external-control-readiness.md","extragoal-skill-template.md","fs-scan-cache-architecture.md","geobench.md","git-daemon.md","gjc-dogfood-skill-template.md","gjc-plugins.md","gjc-session-clawhip-routing.md","gpt-5.6-codex-preset-benchmark.md","grok-build-provider-design.md","handoff-generation-pipeline.md","hermes-mcp-bridge.md","hooks.md","hotspot-map-successor.md","install.md","keybindings.md","lsp-config.md","macos-option-key.md","managed-task-dag.md","memory.md","models.md","multi-vendor-profiles.md","native-ffi-optimization-policy.md","natives-addon-loader-runtime.md","natives-architecture.md","natives-binding-contract.md","natives-build-release-debugging.md","natives-media-system-utils.md","natives-rust-task-cancellation.md","natives-shell-pty-process.md","natives-text-search-pipeline.md","non-compaction-retry-policy.md","notebook-tool-runtime.md","onboarding-packet.md","onboarding-receipt.md","ooo-bridge-extension-contract.md","perf-profiling-corpus.md","porting-from-pi-mono.md","porting-to-natives.md","prompt-architect-reports/README.md","prompt-architect-reports/recovered-context/0-ToolPrompts.recovered.md","prompt-architect-reports/recovered-context/1-SystemPrompts.recovered.md","prompt-architect-reports/recovered-context/3-SkillMiscPrompts.recovered.md","prompt-architect-reports/recovery-summary.md","prompt-architect-reports/system-prompts.raw.md","prompt-architect-reports/tool-prompts.raw.md","provider-streaming-internals.md","python-repl.md","release-0.13.3-integration.md","release-0.14.2-handoff.md","render-mermaid.md","research-plan-ledger.md","research/unlazy-evaluation/REPORT.md","resolve-tool-runtime.md","rulebook-matching-pipeline.md","rust-porting-inventory.md","sdk-app-guide.md","sdk-embedding.md","sdk-owned-session-lifecycle-handoff.md","sdk-rpc-parity-audit.md","sdk-session-cli.md","sdk.md","secrets.md","session-import.md","session-operations-export-share-fork-resume.md","session-switching-and-recent-listing.md","session-tree-plan.md","session.md","skills.md","slack-onboarding.md","speech-to-text.md","standalone-mcp.md","streamdeck-integration-guide-with-cmux.md","telegram-onboarding.md","telemetry.md","terminal-app-integrations.md","theme.md","tools/ask.md","tools/ast-edit.md","tools/ast-grep.md","tools/bash.md","tools/bisect.md","tools/browser.md","tools/calc.md","tools/checkpoint.md","tools/computer.md","tools/cron.md","tools/debug.md","tools/edit.md","tools/eval.md","tools/find.md","tools/github.md","tools/irc.md","tools/job.md","tools/lsp.md","tools/monitor.md","tools/python.md","tools/read.md","tools/recipe.md","tools/render_mermaid.md","tools/resolve.md","tools/rewind.md","tools/search.md","tools/search_tool_bm25.md","tools/ssh.md","tools/task.md","tools/todo_write.md","tools/web_search.md","tools/write.md","tree.md","ttsr-injection-lifecycle.md","tui-lowrisk-ux-handoff.md","tui-runtime-internals.md","ui-design-visual-qa.md","ui-language.md","workflow-recovery-and-risk-proportional-validation.md"];
 
 export const EMBEDDED_DOCS: Readonly<Record<string, string>> = {
 	"ERRATA-GPT5-HARMONY.md": "# ERRATA — GPT-5 Harmony-Header Leakage\n\n## 1. The problem\n\nOpenAI frames tool calls in the Harmony chat protocol:\n\n```\n<|start|>assistant<|channel|>commentary to=functions.<NAME><|message|>{ARGS}<|call|>\n```\n\n`<|channel|>commentary to=functions.NAME` is the **routing header** —\ncontrol tokens consumed by the runtime to dispatch the call. These\ntokens never appear as content under normal operation; the runtime\nstrips them.\n\nThe defect: gpt-5 models occasionally emit, **as ordinary content\ninside `{ARGS}`**, the **plain-text shadow** of these routing tokens —\nthe same characters without the `<|…|>` brackets — and continue\nproducing more pseudo-routing structure (channel name, body marker,\nmultilingual spam, fake tool-result framing). The contamination lives\ninside the visible tool argument and is dispatched to the tool as if it\nwere intended content.\n\n**Critical detail.** The actual `<|start|>` / `<|channel|>` /\n`<|message|>` / `<|call|>` special tokens almost never appear in tool\nargs. What leaks is the bracket-less spelling — `analysis to=functions.X\ncode …` — because OpenAI applies a logit mask suppressing the\ncontrol-token IDs inside the args region. The mass that would have gone\nto those special tokens redistributes onto the un-bracketed plain-text\nrepresentation the model also learned. This makes the leak structurally\ninvisible to the routing parser and lands it in the tool input verbatim.\n\nManifestation in tool args (real corpus example):\n\n```\n~      add_function(iso, ctx, ns, \"installSystemChangeObserver\",\n        os_install_system_change_observer);】【\"】【analysis to=functions.edit\n        code above เงินไทยฟรีuser to=functions.edit code …\n```\n\nThe leading code is real and intended. Everything after the first\nnon-Latin token through the next clean structural boundary is corruption.\n\n---\n\n## 2. Observed statistics & failure modes\n\nSource: `~/.gjc/stats.db` (`ss_tool_calls`, `ss_assistant_msgs`), through\n2026-05-10. 1.05M tool calls scanned.\n\n### 2.1 Rate\n\n| Model            | Leaks in tool args | Calls   | per million |\n|------------------|-------------------:|--------:|------------:|\n| gpt-5.4          | 37                 | 226,957 | 163         |\n| gpt-5.3-openai-code    | 17                 | 112,243 | 151         |\n| gpt-5.5          | 2                  |  80,750 |  25         |\n| gpt-5.2-openai-code    | 0                  |    —    |   —         |\n\nPlus 15 hits in assistant visible text / thinking blobs.\n\n### 2.2 Tool distribution\n\n| Tool                | Hits |\n|---------------------|-----:|\n| `edit`              | 38   |\n| `eval`              | 11   |\n| `report_tool_issue` | 3    |\n| `grep`/`read`/`search`/`yield` | 1 each |\n\nConcentrated in tools with free-form (non-JSON-schema) argument formats.\n\n### 2.3 Leak shape (deterministic)\n\n```\nLEAK         ::= JUNK_PREFIX MARKER CHANNEL_BODY (LEAK)?\nMARKER       ::= \"to=functions.\" TOOL_NAME\nCHANNEL_BODY ::= \" code \" (SPAM | reasoning_prose | fake_tool_output)*\nJUNK_PREFIX  ::= (GLITCH_TOKEN | CHANNEL_WORD | NON_LATIN_RUN | \"}\" | \"】【\")+\n```\n\n**Cascading is common.** Of 96 marker occurrences across 71 contaminated\nrecords, 39 contain ≥2 markers and 7 contain ≥3 — the model emits\nmultiple fake `to=functions.X code …` blocks back-to-back, often with\nfake `code_output\\nCell N:\\n…` framing between them. Once the\nplain-text scaffolding is in the residual stream, the prefix now *looks\nlike* a fresh tool envelope start, so the macro prior over continuations\nkeeps voting for more scaffolding. Self-amplifying.\n\n### 2.4 Glitch tokens\n\nSingle-token identifiers in `o200k_base` whose embeddings appear to be\nnear-init from underrepresentation in post-training. ASCII residue\nimmediately before the marker in the natural corpus:\n\n| Surface string    | Single-token | Token ID | Hits in corpus |\n|-------------------|:-:|---------:|---:|\n| `Japgolly`        | ✅ | 199,745 | 1 |\n| `Jsii`            | ✅ | 114,318 | (subtoken of `Jsii_commentary`) |\n| `Jsii_commentary` | — (3 toks) | — | 2 |\n| `changedFiles`    | — (2 toks) | — | 8 |\n| `RTLU`            | — (2 toks) | — | 3 |\n\n`Japgolly` is in the last 0.13% of the vocabulary — the same family of\nGitHub-corpus residue that produced `SolidGoldMagikarp` in the 2023\nGPT-2 vocabulary (Rumbelow & Watkins). `SolidGoldMagikarp` itself\ntokenizes to 5 tokens in `o200k_base` — that specific token was retired,\nbut the class wasn't.\n\nFor the multi-token entries, the corpus-level signature is the surface\nstring; the underlying glitch trigger is a sub-token (e.g. `Jsii` inside\n`Jsii_commentary`). The detector list (`G` signal) keys on the surface\nstrings.\n\nStable across unrelated sessions. Treated as a high-precision detector\nsignal.\n\n### 2.5 Channel-word leakage\n\n`analysis` (5), `assistant` (5), `commentary` (3), `user` (1) appear\ndirectly preceding `to=`. Always bare words; never `<|channel|>analysis`\nor any other bracketed form. Consistent with §1 — the brackets are\nmasked, the words are not.\n\n### 2.6 Non-Latin spam residue\n\n96 marker hits, by script: CJK 40, Cyrillic 12, Telugu/Kannada/Malayalam\n18, Thai 8, Georgian 7, Armenian 7, Arabic 1. Recurring fragments are\nChinese gambling SEO (`大发时时彩`, `天天中彩票`), Georgian/Abkhaz junk,\nand Thai casino spam — well-known low-quality crawl residue.\n\nThis is the same script distribution observed in the controlled\nreproduction (§7.3), independent of the prompt's natural language.\n\n### 2.7 Failure-mode breakdown for the `edit` tool\n\nThe `edit` tool exists in two variants in the corpus:\n\n| Variant                  | Calls | Recovery |\n|--------------------------|------:|----------|\n| Patch-DSL (`§PATH`/anchor/`«»≔` ops) | 27 | **Recoverable** by op-truncation (§3.3) |\n| JSON-schema (`{path,edits:[…]}`)      | 11 | **Not recoverable** — contamination is escaped *inside* JSON strings, parser accepts it cleanly, content would be written verbatim into source files |\n\nFor Patch-DSL leaks specifically:\n\n- 20/27 cases: contamination on the last input line; nothing follows.\n- 7/27 cases: contamination mid-input; what follows is one of: a\n  duplicate replay of an earlier file/anchor, intended content for a\n  *different* tool call (the model started its next call inline), or\n  pure hallucination. Post-contamination content is never trustworthy.\n\n### 2.8 Mechanism (confirmed)\n\n**Prior collapse from null-embedding glitch tokens, into a\ncontrol-token-masked basin whose mass redistributes onto the\nplain-text shadow of the Harmony protocol.**\n\nStep by step:\n\n1. The model is mid-`{ARGS}` of a Harmony tool call. The runtime applies\n   a logit mask suppressing structural control tokens (`<|channel|>`,\n   `<|message|>`, `<|call|>`, `<|start|>`, `<|end|>`) inside the args\n   region. Without this mask, normal generation would constantly\n   hallucinate envelope-closes; with it, those token IDs have logit\n   `-∞` in args.\n2. A glitch token `g` is sampled. By construction `g` was in the BPE\n   merge corpus but barely in LM/RL training, so its **input embedding\n   `e_g` ≈ near-init noise of small norm**.\n3. At position t+1, the residual update `h_{t+1} ≈ LN(h_t + e_g + Attn +\n   MLP)` is dominated by the prefix-derived terms; the just-emitted-token\n   signal is effectively absent. Generation diversity normally comes\n   from `e_x` steering the residual into different sub-regions —\n   stripped here.\n4. The next-token distribution therefore collapses onto the **conditional\n   prior over continuations of the prefix, with local conditioning\n   removed**. In a tool-calling rollout context, that prior is sharply\n   peaked on Harmony scaffolding (control tokens + routing tokens) —\n   that's what RL trained.\n5. The mask zeros the control-token IDs. Mass redistributes onto the\n   **next-best continuation**: the un-bracketed surface-form spelling of\n   the same protocol (`analysis`, `commentary`, ` to=functions.X`,\n   ` code `). This spelling is unmasked because those characters are\n   ordinary tokens.\n6. Once a few tokens of plain-text scaffolding land in the residual\n   stream, the prefix now resembles a fresh envelope start. The macro\n   prior keeps voting for more scaffolding. Cascading (§2.3) follows.\n7. Multilingual spam after the marker is the same prior-collapse\n   continuation, drawn from the training neighborhood of the glitch\n   token (often ESL/auto-generated multilingual web junk — exactly the\n   crawl residue in §2.6).\n\n**Two corollaries the corpus data demanded but only the experiment\nexplained:**\n\n- **The brackets never appear** (§1, §2.5). The mask is what makes the\n  leak land in plain text instead of as a real envelope-close.\n- **Counterintuitive grammar dependency** (§7.4). The leak is *worse* in\n  formats closest to OpenAI's training distribution. Off-distribution\n  custom grammars dampen the macro-prior basin; the official\n  `*** Begin Patch` format is the strongest collapse target.\n\nThe 2023 SolidGoldMagikarp paper documented mechanism (1)+(2)+(4). The\nnew piece is (5): when constrained decoding masks the natural collapse\ntarget, the mass laundered through the un-masked plain-text shadow\nbecomes a structurally-invisible exfiltration channel.",
@@ -58,7 +58,7 @@ export const EMBEDDED_DOCS: Readonly<Record<string, string>> = {
 	"macos-option-key.md": "# macOS + iTerm2 Option/Alt key setup for GJC\n\nHow to make the macOS Option key reach GJC as Alt/Meta input instead of producing composed characters like `œ` or `ˆ`.\n\n## iTerm2 settings\n\nIn **Settings → Profiles → Keys → General** for the profile you use:\n\n- Left Option Key: `+Esc`\n- Right Option Key: `+Esc`\n\nA verified live configuration sets `Option Key Sends = 2` and `Right Option Key Sends = 2` for both the `Default` and `tmux` profiles. iTerm2's `+Esc` setting (`OPTION_KEY_ESC = 2`) prepends ESC to Option input, delivering `Option+Q` as `ESC q` and `Option+I` as `ESC i`. Value `1` is Meta mode and is not an ESC prefix.\n\nIn **Settings → Profiles → Keys → Key Mappings**, remove any `Send Text`, `Send Escape Sequence`, or other mappings that intercept `Option+Q` or `Option+I`, then open a new session for each profile after changing settings.\n\n## macOS input source\n\nSwitch the active keyboard layout to `ABC` when typing GJC Alt commands. `scripts/verify-option-key.sh` does not merely check that ABC is in the list; it verifies `AppleCurrentKeyboardLayoutInputSourceID = com.apple.keylayout.ABC` together with ABC in the selection list.\n\n## Verification\n\n```sh\n./scripts/verify-option-key.sh\npython3 scripts/capture-option-key.py\n```\n\nThe verify script checks the `Default` and `tmux` profiles, both Option keys, Option+Q/I mapping conflicts in both physical-keycode (`Q=12`, `I=34`) and character-code (`q=0x71`, `i=0x69`) form, the active ABC layout, Bun, and the GJC smoke test.\n\nUse the capture tool in a real TTY. In raw mode, Ctrl-C arrives as `0x03` rather than `KeyboardInterrupt`; the tool detects it, restores the terminal, and exits. Confirm with physical key presses in fresh Default and tmux sessions that `Option+Q` and `Option+I` arrive as `ESC q` and `ESC i` and trigger the GJC commands.\n\nRelated live and fixture verification evidence is recorded in `artifacts/option-key-verification.json`.\n",
 	"managed-task-dag.md": "# Managed task DAG — domain and verification contract\n\nThis document describes the private durable domain, graph/resource reservations, authenticated Broker admission, recovery, and trusted verification APIs. It is not a production qualification or release announcement. No public PASS boolean, receipt source label, or caller-supplied verification id authorizes readiness.\n\n## Boundary\n\n- Protection applies only to enrolled managed callers that persist through this domain and later authenticated Broker admission (M2). Ordinary spawn, editors, raw shell, other task tools, and foreign control roots or agent directories are outside prevention.\n- There is no OS-global write exclusion, sandbox, or syscall monitor. Identity checks observe declared drift; they do not certify unmanaged writers.\n- Distinct control roots and agent-directory identities do not exclude one another.\n- Linux, private, and offline is the first publication boundary. Cross-host and DrvFS semantics are out of scope.\n- Native spawn journals, lock recovery, default workflow/role surfaces, and Workroom product code are unchanged by this slice.\n\n## Domain address and enrollment\n\nPersist exactly one v1 snapshot per enrolled control root:\n\n`<canonicalControlRoot>/.gjc/managed-task-domain/state.json`\n\nDo not hunt the filesystem, copy per session/run/graph, or treat `commonDir` as root authority. Enrollment is explicit: control root, agent directory, enrollment id, worktrees, and optional aliases that still resolve to an enrolled target.\n\n`createManagedDomainBinding` records canonical real paths plus directory device/inode identities. Changed, unprovable, or escaped bindings refuse later admission. Aliases are accepted only while their real target remains the enrolled target.\n\n## Permissions and publication\n\nOpt-in Linux private durable source publication (state writer `privateDurable`) applies only to this domain subtree:\n\n- newly created domain directory `0700`\n- domain state file `0600`\n- sync the written file before rename and the publication directory after rename\n- establish and sync new directory entries, including initial subtree creation through the existing parent\n\nExisting unrelated directories are never chmodded or repaired. An unsafe or unprovable existing subtree is rejected. Generic writer callers keep their existing corruption policy.\n\nPublication uses existing `withWorkflowStateLock`, strict `readExistingStateForMutation`, and `writeGuardedJsonAtomic` with `policy: \"source\"`, `expectedRevision`, and `lockHeld: true`. The generic writer receives no Broker or DAG types. Do not nest `updateJsonAtomic` or reacquire the same non-reentrant lock.\n\nOnce a domain is established, missing, corrupt, unreadable, non-object, extra-key, or binding-mismatched state fails closed. Fresh enrollment (`expectedRevision === 0` and absent file) requires `assertNoManagedEvidence` under the domain lock; it must not initialize an empty replacement automatically. Post-rename sync or audit failure is potentially committed: reload authoritative state; never discard a reservation or retry with a new native key.\n\n## Graph, resources, and byte roles\n\n`ManagedTaskGraph` / `ManagedTaskDefinition` bind node id, task revision, graph revision, attempts, dependency vectors, criteria identity, resource declarations, and native references. Duplicate ids, missing predecessors, cycles, extra keys, empty validation lists, and unauthorized bindings are rejected before mutation.\n\nReadiness is deterministic and dependency-based: a node is ready only from an accepted current predecessor verification vector, never from `terminal_ok`, accepted seed, valid JSON, or a closed worker. M1 stores reservations with `accepted: null`, so successors stay unready until later trusted verification.\n\nResource overlap is domain-wide across graph runs:\n\n- read/read allowed\n- overlapping read/write and write/write denied\n- path identity uses canonical path plus object identity; absent outputs use ancestor identity and normalized suffix\n- recursive directory overlap is segment-aware (`a` is not an ancestor of `ab`)\n- same-object hardlinks conflict; unprovable symlink/escape paths fail closed\n- parent namespace writes are required for create/delete/rename\n- named resources use canonical database identity, port (protocol/address/number), and integration target; supported address wildcards conflict with concrete values\n\nByte roles (I0/P/V/Q/PV) are recorded on attempts. M1 captures admission input manifests and predecessor vectors; it does not accept produced output or validation results. Conflicting artifact roles and missing namespace writes refuse graph mutation.\n\n## Dual lifetimes (policy only)\n\nReservations remain while either native-worker or validation lifetime is unproven. `canRetireManagedAttempt` is conjunctive: worker is `no-effect` or `closed`, validation is `not-started` or `finished`, and a current fence still requires accepted verification. Unknown validation cannot retire. Cancel and revise fence logical success and retain immutable attempt history; they do not rewrite old reservations or release unproven effects.\n\n## Exported APIs for M2\n\nTrusted internal policy surface in `src/sdk/broker/managed-task-dag.ts`. Not a public wire parser.\n\n| Symbol | Role |\n| --- | --- |\n| `createManagedDomainBinding` | Explicit enrollment identities |\n| `managedTaskDomainPath` | Exact snapshot address |\n| `transactManagedTaskDomain` | Domain lock, strict read, schema/binding, source CAS, private durable write |\n| `defineManagedTaskGraph` | Atomic graph insert under a held transaction |\n| `admitManagedTask` | All-or-none reservation; returns private `ManagedAttemptRef` |\n| `readyManagedTasks` | Deterministic ready node ids |\n| `canonicalizeManagedResources` / `managedResourcesOverlap` / `managedResourcesConflict` | Canonical overlap |\n| `parseManagedTaskDefinitions` / `validateManagedTaskDomain` | Fail-closed schema |\n| `captureManagedManifest` / `assertManagedManifestCurrent` | Byte identity |\n| `cancelManagedTasks` / `reviseManagedTaskGraph` | Fence without releasing unproven lifetimes |\n| `canRetireManagedAttempt` / `retireManagedAttempt` | Conjunctive retirement |\n| `managedIdentity` | Canonical digest |\n| `ManagedAttemptRef` | Internal handoff after durable reservation; M2 keeps it private after verified Broker admission |\n\n`ManagedAttemptRef` binds control root, enrollment id, agent-directory identity, graph/node/task/attempt revisions, definition/input/predecessor/resource identities, and the caller-supplied native `deriveIdempotencyIdentity` result. Caller fields cannot mint this object on the wire.\n\n`transactManagedTaskDomain({ binding, expectedRevision, assertNoManagedEvidence? }, mutation)` is the only durable mutation entry. CAS losers recompute from fresh state. Competing same-resource writers: exactly one complete reservation at the next revision; the loser is stale/conflict. Disjoint writers may both admit after retry.\n\n## M2 raw wire and auth (test-only)\n\n`task.dag` is on the Broker WebSocket allowlist (`BROKER_OPERATIONS`). The documented initial interface is protocolVersion 3 loopback `broker_request` through `Broker.start()` discovery URL/token. There is no CLI, generated protocol, or generic lifecycle lookup for spawn.\n\nPlaceholder envelope (not live credentials):\n\n`{type:\"broker_request\",id:\"req-1\",operation:\"task.dag\",input:{action:\"advance\",controlRoot:\"<canonical enrolled root>\",enrollmentId:\"<enrollment>\",graphId:\"g1\",nodeId:\"n1\",expectedRevision:7,ownerSessionId:\"<owner>\",attestationEpoch:\"<epoch>\",masterCapability:\"<live capability>\",maxAdmissions:2}}`\n\nActions: `define`, `advance`, `status`, `revise`, `cancel`, `verify`. All require authenticated transport plus live master capability/owner/epoch and exact domain binding. Mutations require `expectedRevision`. Public `pass`/`accepted`/`receipt` fields are refused. Worker `cwd` is the admitted node `workspace`; an explicit caller cwd that does not match is refused before reservation. Exact same-key `advance` observes the original unretired reservation and re-enters native claim recovery; it does not allocate a second attempt.\n\nPublic `session.spawn` and `task.dag` both verify the live capability, erase it, then use one private verified-admission path. `ManagedAttemptRef` is minted only after durable domain reservation; wire fields cannot create it. Ordinary `session.spawn` on a known managed native identity is rejected without that internal authority. If the enrollment index cannot be proven readable, ordinary spawn is refused with a bounded membership error rather than authorized as unmanaged. Unrelated keys remain unmanaged only while the index is provable. No graph fields enter the spawn-authority journal.\n\nNative fences recheck the current managed vector and cancel fence immediately before `prepared -> substrate_starting` and before `seed_prepared -> dispatching`. Launch authorization and the native `prepared -> substrate_starting` transition share the domain lock, same as seed; the lock is released before `provider.launch`. Domain lock is also released before registration, prompt dispatch, close, or validation. Workspace is part of definition and native identity, so a workspace-only revision fences the old attempt.\nClients consume `broker_hello` once after connect, then match each `broker_response` by request `id`. A leftover hello or unmatched frame is not a later action's result.\n\nWrong transport token never reaches the broker. Correct token with wrong master capability yields domain writes 0 and native launches 0. Competing same-resource advance starts 0 additional effects; disjoint pair starts 2.\n\nM3 restores enrolled managed-key protection on cold restart from the durable enrollment index at `<agentDir>/.gjc/managed-task-enrollments/index.json` plus the domain snapshot. An unreadable index cannot authorize ordinary unknown membership. Ordinary spawn still does not hunt `agentDir` or TMPDIR.\n\n## M3 recovery and close\n\nStartup restores unretired ManagedAttemptRef values from enrolled control roots whose agentDir identity still matches, then reconciles native journals before Broker discovery publication. Same native identity cannot start a second effect. Authenticated retry of the original key with a live revision observes the existing reserved attempt and resumes native `claimOrJoin` for `reserved`/`prepared`/`seed_prepared` after revalidating the immutable vector; it does not mint a duplicate reservation. `substrate_starting`, `dispatching`, response loss, `uncertain`, and missing authority observe worker `unknown` and retain reservations. Accepted seed or a terminal turn does not close the worker.\n\nCancel/revise first fences logical success, then exact owned close of attempts belonging to that graph identity and affected node ids only. A second graph that reuses the same node id keeps its child. Signal, `close_requested`, and timeout do not prove gone. Pre-send rejection with a substrate still needs close. Release remains conjunctive: worker no-effect or exact closed/gone, and validation not-started or finished. A closed worker does not retire an active/unknown validator. Missing or corrupt evidence blocks; there is no TTL, new-key retry, process hunt, or lock cleanup.\nCancel and revise require the caller's `expectedRevision` to equal the live domain revision (strict CAS). A stale caller view is conflict, not applied over unseen current state. After both lifetimes are proven quiescent, retirement can admit a replacement attempt for the current node revision.\n`session.close` of an exact spawn child observes worker `closed` in the same broker lifetime, so `task.dag verify` does not require a broker restart.\n\n## M4a shared asynchronous validation runner\n\n`defaultFinalizeChecks(workspace).runValidation(spec)` remains the one shared executor. It still returns `{ exactCommand, cwd, exitStatus, pass }` from `bash -lc spec.command` in `workspace`. Existing owner callers already await that Promise; the signature is unchanged.\n\nThe body is asynchronous Bun.spawn, not spawnSync. stdout and stderr are continuously drained and discarded as they arrive; chunks are not retained as unbounded buffers and are not returned. Spawn failure (no process) is a terminal `pass: false` with `exitStatus` 1. After spawn succeeds, a failed stream or exit observation is not a finished `ValidationRun`: the runner kills, awaits real exit, and throws `ValidationObservationUncertainError` so managed verification stays unknown. The return never includes pid, receipt id, output paths, or process authority.\n\nThe existing owner and finalizer catch this typed uncertainty, return a blocked outcome, and issue no validation receipt for that command or completion receipt. Later commands and publication checks do not continue after the uncertain observation. Managed verification reports `unknown` consistently with durable state; `commandsStarted` is true for the call that invoked validation and false for a later observation-only retry.\n\nGit and gh methods on the same object are unchanged. During a long validation the event loop stays free for timers, Broker heartbeat, and status.\n\n## M4b trusted verification\n\n`task.dag` action `verify` runs `verifyManagedTaskAttempt` against the shared `defaultFinalizeChecks(workspace).runValidation` executor. Public `pass`/`accepted`/`receipt` fields remain refused. Trusted PASS is published only after:\n\n1. worker is exact `closed`\n2. durable verification-start marker (`validation: running` + execution id/commands) is stored before any command\n3. sequential approved nonempty criteria, each actual `ValidationRun` persisted\n4. I0 read-only and predecessor PV bytes still match, produced P frozen through V, Q on declared validation-output artifact roots including recursive children of a declared Q directory (paths outside those Q roots fail closed). Role roots are the declared artifact paths; recursive resources authorize coverage only and do not erase a declared input or enlarge P/Q to a covering workspace reservation.\n5. existing `buildReceipt`/`validateReceipt` envelopes stored privately with owner sessionId, exact workspace, internal source, exitStatus 0 and pass true\n6. domain CAS publishes `accepted` + `validation: finished`\n\nDuplicate verify while running/unknown/finished starts 0 additional commands. Repeat verify of a current accepted attempt returns the existing trusted receipt only while fence is `current`, the attempt matches the current node definition/taskRevision, and I0/P/PV bytes still match; drifted bytes refuse a stale PASS. Historical accepted receipts after cancel/revise are not current PASS. Recursive children of a declared input/output artifact remain in I0/P/V/PV; a shared recursive write reservation over the workspace does not promote that reservation into the input or output role. The first failed criterion records `validation: finished` with `fence: failed` and the proven observations only; later commands do not run and the result is not `unknown`. Internal verification mutations recompute under the domain lock. `accepted.hash` is the stored receipt envelope `sha256`, not a composite digest. Start marker without finish, or receipt publication failure, becomes `validation: unknown` and retains reservations. A corrupt domain snapshot remains fail-closed (`managed-task: corrupt authority`); it is not re-initialized. Cancel/revise fence immediately; an active or unknown validator is not retired by worker close. Restart reconciles running markers to unknown before discovery publication. No PID authority, extra daemon, or client-uploaded PASS.\n\n## Remaining limits\n\n- Unknown validator recovery still requires independently authoritative evidence outside v1 automatic recovery.\n- No new daemon, database, or lock-recovery path.\n- Feature completeness waits for later connected offline acceptance.\n\n## M5 revision and invalidation\n\n`reviseManagedTaskGraph` validates the whole replacement graph, then seeds from changed task/criteria/resources/artifacts/validations/predecessor sets (including removed nodes and edges). Downstream closure is the union of old and new edges. Affected current attempts are fenced `superseded`; already canceled fences stay canceled. Immutable attempt history and reservation sets are retained. Global graph revision alone is not staleness: an unchanged T/I0/P/V/PV vector keeps its current PASS.\n\nSuccessor eligibility still requires a current accepted predecessor vector and live consumed P bytes at admission. Cache-only Q writes are not predecessor inputs. A late verify cannot mint PASS after cancel/revise wins the domain transaction. `reducedWorkroomManagedDefinitions` is a native fixture for S5→UI1a→S8→UI1b→UI2, S5→S6→S7→S8, S8→S10a→S10b, optional S8→S9a→S9b; S11 is not a common prerequisite. Workroom product code is not edited.\nStored definition hashes are computed from JSON-canonical schema output so reload matches insert. Independent concurrent writers must declare disjoint write namespaces; a shared parent-directory write remains a real conflict.\n\n## M6 connected offline boundary\n\nConnected offline tests exercise authenticated `task.dag` WebSocket frames through `Broker.start()`, native spawn claim/launch/seed, shared `defaultFinalizeChecks.runValidation`, and trusted domain PASS. They do not enable a user-facing release.\n\nScenario inventory (parent gates):\nConnected tests fetch live `task.dag` `status.stateRevision` before later define/advance/revise after native observation writes; they do not guess CAS counters.\n\n1. Independent writers 2 launches; overlapping writer 0 extra effects. Wrong transport token and wrong master capability yield launches 0.\n2. Same graph defines A then B. Same-broker-lifetime `session.close` observes worker `closed`, then verify PASS, then advance B consuming A's accepted P/PV and producing B's output.\n3. Failed predecessor: close and verify A first (`exit 7` / absent required output, no accepted PV), then advance B is effects 0.\n4. Response-loss then restart: same native identity launches 0 duplicates; ordinary spawn on the managed key is refused. This is spawn-uncertain retention, not a live validation-unknown start-marker.\n5. Graph revise with live expectedRevision fences superseded attempts; stale expectedRevision is rejected. Reservations stay until both lifetimes are proven.\n\nHonest limits: there is no OS-global write exclusion. Ordinary spawn, editors, and raw shell remain outside prevention. Undeclared sibling files are not a Q-isolation gate; Q isolation is declared validation-output roots and their children. Connected e2e kills a test-owned Broker after its shared validator starts, then checks recovered uncertainty, retained reservations, and a countable single invocation. It does not certify recovery from every OS or validator failure. Feature-complete requires independent architect/critic review of these gates; this slice is not a release advertisement.\n",
 	"memory.md": "# Autonomous Memory\n\nWhen enabled, the agent automatically extracts durable knowledge from past sessions and injects a compact summary into each new session. Over time it builds a project-scoped memory store — technical decisions, recurring workflows, pitfalls — that carries forward without manual effort.\n\nDisabled by default. Enable via `/settings` or `config.yml`:\n\n```yaml\nmemories:\n  enabled: true\n```\n\n## Usage\n\n### What gets injected\n\nAt session start, if a memory summary exists for the current project, it is injected into the system prompt as a **Memory Guidance** block. The agent is instructed to:\n\n- Treat memory as heuristic context — useful for process and prior decisions, not authoritative on current repo state.\n- Pair memory-influenced decisions with current-repo evidence before acting.\n- Prefer repo state and user instruction when they conflict with memory; treat conflicting memory as stale.\n\n### Memory artifacts\n\nGenerated local-memory artifacts are private runtime state, not a public tool or URI surface. They may be summarized into the system prompt when local memory is enabled, but users and model-facing tool docs should not rely on direct `memory://` reads. The legacy internal `memory://` resolver remains only for compatibility with existing persisted guidance and is not part of the public coding harness contract; remove it after legacy local-memory prompts no longer reference it.\n### `/memory` slash command\n\n| Subcommand            | Effect                                         |\n| --------------------- | ---------------------------------------------- |\n| `view`                | Show the current memory injection payload      |\n| `clear` / `reset`     | Delete all memory data and generated artifacts |\n| `enqueue` / `rebuild` | Force consolidation to run at next startup     |\n\n## How it works\n\nMemories are built by a background pipeline that runs at startup or when manually triggered via slash command.\n\n**Phase 1 — per-session extraction:** For each past session that has changed since it was last processed, a model reads the session history and extracts durable signal: technical decisions, constraints, resolved failures, recurring workflows. Sessions that are too recent, too old, or currently active are skipped. Each extraction produces a raw memory block and a short synopsis for that session.\n\n**Phase 2 — consolidation:** After extraction, a second model pass reads all per-session extractions and produces three outputs written to disk:\n\n- `MEMORY.md` — a curated long-term memory document\n- `memory_summary.md` — the compact text injected at session start\n- `skills/` — reusable procedural playbooks, each in its own subdirectory\n\nPhase 2 uses a lease to prevent double-running when multiple processes start simultaneously. Stale skill directories from prior runs are pruned automatically.\n\nAll output is scanned for secrets before being written to disk.\n\n### Extraction behavior\n\nMemory extraction and consolidation behavior is driven by static prompt files in `packages/coding-agent/src/prompts/memories/`.\n\n| File                  | Purpose                                     | Variables                                   |\n| --------------------- | ------------------------------------------- | ------------------------------------------- |\n| `stage_one_system.md` | System prompt for per-session extraction    | —                                           |\n| `stage_one_input.md`  | User-turn template wrapping session content | `{{thread_id}}`, `{{response_items_json}}`  |\n| `consolidation.md`    | Prompt for cross-session consolidation      | `{{raw_memories}}`, `{{rollout_summaries}}` |\n| `read_path.md`        | Memory guidance injected into live sessions | `{{memory_summary}}`                        |\n\n### Model selection\n\nMemory piggybacks on the model role system.\n\n| Phase                   | Role                                                                | Purpose                          |\n| ----------------------- | ------------------------------------------------------------------- | -------------------------------- |\n| Phase 1 (extraction)    | `default`                                                           | Per-session knowledge extraction |\n| Phase 2 (consolidation) | `smol` (falls back to `default`, then current/first registry model) | Cross-session synthesis          |\n\nIf the requested memory role is not configured, memory model resolution falls back to the `default` role, then the active session model, then the first model in the registry.\n\n## Configuration\n\n| Setting                               | Default | Description                                               |\n| ------------------------------------- | ------- | --------------------------------------------------------- |\n| `memories.enabled`                    | `false` | Master switch                                             |\n| `memories.maxRolloutAgeDays`          | `30`    | Sessions older than this are not processed                |\n| `memories.minRolloutIdleHours`        | `12`    | Sessions active more recently than this are skipped       |\n| `memories.maxRolloutsPerStartup`      | `64`    | Cap on sessions processed in a single startup             |\n| `memories.summaryInjectionTokenLimit` | `5000`  | Max tokens of the summary injected into the system prompt |\n\nAdditional tuning knobs (concurrency, lease durations, token budgets) are available in config for advanced use.\n\n## Key files\n\n- `packages/coding-agent/src/memories/index.ts` — pipeline orchestration, injection, slash command handling\n- `packages/coding-agent/src/memories/storage.ts` — SQLite-backed job queue and thread registry\n- `packages/coding-agent/src/prompts/memories/` — memory prompt templates\n- `packages/coding-agent/src/internal-urls/memory-protocol.ts` — legacy non-public `memory://` compatibility handler\n",
-	"models.md": "# Model and Provider Configuration (`models.yml`)\n\nThis document describes how the coding-agent currently loads models, applies overrides, resolves credentials, and chooses models at runtime.\n\n## What controls model behavior\n\nPrimary implementation files:\n\n- `src/config/model-registry.ts` — loads embedded + signed-registry + custom models, provider overrides, runtime discovery, auth integration\n- `src/config/model-resolver.ts` — parses model patterns and selects models for the default and agent roles\n- `src/config/settings-schema.ts` — model-related settings (`modelRoles`, provider transport preferences)\n- `src/session/auth-storage.ts` — API key + OAuth resolution order\n- `packages/ai/src/models.ts` and `packages/ai/src/types.ts` — built-in providers/models and `Model`/`compat` types\n\n## Config file location and legacy behavior\n\nDefault config path:\n\n- `~/.gjc/agent/models.yml`\n\nLegacy behavior still present:\n\n- If `models.yml` is missing and `models.json` exists at the same location, it is migrated to `models.yml`.\n- Explicit `.json` / `.jsonc` config paths are still supported when passed programmatically to `ModelRegistry`.\n\n## `models.yml` shape\n\n```yaml\nproviders:\n  <provider-id>:\n    # provider-level config\nequivalence:\n  overrides:\n    <provider-id>/<model-id>: <canonical-model-id>\n  exclude:\n    - <provider-id>/<model-id>\n```\n\n`provider-id` is the canonical provider key used across selection and auth lookup.\n\n`equivalence` is optional and configures canonical model grouping on top of concrete provider models:\n\n- `overrides` maps an exact concrete selector (`provider/modelId`) to an official upstream canonical id\n- `exclude` opts a concrete selector out of canonical grouping\n\n## Provider-level fields\n\n```yaml\nproviders:\n  my-provider:\n    baseUrl: https://api.example.com/v1\n    apiKey: MY_PROVIDER_API_KEY\n    api: openai-completions\n    headers:\n      X-Team: platform\n    authHeader: true\n    auth: apiKey\n    disableStrictTools: false  # set true for Anthropic-compatible endpoints that reject the strict field\n    cacheRetention: short  # none | short | long; model entries and modelOverrides can override this\n    discovery:\n      type: ollama\n    modelOverrides:\n      some-model-id:\n        name: Renamed model\n        cacheRetention: long\n    models:\n      - id: some-model-id\n        name: Some Model\n        api: openai-completions\n        reasoning: false\n        input: [text]\n        cost:\n          input: 0\n          output: 0\n          cacheRead: 0\n          cacheWrite: 0\n        contextWindow: 128000\n        maxTokens: 16384\n        headers:\n          X-Model: value\n        cacheRetention: none\n        thinking:\n          minLevel: low\n          maxLevel: xhigh\n          mode: effort\n          defaultLevel: high\n          levels: [low, medium, high, xhigh]\n        compat:\n          supportsStore: true\n          supportsDeveloperRole: true\n          supportsReasoningEffort: true\n          maxTokensField: max_completion_tokens\n          openRouterRouting:\n            only: [anthropic]\n          vercelGatewayRouting:\n            order: [anthropic, openai]\n          extraBody:\n            gateway: m1-01\n            controller: mlx\nmodelBindings:\n  modelRoles:\n    default: my-provider/some-model-id:high\n  agentModelOverrides:\n    executor: my-provider/some-model-id\n```\n\n### Allowed provider/model `api` values\n\n- `openai-completions`\n- `openai-responses`\n- `openai-codex-responses`\n- `azure-openai-responses`\n- `bedrock-converse-stream`\n- `anthropic-messages`\n- `google-generative-ai`\n- `google-vertex`\n- `google-gemini-cli`\n- `ollama-chat`\n- `cursor-agent`\n\n\n### First-class DeepInfra, Azure OpenAI, and Amazon Bedrock examples\n\nAzure OpenAI uses canonical OpenAI model IDs in GJC and resolves those IDs to Azure deployment names at request time. Set `AZURE_OPENAI_DEPLOYMENT_NAME_MAP` to avoid assuming model id equals deployment name:\n\n```yaml\nproviders:\n  azure-openai:\n    baseUrl: https://my-resource.openai.azure.com/openai/v1\n    apiKeyEnv: AZURE_OPENAI_API_KEY\n    api: azure-openai-responses\n    models:\n      - id: gpt-4.1\n      - id: o3\n```\n\n```sh\nexport AZURE_OPENAI_DEPLOYMENT_NAME_MAP='gpt-4.1=gpt-41-prod,o3=o3-reasoning-prod'\n```\n\nDeepInfra is available as the first-class `deepinfra` provider. It uses DeepInfra's OpenAI-compatible Chat Completions endpoint and reads `DEEPINFRA_API_KEY` when no explicit config key is provided. Set `serviceTier: priority` in GJC config or use the runtime service-tier controls to send DeepInfra's `service_tier: \"priority\"` request field for supported models:\n\n```yaml\nproviders:\n  deepinfra:\n    baseUrl: https://api.deepinfra.com/v1/openai\n    apiKeyEnv: DEEPINFRA_API_KEY\n    api: openai-completions\n    models:\n      - id: deepseek-ai/DeepSeek-V3.2\n```\n\n#### `/fast` provider support\n\n`/fast on` only shows `⚡` when GJC will put a fast/priority field on the selected provider's wire request:\n\n| Provider ID | Wire request | Notes |\n|---|---|---|\n| `openai` | `service_tier: \"priority\"` | OpenAI renamed Priority processing to [Fast mode](https://developers.openai.com/api/docs/guides/fast-mode); `priority` remains an accepted alias. For API-key requests, the response `service_tier` reports the tier actually used and may be `default` after a ramp-rate downgrade. |\n| `openai-codex` | `service_tier: \"priority\"` | ChatGPT-authenticated Codex handles Fast through server-side routing. A final response value of `service_tier: \"default\"` does not show that Fast was ignored or downgraded. |\n| `anthropic` | `speed: \"fast\"` plus `fast-mode-2026-02-01` beta | Direct Claude API only. Anthropic's [Fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode) is model- and account-gated; unsupported or unavailable requests can fall back after a provider rejection. Bedrock, Vertex, and Microsoft Foundry do not support it. |\n| `deepinfra` | `service_tier: \"priority\"` | Sent only for the first-class `deepinfra` provider ID and only with the `priority` tier. |\n| `opencodex` | `service_tier: \"priority\"` | First-class OpenCodex discovery opts in automatically; OpenCodex Fast Mode must remain `Auto` for client passthrough. When OpenCodex uses ChatGPT authentication, a final `service_tier: \"default\"` is not downgrade evidence. |\n\nCustom OpenAI-compatible providers remain fail-closed unless their provider or model configuration explicitly sets `compat.supportsServiceTier: true`. Use that opt-in only when the proxy preserves or intentionally realizes OpenAI's `service_tier` contract:\n\n```yaml\nproviders:\n  my-openai-proxy:\n    baseUrl: http://proxy.example/v1\n    api: openai-responses\n    compat:\n      supportsServiceTier: true\n```\n\nWithout that capability, `/fast status` shows `off` even when the session retains an unscoped `priority` intent. The `⚡` indicator means that GJC sends the provider's fast request field. API-key providers may report a downgrade in their response; ChatGPT-authenticated Codex and OpenCodex route Fast server-side and cannot be verified from the final `service_tier` value.\n\nAmazon Bedrock uses the native `bedrock-converse-stream` transport and AWS credential chain auth. Do not put AWS access keys in `models.yml`; configure `AWS_REGION` / `AWS_PROFILE` or standard static AWS credential environment variables instead:\n\n```yaml\nproviders:\n  amazon-bedrock:\n    baseUrl: https://bedrock-runtime.us-east-1.amazonaws.com\n    api: bedrock-converse-stream\n    models:\n      - id: us.anthropic.claude-opus-4-6-v1\n      - id: anthropic.claude-3-5-sonnet-20241022-v2:0\n```\n\n### Coding-plan provider presets\n\nFor supported coding-plan providers, prefer presets so the API type, base URL, environment variable, model catalog, discovery behavior, and compatibility flags are written together:\n\n```sh\ngjc setup provider --preset minimax\ngjc setup provider --preset minimax-cn\ngjc setup provider --preset glm\ngjc setup provider --preset alibaba-token-plan\ngjc setup provider --preset cline-pass\ngjc setup provider --preset commandcode-goat\ngjc setup provider --preset ionet\n```\n\nThe same presets are available inside the TUI:\n\n```text\n/provider add --preset minimax\n/provider add --preset glm\n/provider add zai\n/provider add --preset alibaba-token-plan\n/provider add --preset cline-pass\n/provider add --preset commandcode-goat\n/provider add --preset ionet\n```\n\nPresets only write `models.yml` entries that reference documented environment variable names (`MINIMAX_CODE_API_KEY`, `MINIMAX_CODE_CN_API_KEY`, `ZAI_API_KEY`, `ALIBABA_TOKEN_PLAN_API_KEY`, `CLINE_API_KEY`, `CMD_API_KEY`, or `IONET_API_KEY`); they do not store or validate real credentials. The GLM preset aliases (`glm`, `zai`, `z-ai`) write an OpenAI-compatible custom provider named `glm-proxy` and do not replace the first-class `zai` provider. The Alibaba Token Plan preset (aliases: `alibaba`, `token-plan`) writes an OpenAI-compatible custom provider named `alibaba-token-plan` with per-model API routing. The ClinePass preset (aliases: `clinepass`, `cline`) does not hardcode models: Cline's inference API has no working `/models` route, so GJC follows Cline's own catalog-generation source and fetches the live `cline-pass` provider catalog from `https://models.dev/api.json`. The Command Code GOAT preset (aliases: `commandcode`, `command-code`, `goat`) fetches its live `/provider/v1/models` catalog, keeps every current or future model—including Claude-named IDs—on the provider's documented OpenAI-compatible `/chat/completions` transport, and requires a fixed harmless inference entitlement probe before login persistence. The IO Intelligence preset (aliases: `io-net`, `io-intelligence`) writes an OpenAI-compatible custom provider named `ionet` for [IO Intelligence](https://io.net) by io.net; model ids are `org/name` pairs discovered live from the endpoint's `/models` route, so no models are hardcoded. Create the corresponding API key in the provider dashboard before inference.\n\n## Signed remote preset registry\n\nGJC ships its embedded model metadata and profiles as an immutable bootstrap fallback, then overlays a separately published signed registry before applying local configuration:\n\n1. embedded model presets and profiles\n2. the last accepted `Yeachan-Heo/gajae-code-presets` registry snapshot\n3. user `~/.gjc/agent/models.yml` entries and overrides\n\nLocal user configuration always wins. Registry refresh never writes `models.yml`, and a failed, partial, oversized, incompatible, downgraded, equivocated, digest-mismatched, or untrusted update never replaces the active snapshot. Startup reads only the verified local cache and does not wait for network I/O; a delayed best-effort refresh runs at a bounded cadence. Offline cold starts use embedded data, while offline warm starts use the last-known-good accepted snapshot.\n\nThe registry manifest is canonical JSON signed with a compiled Ed25519 trust root. Signatures are 64-byte Ed25519 values encoded as canonical RFC 4648 Base64; unused padding bits must be zero, so two encodings of the same signature cannot produce distinct anti-equivocation digests. The signed payload binds the monotonic revision, consumer-contract compatibility, immutable revision paths, exact byte counts, SHA-256 digests, source commit provenance, snapshot, profile data, and credential-free model metadata. GJC sends no cookies, authorization headers, API keys, or provider credentials when fetching it. Registry schemas do not permit endpoints, request headers, credentials, environment references, commands, scripts, or arbitrary executable content. Selectors, preset identifiers, display text, and context-promotion targets reject Unicode format controls. Registry provider IDs are slash-free (`[a-z0-9][a-z0-9._-]*`), matching profile `requiredProviders` and the first-slash selector boundary used at runtime.\n\nAdministrative commands:\n\n```sh\ngjc models presets status [--json]\ngjc models presets refresh [--json]\ngjc models presets rollback <accepted-revision> [--json]\ngjc models presets pin <accepted-revision> [--json]\ngjc models presets unpin [--json]\ngjc models presets disable [--json]\ngjc models presets enable [--json]\n```\n\n`status` reports deterministic, credential-free provenance: active and highest-seen revisions, manifest/snapshot/profile/preset digests, signature key id, source GJC commit, accepted/published/check timestamps, retained removed entries, cache health, history, and pin/disable state. Rollback and pin can select only previously verified retained revisions; neither lowers the highest-seen anti-rollback floor, and selected generations are protected from bounded-history eviction. A rollback remains selected across background refreshes until another rollback/pin is chosen or `unpin` returns selection to the highest accepted revision. When a registry revision removes a profile, GJC retains that profile plus only the removed model metadata and dynamic-provider declarations it references so an existing default/current selection remains usable without unboundedly copying the whole prior catalog.\n\nThe cache and control files live under `~/.gjc/agent/model-presets/` (respecting `GJC_CODING_AGENT_DIR`). Writes use an interprocess lock, file fsync, and atomic rename. POSIX filesystems also receive a parent-directory durability barrier; Windows does not expose an equivalent directory fsync through Bun/Node, so it retains the file-fsync + atomic-rename guarantee with weaker crash durability for the renamed directory entry. `GJC_MODEL_PRESET_REGISTRY_URL` may override the manifest URL only with credential-free HTTPS; the trust root cannot be replaced at runtime. `GJC_MODEL_PRESET_REGISTRY_DISABLED=1` provides a non-destructive environment disable.\n\n## Model profiles (`--mpreset`)\n\nModel profiles are optional top-level `profiles:` entries in `~/.gjc/agent/models.yml`. A profile can require provider credentials before activation and can map one or more model roles; omitted roles inherit from the active defaults.\n\n> See also: [Cross-vendor role-based profiles](./multi-vendor-profiles.md) — a curated multi-vendor `profiles:` recipe and verified selector notes that build on the mechanism described here.\n\n```yaml\nprofiles:\n  team-standard:\n    required_providers: [openai, anthropic]\n    model_mapping:\n      default: openai/gpt-5.2\n      executor: anthropic/claude-sonnet-5:medium\n      architect: openai/o3:high\n      planner: openai/o3:high\n      critic: openai/o3:high\n```\n\n`model_mapping` keys are role names (`default`, `executor`, `architect`, `planner`, `critic`). Every role accepts either one selector or a non-empty ordered array of selectors; the first entry is primary and later entries are fallback candidates. A selector may be a provider-agnostic bare alias such as `glm-5.2[:effort]` or an explicit `provider/modelId[:effort]` pin, including nested model IDs such as `openrouter/anthropic/claude-sonnet-5`. `required_providers` lists explicit provider prerequisites and may be empty when availability is resolved from bare aliases.\n\n### Fallback chains\n\nPreset `model_mapping` roles, top-level `modelRoles`, and `task.agentModelOverrides` all accept `string | string[]`. Keep one selector per line when a chain needs to be readable:\n\n```yaml\nprofiles:\n  reliable:\n    required_providers: [anthropic, openai]\n    model_mapping:\n      default: [anthropic/claude-sonnet-4-5, openai/gpt-4o-mini]\nmodelBindings:\n  modelRoles:\n    default: [anthropic/claude-sonnet-4-5, openai/gpt-4o-mini]\n  agentModelOverrides:\n    executor: [anthropic/claude-sonnet-4-5, openai/gpt-4o-mini]\n```\n\nResolution-time skips for unavailable, unauthenticated, or unknown entries cost zero attempts and advance immediately. Only request-time retryable failures (such as 429, quota, authentication, or 5xx failures) consume an entry's `fallback.maxAttempts` total attempts (default: `3`). The active default fallback remains sticky for the session; role-override fallback state is fresh for each subagent call. The active model is shown consistently in status and `/model`.\n\nManaged fallback attempts buffer provisional streamed output until an attempt is accepted, so output can appear later than it does for a one-model stream. Current Cursor-agent transports are fail-closed unavailable in retryable fallback chains: resolution rejects them with `Cursor model <selector> requires provider-side tool execution and cannot be used in a retryable fallback chain` because they do not provide a client-side tool-call mode.\n\nCancellation discards provisional output and emits exactly one cancelled `agent_end`; RPC, ACP, and the TUI therefore settle once. On load, the source-aware one-shot migration reads legacy `retry.fallbackChains`, prepends the effective role chain, and writes the ordered, deduplicated result to the corresponding role array; the legacy key is then ignored.\n\nBuilt-in profiles are grouped by provider mix and tier:\n\n- `codex-{eco,medium,pro}` — GPT-5.6 Sol/Terra/Luna role mixes tuned by tier and reasoning effort; `lunamaxxing` — OpenAI Codex Luna-only profile with maximum reasoning on delegated roles\n- `astra-{lite,default,heavy}` — additive OpenAI Codex profiles led by `openai-codex/gpt-6-astra`, displayed as `ASTRA-Lite`, `ASTRA-Default`, and `ASTRA-Heavy` in the CODEX group\n- `opencodego` — single OpenCode Go preset (Kimi K3 default and planner, DeepSeek executor/architect, MiMo critic)\n- `commandcode-goat` — Command Code GOAT preset (GLM-5.3 default, DeepSeek V4 Flash executor, Kimi K3 planner, GLM-5.2 critic, and DeepSeek V4 Pro architect)\n- Provider-agnostic open-model profiles are named by the model families they require. Single-family choices are `open-weights-{glm,deepseek,kimi,luna}`; two-family choices are `open-weights-glm-deepseek`, `open-weights-kimi-deepseek`, and `open-weights-kimi-glm`; `open-weights-kimi-glm-deepseek` uses all three open-weight families; `open-weights-all` adds GPT-5.6 Luna. Choose the smallest combination covered by the models available through your configured providers. Every selector is a bare final-segment alias with `required_providers: []`, so each family may come from any authenticated bundled or custom provider under Provider Priority. GPT-5.6 Luna is proprietary despite its inclusion in this group.\n- `macos-omlx-{fast,balanced,quality}` — oMLX presets for local Apple Silicon inference, tuned by measured same-machine throughput. `fast` pins the 4-bit and `balanced` the 8-bit quant of Qwen 3.6 35B A3B; `quality` keeps the 8-bit MoE for the default, executor, planner, and architect roles and routes the critic to the official dense `Qwen3.8-27B-8bit` checkpoint; `macos-omlx-abliterated-{fast,balanced}` both pin `Qwen3.8-27B-Uncensored-MLX-4bit`, the faster of the measured uncensored quants. Every preset uses one role-effort ladder — critic and architect `high`, planner `medium`, executor and default `low` — and `fast`, `balanced`, and the abliterated presets serve a single model, so sub-agents never trigger an oMLX model unload/reload; `quality` swaps models only for the critic role. Selectors use the ids the local server returns from `/v1/models`; activate after starting oMLX on its default loopback endpoint (see [Implicit oMLX discovery](#implicit-omlx-discovery)) — the provider is keyless, so no `/login` is needed.\n- `claude-opus` — Anthropic OAuth preset that prefers `claude-opus-5` and deterministically falls back to `claude-opus-4-6` when Opus 5 is absent from the active catalog\n- `claude-fable` — Anthropic OAuth preset on `claude-fable-5-1` (default/architect `xhigh`, critic `high`, planner `low`) with `claude-sonnet-5` on the executor role. Fable 5.1 is served only by Anthropic's first-party API; it requires a Claude Code compatibility version of at least `2.1.251` and answers older fingerprints with an HTTP 400 `claude_code_version_too_old`.\n- Single-provider tiers: `glm-{eco,medium,pro}`, `kimi-coding-plan-{eco,medium,pro}`, `mimo-{eco,medium,pro}`, `grok-{eco,medium,pro}`, `grok-45-{eco,medium,pro}`, `grok-46-{eco,medium,pro}`, `cursor-{eco,medium,pro}`, `minimax-{eco,medium,pro}`. The versioned Grok profiles use the existing xAI OAuth/subscription provider: `/login xai` authenticates both versions. Direct `/model` assignment requires an explicit effort for `xai/grok-4.5` (`low`, `medium`, or `high`) and `xai/grok-4.6` (`low`, `medium`, `high`, or `xhigh`) instead of leaving the role at `(inherit)`.\n- Alibaba Token Plan: `alibaba-token-plan-balanced` preserves the established Qwen/DeepSeek V4 Pro/GLM mix; `alibaba-token-plan-pro` raises execution and independent criticism with DeepSeek V4 Flash 0731 max and GLM xhigh; `alibaba-token-plan-qwenmaxxing` stays Qwen-only; `alibaba-token-plan-qwen-deepseek` keeps Qwen 3.8 Max (`qwen3.8-max`) on the expensive default (high)/architect (xhigh)/critic (xhigh) roles and spends DeepSeek V4 Flash 0731 on the cheap planner (max) and executor (high) roles; `alibaba-token-plan-glm-deepseek` does the same with GLM 5.2 (`glm-5.2`) as the expensive model\n- Combos: `opus-codex`, `codex-opencodego`, `fable-opus-codex`, `astra-fable`, and `astra-fable-opus`\n\nGLM-5.3 always enables thinking and accepts only `low`, `high`, and `max`; `max` is the provider default and is recommended for coding. The GLM tiers preserve the former role ordering by collapsing `minimal`/`low` to `low`, `medium`/`high` to `high`, and `xhigh` to `max`. GLM-5.3-Flash keeps the same text contract (per z.ai docs, its text parameters are consistent with GLM-5.3 with a 1M-token context window) and now backs the high-volume lanes of the GLM tiers: `glm-eco` runs default, executor, and planner on `glm-5.3-flash:low` while critic and architect stay on `glm-5.3:high`; `glm-medium` and `glm-pro` keep every role on `glm-5.3` except the executor, which uses `glm-5.3-flash:low` (Medium) and `glm-5.3-flash:high` (Pro).\n\nGemini 3.7 Flash is bundled wherever Gemini 3.6 Flash already was (`google/gemini-3.7-flash`, `google-gemini-cli/gemini-3.7-flash`, Copilot, Antigravity effort variants, OpenCode Zen, OpenRouter, Vercel AI Gateway, Cursor, and the other 3.6 Flash gateways). First-class Google transports use `google-level` thinking and accept only `low`, `medium`, and `high`; `minimal` is rejected because the official Gemini API returns an error. Provider defaults stay on the existing Pro-class models.\n\nThe `eco`, `medium`, and `pro` Codex profile mappings are current product judgments: Eco assigns Terra low/Luna low/Luna high/Terra xhigh/Terra high to default/executor/planner/critic/architect; Medium assigns Sol low/Terra low/Terra high/Sol xhigh/Sol high; Pro assigns Sol medium/Terra medium/Sol high/Sol max/Sol xhigh; and LunaMaxxing assigns Luna medium/Luna xhigh/Luna max/Luna max/Luna max. `opus-codex` retains the Medium Codex executor, critic, and architect roles but uses `anthropic/claude-sonnet-5` for planner; `codex-opencodego` retains the Medium Codex default and architect roles; and `fable-opus-codex` uses the Pro Codex executor and architect roles with `anthropic/claude-opus-5:medium` for planner. The descriptive repeated local exact-edit evidence informs only selected executor-style TypeScript tasks; it does not evaluate or prove default, planner, architect, or critic performance. See [GPT-5.6 Codex preset benchmark](./gpt-5.6-codex-preset-benchmark.md). The Alibaba Pro role evidence and its limits are recorded separately in [Alibaba Token Plan Pro profile benchmark](./alibaba-token-plan-pro-profile-benchmark.md). Cursor Eco uses Composer 2.5 for every role; Medium keeps standard Composer for default/planning and spends the Fast premium on execution, criticism, and architecture; Pro uses Composer 2.5 Fast throughout. Composer does not expose a strength value through the current Cursor RPC, so these profiles use exact model IDs without inert generic effort suffixes. See [Cursor Composer profile tiers](./cursor-composer-profile-tiers.md). Effort suffixes are clamped to each model's supported thinking range at preview and activation time. Single-provider tiers pin each provider's current flagship (`zai/glm-5.2`, `kimi-code/kimi-k2.7-code`, `xiaomi/mimo-v2.5-pro`, `xai/grok-4.3`, `cursor/composer-2.5`, `minimax-code/MiniMax-M3`). User-defined profiles override built-ins by exact profile name.\n\nGPT-6 Astra supports `low`, `medium`, `high`, `xhigh`, and `max`; the ASTRA profiles use only those catalog-backed levels. In default/executor/architect/planner/critic order, `astra-lite` assigns Astra medium/Luna xhigh/Terra xhigh/Astra xhigh/Sol high; `astra-default` assigns Astra medium/Luna max/Terra xhigh/Astra xhigh/Sol xhigh; and `astra-heavy` assigns Astra medium/Sol max/Astra max/Sol max/Astra max. `astra-fable` keeps the ASTRA-Default default, executor, and planner bindings while routing architect and critic to `anthropic/claude-fable-5-1:xhigh`; `astra-fable-opus` additionally routes planner to `anthropic/claude-opus-5:medium`. Both combinations require `openai-codex` and `anthropic` availability, either directly or through the configured preset proxy. The existing Codex presets and the `openai-codex` recommendation remain unchanged.\n\nUse `gjc --mpreset <name>` to activate a profile for the current session only. Activation hard-blocks when any provider listed in `required_providers` lacks credentials. Add `--default` to persist the selected profile as `modelProfile.default` in `config.yml`, so it applies at startup:\n\n```sh\ngjc --mpreset codex-medium\ngjc --mpreset astra-default\ngjc --mpreset opencodego --default\n```\n\n### Routing built-in presets through a proxy (`modelProfile.proxyProvider`)\n\nFor a local OpenCodex pool, set `modelProfile.proxyProvider` to `opencodex` and\n`modelProfile.proxyMode` to `always`. With a persisted `modelProfile.default`, plain\n`gjc` applies that preset through the pool on startup, even when direct Anthropic\nand Codex credentials exist. GJC discovers the local proxy's public `/v1/models`\ncatalog automatically; no management token or static `models.yml` roster is needed.\nModel IDs retain their GJC namespace, while preset matching uses the upstream wire\nID. A missing proxy model still fails activation instead of silently bypassing the pool.\n\nBuilt-in preset selectors pin a direct provider endpoint (`xai/grok-4.3`, `xiaomi/mimo-v2.5-pro`, …). To serve those models through your own OpenAI-compatible gateway (LiteLLM, OpenRouter, or a custom proxy) instead of each vendor's endpoint, configure the proxy provider id and routing mode in `config.yml`:\n\n```yaml\nmodelProfile:\n  proxyProvider: litellm\n  proxyMode: always # use fallback to keep directly authenticated providers direct\n```\n\nThe proxy provider is a normal `providers:` entry. Add it with `gjc setup provider --preset litellm --base-url <url>` or the generic `gjc setup provider --preset openai-compatible-proxy --base-url <url>` (both presets require `--base-url` and use live model discovery). The configured proxy must be authenticated and expose every routed model. Activation rewrites each selected built-in preset selector from `<direct-provider>/<model>` to `<proxy>/<direct-provider>/<model>` (for example `xai/grok-4.3` → `litellm/xai/grok-4.3`), matching the proxy's catalog entry for the model. The rules:\n\n- Routing applies to **built-in presets only**. User-defined `profiles:` entries always keep their exact selectors — set them explicitly if you want them proxied.\n- `proxyMode: fallback` (the default) routes only selectors whose direct provider is unauthenticated. `proxyMode: always` routes every proxy-routable built-in selector through the configured proxy, including selectors with direct credentials.\n- The proxy id must name a configured provider. `proxyMode: always` requires `proxyProvider` and a usable proxy credential; activation fails closed when a required proxy is unset or unauthenticated. `auth: none` proxies count as authenticated.\n- Only providers the bundled preset catalog treats as routable are rewritten; providers outside that set (for example a custom `acme-private`) keep the direct credential error.\n- A routed selector must have exactly one matching proxy catalog model. Exact `<direct-provider>/<model>` proxy ids win over suffix matches; missing or ambiguous matches fail activation before any role can run.\n\nThe `/model` command opens to a preset landing view: presets are grouped by provider with live auth marks (✓/✗), highlighting a group expands its tiers, and selecting a tier shows the full role→model preview before applying for the session or as default. Typing jumps straight to model search, and `Browse all models` opens the classic tabbed model selector. In `/login`, `Add custom provider` is the first option for configuring credentials needed by custom or profile-required providers; after a successful provider login, the matching preset is recommended automatically. Custom providers participate in provider-agnostic alias resolution but require manual preset selection.\n\nExternal SDK/ACP clients (e.g. the Paseo TUI) can select profiles like ordinary models: the SDK `models.list/current` (Q10) catalog exposes every usable profile as a synthetic `gajae-code/<profile>` entry (e.g. `gajae-code/codex-eco`), and selecting one through `model.set` (or the ACP Model picker) activates the profile for the live session only. Persisting a profile remains an explicit TUI choice, mirroring `gjc --mpreset <name> --default`. See [SDK model profiles](./sdk.md#model-profiles-as-synthetic-models-gajae-codeprofile).\n\nMiniMax's OpenAI-compatible endpoint rejects multiple system messages and emits thinking in `reasoning_content`, so pin the public-safe compatibility fields when hand-authoring a custom provider:\n\n```yaml\nproviders:\n  minimax-custom:\n    baseUrl: https://api.minimax.io/v1\n    apiKeyEnv: MINIMAX_API_KEY\n    api: openai-completions\n    compat:\n      supportsStore: false\n      supportsDeveloperRole: false\n      supportsReasoningEffort: false\n      reasoningContentField: reasoning_content\n    models:\n      - id: MiniMax-M2.5\n```\n\nGLM via z.ai is available as the first-class `zai` provider. For a private GLM-compatible proxy, keep secrets in an env var and disable OpenAI-only request fields as needed:\n\n```yaml\nproviders:\n  glm-proxy:\n    baseUrl: https://api.z.ai/api/paas/v4\n    apiKeyEnv: ZAI_API_KEY\n    api: openai-completions\n    compat:\n      supportsDeveloperRole: false\n      supportsReasoningEffort: false\n    models:\n      - id: glm-4.6\n```\n\n### JetBrains AI (Junie)\n\n`jetbrains-junie` is a first-class provider serving JetBrains-hosted models through the documented\nIngrazzio gateway (`https://ingrazzio-cloud-prod.labs.jb.gg`).\n\nAuthenticate with an access token generated at [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli):\n\n```sh\nexport JUNIE_API_KEY=...\n```\n\nThe token is sent as `Authorization: Bearer` — JetBrains AI rejects requests that also carry `x-api-key`, so\nthis provider never lets the Anthropic SDK attach one. Usage is billed against your JetBrains AI\nsubscription, so bundled per-token costs are zero. There is no OAuth login flow; the environment variable is\nthe only supported credential source.\n\nThe gateway multiplexes transports by model family:\n\n| Family | Models | Transport | Prompt limit |\n| --- | --- | --- | --- |\n| Claude | `claude-sonnet-4-6` (default), `claude-sonnet-5`, `claude-opus-4-6`, `claude-opus-4-7`, `claude-opus-4-8`, `claude-opus-5`, `claude-fable-5` | `anthropic-messages` | 1M |\n| GPT | `gpt-5-2025-08-07`, `gpt-5.2-2025-12-11`, `gpt-5.4`, `gpt-5.5`, `gpt-5.6-luna`, `gpt-5.6-sol`, `gpt-5.6-terra` | `openai-completions` | 922K |\n| GPT (Responses-only) | `gpt-5.3-codex` | `openai-responses` | 272K |\n\nAll models cap output at 128K. Junie also exposes Gemini and Grok, but those ride a proprietary Grazie\ntranslation protocol that GJC does not implement, so they are deliberately not bundled. The bare\n`opus`/`sonnet`/`gpt`/`grok` aliases are Junie CLI shorthands the gateway itself rejects.\n\n### Allowed auth/discovery values\n\n- `auth`: `apiKey` (default), `none`, or `oauth`; for `models.yml` custom models, `oauth` is accepted by schema but does not waive the `apiKey` requirement\n- `models.yml` is strict: unknown provider/model keys fail validation before provider dispatch, so stale keys such as `requestTransform` or `wireModelId` only work where this document lists them.\n- `discovery.type`: `ollama`, `llama.cpp`, `lm-studio`, `omlx`, `vllm`, `sglang`, `openai-models-list`, or `models-dev`; `models-dev` may select a different catalog entry with `modelsDevProvider`\n- `cacheRetention`: `none`, `short`, or `long`; request-time options win over model/modelOverride values, then provider values, then `GJC_CACHE_RETENTION`, then the runtime default. The runtime default is `short` for most providers, but the Anthropic provider defaults to `long` because the ~5m cache is fragile for long-running subagent workflows. Canonical Anthropic models use top-level automatic caching and emit `ttl: \"1h\"` when long retention is supported. Claude-family models on non-canonical Anthropic-compatible endpoints default to explicit block markers because compatible proxies commonly inject, rewrite, or reject top-level cache controls; they omit `ttl` unless `compat.supportsLongCacheRetention: true` opts the endpoint into 1-hour retention. For OpenAI Responses, this controls `prompt_cache_retention` only; it does not disable `prompt_cache_key` when a stable session id exists.\n\n## OpenAI-compatible proxy configuration\n\nOpenAI-compatible proxy providers should use schema-supported provider keys first:\nThe first-class way to add a proxy provider is `gjc setup provider --preset litellm --base-url <url>` (LiteLLM) or `gjc setup provider --preset openai-compatible-proxy --base-url <url>` (any OpenAI-compatible gateway); both presets require `--base-url` and configure live model discovery. For a fully custom id, `gjc setup provider --compat openai --provider <id> --base-url <url> --api-key-env <ENV> --discover [--model <id>]` (or `/provider add` with `--discover`) persists the same live discovery without requiring manual model ids. The Add-custom-provider wizard automatically probes after OpenAI-compatible URL and credentials are supplied, offers the discovered catalog, and retains retry and manual entry when discovery fails or returns no models. Anthropic-compatible setup keeps manual entry. Leaving discovery cancels its preview; cancellation before the atomic configuration commit prevents saving the provider, and credential-restoration failures are reported without secret material. Proxy providers can also be used to route built-in model-preset selectors — see [Routing built-in presets through a proxy](#routing-built-in-presets-through-a-proxy-modelprofileproxyprovider). The YAML below shows the equivalent hand-written provider config:\n\n```yaml\nproviders:\n  proxy-provider:\n    baseUrl: https://api.proxy.example/v1\n    apiKeyEnv: PROXY_API_KEY\n    api: openai-completions\n    auth: apiKey\n    headers:\n      User-Agent: curl/8.7.1\n    models:\n      - id: local-gpt\n        name: Local GPT\n        reasoning: true\n        thinking:\n          minLevel: low\n          maxLevel: high\n          mode: effort\n        compat:\n          supportsReasoningEffort: true\n        input: [text]\n        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }\n        contextWindow: 400000\n        maxTokens: 128000\n```\n\nUse provider-level `headers` for proxy-required headers. Keep the provider `api` set to `openai-completions` when the proxy exposes Chat Completions-compatible `/v1/chat/completions` semantics. `auth: apiKey` sends the resolved token as bearer auth; use `auth: none` only for trusted local/no-auth endpoints.\n\nFor an unknown custom endpoint, `reasoning: true` declares model capability but does not prove the proxy accepts a control parameter. A familiar provider id or model-family name is not transport evidence: configurable LiteLLM/vLLM/local endpoints still fail closed. Add `thinking` and `compat.supportsReasoningEffort: true` only when the endpoint documents OpenAI-style `reasoning_effort`; set `compat.thinkingFormat` as well when it uses a different documented request shape. Otherwise GJC keeps reasoning-level controls unavailable and omits the parameter.\n\n`auth` selects the transport scheme only; it never supplies a credential. A provider that declares `models:` must therefore also declare where its key comes from, and `models.yml` validation rejects the config before model discovery otherwise:\n\n| Intent | Required keys |\n| --- | --- |\n| Authenticated proxy (recommended) | `auth: apiKey` (default) + `apiKeyEnv: MY_TOKEN` |\n| Authenticated proxy, key inline | `auth: apiKey` (default) + `apiKey: sk-…` (less safe; stored in plaintext) |\n| Genuinely unauthenticated endpoint | `auth: none`, no key |\n\nOmitting both `apiKey` and `apiKeyEnv` while leaving `auth` at its `apiKey` default fails with `Provider <name>: custom models need a credential source, but none is configured.` — the fix is to add one of the rows above, not to change `api` or `baseUrl`.\n\n`input` is the model modality list GJC uses to decide whether image content is forwarded. When a custom model omits `input`, GJC defaults to `[text]` (unless a bundled model with the same id contributes a reference). Vision-capable upstream models therefore need an explicit `input: [text, image]`; otherwise `read`/tool images are stripped before the request and replaced with `[image omitted: model does not support vision]`, even if the remote model can see images.\n\n```yaml\nproviders:\n  ali:\n    baseUrl: https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1\n    apiKeyEnv: ALI_API_KEY\n    api: openai-completions\n    auth: apiKey\n    models:\n      # id-only → text-only; images will be omitted\n      - id: some-text-model\n      # vision-capable hosted model must declare image input\n      - id: qwen3.8-max-preview\n        name: Qwen3.8 Max Preview\n        reasoning: true\n        input: [text, image]\n```\n\n`requestTransform` and `wireModelId` remain supported for request-body shaping, but they are not needed for ordinary OpenAI-compatible proxies whose local model id is already the upstream wire id. Unknown config keys fail validation before a provider request is sent.\n\nWhen request shaping is needed:\n\n- `requestTransform.profile: openai-proxy` strips OpenAI SDK/Stainless telemetry and beta headers at final fetch time and sets a generic GJC user agent.\n- `stripHeaders` replaces the preset strip list when provided.\n- `setHeaders` is applied after stripping; use `null` to remove a header.\n- `extraBody` is shallow-merged into the JSON request body after provider compatibility fields; core transport keys such as `model`, `messages`/`input`, `stream`, `tools`, and `tool_choice` are protected and ignored.\n- Model-level `requestTransform` overrides provider-level fields and shallow-merges `setHeaders`/`extraBody`.\n- `wireModelId` changes only the upstream request body model id; local selection still uses `provider/id`.\n\n### Layofflabs-style proxy example\n\n```yaml\nproviders:\n  layofflabs:\n    baseUrl: https://api.layofflabs.com/v1\n    apiKeyEnv: OPENAI_API_KEY\n    api: openai-completions\n    auth: apiKey\n    headers:\n      User-Agent: curl/8.7.1\n    models:\n      - id: gpt-5.5\n        name: GPT 5.5 via Layofflabs\n        reasoning: true\n        thinking:\n          minLevel: low\n          maxLevel: xhigh\n          mode: effort\n          defaultLevel: high\n          levels: [low, medium, high, xhigh]\n        compat:\n          supportsReasoningEffort: true\n        input: [text]\n        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }\n        contextWindow: 400000\n        maxTokens: 128000\n\nmodelBindings:\n  modelRoles:\n    default: layofflabs/gpt-5.5:high\n  agentModelOverrides:\n    executor: layofflabs/gpt-5.5:high\n```\n\n## Validation rules (current)\n\n### Full custom provider (`models` is non-empty)\n\nRequired:\n\n- `baseUrl`\n- A credential source: `apiKeyEnv` or `apiKey`. `auth` selects the scheme, not the credential, so `auth: apiKey` (the default) still needs one of them. Exempt: `auth: none`, and `api: bedrock-converse-stream`, which resolves AWS credentials from its own chain.\n- `api` at provider level or each model\n\n### Override-only provider (`models` missing or empty)\n\nMust define at least one of:\n\n- `baseUrl`\n- `headers`\n- `compat`\n- `requestTransform`\n- `disableStrictTools`\n- `modelOverrides`\n- `discovery`\n\n### Discovery\n\n- `discovery` requires provider-level `api`.\n\n### Model value checks\n\n- `id` required\n- `contextWindow` and `maxTokens` must be positive if provided\n- unknown provider, model, override, and request-transform keys fail schema validation; remove stale keys instead of relying on them being ignored.\n\n`maxTokens` on an explicit `models.yml` model (or `modelOverrides` entry) is the\nauthoritative default output budget for that configured model. A positive\nper-request `maxTokens` option still wins. Built-in catalog values and runtime\ndiscovery metadata retain the transport's conservative 32,000-token default\nunless the caller supplies a positive request override; their displayed\n`maxTokens`/`max-out` value is model metadata, not an unconditional request\npromise. A request value of `0` is treated as unspecified and does not bypass\nthe safe default. Provider hard limits and reasoning-budget rules remain\nenforced by the selected transport.\nValid budget values — configured or per-request — are positive safe integers\n(1 … 9007199254740991). Fractional values and anything above\n`Number.MAX_SAFE_INTEGER` fail schema validation in `models.yml`/overrides and\nare treated as unspecified when passed programmatically, so integer-only\nprovider fields (`max_tokens`, `max_completion_tokens`, `max_output_tokens`)\nnever receive an unsatisfiable budget. The low-level `stream()`/`complete()`\nboundary applies the same rule to provider options.\n\n## Merge and override order\n\nModelRegistry pipeline (on refresh):\n\n1. Load built-in providers/models from `@gajae-code/ai`.\n2. Load `models.yml` custom config.\n3. Apply provider overrides (`baseUrl`, `headers`, `requestTransform`, `disableStrictTools`, `cacheRetention`) to built-in models.\n4. Apply `modelOverrides` (per provider + model id).\n5. Merge custom `models`:\n   - same `provider + id` replaces existing\n   - otherwise append\n6. Load cached/runtime-discovered models (Ollama, llama.cpp, LM Studio, plus built-in provider managers), then re-apply model overrides.\n\n### Provider-model cache and static fingerprint\n\nCached per-provider model lists are persisted in the model-cache SQLite\ndatabase (schema v3) with a `static_fingerprint` column that hashes the\nstatic catalog slice merged into the row. When `resolveProviderModels`\nskips the network fetch and the fingerprint of the in-memory static\ncatalog matches the cached one, the cached rows are returned verbatim —\nthe static + dynamic merge is bypassed entirely. The fingerprint is\nmemoized per process via a WeakMap keyed by the static-models array\nreference, so repeated cold-start calls do not re-hash.\n\n## Canonical model equivalence and coalescing\n\nThe registry keeps every concrete provider model and then builds a canonical layer above them.\n\nCanonical ids are official upstream ids only, for example:\n\n- `anthropic-model-opus-4-6`\n- `anthropic-model-haiku-4-5`\n- `gpt-5.3-openai-code`\n\n### `models.yml` equivalence config\n\nExample:\n\n```yaml\nproviders:\n  zenmux:\n    baseUrl: https://api.zenmux.example/v1\n    apiKey: ZENMUX_API_KEY\n    api: openai-codex-responses\n    models:\n      - id: openai-code\n        name: Zenmux OpenAI code\n        reasoning: true\n        input: [text]\n        cost:\n          input: 0\n          output: 0\n          cacheRead: 0\n          cacheWrite: 0\n        contextWindow: 200000\n        maxTokens: 32768\n\nequivalence:\n  overrides:\n    zenmux/openai-code: gpt-5.3-openai-code\n    p-openai-code/openai-code: gpt-5.3-openai-code\n  exclude:\n    - demo/openai-code-preview\n```\n\nBuild order for canonical grouping:\n\n1. exact user override from `equivalence.overrides`\n2. bundled official-id matches from built-in model metadata\n3. conservative heuristic normalization for gateway/provider variants\n4. fallback to the concrete model's own id\n\nCurrent heuristics are intentionally narrow:\n\n- embedded upstream prefixes can be stripped when present, for example `anthropic/...` or `openai/...`\n- dotted and dashed version variants can normalize only when they map to an existing official id, for example `4.6 -> 4-6`\n- ambiguous families or versions are not merged without a bundled match or explicit override\n\n### Canonical and preset-equivalent resolution behavior\n\nWhen multiple concrete variants are eligible for automatic resolution, the global provider policy uses this order:\n\n1. explicit `config.yml` `modelProviderOrder` entries, in their saved order\n2. omitted providers whose effective credential came from OAuth\n3. omitted providers using a manual API key, unknown credential provenance, or keyless access\n4. vision capability, exact canonical identity, canonical source quality, lowest `cost.input + cost.cacheRead`, stable registry model order, then concrete selector order\n\nThe explicit provider list may be partial. A listed API-key provider beats every omitted OAuth provider. Resetting Provider Priority clears the explicit list and restores OAuth-first plus deterministic fallback. Saved providers that are not currently available remain visible and persisted, but runtime resolution skips them.\n\nModel-profile and preset assignments support a lookup-only alias when the assignment does not explicitly name a provider. For example, a bare preset assignment `gpt-5` can select any available concrete variant whose final model-id segment is `gpt-5`, ranked by the same global policy. An assignment such as `openai/gpt-5` is an explicit provider pin: if that exact model is unavailable, activation reports it unavailable instead of switching providers. Alias lookup never rewrites the selected model's concrete provider, full model id, or `wireModelId`; a known bare alias with no eligible variant is unavailable and does not fall through to a different fuzzy match. Direct model selection remains unchanged.\nRuntime custom providers participate in the same lookup automatically. A custom provider model such as `hosted/glm-5.2` contributes the alias `glm-5.2` when the provider is registered, authenticated, and available; Provider Priority can rank that custom provider ahead of bundled providers without changing the preset. Custom IDs whose final segment differs (for example `glm-5.2-special`) do not join the alias.\n\nA session that resolves a canonical or alias selector keeps its concrete variant across provider-priority edits and discovery refreshes. Updated priority applies to new or unpinned resolutions. The session re-ranks only after explicit reselection or when the sticky variant becomes unavailable. Session state and transcripts continue to record the concrete provider/model that executed the turn.\n\nProvider defaults vs per-model overrides:\n\n- Provider `headers` are baseline.\n- Model `headers` override provider header keys.\n- `modelOverrides` can override model metadata (`name`, `reasoning`, `input`, `cost`, `contextWindow`, `maxTokens`, `headers`, `compat`, `contextPromotionTarget`).\n- `compat` is deep-merged for nested routing blocks (`openRouterRouting`, `vercelGatewayRouting`, `extraBody`).\n\n## Runtime discovery integration\n\n### Implicit Ollama discovery\n\nIf `ollama` is not explicitly configured, registry adds an implicit discoverable provider:\n\n- provider: `ollama`\n- api: `openai-responses`\n- base URL: `OLLAMA_BASE_URL` or `http://127.0.0.1:11434`\n- auth mode: keyless (`auth: none` behavior)\n\nRuntime discovery calls Ollama endpoints and normalizes discovered OpenAI-compatible models to `openai-responses`.\n\n### Implicit llama.cpp discovery\n\nIf `llama.cpp` is not explicitly configured, registry adds an implicit discoverable provider:\n\n- provider: `llama.cpp`\n- api: `openai-responses`\n- base URL: `LLAMA_CPP_BASE_URL` or `http://127.0.0.1:8080`\n- auth mode: keyless (`auth: none` behavior)\n\nRuntime discovery calls llama.cpp model endpoints and synthesizes model entries with local defaults.\n\n### Implicit LM Studio discovery\n\nIf `lm-studio` is not explicitly configured, registry adds an implicit discoverable provider:\n\n- provider: `lm-studio`\n- api: `openai-completions`\n- base URL: `LM_STUDIO_BASE_URL` or `http://127.0.0.1:1234/v1`\n- auth mode: keyless (`auth: none` behavior)\n\nRuntime discovery fetches models (`GET /models`) and synthesizes model entries with local defaults.\n\n### Implicit oMLX discovery\n\nIf `omlx` is not explicitly configured, registry adds an implicit discoverable provider:\n\n- provider: `omlx`\n- api: `openai-completions`\n- base URL: `OMLX_BASE_URL` or `http://127.0.0.1:8080/v1`\n- auth mode: keyless (`auth: none` behavior)\n\nRuntime discovery fetches models (`GET /v1/models`) and synthesizes model entries with local defaults and `max_model_len` support.\n\n### Implicit vLLM discovery\n\nIf `vllm` is not explicitly configured, its bundled provider descriptor discovers the local server implicitly:\n\n- provider: `vllm`\n- api: `openai-completions`\n- base URL: trusted `VLLM_BASE_URL` or `http://127.0.0.1:8000/v1` (a project `.env` cannot redirect authenticated traffic)\n- auth mode: keyless (`auth: none` behavior), `VLLM_API_KEY` attaches when present\n\nRuntime discovery fetches models (`GET /v1/models`) and synthesizes model entries with local defaults and `max_model_len` support. Credentialless implicit discovery is limited to loopback. For a remote vLLM server (for example, a LAN GPU box), set `VLLM_BASE_URL` and `VLLM_API_KEY` in the launching shell or a user-owned GJC environment file, or configure it explicitly under `providers` as shown below.\n\n### Implicit SGLang discovery\n\nIf `sglang` is not explicitly configured, its bundled provider descriptor discovers the local server implicitly:\n\n- provider: `sglang`\n- api: `openai-completions`\n- base URL: trusted `SGLANG_BASE_URL` or `http://127.0.0.1:30000/v1` (a project `.env` cannot redirect authenticated traffic)\n- auth mode: keyless (`auth: none` behavior), `SGLANG_API_KEY` attaches when present\n\nRuntime discovery fetches models (`GET /v1/models`) and synthesizes model entries with local defaults and `max_model_len` support. Credentialless implicit discovery is limited to loopback and needs no `/login`; `/login sglang` stores only an actual API key. For a remote SGLang server (for example, a LAN GPU box), set `SGLANG_BASE_URL` and `SGLANG_API_KEY` in the launching shell or a user-owned GJC environment file, or configure it explicitly under `providers` as shown below. Standard proxy environment variables remain explicit transport configuration, so include local SGLang hosts in `NO_PROXY` when local traffic must connect directly.\n\n### Explicit provider discovery\n\nYou can configure discovery yourself:\n\n```yaml\nproviders:\n  ollama:\n    baseUrl: http://127.0.0.1:11434\n    api: openai-responses\n    auth: none\n    discovery:\n      type: ollama\n\n  llama.cpp:\n    baseUrl: http://127.0.0.1:8080\n    api: openai-responses\n    auth: none\n    discovery:\n      type: llama.cpp\n```\n\n### Extension provider registration\n\nExtensions can register providers at runtime (`pi.registerProvider(...)`), including:\n\n- model replacement/append for a provider\n- custom stream handler registration for new API IDs\n- custom OAuth provider registration\n\n### Agent-level providers (ACP)\n\nSome upstreams publish a complete agent instead of a model endpoint. Those are\nintegrated as **agent-level providers**: the provider id is selectable like any\nother, but the upstream agent owns model choice, tool execution, conversation\nhistory, and usage accounting.\n\n`devin` (Devin CLI) is the first one. GJC spawns `devin acp` and speaks the\nAgent Client Protocol over stdio; `devin` models appear through the ordinary\nprovider/model selection path once the CLI is installed and authenticated, and\nthe provider is credentialless (`getApiKey*` returns `kNoAuth`) because\nauthentication belongs to the CLI (`devin auth login`).\n\nSee [Devin CLI provider (ACP)](./devin-provider.md) for the full boundary: which\nGJC surfaces apply to a Devin turn, the tool-call permission policy\n(`GJC_DEVIN_PERMISSION_MODE`), and billing.\n\n## Auth and API key resolution order\n\nWhen requesting a key for a provider, effective order is:\n\n1. Runtime override (CLI `--api-key`)\n2. `models.yml` `providers.<name>.apiKey` literal pin\n3. Stored API key credential in `agent.db` (written by `auth login`)\n4. `models.yml` `providers.<name>.apiKeyEnv` indirection — a pointer to a key,\n   not a pinned value, so a stored login credential outranks it; it still\n   outranks stored OAuth credentials\n5. Stored OAuth credential in `agent.db` (with refresh)\n6. Environment variable mapping (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.)\n7. ModelRegistry fallback resolver (provider `apiKey` from `models.yml`, env-name-or-literal semantics)\n\n`models.yml` `apiKey` behavior:\n\n- Value is first treated as an environment variable name.\n- If no env var exists, the literal string is used as the token.\n\nIf `authHeader: true` and provider `apiKey` is set, models get:\n\n- `Authorization: Bearer <resolved-key>` header injected.\n\nKeyless providers:\n\n- Providers marked `auth: none` are treated as available without credentials.\n- `getApiKey*` returns `kNoAuth` for them.\n\n### Broker mode\n\nWhen `GJC_AUTH_BROKER_URL` (or `auth.broker.url`) is set, the local SQLite credential store is replaced by `RemoteAuthCredentialStore`. Layers 2 and 3 above (stored API key / OAuth in `agent.db`) are served from a broker-supplied snapshot whose `refresh` tokens are redacted; expiry triggers `POST /v1/credential/:id/refresh` on the broker rather than a local refresh.\n\n`AuthStorage.setConfigApiKey` lets a `models.yml` `apiKey` win over a broker-resolved OAuth token without overriding a runtime `--api-key`. See [`auth-broker-gateway.md`](./auth-broker-gateway.md) for the full broker / gateway design and env surface (`GJC_AUTH_BROKER_URL`, `GJC_AUTH_BROKER_TOKEN`, `auth.broker.url`, `auth.broker.token`).\n\n## Model availability vs all models\n\n- `getAll()` returns the loaded model registry (built-in + merged custom + discovered).\n- `getAvailable()` filters to models that are keyless or have resolvable auth.\n\nSo a model can exist in registry but not be selectable until auth is available.\n\n## Runtime model resolution\n\n### CLI and pattern parsing\n\n`model-resolver.ts` supports:\n\n- exact `provider/modelId`\n- exact canonical model id\n- exact model id (provider inferred)\n- fuzzy/substring matching\n- glob scope patterns in `--models` (e.g. `openai/*`, `*sonnet*`)\n- optional `:thinkingLevel` suffix (`off|minimal|low|medium|high|xhigh`)\n\n`--provider` is legacy; `--model` is preferred.\n\nResolution precedence for exact selectors:\n\n1. exact `provider/modelId` bypasses coalescing\n2. exact canonical id resolves through the canonical index\n3. exact bare concrete id still works\n4. fuzzy and glob matching run after the exact paths\n\nThinking suffixes are split once from the final `:` only after the complete selector does not resolve. This preserves concrete OpenRouter route IDs such as `openrouter/z-ai/glm-4.7:nitro`; `:high` can follow that route suffix. Multiple suffixes are not recursively consumed. A complete `provider/modelId` selector is exact-only: it never falls back to fuzzy, substring, glob, or another provider when that concrete selector is absent. Exact-case provider/model entries resolve deterministically for custom replacement semantics; a case-insensitive selector that remains ambiguous does not guess.\n\nPreset/profile activation may use an unqualified assignment as a final-segment lookup alias after exact resolution fails. Provider-qualified assignments remain exact pins, and this opt-in does not apply to CLI or direct concrete model selection.\n\n### Initial model selection priority\n\n`findInitialModel(...)` uses this order:\n\n1. explicit CLI provider+model\n2. first scoped model (if not resuming)\n3. saved default provider/model\n4. known provider defaults (e.g. OpenAI/Anthropic/etc.) among available models\n5. first available model\n\n### Role aliases and settings\n\nSupported model roles:\n\n- `default` plus the agent assignment targets `executor`, `architect`, `planner`, `critic`\n\nRole aliases like `pi/default` expand through `settings.modelRoles`. Each role value can also append a thinking selector such as `:minimal`, `:low`, `:medium`, or `:high`.\n\nIf a role points at another role, the target model still inherits normally and any explicit suffix on the referring role wins for that role-specific use.\n\nRelated settings:\n\n- `modelRoles` (record)\n- `enabledModels` (scoped pattern list)\n- `modelProviderOrder` (global automatic provider precedence; editable under Settings → Providers with add/remove, move up/down, unavailable-entry retention, and Reset)\n- `providers.kimiApiFormat` (`openai` or `anthropic` request format)\n- `providers.openaiWebsockets` (`auto|off|on` websocket preference for OpenAI code provider transport)\n\n`modelRoles` may store either:\n\n- `provider/modelId` to pin a concrete provider variant\n- a canonical id such as `gpt-5.3-openai-code` to allow provider coalescing\n\nFor `enabledModels` and CLI `--models`:\n\n- exact canonical ids expand to all concrete variants in that canonical group\n- explicit `provider/modelId` entries stay exact\n- globs and fuzzy matches still operate on concrete models\n\nGlobal `enabledModels` and `disabledProviders` entries may also be scoped to a path prefix:\n\n```yaml\nenabledModels:\n  - anthropic-model-sonnet-4-5\n  - path: ~/work\n    models:\n      - anthropic/anthropic-model-opus-4-5\ndisabledProviders:\n  - ollama\n  - path: ~/private\n    providers:\n      - anthropic\n```\n\nString entries apply everywhere. Scoped entries apply when the current working directory is the configured path or one of its subdirectories. Use `path`, `paths`, `pathPrefix`, or `pathPrefixes`; use `models` for `enabledModels`, `providers` for `disabledProviders`, or `values` for either.\n\n## `/model` and `--list-models`\n\nBoth surfaces keep provider-prefixed models visible and selectable.\n\nThey now also expose canonical/coalesced models:\n\n- `/model` includes a canonical view alongside provider tabs\n- `--list-models` prints a canonical section plus the concrete provider rows\n\nSelecting a canonical entry stores the canonical selector. Selecting a provider row stores the explicit `provider/modelId`.\n\n## Context promotion (model-level fallback chains)\n\nContext promotion is an overflow recovery mechanism for small-context variants (for example `*-spark`) that automatically promotes to a larger-context sibling when the API rejects a request with a context length error. It is **off by default** (`contextPromotion.enabled` is `false`); opt in to enable it.\n\n### Trigger and order\n\nWhen a turn fails with a context overflow error (e.g. `context_length_exceeded`), `AgentSession` attempts promotion **before** falling back to compaction:\n\n1. If `contextPromotion.enabled` is true, resolve a promotion target (see below).\n2. If a target is found, switch to it and retry the request — no compaction needed.\n3. If no target is available, fall through to auto-compaction on the current model.\n\n### Target selection\n\nSelection is model-driven, not role-driven:\n\n1. `currentModel.contextPromotionTarget` (if configured)\n2. smallest larger-context model on the same provider + API\n\nCandidates are ignored unless credentials resolve (`ModelRegistry.getApiKey(...)`).\n\n### OpenAI code provider websocket handoff\n\nIf switching from/to `openai-codex-responses`, session provider state key `openai-codex-responses` is closed before model switch. This drops websocket transport state so the next turn starts clean on the promoted model.\n\n### Persistence behavior\n\nPromotion uses temporary switching (`setModelTemporary`):\n\n- recorded as a temporary `model_change` in session history\n- does not rewrite saved role mapping\n\n### Configuring explicit fallback chains\n\nConfigure fallback directly in model metadata via `contextPromotionTarget`.\n\n`contextPromotionTarget` accepts either:\n\n- `provider/model-id` (explicit)\n- `model-id` (resolved within current provider)\n\nExample (`models.yml`) for Spark -> non-Spark on the same provider:\n\n```yaml\nproviders:\n  openai-code:\n    modelOverrides:\n      gpt-5.3-openai-code-spark:\n        contextPromotionTarget: openai-code/gpt-5.3-openai-code\n```\n\nThe built-in model generator also assigns this automatically for `*-spark` models when a same-provider base model exists.\n\n## Compatibility and routing fields\n\nThe `compat` block on a provider or model overrides the URL-based auto-detection in `packages/ai/src/providers/openai-completions-compat.ts`. It is validated by `OpenAICompatSchema` in `packages/coding-agent/src/config/model-registry.ts` and consumed by every `openai-completions` transport (`packages/ai/src/providers/openai-completions.ts`). The canonical type is `OpenAICompat` in `packages/ai/src/types.ts`.\n\n`models.yml` accepts the following keys (all optional; unset falls back to URL detection):\n\nRequest shaping:\n\n- `supportsStore` — emit `store: false` on requests. Default: auto (off for non-standard endpoints).\n- `supportsDeveloperRole` — use the `developer` system role for reasoning models instead of `system`. Default: auto.\n- `sendSessionHeaders` — forward the agent session id as `session_id` and `x-session-id` request headers so OpenAI-compatible relays/proxies can do session-affinity routing and reuse a server-side prompt cache. Default: `false`. Caller-set `headers`/`requestTransform` values are never overwritten.\n- `supportsResponsesSessionAffinity` — for `openai-responses`, opt in to forwarding `session_id` and `x-client-request-id` affinity headers to a custom OpenAI-compatible relay. Canonical OpenAI routing remains automatic; known non-OpenAI provider IDs are rejected. Default: `false`.\n- `supportsUsageInStreaming` — send `stream_options: { include_usage: true }` to receive token usage on streaming responses. Default: `true`.\n- `maxTokensField` — `\"max_completion_tokens\"` or `\"max_tokens\"`. Default: auto.\n- `supportsToolChoice` — emit the `tool_choice` parameter when the caller forces a specific tool. Default: `true`. Set `false` for endpoints that 400 on `tool_choice` (e.g. DeepSeek when reasoning is on).\n- `disableReasoningOnForcedToolChoice` — drop `reasoning_effort` / OpenRouter `reasoning` whenever `tool_choice` forces a call. Default: auto (Kimi/Anthropic-fronted endpoints).\n- `extraBody` — extra top-level fields merged into every request body (gateway hints, controller selectors, etc.). A `tool_choice` here acts as an endpoint default rather than an override: it applies only on a turn that offers tools and resolved no directive of its own, so forced-tool directives are preserved and deliberate no-tools turns are left untouched.\n\nReasoning / thinking:\n\n- `supportsReasoningEffort` — accept OpenAI-style `reasoning_effort`. Default: auto for bundled/audited providers and recognized first-party endpoints; `false` for unknown custom endpoints. Set `true` only from provider documentation or probe evidence, and pair it with explicit `reasoning: true` plus `thinking` metadata.\n- `reasoningEffortMap` — partial map from internal effort levels (`minimal|low|medium|high|xhigh`) to provider-specific strings (e.g. DeepSeek maps `xhigh -> \"max\"`).\n- `thinkingFormat` — request shape for thinking: `\"openai\"` (`reasoning_effort`), `\"openrouter\"` (`reasoning: { effort }`), `\"zai\"` (`thinking: { type: \"enabled\" }`), `\"qwen\"` (top-level `enable_thinking`), or `\"qwen-chat-template\"` (`chat_template_kwargs.enable_thinking`). Default: `\"openai\"`.\n- `reasoningContentField` — assistant field carrying chain-of-thought: `\"reasoning_content\"`, `\"reasoning\"`, or `\"reasoning_text\"`. Default: auto.\n- `requiresReasoningContentForToolCalls` — assistant tool-call turns must round-trip the reasoning field (DeepSeek-R1, Kimi, OpenRouter when reasoning is on). Default: `false`.\n- `requiresAssistantContentForToolCalls` — assistant tool-call turns must include non-empty text content (Kimi). Default: `false`.\n\nTool / message normalization:\n\n- `requiresToolResultName` — tool-result messages need a `name` field (Mistral). Default: auto.\n- `requiresAssistantAfterToolResult` — a user message after a tool result needs an assistant turn in between. Default: auto.\n- `requiresThinkingAsText` — convert thinking blocks to text wrapped in `<thinking>` delimiters (Mistral). Default: auto.\n- `requiresMistralToolIds` — normalize tool-call ids to exactly 9 alphanumeric chars. Default: auto.\n- `supportsStrictMode` — accept the per-tool `strict` field on tool schemas. Default: conservative auto-detect per provider/baseUrl.\n- `toolStrictMode` — `\"all_strict\"` forces strict on every tool, `\"none\"` forces it off; unset keeps the existing per-tool mixed behavior.\n\nGateway routing (only applied when `baseUrl` matches the gateway):\n\n- `openRouterRouting.only` / `openRouterRouting.order` — provider routing on `openrouter.ai` (see <https://openrouter.ai/docs/provider-routing>).\n- `vercelGatewayRouting.only` / `vercelGatewayRouting.order` — provider routing on `ai-gateway.vercel.sh` (see <https://vercel.com/docs/ai-gateway/models-and-providers/provider-options>).\n\nProvider-level `compat` is the baseline; per-model `compat` is deep-merged on top, with `openRouterRouting`, `vercelGatewayRouting`, and `extraBody` merged as nested objects.\n\n### Anthropic compatibility (`anthropic-messages`)\n\nFor `anthropic-messages` models, `compat.promptCacheMode` and `compat.supportsLongCacheRetention` are configurable at provider, model, and `modelOverrides` levels. Provider-level `compat` is the baseline; model and override values merge on top.\n\nPrompt-cache modes:\n\n- `automatic` — emit one top-level `cache_control` marker and let the Anthropic-compatible endpoint advance the breakpoint as the conversation grows.\n- `explicit` — emit block-level breakpoints instead. Use this for endpoints that reject top-level `cache_control` but support Anthropic's explicit content-block markers.\n- `none` — emit no generated Anthropic cache controls. Per-request or configured `cacheRetention: none` also disables generated caching.\n\nWithout an explicit mode, canonical Anthropic endpoints default to `automatic`, Claude-family model ids on non-canonical compatible endpoints default to `explicit`, and unknown non-Claude compatible endpoints default to `none`. Non-canonical endpoints get the default ~5m lifetime unless they opt into `supportsLongCacheRetention: true`. Set `promptCacheMode: automatic` only when a gateway is known to pass through Anthropic's top-level cache control without adding conflicting block markers.\n\nIf a gateway attaches enough cache markers of its own that ours push the request past Anthropic's four-breakpoint limit, Anthropic rejects it with `A maximum of 4 blocks with cache_control may be provided.` Those extra markers are not visible in the request GJC builds, so the limit is handled at runtime rather than predicted. Because the rejection means \"too many\" rather than \"none allowed\", recovery reduces the generated breakpoints one step at a time: `explicit` mode normally emits two markers (a conversation-prefix anchor and a current-turn refresh point), so the first retry keeps only the prefix anchor, and generated caching is disabled entirely only if that is rejected too. The reduced setting persists for the rest of the provider session, so an endpoint with one free slot keeps caching its conversation prefix instead of losing caching altogether. Set `promptCacheMode: none` on a gateway that never has a free slot to skip the wasted attempts.\n\n```yaml\nproviders:\n  corp-anthropic:\n    baseUrl: https://proxy.example.com/anthropic\n    apiKeyEnv: CORP_ANTHROPIC_API_KEY\n    api: anthropic-messages\n    compat:\n      promptCacheMode: explicit\n      supportsLongCacheRetention: false\n    models:\n      - id: claude-sonnet-4-5\n        contextWindow: 200000\n        maxTokens: 8192\n```\n\nOther Anthropic-side compatibility knobs such as `disableAdaptiveThinking` and `supportsEagerToolInputStreaming` remain built-in catalog metadata rather than `models.yml` fields. `disableStrictTools` stays a provider-level setting (below).\n\n### Strict tool schemas (`disableStrictTools`)\n\nAnthropic's API supports a `strict` field on tool definitions that forces the model to always follow the provided schema exactly. This is enabled by default for all `anthropic-messages` providers because it guarantees schema conformance in agentic systems.\n\nThird-party providers that front the Anthropic API (AWS Bedrock, Azure, self-hosted proxies) do not always implement this field and will reject requests that include it. Set `disableStrictTools: true` at the provider level to opt out:\n\n```yaml\nproviders:\n  bedrock-anthropic:\n    baseUrl: https://bedrock-runtime.us-east-1.amazonaws.com/anthropic\n    apiKey: AWS_BEARER_TOKEN\n    api: anthropic-messages\n    disableStrictTools: true\n    models:\n      - id: anthropic-model-sonnet-4-20250514\n        name: Anthropic model Sonnet 4 (Bedrock)\n        input: [text, image]\n        contextWindow: 200000\n        maxTokens: 16384\n        cost:\n          input: 3.00\n          output: 15.00\n          cacheRead: 0.30\n          cacheWrite: 3.75\n```\n\n`disableStrictTools` is a provider-level flag that applies to all models in the provider.\n\nTool schemas going on the wire are normalized by the unified flow in\n`packages/ai/src/utils/schema/normalize.ts` (Google/CCA/MCP dispatchers\nplus the OpenAI strict-mode sanitize+enforce pipeline). See\n[`ai-schema-normalize.md`](./ai-schema-normalize.md) for the strict-mode\nedge cases (local `$ref` inlining, single-item `allOf` collapse,\n`anyOf`-wrapper description hoist, enum/const primitive-type inference)\nand the per-provider dispatcher mapping.\n## Practical examples\n\n### Local OpenAI-compatible endpoint (no auth)\n\n```yaml\nproviders:\n  local-openai:\n    baseUrl: http://127.0.0.1:8000/v1\n    auth: none\n    api: openai-completions\n    models:\n      - id: Qwen/Qwen2.5-Coder-32B-Instruct\n        name: Qwen 2.5 Coder 32B (local)\n```\n\n### Hosted proxy with env-based key\n\n```yaml\nproviders:\n  anthropic-proxy:\n    baseUrl: https://proxy.example.com/anthropic\n    apiKey: ANTHROPIC_PROXY_API_KEY\n    api: anthropic-messages\n    authHeader: true\n    disableStrictTools: true  # if the proxy doesn't support strict tool schemas\n    models:\n      - id: anthropic-model-sonnet-4-20250514\n        name: Anthropic model Sonnet 4 (Proxy)\n        reasoning: true\n        input: [text, image]\n```\n\n### Override built-in provider route + model metadata\n\n```yaml\nproviders:\n  openrouter:\n    baseUrl: https://my-proxy.example.com/v1\n    headers:\n      X-Team: platform\n    modelOverrides:\n      anthropic/anthropic-model-sonnet-4:\n        name: Sonnet 4 (Corp)\n        compat:\n          openRouterRouting:\n            only: [anthropic]\n```\n\n## Legacy consumer caveat\n\nMost model configuration now flows through `models.yml` via `ModelRegistry`. Explicit `.json` / `.jsonc` paths remain supported only when passed programmatically to `ModelRegistry`; the default user config is `~/.gjc/agent/models.yml`.\n\n## Failure mode\n\nIf `models.yml` fails schema or validation checks:\n\n- registry keeps operating with built-in models\n- error is exposed via `ModelRegistry.getError()` and surfaced in UI/notifications\n",
+	"models.md": "# Model and Provider Configuration (`models.yml`)\n\nThis document describes how the coding-agent currently loads models, applies overrides, resolves credentials, and chooses models at runtime.\n\n## What controls model behavior\n\nPrimary implementation files:\n\n- `src/config/model-registry.ts` — loads embedded + signed-registry + custom models, provider overrides, runtime discovery, auth integration\n- `src/config/model-resolver.ts` — parses model patterns and selects models for the default and agent roles\n- `src/config/settings-schema.ts` — model-related settings (`modelRoles`, provider transport preferences)\n- `src/session/auth-storage.ts` — API key + OAuth resolution order\n- `packages/ai/src/models.ts` and `packages/ai/src/types.ts` — built-in providers/models and `Model`/`compat` types\n\n## Config file location and legacy behavior\n\nDefault config path:\n\n- `~/.gjc/agent/models.yml`\n\nLegacy behavior still present:\n\n- If `models.yml` is missing and `models.json` exists at the same location, it is migrated to `models.yml`.\n- Explicit `.json` / `.jsonc` config paths are still supported when passed programmatically to `ModelRegistry`.\n\n## `models.yml` shape\n\n```yaml\nproviders:\n  <provider-id>:\n    # provider-level config\nequivalence:\n  overrides:\n    <provider-id>/<model-id>: <canonical-model-id>\n  exclude:\n    - <provider-id>/<model-id>\n```\n\n`provider-id` is the canonical provider key used across selection and auth lookup.\n\n`equivalence` is optional and configures canonical model grouping on top of concrete provider models:\n\n- `overrides` maps an exact concrete selector (`provider/modelId`) to an official upstream canonical id\n- `exclude` opts a concrete selector out of canonical grouping\n\n## Provider-level fields\n\n```yaml\nproviders:\n  my-provider:\n    baseUrl: https://api.example.com/v1\n    apiKey: MY_PROVIDER_API_KEY\n    api: openai-completions\n    headers:\n      X-Team: platform\n    authHeader: true\n    auth: apiKey\n    disableStrictTools: false  # set true for Anthropic-compatible endpoints that reject the strict field\n    cacheRetention: short  # none | short | long; model entries and modelOverrides can override this\n    discovery:\n      type: ollama\n    modelOverrides:\n      some-model-id:\n        name: Renamed model\n        cacheRetention: long\n    models:\n      - id: some-model-id\n        name: Some Model\n        api: openai-completions\n        reasoning: false\n        input: [text]\n        cost:\n          input: 0\n          output: 0\n          cacheRead: 0\n          cacheWrite: 0\n        contextWindow: 128000\n        maxTokens: 16384\n        headers:\n          X-Model: value\n        cacheRetention: none\n        thinking:\n          minLevel: low\n          maxLevel: xhigh\n          mode: effort\n          defaultLevel: high\n          levels: [low, medium, high, xhigh]\n        compat:\n          supportsStore: true\n          supportsDeveloperRole: true\n          supportsReasoningEffort: true\n          maxTokensField: max_completion_tokens\n          openRouterRouting:\n            only: [anthropic]\n          vercelGatewayRouting:\n            order: [anthropic, openai]\n          extraBody:\n            gateway: m1-01\n            controller: mlx\nmodelBindings:\n  modelRoles:\n    default: my-provider/some-model-id:high\n  agentModelOverrides:\n    executor: my-provider/some-model-id\n```\n\n### Allowed provider/model `api` values\n\n- `openai-completions`\n- `openai-responses`\n- `openai-codex-responses`\n- `azure-openai-responses`\n- `bedrock-converse-stream`\n- `anthropic-messages`\n- `google-generative-ai`\n- `google-vertex`\n- `google-gemini-cli`\n- `ollama-chat`\n- `cursor-agent`\n\n\n### First-class DeepInfra, Azure OpenAI, and Amazon Bedrock examples\n\nAzure OpenAI uses canonical OpenAI model IDs in GJC and resolves those IDs to Azure deployment names at request time. Set `AZURE_OPENAI_DEPLOYMENT_NAME_MAP` to avoid assuming model id equals deployment name:\n\n```yaml\nproviders:\n  azure-openai:\n    baseUrl: https://my-resource.openai.azure.com/openai/v1\n    apiKeyEnv: AZURE_OPENAI_API_KEY\n    api: azure-openai-responses\n    models:\n      - id: gpt-4.1\n      - id: o3\n```\n\n```sh\nexport AZURE_OPENAI_DEPLOYMENT_NAME_MAP='gpt-4.1=gpt-41-prod,o3=o3-reasoning-prod'\n```\n\nDeepInfra is available as the first-class `deepinfra` provider. It uses DeepInfra's OpenAI-compatible Chat Completions endpoint and reads `DEEPINFRA_API_KEY` when no explicit config key is provided. Set `serviceTier: priority` in GJC config or use the runtime service-tier controls to send DeepInfra's `service_tier: \"priority\"` request field for supported models:\n\n```yaml\nproviders:\n  deepinfra:\n    baseUrl: https://api.deepinfra.com/v1/openai\n    apiKeyEnv: DEEPINFRA_API_KEY\n    api: openai-completions\n    models:\n      - id: deepseek-ai/DeepSeek-V3.2\n```\n\n#### `/fast` provider support\n\n`/fast on` only shows `⚡` when GJC will put a fast/priority field on the selected provider's wire request:\n\n| Provider ID | Wire request | Notes |\n|---|---|---|\n| `openai` | `service_tier: \"priority\"` | OpenAI renamed Priority processing to [Fast mode](https://developers.openai.com/api/docs/guides/fast-mode); `priority` remains an accepted alias. For API-key requests, the response `service_tier` reports the tier actually used and may be `default` after a ramp-rate downgrade. |\n| `openai-codex` | `service_tier: \"priority\"` | ChatGPT-authenticated Codex handles Fast through server-side routing. A final response value of `service_tier: \"default\"` does not show that Fast was ignored or downgraded. |\n| `anthropic` | `speed: \"fast\"` plus `fast-mode-2026-02-01` beta | Direct Claude API only. Anthropic's [Fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode) is model- and account-gated; unsupported or unavailable requests can fall back after a provider rejection. Bedrock, Vertex, and Microsoft Foundry do not support it. |\n| `deepinfra` | `service_tier: \"priority\"` | Sent only for the first-class `deepinfra` provider ID and only with the `priority` tier. |\n| `opencodex` | `service_tier: \"priority\"` | First-class OpenCodex discovery opts in automatically; OpenCodex Fast Mode must remain `Auto` for client passthrough. When OpenCodex uses ChatGPT authentication, a final `service_tier: \"default\"` is not downgrade evidence. |\n\nCustom OpenAI-compatible providers remain fail-closed unless their provider or model configuration explicitly sets `compat.supportsServiceTier: true`. Use that opt-in only when the proxy preserves or intentionally realizes OpenAI's `service_tier` contract:\n\n```yaml\nproviders:\n  my-openai-proxy:\n    baseUrl: http://proxy.example/v1\n    api: openai-responses\n    compat:\n      supportsServiceTier: true\n```\n\nWithout that capability, `/fast status` shows `off` even when the session retains an unscoped `priority` intent. The `⚡` indicator means that GJC sends the provider's fast request field. API-key providers may report a downgrade in their response; ChatGPT-authenticated Codex and OpenCodex route Fast server-side and cannot be verified from the final `service_tier` value.\n\nAmazon Bedrock uses the native `bedrock-converse-stream` transport and AWS credential chain auth. Do not put AWS access keys in `models.yml`; configure `AWS_REGION` / `AWS_PROFILE` or standard static AWS credential environment variables instead:\n\n```yaml\nproviders:\n  amazon-bedrock:\n    baseUrl: https://bedrock-runtime.us-east-1.amazonaws.com\n    api: bedrock-converse-stream\n    models:\n      - id: us.anthropic.claude-opus-4-6-v1\n      - id: anthropic.claude-3-5-sonnet-20241022-v2:0\n```\n\n### Coding-plan provider presets\n\nFor supported coding-plan providers, prefer presets so the API type, base URL, environment variable, model catalog, discovery behavior, and compatibility flags are written together:\n\n```sh\ngjc setup provider --preset minimax\ngjc setup provider --preset minimax-cn\ngjc setup provider --preset glm\ngjc setup provider --preset alibaba-token-plan\ngjc setup provider --preset cline-pass\ngjc setup provider --preset commandcode-goat\ngjc setup provider --preset ionet\n```\n\nThe same presets are available inside the TUI:\n\n```text\n/provider add --preset minimax\n/provider add --preset glm\n/provider add zai\n/provider add --preset alibaba-token-plan\n/provider add --preset cline-pass\n/provider add --preset commandcode-goat\n/provider add --preset ionet\n```\n\nPresets only write `models.yml` entries that reference documented environment variable names (`MINIMAX_CODE_API_KEY`, `MINIMAX_CODE_CN_API_KEY`, `ZAI_API_KEY`, `ALIBABA_TOKEN_PLAN_API_KEY`, `CLINE_API_KEY`, `CMD_API_KEY`, or `IONET_API_KEY`); they do not store or validate real credentials. The GLM preset aliases (`glm`, `zai`, `z-ai`) write an OpenAI-compatible custom provider named `glm-proxy` and do not replace the first-class `zai` provider. The Alibaba Token Plan preset (aliases: `alibaba`, `token-plan`) writes an OpenAI-compatible custom provider named `alibaba-token-plan` with per-model API routing. The ClinePass preset (aliases: `clinepass`, `cline`) does not hardcode models: Cline's inference API has no working `/models` route, so GJC follows Cline's own catalog-generation source and fetches the live `cline-pass` provider catalog from `https://models.dev/api.json`. The Command Code GOAT preset (aliases: `commandcode`, `command-code`, `goat`) fetches its live `/provider/v1/models` catalog, keeps every current or future model—including Claude-named IDs—on the provider's documented OpenAI-compatible `/chat/completions` transport, and requires a fixed harmless inference entitlement probe before login persistence. The IO Intelligence preset (aliases: `io-net`, `io-intelligence`) writes an OpenAI-compatible custom provider named `ionet` for [IO Intelligence](https://io.net) by io.net; model ids are `org/name` pairs discovered live from the endpoint's `/models` route, so no models are hardcoded. Create the corresponding API key in the provider dashboard before inference.\n\n## Signed remote preset registry\n\nGJC ships its embedded model metadata and profiles as an immutable bootstrap fallback, then overlays a separately published signed registry before applying local configuration:\n\n1. embedded model presets and profiles\n2. the last accepted `Yeachan-Heo/gajae-code-presets` registry snapshot\n3. user `~/.gjc/agent/models.yml` entries and overrides\n\nLocal user configuration always wins. Registry refresh never writes `models.yml`, and a failed, partial, oversized, incompatible, downgraded, equivocated, digest-mismatched, or untrusted update never replaces the active snapshot. Startup reads only the verified local cache and does not wait for network I/O; a delayed best-effort refresh runs at a bounded cadence. Offline cold starts use embedded data, while offline warm starts use the last-known-good accepted snapshot.\n\nThe registry manifest is canonical JSON signed with a compiled Ed25519 trust root. Signatures are 64-byte Ed25519 values encoded as canonical RFC 4648 Base64; unused padding bits must be zero, so two encodings of the same signature cannot produce distinct anti-equivocation digests. The signed payload binds the monotonic revision, consumer-contract compatibility, immutable revision paths, exact byte counts, SHA-256 digests, source commit provenance, snapshot, profile data, and credential-free model metadata. GJC sends no cookies, authorization headers, API keys, or provider credentials when fetching it. Registry schemas do not permit endpoints, request headers, credentials, environment references, commands, scripts, or arbitrary executable content. Selectors, preset identifiers, display text, and context-promotion targets reject Unicode format controls. Registry provider IDs are slash-free (`[a-z0-9][a-z0-9._-]*`), matching profile `requiredProviders` and the first-slash selector boundary used at runtime.\n\nAdministrative commands:\n\n```sh\ngjc models presets status [--json]\ngjc models presets refresh [--json]\ngjc models presets rollback <accepted-revision> [--json]\ngjc models presets pin <accepted-revision> [--json]\ngjc models presets unpin [--json]\ngjc models presets disable [--json]\ngjc models presets enable [--json]\n```\n\n`status` reports deterministic, credential-free provenance: active and highest-seen revisions, manifest/snapshot/profile/preset digests, signature key id, source GJC commit, accepted/published/check timestamps, retained removed entries, cache health, history, and pin/disable state. Rollback and pin can select only previously verified retained revisions; neither lowers the highest-seen anti-rollback floor, and selected generations are protected from bounded-history eviction. A rollback remains selected across background refreshes until another rollback/pin is chosen or `unpin` returns selection to the highest accepted revision. When a registry revision removes a profile, GJC retains that profile plus only the removed model metadata and dynamic-provider declarations it references so an existing default/current selection remains usable without unboundedly copying the whole prior catalog.\n\nThe cache and control files live under `~/.gjc/agent/model-presets/` (respecting `GJC_CODING_AGENT_DIR`). Writes use an interprocess lock, file fsync, and atomic rename. POSIX filesystems also receive a parent-directory durability barrier; Windows does not expose an equivalent directory fsync through Bun/Node, so it retains the file-fsync + atomic-rename guarantee with weaker crash durability for the renamed directory entry. `GJC_MODEL_PRESET_REGISTRY_URL` may override the manifest URL only with credential-free HTTPS; the trust root cannot be replaced at runtime. `GJC_MODEL_PRESET_REGISTRY_DISABLED=1` provides a non-destructive environment disable.\n\n## Model profiles (`--mpreset`)\n\nModel profiles are optional top-level `profiles:` entries in `~/.gjc/agent/models.yml`. A profile can require provider credentials before activation and can map one or more model roles; omitted roles inherit from the active defaults.\n\n> See also: [Cross-vendor role-based profiles](./multi-vendor-profiles.md) — a curated multi-vendor `profiles:` recipe and verified selector notes that build on the mechanism described here.\n\n```yaml\nprofiles:\n  team-standard:\n    required_providers: [openai, anthropic]\n    model_mapping:\n      default: openai/gpt-5.2\n      executor: anthropic/claude-sonnet-5:medium\n      architect: openai/o3:high\n      planner: openai/o3:high\n      critic: openai/o3:high\n```\n\n`model_mapping` keys are role names (`default`, `executor`, `architect`, `planner`, `critic`). Every role accepts either one selector or a non-empty ordered array of selectors; the first entry is primary and later entries are fallback candidates. A selector may be a provider-agnostic bare alias such as `glm-5.2[:effort]` or an explicit `provider/modelId[:effort]` pin, including nested model IDs such as `openrouter/anthropic/claude-sonnet-5`. `required_providers` lists explicit provider prerequisites and may be empty when availability is resolved from bare aliases.\n\n### Fallback chains\n\nPreset `model_mapping` roles, top-level `modelRoles`, and `task.agentModelOverrides` all accept `string | string[]`. Keep one selector per line when a chain needs to be readable:\n\n```yaml\nprofiles:\n  reliable:\n    required_providers: [anthropic, openai]\n    model_mapping:\n      default: [anthropic/claude-sonnet-4-5, openai/gpt-4o-mini]\nmodelBindings:\n  modelRoles:\n    default: [anthropic/claude-sonnet-4-5, openai/gpt-4o-mini]\n  agentModelOverrides:\n    executor: [anthropic/claude-sonnet-4-5, openai/gpt-4o-mini]\n```\n\nResolution-time skips for unavailable, unauthenticated, or unknown entries cost zero attempts and advance immediately. Only request-time retryable failures (such as 429, quota, authentication, or 5xx failures) consume an entry's `fallback.maxAttempts` total attempts (default: `3`). The active default fallback remains sticky for the session; role-override fallback state is fresh for each subagent call. The active model is shown consistently in status and `/model`.\n\nManaged fallback attempts buffer provisional streamed output until an attempt is accepted, so output can appear later than it does for a one-model stream. Current Cursor-agent transports are fail-closed unavailable in retryable fallback chains: resolution rejects them with `Cursor model <selector> requires provider-side tool execution and cannot be used in a retryable fallback chain` because they do not provide a client-side tool-call mode.\n\nCancellation discards provisional output and emits exactly one cancelled `agent_end`; RPC, ACP, and the TUI therefore settle once. On load, the source-aware one-shot migration reads legacy `retry.fallbackChains`, prepends the effective role chain, and writes the ordered, deduplicated result to the corresponding role array; the legacy key is then ignored.\n\nBuilt-in profiles are grouped by provider mix and tier:\n\n- `codex-{eco,medium,pro}` — GPT-5.6 Sol/Terra/Luna role mixes tuned by tier and reasoning effort; `lunamaxxing` — OpenAI Codex Luna-only profile with maximum reasoning on delegated roles\n- `astra-{lite,default,heavy}` — additive OpenAI Codex profiles led by `openai-codex/gpt-6-astra`, displayed as `ASTRA-Lite`, `ASTRA-Default`, and `ASTRA-Heavy` in the CODEX group\n- `opencodego` — single OpenCode Go preset (Kimi K3 default and planner, DeepSeek executor/architect, MiMo critic)\n- `commandcode-goat` — Command Code GOAT preset (GLM-5.3 default, DeepSeek V4 Flash executor, Kimi K3 planner, GLM-5.2 critic, and DeepSeek V4 Pro architect)\n- Provider-agnostic open-model profiles are named by the model families they require. Single-family choices are `open-weights-{glm,deepseek,kimi,luna}`; two-family choices are `open-weights-glm-deepseek`, `open-weights-kimi-deepseek`, and `open-weights-kimi-glm`; `open-weights-kimi-glm-deepseek` uses all three open-weight families; `open-weights-all` adds GPT-5.6 Luna. Choose the smallest combination covered by the models available through your configured providers. Every selector is a bare final-segment alias with `required_providers: []`, so each family may come from any authenticated bundled or custom provider under Provider Priority. GPT-5.6 Luna is proprietary despite its inclusion in this group.\n- `macos-omlx-{fast,balanced,quality}` — oMLX presets for local Apple Silicon inference, tuned by measured same-machine throughput. `fast` pins the 4-bit and `balanced` the 8-bit quant of Qwen 3.6 35B A3B; `quality` keeps the 8-bit MoE for the default, executor, planner, and architect roles and routes the critic to the official dense `Qwen3.8-27B-8bit` checkpoint; `macos-omlx-abliterated-{fast,balanced}` both pin `Qwen3.8-27B-Uncensored-MLX-4bit`, the faster of the measured uncensored quants. Every preset uses one role-effort ladder — critic and architect `high`, planner `medium`, executor and default `low` — and `fast`, `balanced`, and the abliterated presets serve a single model, so sub-agents never trigger an oMLX model unload/reload; `quality` swaps models only for the critic role. Selectors use the ids the local server returns from `/v1/models`; activate after starting oMLX on its default loopback endpoint (see [Implicit oMLX discovery](#implicit-omlx-discovery)) — the provider is keyless, so no `/login` is needed.\n- `claude-opus` — Anthropic OAuth preset that prefers `claude-opus-5` and deterministically falls back to `claude-opus-4-6` when Opus 5 is absent from the active catalog\n- `claude-fable` — Anthropic OAuth preset on `claude-fable-5-1` (default/architect `xhigh`, critic `high`, planner `low`) with `claude-sonnet-5` on the executor role. Fable 5.1 is served only by Anthropic's first-party API; it requires a Claude Code compatibility version of at least `2.1.251` and answers older fingerprints with an HTTP 400 `claude_code_version_too_old`.\n- Single-provider tiers: `glm-{eco,medium,pro}`, `kimi-coding-plan-{eco,medium,pro}`, `mimo-{eco,medium,pro}`, `grok-{eco,medium,pro}`, `grok-45-{eco,medium,pro}`, `grok-46-{eco,medium,pro}`, `cursor-{eco,medium,pro}`, `minimax-{eco,medium,pro}`. The versioned Grok profiles use the existing xAI OAuth/subscription provider: `/login xai` authenticates both versions. Direct `/model` assignment requires an explicit effort for `xai/grok-4.5` (`low`, `medium`, or `high`) and `xai/grok-4.6` (`low`, `medium`, `high`, or `xhigh`) instead of leaving the role at `(inherit)`.\n- Alibaba Token Plan: `alibaba-token-plan-balanced` preserves the established Qwen/DeepSeek V4 Pro/GLM mix; `alibaba-token-plan-pro` raises execution and independent criticism with DeepSeek V4 Flash 0731 max and GLM xhigh; `alibaba-token-plan-qwenmaxxing` stays Qwen-only; `alibaba-token-plan-qwen-deepseek` keeps Qwen 3.8 Max (`qwen3.8-max`) on the expensive default (high)/architect (xhigh)/critic (xhigh) roles and spends DeepSeek V4 Flash 0731 on the cheap planner (max) and executor (high) roles; `alibaba-token-plan-glm-deepseek` does the same with GLM 5.2 (`glm-5.2`) as the expensive model\n- Combos: `opus-codex`, `codex-opencodego`, `fable-opus-codex`, `astra-fable`, and `astra-fable-opus`\n\nGLM-5.3 always enables thinking and accepts only `low`, `high`, and `max`; `max` is the provider default and is recommended for coding. The GLM tiers preserve the former role ordering by collapsing `minimal`/`low` to `low`, `medium`/`high` to `high`, and `xhigh` to `max`. GLM-5.3-Flash keeps the same text contract (per z.ai docs, its text parameters are consistent with GLM-5.3 with a 1M-token context window) and now backs the high-volume lanes of the GLM tiers: `glm-eco` runs default, executor, and planner on `glm-5.3-flash:low` while critic and architect stay on `glm-5.3:high`; `glm-medium` and `glm-pro` keep every role on `glm-5.3` except the executor, which uses `glm-5.3-flash:low` (Medium) and `glm-5.3-flash:high` (Pro).\n\nGemini 3.7 Flash is bundled wherever Gemini 3.6 Flash already was (`google/gemini-3.7-flash`, `google-gemini-cli/gemini-3.7-flash`, Copilot, Antigravity effort variants, OpenCode Zen, OpenRouter, Vercel AI Gateway, Cursor, and the other 3.6 Flash gateways). First-class Google transports use `google-level` thinking and accept only `low`, `medium`, and `high`; `minimal` is rejected because the official Gemini API returns an error. Provider defaults stay on the existing Pro-class models.\n\nThe `eco`, `medium`, and `pro` Codex profile mappings are current product judgments: Eco assigns Terra low/Luna low/Luna high/Terra xhigh/Terra high to default/executor/planner/critic/architect; Medium assigns Sol low/Terra low/Terra high/Sol xhigh/Sol high; Pro assigns Sol medium/Terra medium/Sol high/Sol max/Sol xhigh; and LunaMaxxing assigns Luna medium/Luna xhigh/Luna max/Luna max/Luna max. `opus-codex` retains the Medium Codex executor, critic, and architect roles but uses `anthropic/claude-sonnet-5` for planner; `codex-opencodego` retains the Medium Codex default and architect roles; and `fable-opus-codex` uses the Pro Codex executor and architect roles with `anthropic/claude-opus-5:medium` for planner. The descriptive repeated local exact-edit evidence informs only selected executor-style TypeScript tasks; it does not evaluate or prove default, planner, architect, or critic performance. See [GPT-5.6 Codex preset benchmark](./gpt-5.6-codex-preset-benchmark.md). The Alibaba Pro role evidence and its limits are recorded separately in [Alibaba Token Plan Pro profile benchmark](./alibaba-token-plan-pro-profile-benchmark.md). Cursor Eco uses Composer 2.5 for every role; Medium keeps standard Composer for default/planning and spends the Fast premium on execution, criticism, and architecture; Pro uses Composer 2.5 Fast throughout. Composer does not expose a strength value through the current Cursor RPC, so these profiles use exact model IDs without inert generic effort suffixes. See [Cursor Composer profile tiers](./cursor-composer-profile-tiers.md). Effort suffixes are clamped to each model's supported thinking range at preview and activation time. Single-provider tiers pin each provider's current flagship (`zai/glm-5.2`, `kimi-code/kimi-k2.7-code`, `xiaomi/mimo-v2.5-pro`, `xai/grok-4.3`, `cursor/composer-2.5`, `minimax-code/MiniMax-M3`). User-defined profiles override built-ins by exact profile name.\n\nGPT-6 Astra supports `low`, `medium`, `high`, `xhigh`, and `max`; the ASTRA profiles use only those catalog-backed levels. In default/executor/architect/planner/critic order, `astra-lite` assigns Astra medium/Luna xhigh/Terra xhigh/Astra xhigh/Sol high; `astra-default` assigns Astra medium/Luna max/Terra xhigh/Astra xhigh/Sol xhigh; and `astra-heavy` assigns Astra medium/Sol max/Astra max/Sol max/Astra max. `astra-fable` keeps the ASTRA-Default default, executor, and planner bindings while routing architect and critic to `anthropic/claude-fable-5-1:xhigh`; `astra-fable-opus` additionally routes planner to `anthropic/claude-opus-5:medium`. Both combinations require `openai-codex` and `anthropic` availability, either directly or through the configured preset proxy. The existing Codex presets and the `openai-codex` recommendation remain unchanged.\n\nUse `gjc --mpreset <name>` to activate a profile for the current session only. Activation hard-blocks when any provider listed in `required_providers` lacks credentials. Add `--default` to persist the selected profile as `modelProfile.default` in `config.yml`, so it applies at startup:\n\n```sh\ngjc --mpreset codex-medium\ngjc --mpreset astra-default\ngjc --mpreset opencodego --default\n```\n\n### Routing built-in presets through a proxy (`modelProfile.proxyProvider`)\n\nFor a local OpenCodex pool, set `modelProfile.proxyProvider` to `opencodex` and\n`modelProfile.proxyMode` to `always`. With a persisted `modelProfile.default`, plain\n`gjc` applies that preset through the pool on startup, even when direct Anthropic\nand Codex credentials exist. GJC discovers the local proxy's public `/v1/models`\ncatalog automatically; no management token or static `models.yml` roster is needed.\nModel IDs retain their GJC namespace, while preset matching uses the upstream wire\nID. A missing proxy model still fails activation instead of silently bypassing the pool.\n\nBuilt-in preset selectors pin a direct provider endpoint (`xai/grok-4.3`, `xiaomi/mimo-v2.5-pro`, …). To serve those models through your own OpenAI-compatible gateway (LiteLLM, OpenRouter, or a custom proxy) instead of each vendor's endpoint, configure the proxy provider id and routing mode in `config.yml`:\n\n```yaml\nmodelProfile:\n  proxyProvider: litellm\n  proxyMode: always # use fallback to keep directly authenticated providers direct\n```\n\nThe proxy provider is a normal `providers:` entry. Add it with `gjc setup provider --preset litellm --base-url <url>` or the generic `gjc setup provider --preset openai-compatible-proxy --base-url <url>` (both presets require `--base-url` and use live model discovery). The configured proxy must be authenticated and expose every routed model. Activation rewrites each selected built-in preset selector from `<direct-provider>/<model>` to `<proxy>/<direct-provider>/<model>` (for example `xai/grok-4.3` → `litellm/xai/grok-4.3`), matching the proxy's catalog entry for the model. The rules:\n\n- Routing applies to **built-in presets only**. User-defined `profiles:` entries always keep their exact selectors — set them explicitly if you want them proxied.\n- `proxyMode: fallback` (the default) routes only selectors whose direct provider is unauthenticated. `proxyMode: always` routes every proxy-routable built-in selector through the configured proxy, including selectors with direct credentials.\n- The proxy id must name a configured provider. `proxyMode: always` requires `proxyProvider` and a usable proxy credential; activation fails closed when a required proxy is unset or unauthenticated. `auth: none` proxies count as authenticated.\n- Only providers the bundled preset catalog treats as routable are rewritten; providers outside that set (for example a custom `acme-private`) keep the direct credential error.\n- A routed selector must have exactly one matching proxy catalog model. Exact `<direct-provider>/<model>` proxy ids win over suffix matches; missing or ambiguous matches fail activation before any role can run.\n\nThe `/model` command opens to a preset landing view: presets are grouped by provider with live auth marks (✓/✗), highlighting a group expands its tiers, and selecting a tier shows the full role→model preview before applying for the session or as default. Typing jumps straight to model search, and `Browse all models` opens the classic tabbed model selector. In `/login`, `Add custom provider` is the first option for configuring credentials needed by custom or profile-required providers; after a successful provider login, the matching preset is recommended automatically. Custom providers participate in provider-agnostic alias resolution but require manual preset selection.\n\nExternal SDK/ACP clients (e.g. the Paseo TUI) can select profiles like ordinary models: the SDK `models.list/current` (Q10) catalog exposes every usable profile as a synthetic `gajae-code/<profile>` entry (e.g. `gajae-code/codex-eco`), and selecting one through `model.set` (or the ACP Model picker) activates the profile for the live session only. Persisting a profile remains an explicit TUI choice, mirroring `gjc --mpreset <name> --default`. See [SDK model profiles](./sdk.md#model-profiles-as-synthetic-models-gajae-codeprofile).\n\nMiniMax's OpenAI-compatible endpoint rejects multiple system messages and emits thinking in `reasoning_content`, so pin the public-safe compatibility fields when hand-authoring a custom provider:\n\n```yaml\nproviders:\n  minimax-custom:\n    baseUrl: https://api.minimax.io/v1\n    apiKeyEnv: MINIMAX_API_KEY\n    api: openai-completions\n    compat:\n      supportsStore: false\n      supportsDeveloperRole: false\n      supportsReasoningEffort: false\n      reasoningContentField: reasoning_content\n    models:\n      - id: MiniMax-M2.5\n```\n\nGLM via z.ai is available as the first-class `zai` provider. For a private GLM-compatible proxy, keep secrets in an env var and disable OpenAI-only request fields as needed:\n\n```yaml\nproviders:\n  glm-proxy:\n    baseUrl: https://api.z.ai/api/paas/v4\n    apiKeyEnv: ZAI_API_KEY\n    api: openai-completions\n    compat:\n      supportsDeveloperRole: false\n      supportsReasoningEffort: false\n    models:\n      - id: glm-4.6\n```\n\n### JetBrains AI (Junie)\n\n`jetbrains-junie` is a first-class provider serving JetBrains-hosted models through the documented\nIngrazzio gateway (`https://ingrazzio-cloud-prod.labs.jb.gg`).\n\nAuthenticate with an access token generated at [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli):\n\n```sh\nexport JUNIE_API_KEY=...\n```\n\nThe token is sent as `Authorization: Bearer` — JetBrains AI rejects requests that also carry `x-api-key`, so\nthis provider never lets the Anthropic SDK attach one. Usage is billed against your JetBrains AI\nsubscription, so bundled per-token costs are zero. There is no OAuth login flow; the environment variable is\nthe only supported credential source.\n\nThe gateway multiplexes transports by model family:\n\n| Family | Models | Transport | Prompt limit |\n| --- | --- | --- | --- |\n| Claude | `claude-sonnet-4-6` (default), `claude-sonnet-5`, `claude-opus-4-6`, `claude-opus-4-7`, `claude-opus-4-8`, `claude-opus-5`, `claude-fable-5` | `anthropic-messages` | 1M |\n| GPT | `gpt-5-2025-08-07`, `gpt-5.2-2025-12-11`, `gpt-5.4`, `gpt-5.5`, `gpt-5.6-luna`, `gpt-5.6-sol`, `gpt-5.6-terra` | `openai-completions` | 922K |\n| GPT (Responses-only) | `gpt-5.3-codex` | `openai-responses` | 272K |\n\nAll models cap output at 128K. Junie also exposes Gemini and Grok, but those ride a proprietary Grazie\ntranslation protocol that GJC does not implement, so they are deliberately not bundled. The bare\n`opus`/`sonnet`/`gpt`/`grok` aliases are Junie CLI shorthands the gateway itself rejects.\n\n### Allowed auth/discovery values\n\n- `auth`: `apiKey` (default), `none`, or `oauth`; for `models.yml` custom models, `oauth` is accepted by schema but does not waive the `apiKey` requirement\n- `models.yml` is strict: unknown provider/model keys fail validation before provider dispatch, so stale keys such as `requestTransform` or `wireModelId` only work where this document lists them.\n- `discovery.type`: `ollama`, `llama.cpp`, `lm-studio`, `omlx`, `vllm`, `sglang`, `openai-models-list`, or `models-dev`; `models-dev` may select a different catalog entry with `modelsDevProvider`\n- `cacheRetention`: `none`, `short`, or `long`; request-time options win over model/modelOverride values, then provider values, then `GJC_CACHE_RETENTION`, then the runtime default. The runtime default is `short` for most providers, but the Anthropic provider defaults to `long` because the ~5m cache is fragile for long-running subagent workflows. Canonical Anthropic models use top-level automatic caching and emit `ttl: \"1h\"` when long retention is supported. Claude-family models on non-canonical Anthropic-compatible endpoints default to explicit block markers because compatible proxies commonly inject, rewrite, or reject top-level cache controls; they omit `ttl` unless `compat.supportsLongCacheRetention: true` opts the endpoint into 1-hour retention. For OpenAI Responses, this controls `prompt_cache_retention` only; it does not disable `prompt_cache_key` when a stable session id exists.\n\n## OpenAI-compatible proxy configuration\n\nOpenAI-compatible proxy providers should use schema-supported provider keys first:\nThe first-class way to add a proxy provider is `gjc setup provider --preset litellm --base-url <url>` (LiteLLM) or `gjc setup provider --preset openai-compatible-proxy --base-url <url>` (any OpenAI-compatible gateway); both presets require `--base-url` and configure live model discovery. For a fully custom id, `gjc setup provider --compat openai --provider <id> --base-url <url> --api-key-env <ENV> --discover [--model <id>]` (or `/provider add` with `--discover`) persists the same live discovery without requiring manual model ids. The Add-custom-provider wizard automatically probes after OpenAI-compatible URL and credentials are supplied, offers the discovered catalog, and retains retry and manual entry when discovery fails or returns no models. Anthropic-compatible setup keeps manual entry. Leaving discovery cancels its preview; cancellation before the atomic configuration commit prevents saving the provider, and credential-restoration failures are reported without secret material. Proxy providers can also be used to route built-in model-preset selectors — see [Routing built-in presets through a proxy](#routing-built-in-presets-through-a-proxy-modelprofileproxyprovider). The YAML below shows the equivalent hand-written provider config:\n\n```yaml\nproviders:\n  proxy-provider:\n    baseUrl: https://api.proxy.example/v1\n    apiKeyEnv: PROXY_API_KEY\n    api: openai-completions\n    auth: apiKey\n    headers:\n      User-Agent: curl/8.7.1\n    models:\n      - id: local-gpt\n        name: Local GPT\n        reasoning: true\n        thinking:\n          minLevel: low\n          maxLevel: high\n          mode: effort\n        compat:\n          supportsReasoningEffort: true\n        input: [text]\n        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }\n        contextWindow: 400000\n        maxTokens: 128000\n```\n\nUse provider-level `headers` for proxy-required headers. Keep the provider `api` set to `openai-completions` when the proxy exposes Chat Completions-compatible `/v1/chat/completions` semantics. `auth: apiKey` sends the resolved token as bearer auth; use `auth: none` only for trusted local/no-auth endpoints.\n\nFor an unknown custom endpoint, `reasoning: true` declares model capability but does not prove the proxy accepts a control parameter. A familiar provider id or model-family name is not transport evidence: configurable LiteLLM/vLLM/local endpoints still fail closed. Add `thinking` and `compat.supportsReasoningEffort: true` only when the endpoint documents OpenAI-style `reasoning_effort`; set `compat.thinkingFormat` as well when it uses a different documented request shape. Otherwise GJC keeps reasoning-level controls unavailable and omits the parameter.\n\n`auth` selects the transport scheme only; it never supplies a credential. A provider that declares `models:` must therefore also declare where its key comes from, and `models.yml` validation rejects the config before model discovery otherwise:\n\n| Intent | Required keys |\n| --- | --- |\n| Authenticated proxy (recommended) | `auth: apiKey` (default) + `apiKeyEnv: MY_TOKEN` |\n| Authenticated proxy, key inline | `auth: apiKey` (default) + `apiKey: sk-…` (less safe; stored in plaintext) |\n| Genuinely unauthenticated endpoint | `auth: none`, no key |\n\nOmitting both `apiKey` and `apiKeyEnv` while leaving `auth` at its `apiKey` default fails with `Provider <name>: custom models need a credential source, but none is configured.` — the fix is to add one of the rows above, not to change `api` or `baseUrl`.\n\n`input` is the model modality list GJC uses to decide whether image content is forwarded. When a custom model omits `input`, GJC defaults to `[text]` (unless a bundled model with the same id contributes a reference). Vision-capable upstream models therefore need an explicit `input: [text, image]`; otherwise `read`/tool images are stripped before the request and replaced with `[image omitted: model does not support vision]`, even if the remote model can see images.\n\n```yaml\nproviders:\n  ali:\n    baseUrl: https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1\n    apiKeyEnv: ALI_API_KEY\n    api: openai-completions\n    auth: apiKey\n    models:\n      # id-only → text-only; images will be omitted\n      - id: some-text-model\n      # vision-capable hosted model must declare image input\n      - id: qwen3.8-max-preview\n        name: Qwen3.8 Max Preview\n        reasoning: true\n        input: [text, image]\n```\n\n`requestTransform` and `wireModelId` remain supported for request-body shaping, but they are not needed for ordinary OpenAI-compatible proxies whose local model id is already the upstream wire id. Unknown config keys fail validation before a provider request is sent.\n\nWhen request shaping is needed:\n\n- `requestTransform.profile: openai-proxy` strips OpenAI SDK/Stainless telemetry and beta headers at final fetch time and sets a generic GJC user agent.\n- `stripHeaders` replaces the preset strip list when provided.\n- `setHeaders` is applied after stripping; use `null` to remove a header.\n- `extraBody` is shallow-merged into the JSON request body after provider compatibility fields; core transport keys such as `model`, `messages`/`input`, `stream`, `tools`, and `tool_choice` are protected and ignored.\n- Model-level `requestTransform` overrides provider-level fields and shallow-merges `setHeaders`/`extraBody`.\n- `wireModelId` changes only the upstream request body model id; local selection still uses `provider/id`.\n\n### Layofflabs-style proxy example\n\n```yaml\nproviders:\n  layofflabs:\n    baseUrl: https://api.layofflabs.com/v1\n    apiKeyEnv: OPENAI_API_KEY\n    api: openai-completions\n    auth: apiKey\n    headers:\n      User-Agent: curl/8.7.1\n    models:\n      - id: gpt-5.5\n        name: GPT 5.5 via Layofflabs\n        reasoning: true\n        thinking:\n          minLevel: low\n          maxLevel: xhigh\n          mode: effort\n          defaultLevel: high\n          levels: [low, medium, high, xhigh]\n        compat:\n          supportsReasoningEffort: true\n        input: [text]\n        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }\n        contextWindow: 400000\n        maxTokens: 128000\n\nmodelBindings:\n  modelRoles:\n    default: layofflabs/gpt-5.5:high\n  agentModelOverrides:\n    executor: layofflabs/gpt-5.5:high\n```\n\n## Validation rules (current)\n\n### Full custom provider (`models` is non-empty)\n\nRequired:\n\n- `baseUrl`\n- A credential source: `apiKeyEnv` or `apiKey`. `auth` selects the scheme, not the credential, so `auth: apiKey` (the default) still needs one of them. Exempt: `auth: none`, and `api: bedrock-converse-stream`, which resolves AWS credentials from its own chain.\n- `api` at provider level or each model\n\n### Override-only provider (`models` missing or empty)\n\nMust define at least one of:\n\n- `baseUrl`\n- `headers`\n- `compat`\n- `requestTransform`\n- `disableStrictTools`\n- `modelOverrides`\n- `discovery`\n\n### Discovery\n\n- `discovery` requires provider-level `api`.\n\n### Model value checks\n\n- `id` required\n- `contextWindow` and `maxTokens` must be positive if provided\n- unknown provider, model, override, and request-transform keys fail schema validation; remove stale keys instead of relying on them being ignored.\n\n`maxTokens` on an explicit `models.yml` model (or `modelOverrides` entry) is the\nauthoritative default output budget for that configured model. A positive\nper-request `maxTokens` option still wins. Built-in catalog values and runtime\ndiscovery metadata retain the transport's conservative 32,000-token default\nunless the caller supplies a positive request override; their displayed\n`maxTokens`/`max-out` value is model metadata, not an unconditional request\npromise. A request value of `0` is treated as unspecified and does not bypass\nthe safe default. Provider hard limits and reasoning-budget rules remain\nenforced by the selected transport.\nValid budget values — configured or per-request — are positive safe integers\n(1 … 9007199254740991). Fractional values and anything above\n`Number.MAX_SAFE_INTEGER` fail schema validation in `models.yml`/overrides and\nare treated as unspecified when passed programmatically, so integer-only\nprovider fields (`max_tokens`, `max_completion_tokens`, `max_output_tokens`)\nnever receive an unsatisfiable budget. The low-level `stream()`/`complete()`\nboundary applies the same rule to provider options.\n\n## Merge and override order\n\nModelRegistry pipeline (on refresh):\n\n1. Load built-in providers/models from `@gajae-code/ai`.\n2. Load `models.yml` custom config.\n3. Apply provider overrides (`baseUrl`, `headers`, `requestTransform`, `disableStrictTools`, `cacheRetention`) to built-in models.\n4. Apply `modelOverrides` (per provider + model id).\n5. Merge custom `models`:\n   - same `provider + id` replaces existing\n   - otherwise append\n6. Load cached/runtime-discovered models (Ollama, llama.cpp, LM Studio, plus built-in provider managers), then re-apply model overrides.\n\n### Provider-model cache and static fingerprint\n\nCached per-provider model lists are persisted in the model-cache SQLite\ndatabase (schema v3) with a `static_fingerprint` column that hashes the\nstatic catalog slice merged into the row. When `resolveProviderModels`\nskips the network fetch and the fingerprint of the in-memory static\ncatalog matches the cached one, the cached rows are returned verbatim —\nthe static + dynamic merge is bypassed entirely. The fingerprint is\nmemoized per process via a WeakMap keyed by the static-models array\nreference, so repeated cold-start calls do not re-hash.\n\n## Canonical model equivalence and coalescing\n\nThe registry keeps every concrete provider model and then builds a canonical layer above them.\n\nCanonical ids are official upstream ids only, for example:\n\n- `anthropic-model-opus-4-6`\n- `anthropic-model-haiku-4-5`\n- `gpt-5.3-openai-code`\n\n### `models.yml` equivalence config\n\nExample:\n\n```yaml\nproviders:\n  zenmux:\n    baseUrl: https://api.zenmux.example/v1\n    apiKey: ZENMUX_API_KEY\n    api: openai-codex-responses\n    models:\n      - id: openai-code\n        name: Zenmux OpenAI code\n        reasoning: true\n        input: [text]\n        cost:\n          input: 0\n          output: 0\n          cacheRead: 0\n          cacheWrite: 0\n        contextWindow: 200000\n        maxTokens: 32768\n\nequivalence:\n  overrides:\n    zenmux/openai-code: gpt-5.3-openai-code\n    p-openai-code/openai-code: gpt-5.3-openai-code\n  exclude:\n    - demo/openai-code-preview\n```\n\nBuild order for canonical grouping:\n\n1. exact user override from `equivalence.overrides`\n2. bundled official-id matches from built-in model metadata\n3. conservative heuristic normalization for gateway/provider variants\n4. fallback to the concrete model's own id\n\nCurrent heuristics are intentionally narrow:\n\n- embedded upstream prefixes can be stripped when present, for example `anthropic/...` or `openai/...`\n- dotted and dashed version variants can normalize only when they map to an existing official id, for example `4.6 -> 4-6`\n- ambiguous families or versions are not merged without a bundled match or explicit override\n\n### Canonical and preset-equivalent resolution behavior\n\nWhen multiple concrete variants are eligible for automatic resolution, the global provider policy uses this order:\n\n1. explicit `config.yml` `modelProviderOrder` entries, in their saved order\n2. omitted providers whose effective credential came from OAuth\n3. omitted providers using a manual API key, unknown credential provenance, or keyless access\n4. vision capability, exact canonical identity, canonical source quality, lowest `cost.input + cost.cacheRead`, stable registry model order, then concrete selector order\n\nThe explicit provider list may be partial. A listed API-key provider beats every omitted OAuth provider. Resetting Provider Priority clears the explicit list and restores OAuth-first plus deterministic fallback. Saved providers that are not currently available remain visible and persisted, but runtime resolution skips them.\n\nModel-profile and preset assignments support a lookup-only alias when the assignment does not explicitly name a provider. For example, a bare preset assignment `gpt-5` can select any available concrete variant whose final model-id segment is `gpt-5`, ranked by the same global policy. An assignment such as `openai/gpt-5` is an explicit provider pin: if that exact model is unavailable, activation reports it unavailable instead of switching providers. Alias lookup never rewrites the selected model's concrete provider, full model id, or `wireModelId`; a known bare alias with no eligible variant is unavailable and does not fall through to a different fuzzy match. Direct model selection remains unchanged.\nRuntime custom providers participate in the same lookup automatically. A custom provider model such as `hosted/glm-5.2` contributes the alias `glm-5.2` when the provider is registered, authenticated, and available; Provider Priority can rank that custom provider ahead of bundled providers without changing the preset. Custom IDs whose final segment differs (for example `glm-5.2-special`) do not join the alias.\n\nA session that resolves a canonical or alias selector keeps its concrete variant across provider-priority edits and discovery refreshes. Updated priority applies to new or unpinned resolutions. The session re-ranks only after explicit reselection or when the sticky variant becomes unavailable. Session state and transcripts continue to record the concrete provider/model that executed the turn.\n\nProvider defaults vs per-model overrides:\n\n- Provider `headers` are baseline.\n- Model `headers` override provider header keys.\n- `modelOverrides` can override model metadata (`name`, `reasoning`, `input`, `cost`, `contextWindow`, `maxTokens`, `headers`, `compat`, `contextPromotionTarget`).\n- `compat` is deep-merged for nested routing blocks (`openRouterRouting`, `vercelGatewayRouting`, `extraBody`).\n\n## Runtime discovery integration\n\n### Implicit Ollama discovery\n\nIf `ollama` is not explicitly configured, registry adds an implicit discoverable provider:\n\n- provider: `ollama`\n- api: `openai-responses`\n- base URL: `OLLAMA_BASE_URL` or `http://127.0.0.1:11434`\n- auth mode: keyless (`auth: none` behavior)\n\nRuntime discovery calls Ollama endpoints and normalizes discovered OpenAI-compatible models to `openai-responses`.\n\n### Implicit llama.cpp discovery\n\nIf `llama.cpp` is not explicitly configured, registry adds an implicit discoverable provider:\n\n- provider: `llama.cpp`\n- api: `openai-responses`\n- base URL: `LLAMA_CPP_BASE_URL` or `http://127.0.0.1:8080`\n- auth mode: keyless (`auth: none` behavior)\n\nRuntime discovery calls llama.cpp model endpoints and synthesizes model entries with local defaults.\n\n### Implicit LM Studio discovery\n\nIf `lm-studio` is not explicitly configured, registry adds an implicit discoverable provider:\n\n- provider: `lm-studio`\n- api: `openai-completions`\n- base URL: `LM_STUDIO_BASE_URL` or `http://127.0.0.1:1234/v1`\n- auth mode: keyless (`auth: none` behavior)\n\nRuntime discovery fetches models (`GET /models`) and synthesizes model entries with local defaults.\n\n### Implicit oMLX discovery\n\nIf `omlx` is not explicitly configured, registry adds an implicit discoverable provider:\n\n- provider: `omlx`\n- api: `openai-completions`\n- base URL: `OMLX_BASE_URL` or `http://127.0.0.1:8080/v1`\n- auth mode: keyless (`auth: none` behavior)\n\nRuntime discovery fetches models (`GET /v1/models`) and synthesizes model entries with local defaults and `max_model_len` support.\n\n### Implicit vLLM discovery\n\nIf `vllm` is not explicitly configured, its bundled provider descriptor discovers the local server implicitly:\n\n- provider: `vllm`\n- api: `openai-completions`\n- base URL: trusted `VLLM_BASE_URL` or `http://127.0.0.1:8000/v1` (a project `.env` cannot redirect authenticated traffic)\n- auth mode: keyless (`auth: none` behavior), `VLLM_API_KEY` attaches when present\n\nRuntime discovery fetches models (`GET /v1/models`) and synthesizes model entries with local defaults and `max_model_len` support. Credentialless implicit discovery is limited to loopback. For a remote vLLM server (for example, a LAN GPU box), set `VLLM_BASE_URL` and `VLLM_API_KEY` in the launching shell or a user-owned GJC environment file, or configure it explicitly under `providers` as shown below.\n\n### Implicit SGLang discovery\n\nIf `sglang` is not explicitly configured, its bundled provider descriptor discovers the local server implicitly:\n\n- provider: `sglang`\n- api: `openai-completions`\n- base URL: trusted `SGLANG_BASE_URL` or `http://127.0.0.1:30000/v1` (a project `.env` cannot redirect authenticated traffic)\n- auth mode: keyless (`auth: none` behavior), `SGLANG_API_KEY` attaches when present\n\nRuntime discovery fetches models (`GET /v1/models`) and synthesizes model entries with local defaults and `max_model_len` support. Credentialless implicit discovery is limited to loopback and needs no `/login`; `/login sglang` stores only an actual API key. For a remote SGLang server (for example, a LAN GPU box), set `SGLANG_BASE_URL` and `SGLANG_API_KEY` in the launching shell or a user-owned GJC environment file, or configure it explicitly under `providers` as shown below. Standard proxy environment variables remain explicit transport configuration, so include local SGLang hosts in `NO_PROXY` when local traffic must connect directly.\n\n### Explicit provider discovery\n\nYou can configure discovery yourself:\n\n```yaml\nproviders:\n  ollama:\n    baseUrl: http://127.0.0.1:11434\n    api: openai-responses\n    auth: none\n    discovery:\n      type: ollama\n\n  llama.cpp:\n    baseUrl: http://127.0.0.1:8080\n    api: openai-responses\n    auth: none\n    discovery:\n      type: llama.cpp\n```\n\n### Extension provider registration\n\nExtensions can register providers at runtime (`pi.registerProvider(...)`), including:\n\n- model replacement/append for a provider\n- custom stream handler registration for new API IDs\n- custom OAuth provider registration\n\n### Agent-level providers (ACP)\n\nSome upstreams publish a complete agent instead of a model endpoint. Those are\nintegrated as **agent-level providers**: the provider id is selectable like any\nother, but the upstream agent owns model choice, tool execution, conversation\nhistory, and usage accounting.\n\n`devin` (Devin CLI) is the first one. GJC spawns `devin acp` and speaks the\nAgent Client Protocol over stdio; `devin` models appear through the ordinary\nprovider/model selection path once the CLI is installed and authenticated, and\nthe provider is credentialless (`getApiKey*` returns `kNoAuth`) because\nauthentication belongs to the CLI (`devin auth login`).\n\nSee [Devin CLI provider (ACP)](./devin-provider.md) for the full boundary: which\nGJC surfaces apply to a Devin turn, the tool-call permission policy\n(`GJC_DEVIN_PERMISSION_MODE`), and billing.\n\n## Auth and API key resolution order\n\nWhen requesting a key for a provider, effective order is:\n\n1. Runtime override (CLI `--api-key`)\n2. `models.yml` `providers.<name>.apiKey` literal pin\n3. Stored API key credential in `agent.db` (written by `auth login`)\n4. `models.yml` `providers.<name>.apiKeyEnv` indirection — a pointer to a key,\n   not a pinned value, so a stored login credential outranks it; it still\n   outranks stored OAuth credentials\n5. Stored OAuth credential in `agent.db` (with refresh)\n6. Environment variable mapping (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.)\n7. ModelRegistry fallback resolver (provider `apiKey` from `models.yml`, env-name-or-literal semantics)\n\n`models.yml` `apiKey` behavior:\n\n- Value is first treated as an environment variable name.\n- If no env var exists, the literal string is used as the token.\n\nIf `authHeader: true` and provider `apiKey` is set, models get:\n\n- `Authorization: Bearer <resolved-key>` header injected.\n\nKeyless providers:\n\n- Providers marked `auth: none` are treated as available without credentials.\n- `getApiKey*` returns `kNoAuth` for them.\n\n### Broker mode\n\nWhen `GJC_AUTH_BROKER_URL` (or `auth.broker.url`) is set, the local SQLite credential store is replaced by `RemoteAuthCredentialStore`. Layers 2 and 3 above (stored API key / OAuth in `agent.db`) are served from a broker-supplied snapshot whose `refresh` tokens are redacted; expiry triggers `POST /v1/credential/:id/refresh` on the broker rather than a local refresh.\n\n`AuthStorage.setConfigApiKey` lets a `models.yml` `apiKey` win over a broker-resolved OAuth token without overriding a runtime `--api-key`. See [`auth-broker-gateway.md`](./auth-broker-gateway.md) for the full broker / gateway design and env surface (`GJC_AUTH_BROKER_URL`, `GJC_AUTH_BROKER_TOKEN`, `auth.broker.url`, `auth.broker.token`).\n\n## Model availability vs all models\n\n- `getAll()` returns the loaded model registry (built-in + merged custom + discovered).\n- `getAvailable()` filters to models that are keyless or have resolvable auth.\n\nSo a model can exist in registry but not be selectable until auth is available.\n\n## Runtime model resolution\n\n### CLI and pattern parsing\n\n`model-resolver.ts` supports:\n\n- exact `provider/modelId`\n- exact canonical model id\n- exact model id (provider inferred)\n- fuzzy/substring matching\n- glob scope patterns in `--models` (e.g. `openai/*`, `*sonnet*`)\n- optional `:thinkingLevel` suffix (`off|minimal|low|medium|high|xhigh`)\n\n`--provider` is legacy; `--model` is preferred.\n\nResolution precedence for exact selectors:\n\n1. exact `provider/modelId` bypasses coalescing\n2. exact canonical id resolves through the canonical index\n3. exact bare concrete id still works\n4. fuzzy and glob matching run after the exact paths\n\nThinking suffixes are split once from the final `:` only after the complete selector does not resolve. This preserves concrete OpenRouter route IDs such as `openrouter/z-ai/glm-4.7:nitro`; `:high` can follow that route suffix. Multiple suffixes are not recursively consumed. A complete `provider/modelId` selector is exact-only: it never falls back to fuzzy, substring, glob, or another provider when that concrete selector is absent. Exact-case provider/model entries resolve deterministically for custom replacement semantics; a case-insensitive selector that remains ambiguous does not guess.\n\nPreset/profile activation may use an unqualified assignment as a final-segment lookup alias after exact resolution fails. Provider-qualified assignments remain exact pins, and this opt-in does not apply to CLI or direct concrete model selection.\n\n### Initial model selection priority\n\n`findInitialModel(...)` uses this order:\n\n1. explicit CLI provider+model\n2. first scoped model (if not resuming)\n3. saved default provider/model\n4. known provider defaults (e.g. OpenAI/Anthropic/etc.) among available models\n5. first available model\n\n### Role aliases and settings\n\nSupported model roles:\n\n- `default` plus the agent assignment targets `executor`, `architect`, `planner`, `critic`\n\nRole aliases like `pi/default` expand through `settings.modelRoles`. Each role value can also append a thinking selector such as `:minimal`, `:low`, `:medium`, or `:high`.\n\nIf a role points at another role, the target model still inherits normally and any explicit suffix on the referring role wins for that role-specific use.\n\nRelated settings:\n\n- `modelRoles` (record)\n- `enabledModels` (scoped pattern list)\n- `modelProviderOrder` (global automatic provider precedence; editable under Settings → Providers with add/remove, move up/down, unavailable-entry retention, and Reset)\n- `providers.kimiApiFormat` (`openai` or `anthropic` request format)\n- `providers.openaiWebsockets` (`auto|off|on` websocket preference for OpenAI code provider transport)\n\n`modelRoles` may store either:\n\n- `provider/modelId` to pin a concrete provider variant\n- a canonical id such as `gpt-5.3-openai-code` to allow provider coalescing\n\nFor `enabledModels` and CLI `--models`:\n\n- exact canonical ids expand to all concrete variants in that canonical group\n- explicit `provider/modelId` entries stay exact\n- globs and fuzzy matches still operate on concrete models\n\nGlobal `enabledModels` and `disabledProviders` entries may also be scoped to a path prefix:\n\n```yaml\nenabledModels:\n  - anthropic-model-sonnet-4-5\n  - path: ~/work\n    models:\n      - anthropic/anthropic-model-opus-4-5\ndisabledProviders:\n  - ollama\n  - path: ~/private\n    providers:\n      - anthropic\n```\n\nString entries apply everywhere. Scoped entries apply when the current working directory is the configured path or one of its subdirectories. Use `path`, `paths`, `pathPrefix`, or `pathPrefixes`; use `models` for `enabledModels`, `providers` for `disabledProviders`, or `values` for either.\n\n## `/model` and `--list-models`\n\nBoth surfaces keep provider-prefixed models visible and selectable.\n\nThey now also expose canonical/coalesced models:\n\n- `/model` includes a canonical view alongside provider tabs\n- `--list-models` prints a canonical section plus the concrete provider rows\n\nSelecting a canonical entry stores the canonical selector. Selecting a provider row stores the explicit `provider/modelId`.\n\n## Context promotion (model-level fallback chains)\n\nContext promotion is an overflow recovery mechanism for small-context variants (for example `*-spark`) that automatically promotes to a larger-context sibling when the API rejects a request with a context length error. It is **off by default** (`contextPromotion.enabled` is `false`); opt in to enable it.\n\n### Trigger and order\n\nWhen a turn fails with a context overflow error (e.g. `context_length_exceeded`), `AgentSession` attempts promotion **before** falling back to compaction:\n\n1. If `contextPromotion.enabled` is true, resolve a promotion target (see below).\n2. If a target is found, switch to it and retry the request — no compaction needed.\n3. If no target is available, fall through to auto-compaction on the current model.\n\n### Target selection\n\nSelection is model-driven, not role-driven:\n\n1. `currentModel.contextPromotionTarget` (if configured)\n2. smallest larger-context model on the same provider + API\n\nCandidates are ignored unless credentials resolve (`ModelRegistry.getApiKey(...)`).\n\n### OpenAI code provider websocket handoff\n\nIf switching from/to `openai-codex-responses`, session provider state key `openai-codex-responses` is closed before model switch. This drops websocket transport state so the next turn starts clean on the promoted model.\n\n### Persistence behavior\n\nPromotion uses temporary switching (`setModelTemporary`):\n\n- recorded as a temporary `model_change` in session history\n- does not rewrite saved role mapping\n\n### Configuring explicit fallback chains\n\nConfigure fallback directly in model metadata via `contextPromotionTarget`.\n\n`contextPromotionTarget` accepts either:\n\n- `provider/model-id` (explicit)\n- `model-id` (resolved within current provider)\n\nExample (`models.yml`) for Spark -> non-Spark on the same provider:\n\n```yaml\nproviders:\n  openai-code:\n    modelOverrides:\n      gpt-5.3-openai-code-spark:\n        contextPromotionTarget: openai-code/gpt-5.3-openai-code\n```\n\nThe built-in model generator also assigns this automatically for `*-spark` models when a same-provider base model exists.\n\n## Compatibility and routing fields\n\nThe `compat` block on a provider or model overrides the URL-based auto-detection in `packages/ai/src/providers/openai-completions-compat.ts`. It is validated by `OpenAICompatSchema` in `packages/coding-agent/src/config/model-registry.ts` and consumed by every `openai-completions` transport (`packages/ai/src/providers/openai-completions.ts`). The canonical type is `OpenAICompat` in `packages/ai/src/types.ts`.\n\n`models.yml` accepts the following keys (all optional; unset falls back to URL detection):\n\nRequest shaping:\n\n- `supportsStore` — emit `store: false` on requests. Default: auto (off for non-standard endpoints).\n- `supportsDeveloperRole` — use the `developer` system role for reasoning models instead of `system`. Default: auto.\n- `sendSessionHeaders` — forward the agent session id as `session_id` and `x-session-id` request headers so OpenAI-compatible relays/proxies can do session-affinity routing and reuse a server-side prompt cache. Default: `false`. Caller-set `headers`/`requestTransform` values are never overwritten.\n- `supportsResponsesSessionAffinity` — for `openai-responses`, opt in to forwarding `session_id` and `x-client-request-id` affinity headers to a custom OpenAI-compatible relay. Canonical OpenAI routing remains automatic; known non-OpenAI provider IDs are rejected. Default: `false`.\n- `supportsUsageInStreaming` — send `stream_options: { include_usage: true }` to receive token usage on streaming responses. Default: `true`.\n- `maxTokensField` — `\"max_completion_tokens\"` or `\"max_tokens\"`. Default: auto.\n- `supportsToolChoice` — emit the `tool_choice` parameter when the caller forces a specific tool. Default: `true`. Set `false` for endpoints that 400 on `tool_choice` (e.g. DeepSeek when reasoning is on).\n- `disableReasoningOnForcedToolChoice` — drop `reasoning_effort` / OpenRouter `reasoning` whenever `tool_choice` forces a call. Default: auto (Kimi/Anthropic-fronted endpoints).\n- `extraBody` — extra top-level fields merged into every request body (gateway hints, controller selectors, etc.). A `tool_choice` here acts as an endpoint default rather than an override: it applies only on a turn that offers tools and resolved no directive of its own, so forced-tool directives are preserved and deliberate no-tools turns are left untouched.\n\nReasoning / thinking:\n\n- `supportsReasoningEffort` — accept OpenAI-style `reasoning_effort`. Default: auto for bundled/audited providers and recognized first-party endpoints; `false` for unknown custom endpoints. Set `true` only from provider documentation or probe evidence, and pair it with explicit `reasoning: true` plus `thinking` metadata.\n- `reasoningEffortMap` — partial map from internal effort levels (`minimal|low|medium|high|xhigh`) to provider-specific strings (e.g. DeepSeek maps `xhigh -> \"max\"`).\n- `thinkingFormat` — request shape for thinking: `\"openai\"` (`reasoning_effort`), `\"openrouter\"` (`reasoning: { effort }`), `\"zai\"` (`thinking: { type: \"enabled\" }`), `\"qwen\"` (top-level `enable_thinking`), or `\"qwen-chat-template\"` (`chat_template_kwargs.enable_thinking`). Default: `\"openai\"`.\n- `reasoningContentField` — assistant field carrying chain-of-thought: `\"reasoning_content\"`, `\"reasoning\"`, or `\"reasoning_text\"`. Default: auto.\n- `requiresReasoningContentForToolCalls` — assistant tool-call turns must round-trip the reasoning field (DeepSeek-R1, Kimi, OpenRouter when reasoning is on). Default: `false`.\n- `requiresAssistantContentForToolCalls` — assistant tool-call turns must include non-empty text content (Kimi). Default: `false`.\n\nTool / message normalization:\n\n- `requiresToolResultName` — tool-result messages need a `name` field (Mistral). Default: auto.\n- `requiresAssistantAfterToolResult` — a user message after a tool result needs an assistant turn in between. Default: auto.\n- `requiresThinkingAsText` — convert thinking blocks to text wrapped in `<thinking>` delimiters (Mistral). Default: auto.\n- `requiresMistralToolIds` — normalize tool-call ids to exactly 9 alphanumeric chars. Default: auto.\n- `supportsStrictMode` — accept the per-tool `strict` field on tool schemas. Default: conservative auto-detect per provider/baseUrl.\n- `toolStrictMode` — `\"all_strict\"` forces strict on every tool, `\"none\"` forces it off; unset keeps the existing per-tool mixed behavior.\n\nGateway routing (only applied when `baseUrl` matches the gateway):\n\n- `openRouterRouting.only` / `openRouterRouting.order` — provider routing on `openrouter.ai` (see <https://openrouter.ai/docs/provider-routing>).\n- `vercelGatewayRouting.only` / `vercelGatewayRouting.order` — provider routing on `ai-gateway.vercel.sh` (see <https://vercel.com/docs/ai-gateway/models-and-providers/provider-options>).\n\nProvider-level `compat` is the baseline; per-model `compat` is deep-merged on top, with `openRouterRouting`, `vercelGatewayRouting`, and `extraBody` merged as nested objects.\n\n### Anthropic compatibility (`anthropic-messages`)\n\nFor `anthropic-messages` models, `compat.promptCacheMode` and `compat.supportsLongCacheRetention` are configurable at provider, model, and `modelOverrides` levels. Provider-level `compat` is the baseline; model and override values merge on top.\n\nPrompt-cache modes:\n\n- `automatic` — emit one top-level `cache_control` marker and let the Anthropic-compatible endpoint advance the breakpoint as the conversation grows.\n- `explicit` — emit block-level breakpoints instead. Use this for endpoints that reject top-level `cache_control` but support Anthropic's explicit content-block markers.\n- `none` — emit no generated Anthropic cache controls. Per-request or configured `cacheRetention: none` also disables generated caching.\n\nWithout an explicit mode, canonical Anthropic endpoints default to `automatic`, Claude-family model ids on non-canonical compatible endpoints default to `explicit`, and unknown non-Claude compatible endpoints default to `none`. Non-canonical endpoints get the default ~5m lifetime unless they opt into `supportsLongCacheRetention: true`. When `long` retention is requested (the default) against a compatible endpoint that leaves `supportsLongCacheRetention` unset, GJC omits `ttl` and logs a warning once per provider session naming the provider and model; set the flag to `true` for gateways that forward `ttl: \"1h\"` (idle gaps of 5-60 minutes then keep hitting the cache instead of rewriting the whole prefix), or to `false` to acknowledge the ~5m lifetime and silence the warning. Set `promptCacheMode: automatic` only when a gateway is known to pass through Anthropic's top-level cache control without adding conflicting block markers.\n\nIf a gateway attaches enough cache markers of its own that ours push the request past Anthropic's four-breakpoint limit, Anthropic rejects it with `A maximum of 4 blocks with cache_control may be provided.` Those extra markers are not visible in the request GJC builds, so the limit is handled at runtime rather than predicted. Because the rejection means \"too many\" rather than \"none allowed\", recovery reduces the generated breakpoints one step at a time: `explicit` mode normally emits two markers (a conversation-prefix anchor and a current-turn refresh point), so the first retry keeps only the prefix anchor, and generated caching is disabled entirely only if that is rejected too. The reduced setting persists for the rest of the provider session, so an endpoint with one free slot keeps caching its conversation prefix instead of losing caching altogether. Set `promptCacheMode: none` on a gateway that never has a free slot to skip the wasted attempts.\n\n```yaml\nproviders:\n  corp-anthropic:\n    baseUrl: https://proxy.example.com/anthropic\n    apiKeyEnv: CORP_ANTHROPIC_API_KEY\n    api: anthropic-messages\n    compat:\n      promptCacheMode: explicit\n      supportsLongCacheRetention: false\n    models:\n      - id: claude-sonnet-4-5\n        contextWindow: 200000\n        maxTokens: 8192\n```\n\nOther Anthropic-side compatibility knobs such as `disableAdaptiveThinking` and `supportsEagerToolInputStreaming` remain built-in catalog metadata rather than `models.yml` fields. `disableStrictTools` stays a provider-level setting (below).\n\n### Strict tool schemas (`disableStrictTools`)\n\nAnthropic's API supports a `strict` field on tool definitions that forces the model to always follow the provided schema exactly. This is enabled by default for all `anthropic-messages` providers because it guarantees schema conformance in agentic systems.\n\nThird-party providers that front the Anthropic API (AWS Bedrock, Azure, self-hosted proxies) do not always implement this field and will reject requests that include it. Set `disableStrictTools: true` at the provider level to opt out:\n\n```yaml\nproviders:\n  bedrock-anthropic:\n    baseUrl: https://bedrock-runtime.us-east-1.amazonaws.com/anthropic\n    apiKey: AWS_BEARER_TOKEN\n    api: anthropic-messages\n    disableStrictTools: true\n    models:\n      - id: anthropic-model-sonnet-4-20250514\n        name: Anthropic model Sonnet 4 (Bedrock)\n        input: [text, image]\n        contextWindow: 200000\n        maxTokens: 16384\n        cost:\n          input: 3.00\n          output: 15.00\n          cacheRead: 0.30\n          cacheWrite: 3.75\n```\n\n`disableStrictTools` is a provider-level flag that applies to all models in the provider.\n\nTool schemas going on the wire are normalized by the unified flow in\n`packages/ai/src/utils/schema/normalize.ts` (Google/CCA/MCP dispatchers\nplus the OpenAI strict-mode sanitize+enforce pipeline). See\n[`ai-schema-normalize.md`](./ai-schema-normalize.md) for the strict-mode\nedge cases (local `$ref` inlining, single-item `allOf` collapse,\n`anyOf`-wrapper description hoist, enum/const primitive-type inference)\nand the per-provider dispatcher mapping.\n## Practical examples\n\n### Local OpenAI-compatible endpoint (no auth)\n\n```yaml\nproviders:\n  local-openai:\n    baseUrl: http://127.0.0.1:8000/v1\n    auth: none\n    api: openai-completions\n    models:\n      - id: Qwen/Qwen2.5-Coder-32B-Instruct\n        name: Qwen 2.5 Coder 32B (local)\n```\n\n### Hosted proxy with env-based key\n\n```yaml\nproviders:\n  anthropic-proxy:\n    baseUrl: https://proxy.example.com/anthropic\n    apiKey: ANTHROPIC_PROXY_API_KEY\n    api: anthropic-messages\n    authHeader: true\n    disableStrictTools: true  # if the proxy doesn't support strict tool schemas\n    models:\n      - id: anthropic-model-sonnet-4-20250514\n        name: Anthropic model Sonnet 4 (Proxy)\n        reasoning: true\n        input: [text, image]\n```\n\n### Override built-in provider route + model metadata\n\n```yaml\nproviders:\n  openrouter:\n    baseUrl: https://my-proxy.example.com/v1\n    headers:\n      X-Team: platform\n    modelOverrides:\n      anthropic/anthropic-model-sonnet-4:\n        name: Sonnet 4 (Corp)\n        compat:\n          openRouterRouting:\n            only: [anthropic]\n```\n\n## Legacy consumer caveat\n\nMost model configuration now flows through `models.yml` via `ModelRegistry`. Explicit `.json` / `.jsonc` paths remain supported only when passed programmatically to `ModelRegistry`; the default user config is `~/.gjc/agent/models.yml`.\n\n## Failure mode\n\nIf `models.yml` fails schema or validation checks:\n\n- registry keeps operating with built-in models\n- error is exposed via `ModelRegistry.getError()` and surfaced in UI/notifications\n",
 	"multi-vendor-profiles.md": "# Choosing models in GJC: role-based profiles\n\nA practical guide to picking models for GJC's roles, for every subscription situation — one vendor, two vendors, or the full multi-vendor set. It adds curated cross-vendor `profiles:` for `~/.gjc/agent/models.yml` and verified selector notes on top of the mechanism in [Model profiles](./models.md#model-profiles---mpreset). Everything here is **user config**; it complements the built-in `--mpreset` presets and overrides a built-in only when it shares its exact name.\n\n> Selectors, prices, and \"axis leaders\" are catalog- and time-sensitive (selectors and prices observed 2026-07 on the current bundled catalog; the measured latency and single-message-limit notes below were observed 2026-06 on `claude-opus-4-8` and have not been re-measured on `claude-opus-5`). Re-verify any selector with `gjc -p --no-session --no-tools --model <selector> \"Reply OK\"`.\n\n## The five roles\n\n`default` runs the main loop and most turns; `executor` / `architect` / `planner` / `critic` are the four bundled task agents, delegated only when the work calls for it.\n\n| Role | What it optimizes for |\n| --- | --- |\n| `default` | tool-calling reliability + honesty (it routes — its quality bounds the whole system) |\n| `executor` | real coding (SWE-bench Verified) |\n| `planner` | reasoning + sequencing (GPQA / ARC-AGI-2) |\n| `architect` | large-context + multimodal review |\n| `critic` | independent adversarial review (different family from what it reviews) |\n\n## Pick by what you subscribe to\n\n| You have | Use |\n| --- | --- |\n| **One vendor** | the built-in preset for that vendor — `claude-opus` (Anthropic), `codex-{eco,medium,pro}` (OpenAI/Codex), `opencodego` (OpenCode Go), or a single-vendor flagship tier (`zai/glm-5.2`, `kimi-code/...`, `xiaomi/...`, `xai/grok-4.3`, `minimax-code/...`). These already map all five roles inside one vendor. |\n| **Claude + Codex** | the built-in `opus-codex` (Claude main loop + Codex support roles). |\n| **Three or more / all five** | the cross-vendor profiles below — each role on its axis leader, `critic` kept cross-family. |\n\nThe single guiding rule across all of these: **keep `default` on the strongest router you have** (Anthropic Opus when available). A weak `default` caps quality regardless of the delegated models.\n\n## Cross-vendor profiles (3+ vendors)\n\nNo single vendor leads every axis, so these put each role on its axis leader and keep `critic` on a different family from the `executor` it reviews.\n\n```yaml\nprofiles:\n\n  daily:                 # everyday balance\n    required_providers: [anthropic, openai-codex, google-antigravity, xai]\n    model_mapping:\n      default:   anthropic/claude-opus-5:medium\n      executor:  openai-codex/gpt-5.4:high\n      planner:   google-antigravity/gemini-3.1-pro-low:high\n      architect: google-antigravity/gemini-3.1-pro-low:high\n      critic:    xai/grok-4.3:medium\n\n  ultimate:              # cost-no-object, best per role\n    required_providers: [anthropic, openai-codex, google-antigravity, xai]\n    model_mapping:\n      default:   anthropic/claude-opus-5:high\n      executor:  anthropic/claude-opus-5:max\n      planner:   openai-codex/gpt-5.5:xhigh\n      architect: google-antigravity/gemini-3.1-pro-low:high\n      critic:    xai/grok-4.3:high\n\n  eco:                   # cheapest delegated work; main loop stays on Opus\n    required_providers: [anthropic, opencode-go, google-antigravity, xai]\n    model_mapping:\n      default:   anthropic/claude-opus-5:low\n      executor:  opencode-go/deepseek-v4-flash\n      planner:   xai/grok-4-1-fast:high\n      architect: google-antigravity/gemini-3.1-pro-low\n      critic:    google-antigravity/gemini-3.5-flash\n\n  monorepo:              # huge codebases (openai-codex excluded: 372k context cap)\n    required_providers: [anthropic, google-antigravity, opencode-go]\n    model_mapping:\n      default:   anthropic/claude-opus-5:medium\n      executor:  anthropic/claude-opus-5:high\n      planner:   google-antigravity/gemini-3.1-pro-low:high\n      architect: anthropic/claude-opus-5:high\n      critic:    opencode-go/glm-5.2\n\n  reviewer:              # review/audit stance — the author-mode role split, inverted\n    required_providers: [anthropic, openai-codex, google-antigravity]\n    model_mapping:\n      default:   anthropic/claude-opus-5:high                 # aggregator restraint: preserve raw reviewer verdicts\n      executor:  openai-codex/gpt-5.5:high                      # support — repro PoCs, failing tests, harnesses\n      planner:   google-antigravity/gemini-3.1-pro-low:high     # review checklists / audit scoping\n      architect: anthropic/claude-opus-5:high                 # lead 1 — primary code-review judge (effective long-context)\n      critic:    openai-codex/gpt-5.5:high                      # lead 2 — merge gate, cross-family vs Claude-authored code\n```\n\n## Reviewer stance and the external review gate\n\nThe profiles above assume an **authoring** stance: `executor` is the lead and `architect`/`critic` verify its work. In a session whose primary job is reviewing or auditing (not writing) code, the roles invert — `architect`/`critic` become the leads and `executor` is support (reproduction PoCs, failing tests). The `reviewer` profile encodes that inversion, with one generalized provenance rule: **the reviewing model family must differ from the family that authored the code under review**, not merely from the session's own executor.\n\nA verified use is the cross-session final review gate: the authoring session launches a fresh, stateless reviewer sub-session so the finished diff is judged without the authoring context:\n\n```sh\n# the one-shot gate needs only a cross-family --model; add --mpreset reviewer as an\n# optional enhancement AFTER installing this profile in ~/.gjc/agent/models.yml:\ngjc -p --no-session --model openai-codex/gpt-5.5:xhigh --tools read,search,find \"<review prompt: diff + spec paths, severity findings, final line VERDICT: APPROVE|REQUEST_CHANGES>\"\n```\n\nThe `--tools` allowlist is part of the contract: it enforces the reviewer's read-only boundary for the built-in tool surface instead of trusting the prompt (the runtime still injects the session `goal` tool unless `goal.enabled` is off — disabling it for the reviewer invocation is **mandatory**, via a dedicated gate directory outside the repo so the reviewed checkout stays clean, see the template — plus `generate_image` when an image credential exists). In this one-shot form the session's `default` model authors the verdict — a tool-restricted print session cannot delegate to the profile's `critic`/`architect` roles — so the explicit cross-family `--model` carries provenance, and the `reviewer` profile itself serves the interactive review-session case (activate it with `--mpreset reviewer` only after copying it into `models.yml`; otherwise activation fails with an unknown-profile error). Profile names in this document live in the user namespace — a user profile overrides a builtin preset only on an exact name match, and a future builtin with the same name would be silently shadowed by your copy.\n\nSee [Extragoal local skill template](./extragoal-skill-template.md) for the full gate workflow (verdict contract, findings triage, bounded re-sign loop, secret-scan and injection guards) built on this recipe.\n\n## Model cheatsheet (by need)\n\nCurrent axis leaders and the cheaper second option, with metered price ($/1M in/out; Gemini via Antigravity runs on the Google AI subscription):\n\n| Need | First pick | Cheaper option |\n| --- | --- | --- |\n| Router / tool-calling (`default`) | `anthropic/claude-opus-5` (5/25) | `anthropic/claude-sonnet-5` (3/15) |\n| Coding (`executor`) | `anthropic/claude-opus-5` (5/25) — the prior `claude-opus-4-8` scored SWE-bench Verified ~88.6; no Opus 5 measurement yet | `openai-codex/gpt-5.4` (2.5/15) · `opencode-go/deepseek-v4-flash` (0.14/0.28) |\n| Reasoning (`planner`) | `openai-codex/gpt-5.5` (ARC-AGI-2) / `google-antigravity/gemini-3.1-pro-low:high` (GPQA) | `xai/grok-4-1-fast` (0.2/0.5) |\n| Large context (`architect`) | `anthropic/claude-opus-5` (effective long-context) | `xai/grok-4-fast` (2M nominal, 0.2/0.5) |\n| Multimodal review (`architect`) | `google-antigravity/gemini-3.1-pro-low:high` | `google-antigravity/gemini-3.5-flash` |\n| Independent critic | `xai/grok-4.3` (1.25/2.5) | `opencode-go/glm-5.2` · `google-antigravity/gemini-3.5-flash` |\n\nOn standard tasks, all current frontier models in the catalog are accurate; **pick by cost, latency, and role fit, not by raw accuracy on easy prompts.** As an indicative GJC-routed latency reference (`gjc -p`, identical coding + reasoning prompts, all correct): `grok-4.3` and `glm-5.2` ≈ 2–3s, `deepseek-v4-pro` ≈ 3–4s, `claude-opus-4-8` / `gpt-5.5` ≈ 4–7s, `gemini-3.1-pro-low:high` ≈ 7s. `claude-opus-5` shares Opus 4.8's published context/output envelope but has not been latency-measured here.\n\n## Verified selector notes (current catalog)\n\nObserved via live `gjc -p` calls; useful when wiring the profiles above:\n\n- **Antigravity Gemini, high reasoning** → use `google-antigravity/gemini-3.1-pro-low:high`. The id `gemini-3.1-pro-high` returns HTTP 400 (no matching backend model); `thinkingLevel` is a per-request parameter, so raising it on `gemini-3.1-pro-low` invokes the model's native high-reasoning mode rather than a degraded one.\n- **openai-codex on a ChatGPT account** uses provider-authoritative model availability. GJC does not infer eligibility from ChatGPT account or plan labels and does not pre-reject selected models such as GPT-5.6 Sol; the Codex backend accepts or rejects the request, and its response is surfaced through the ordinary provider error path. Model access can vary by account and backend rollout, so treat live provider responses as authoritative.\n- **Single-message input limit is separate from the context window.** Measured on `claude-opus-4-8` (not yet re-measured on `claude-opus-5`, which publishes the same 1M window): the model runs with a 1M window via multi-turn accumulation, but a single `@file` message above ~400k tokens returns 400 on `anthropic` / `google-antigravity`; `xai` / `opencode-go` accept larger single messages. Chunk very large inputs across turns instead of pasting one block.\n- **Some selectors come from a provider's live catalog, not the bundled snapshot.** `opencode-go/glm-5.2` and `google-antigravity/gemini-3.5-flash` resolved in `gjc -p` tests but are **not** in `packages/ai/src/models.json`; they appear only after the provider's online model discovery has populated the registry. `required_providers` verifies credentials at activation — it does **not** guarantee fresh, non-stale discovery — so activation can still fail with `selector did not resolve` until discovery runs (re-login or retry to refresh). If you hit that, substitute a bundled id: `opencode-go/deepseek-v4-pro` for the critic, or `zai/glm-5.2` (add `zai` to `required_providers`) for GLM 5.2.\n\n## Activation\n\n```bash\ngjc --mpreset daily               # this session only\ngjc --mpreset ultimate --default  # persist as the startup default (config.yml)\n```\n\n### Delegation is what makes vendor separation pay off\n\nWorker roles only consume the other vendor's quota when the main agent actually delegates, and the strong \"delegate by default\" directive is gated behind `task.eager`. When `executor` or `planner` is pinned to a provider other than the `default` role's provider, GJC therefore turns eager delegation on for that session unless `task.eager` is set explicitly in config. Setting `task.eager false` by hand stays authoritative and keeps the separated workers idle — `gjc config doctor` reports that combination as an advisory.\n\nActivation hard-blocks when any provider in `required_providers` lacks credentials, so log in first: `/login anthropic`, `/login openai-codex`, `/login google-antigravity`, `/login xai` (and `opencode-go` via `OPENCODE_API_KEY`).\n\n### Serving cross-vendor profiles through one OpenAI-compatible proxy\n\nWhen a single gateway (LiteLLM, OpenRouter, or a custom proxy) fronts several vendors, you do not need to configure every `required_providers` entry directly. Add the gateway as a provider — `gjc setup provider --preset litellm --base-url <url>` or `gjc setup provider --preset openai-compatible-proxy --base-url <url>` — and point `modelProfile.proxyProvider` at it in `config.yml`:\n\n```yaml\nmodelProfile:\n  proxyProvider: litellm\n  proxyMode: always # route all supported built-in preset selectors through the gateway\n```\n\n`proxyMode: fallback` is the default and uses the gateway only when the direct provider is unauthenticated. Set `proxyMode: always` when the gateway must be the single audit, quota, or spend-control surface: it routes all proxy-routable **built-in** preset selectors through the proxy even when direct credentials exist. The configured proxy must be authenticated and expose every routed model; activation fails closed for missing or ambiguous models. User-defined profiles are never rewritten — set their selectors to `litellm/…` explicitly if you want them proxied. Routing and fail-closed behavior are documented in [Routing built-in presets through a proxy](./models.md#routing-built-in-presets-through-a-proxy-modelprofileproxyprovider).\n",
 	"native-ffi-optimization-policy.md": "# ADR: Native FFI Optimization Policy\n\n- Status: Accepted\n- Scope: `crates/pi-natives` algorithmic ports proposed for performance reasons\n- Related: [`porting-to-natives.md`](./porting-to-natives.md), [`natives-architecture.md`](./natives-architecture.md), [`natives-binding-contract.md`](./natives-binding-contract.md), [`cpu-hotspot-map.json`](./cpu-hotspot-map.json), [`hotspot-map-successor.md`](./hotspot-map-successor.md)\n\n## Decision\n\nA new native (Rust N-API / FFI) port proposed **to optimize a leftover hot path** does not land unless **all** of the following gates pass:\n\n1. **Corpus evidence** — a profiling-corpus trace shows the path has user-visible latency or RSS impact on a representative workload (not just a static complexity argument).\n2. **Self-time attribution** — a `profilerSelfTime` artifact identifies the proposed hotspot, **or** fallback-toggle evidence proves an end-to-end benefit without byte changes. Wall-clock proxy timing alone is never sufficient.\n3. **Measured FFI overhead** — the N-API call/marshalling overhead is measured against the JS/TS baseline, not assumed away.\n4. **Representative win** — a representative p50/p95 win exists on realistic inputs, not only microbenchmark seed results.\n5. **Byte parity** — a byte-identical corpus covers rendered, persisted, and provider-visible bytes for the changed path.\n6. **Operational cost** — fallback, packaging, and rollback costs are documented.\n\nThis policy governs **speculative algorithmic ports**. It does **not** re-litigate already-native platform/system surfaces (see [Scope boundary](#scope-boundary)).\n\n## Context\n\nThe CPU/memory hotspot program (Optimization Suites v1–v3, tracked in [`cpu-hotspot-map.json`](./cpu-hotspot-map.json)) is closed out. Its prioritization was a **static structural ranking** (algorithmic complexity × trigger frequency), and the map's own `method` field records that real CPU self-time was \"to be measured by the agreed profiling corpus during optimization.\" That corpus is being built separately; until its evidence exists, new native ports for leftover hotspots would repeat the same evidence gap.\n\nThe suites already produced concrete decisions that this policy codifies so they are not re-discovered:\n\n- **v2 (#530)** measured and **rejected the five remaining Rust port candidates** per the FFI cost gates after shipping only `diffLines` (H03) natively. Native overhead did not beat the JS/TS baseline for those candidates on realistic inputs.\n- **v3 (#558) rejected a native word-diff (H04)** \"without a fresh FFI gate\" — the TS fast paths were retained instead; a native port would need to re-clear gates 1–6 above.\n- **Hunt-Szymanski LCS (H05)** was implemented as a native/algorithmic replacement, then **reverted** because it produced byte-different rendered diffs (reproduced by red-team). Byte parity is the gate, not raw speed.\n- **The custom JSON length counter (H08)** was implemented, made exact, then **deleted** — an exact JS reimplementation was not faster than native `JSON.stringify`. \"More native\" is not automatically \"faster.\"\n\nThese four precedents share a root cause: a plausible algorithmic/native win that failed a real gate (cost, byte parity, or end-to-end benefit). The policy makes those gates a precondition rather than a post-hoc discovery.\n\n## Evidence taxonomy\n\nNative-port claims must classify their evidence using the same separated classes as the profiling corpus. These classes must never be conflated:\n\n- **`wallClockPhase`** — elapsed timing around a phase or operation. Useful for perceived-latency and regression detection; **insufficient** to confirm CPU self-time or to justify a port on its own.\n- **`processCpuUsage`** — `process.cpuUsage()` user/system deltas, optionally normalized by elapsed time. Indicates process-level CPU pressure; **cannot** attribute self-time to a specific hotspot.\n- **`profilerSelfTime`** — profiler (or equivalent sampled/trace) attribution of self-time to a function, module, or native symbol. **Required** before a hotspot may be called \"CPU-self-time confirmed.\"\n\nA native-optimization proposal that cites only `wallClockPhase` or `processCpuUsage` is **not** CPU-self-time confirmed and does not clear gate 2.\n\n## Approval checklist\n\nBefore opening a native-optimization PR, confirm and attach evidence for each:\n\n- [ ] Corpus trace shows user-visible latency or RSS impact for the path (gate 1).\n- [ ] `profilerSelfTime` artifact identifies the hotspot, **or** fallback-toggle before/after evidence proves end-to-end benefit without byte changes (gate 2).\n- [ ] FFI/marshalling overhead measured vs the JS/TS baseline in the same benchmark run (gate 3).\n- [ ] Representative p50/p95 win on realistic inputs, not only seeded microbench results (gate 4).\n- [ ] Byte-identical corpus covers rendered, persisted, and provider-visible bytes (gate 5).\n- [ ] Fallback, packaging (platform variants / embedded addon), and rollback costs documented (gate 6).\n\nIf any box is unchecked, keep the work in TypeScript or hold it as a tracked candidate; do not switch callsites. This mirrors the existing **Rule of thumb** in [`porting-to-natives.md`](./porting-to-natives.md): if native is not faster *and* behavior-compatible, do not switch callsites.\n\n## Scope boundary\n\nThis policy targets **speculative algorithmic ports**, not the established native surface. The following are **already native** by design and are explicitly out of scope (see `alreadyNativeExcluded` in [`cpu-hotspot-map.json`](./cpu-hotspot-map.json)):\n\n`grep`, `fd`/`glob`, text width/wrap/truncate/slice, syntax highlighting, HTML→Markdown, AST, summary, process/PTY/shell, SIXEL, clipboard, `Bun.hash.xxHash32/64`, and `JSON.parse`/`JSON.stringify`.\n\nThese are native because they are I/O, OS/process integration, or platform primitives — the criteria in [`porting-to-natives.md`](./porting-to-natives.md#when-to-port). Distinguishing them from algorithmic ports matters: a leftover algorithmic hotspot must clear gates 1–6, whereas adding a new OS/process/native-primitive binding follows the standard porting guide.\n\n## Consequences\n\n- New native algorithmic ports require profiling-corpus evidence and a measured cost gate before review; this slows speculative optimization but prevents byte-parity regressions and dead native code.\n- The default answer for a leftover hotspot is \"keep it in TypeScript\" until the corpus proves it matters.\n- Already-native platform/system primitives and new OS/process bindings are unaffected; they follow [`porting-to-natives.md`](./porting-to-natives.md) as before.\n- Reviewers can reject a native-optimization PR purely on a missing gate, citing this ADR, without re-deriving the rationale.\n\n## Follow-ups\n\n- Held native candidates (H04 word-diff, H05 LCS, and other v2-rejected candidates) stay held unless a future PR clears gates 1–6 with fresh corpus evidence.\n- When the profiling corpus lands, link its threshold/evidence ledger here so native-port proposals can cite concrete corpus artifacts.\n",
 	"natives-addon-loader-runtime.md": "# Natives Addon Loader Runtime\n\nThis document covers the runtime loader shipped by `@gajae-code/natives`: how `native/index.js` decides which `.node` file to require, how compiled-binary embedded payloads are extracted, and what startup failures report.\n\n## Implementation files\n\n- `packages/natives/native/index.js`\n- `packages/natives/native/loader-state.js`\n- `packages/natives/native/embedded-addon.js`\n- `packages/natives/scripts/embed-native.ts`\n- `packages/natives/package.json`\n\n## Scope and responsibility\n\nThe loader is intentionally narrow:\n\n- Build a platform/CPU-aware candidate list for addon filenames and directories.\n- Treat an embedded-addon manifest as the authoritative compiled-binary signal when present.\n- Optionally materialize an embedded addon into a versioned per-user cache directory.\n- Attempt candidates in deterministic order and return the first addon that `require(...)` loads.\n\nThe current loader does **not** run a separate `validateNative(...)` export-presence gate. API shape is provided by the generated N-API binding file (`native/index.d.ts`) and the loaded addon itself. A stale binary therefore normally fails as a missing property or native load error rather than as a custom \"missing exports\" validation error.\n\n## Runtime inputs and derived state\n\nAt module initialization, `native/index.js` computes:\n\n- **Platform tag**: `${process.platform}-${process.arch}` (for example `darwin-arm64`).\n- **Package version**: from `packages/natives/package.json`.\n- **Core directories**:\n  - `nativeDir`: package-local `packages/natives/native`.\n  - `execDir`: directory containing `process.execPath`.\n  - `versionedDir`: `<getNativesDir()>/<packageVersion>`.\n  - `userDataDir` fallback:\n    - Windows: `%LOCALAPPDATA%/gjc` or `%USERPROFILE%/AppData/Local/gjc`.\n    - Non-Windows: `~/.local/bin`.\n- **Natives cache root** (`getNativesDir()`):\n  - if `$XDG_DATA_HOME/gjc` exists, `$XDG_DATA_HOME/gjc/natives`;\n  - otherwise `~/.gjc/natives`.\n- **Compiled-binary mode** (`detectCompiledBinary`): true if any of:\n  - embedded-addon manifest is non-null,\n  - `GJC_COMPILED` env var is set,\n  - `import.meta.url` contains Bun embedded markers (`$bunfs`, `~BUN`, `%7EBUN`).\n- **Variant override**: `GJC_NATIVE_VARIANT` (`modern`/`baseline` only; invalid values ignored).\n- **Selected variant**: explicit override, otherwise runtime AVX2 detection on x64 (`modern` if AVX2, else `baseline`).\n\n## Platform support and tag resolution\n\n`SUPPORTED_PLATFORMS` is fixed to:\n\n- `linux-x64`\n- `linux-arm64`\n- `darwin-arm64`\n- `win32-x64`\n\nUnsupported platforms are not rejected before probing. The loader first tries the computed candidate paths. If all fail and `platformTag` is unsupported, it throws an unsupported-platform error listing supported tags.\n\n## Variant selection (`modern` / `baseline` / default)\n\n### x64 behavior\n\n1. `GJC_NATIVE_VARIANT=modern|baseline` wins when valid.\n2. Otherwise AVX2 support is detected:\n   - Linux: scan `/proc/cpuinfo` for `avx2`.\n   - macOS: `sysctl -n machdep.cpu.leaf7_features`, then `machdep.cpu.features`.\n   - Windows: PowerShell `[System.Runtime.Intrinsics.X86.Avx2]::IsSupported`.\n3. AVX2 selects `modern`; unavailable or undetectable AVX2 selects `baseline`.\n\n### Non-x64 behavior\n\nNo variant suffix is used; the filename is `pi_natives.<platform>-<arch>.node`.\n\n### Filename construction\n\n`loader-state.js#getAddonFilenames` returns:\n\n- Non-x64 or no variant: `pi_natives.<tag>.node`\n- x64 + `modern`:\n  1. `pi_natives.<tag>-modern.node`\n  2. `pi_natives.<tag>-baseline.node`\n  3. `pi_natives.<tag>.node`\n- x64 + `baseline`:\n  1. `pi_natives.<tag>-baseline.node`\n  2. `pi_natives.<tag>.node`\n\nThe default unsuffixed fallback remains part of the x64 candidate list.\n\n## Candidate path construction and fallback ordering\n\n`resolveLoaderCandidates(...)` expands every filename across directories, then de-duplicates while preserving first occurrence order.\n\n### Non-compiled runtime\n\nFor each filename, candidates are:\n\n1. `<nativeDir>/<filename>`\n2. `<execDir>/<filename>`\n\n### Compiled runtime\n\nFor each filename, candidates are:\n\n1. `<versionedDir>/<filename>`\n2. `<userDataDir>/<filename>`\n3. `<nativeDir>/<filename>`\n4. `<execDir>/<filename>`\n\nAt load time, an extracted embedded candidate, when produced, is prepended ahead of these de-duplicated candidates.\n\n## Embedded addon extraction lifecycle\n\n`embedded-addon.js` is generated by `scripts/embed-native.ts`. The reset stub exports `embeddedAddon = null`. A populated manifest has:\n\n- `platformTag`\n- `version`\n- `files[]` entries with `variant`, `filename`, and `filePath`\n\nExtraction (`maybeExtractEmbeddedAddon`) runs only when:\n\n1. compiled-binary mode is true,\n2. `embeddedAddon` is non-null,\n3. manifest `platformTag` equals the runtime platform tag,\n4. manifest `version` equals the package version,\n5. a variant-appropriate embedded file exists.\n\nVariant file selection:\n\n- Non-x64: prefer `default`, then first available file.\n- x64 + `modern`: prefer `modern`, fallback to `baseline`.\n- x64 + `baseline`: require `baseline`.\n\nMaterialization:\n\n1. Ensure `<versionedDir>` exists.\n2. Reuse `<versionedDir>/<selected filename>` if it already exists.\n3. Otherwise read `selectedEmbeddedFile.filePath` and write the target path.\n4. Return the target path as the first candidate.\n\nDirectory creation or write failures are appended to the loader error list; probing continues through normal candidates.\n\n## Lifecycle and state transitions\n\n```text\nInit\n  -> Load package metadata and embedded-addon manifest\n  -> Compute platform/version/variant/filenames/candidate paths\n  -> (compiled + embedded manifest matches?)\n       yes -> try extract to versionedDir (record errors, continue)\n       no  -> skip extraction\n  -> For each runtime candidate in order:\n       require(candidate)\n       -> success: return addon exports (READY)\n       -> failure: record error, continue\n  -> none loaded:\n       if unsupported platform tag -> throw Unsupported platform\n       else -> throw Failed to load (tried-path diagnostics + hints)\n```\n\n## Failure behavior and diagnostics\n\n### Unsupported platform\n\nIf all candidates fail and `platformTag` is not supported, the loader throws:\n\n- `Unsupported platform: <tag>`\n- supported platform list\n- issue-reporting guidance\n\n### No loadable candidate\n\nIf the platform is supported but no candidate can be loaded, the final error includes:\n\n- `Failed to load pi_natives native addon for <platformTag>` or `<platformTag> (<variant>)`\n- every attempted path with the corresponding `require(...)` error\n- mode-specific remediation hints\n\n### Compiled-binary startup failures\n\nCompiled mode diagnostics include:\n\n- expected versioned cache target paths (`<versionedDir>/<filename>`),\n- remediation to delete the versioned cache and rerun,\n- direct release download `curl` commands for each expected filename.\n\n### Non-compiled startup failures\n\nNormal package/runtime diagnostics include:\n\n- reinstall hint (`bun install @gajae-code/natives`),\n- local rebuild command (`bun --cwd=packages/natives run build`),\n- worktree-safe setup hint when the loader runs from a workspace checkout (`bun run setup:worktree`),\n- optional x64 variant build hint (`TARGET_VARIANT=baseline|modern bun --cwd=packages/natives run build`).\n",
@@ -67,10 +67,10 @@ export const EMBEDDED_DOCS: Readonly<Record<string, string>> = {
 	"natives-build-release-debugging.md": "# Natives Build, Release, and Debugging Runbook\n\nThis runbook describes how `@gajae-code/natives` produces `.node` addons, generated declarations, and compiled-binary embedded payloads, and how to debug loader/build failures.\n\nIt follows the architecture terms from `docs/natives-architecture.md`:\n\n- **build-time artifact production** (`scripts/build-native.ts`)\n- **embedded addon manifest generation** (`scripts/embed-native.ts`)\n- **runtime addon loading** (`native/index.js`, `native/loader-state.js`)\n\n## Implementation files\n\n- `packages/natives/scripts/build-native.ts`\n- `packages/natives/scripts/embed-native.ts`\n- `packages/natives/scripts/gen-enums.ts`\n- `packages/natives/package.json`\n- `packages/natives/native/index.js`\n- `packages/natives/native/loader-state.js`\n- `crates/pi-natives/Cargo.toml`\n\n## Build pipeline overview\n\n### 1) Build entrypoints\n\n`packages/natives/package.json` scripts:\n\n- `bun scripts/build-native.ts` (`build`) → N-API build, addon install, generated declarations install, enum export patch.\n- `bun scripts/embed-native.ts` (`embed:native`) → generate `native/embedded-addon.js` from built files.\n\nRoot scripts include `build:native` as `bun --cwd=packages/natives run build`.\n\n### 2) N-API/Rust artifact build\n\n`build-native.ts` invokes the `@napi-rs/cli` binary directly from `node_modules/.bin` with:\n\n- `napi build`\n- `--manifest-path crates/pi-natives/Cargo.toml`\n- `--package-json-path packages/natives/package.json`\n- `--platform`\n- `--no-js`\n- `--dts index.d.ts`\n- `--profile local` for non-CI local native builds, otherwise `--profile ci`\n- optional `--target <CROSS_TARGET>`\n\n`crates/pi-natives/Cargo.toml` declares `crate-type = [\"cdylib\"]`; napi-rs emits `.node` artifacts plus generated `index.d.ts` in an isolated temporary output directory under `packages/natives/native/.build/`.\n\n### 3) Artifact install\n\nAfter napi-rs succeeds, `build-native.ts`:\n\n1. resolves the built addon in the isolated output directory;\n2. normalizes its name to `pi_natives.<platform>-<arch>(-variant).node` when needed;\n3. installs the addon into `packages/natives/native/` with temp-file + rename semantics;\n4. copies generated `index.js` and `index.d.ts` into `packages/natives/native/` when present;\n5. runs `generateEnumExports()` to append enum runtime objects to `native/index.js`.\n\nWindows locked-DLL replacement failures are reported with an explicit close-running-processes hint.\n\n## Target/variant model and naming conventions\n\n## Platform tag\n\nBoth build and runtime use platform tag:\n\n`<platform>-<arch>` (example: `darwin-arm64`, `linux-x64`).\n\n## Variant model (x64 only)\n\nx64 supports CPU variants:\n\n- `modern` (AVX2-capable path)\n- `baseline` (fallback)\n\nNon-x64 uses a single default artifact with no variant suffix.\n\n### Output filenames\n\n- x64: `pi_natives.<platform>-<arch>-modern.node` or `...-baseline.node`\n- non-x64: `pi_natives.<platform>-<arch>.node`\n\nRuntime x64 candidate order also includes the unsuffixed default filename after the selected variant candidates.\n\n## Environment flags and build options\n\n## Runtime flags\n\n- `GJC_NATIVE_VARIANT`: x64 runtime override; valid values are `modern` and `baseline`.\n- `GJC_COMPILED`: legacy compiled-mode signal. A populated embedded-addon manifest is also a compiled-mode signal and is the authoritative signal for Bun standalone builds that do not preserve `process.env.GJC_COMPILED`.\n\n## Build-time flags/options\n\n- `CROSS_TARGET`: passed to napi-rs as `--target <CROSS_TARGET>`.\n- `TARGET_PLATFORM`: override output platform tag naming.\n- `TARGET_ARCH`: override output arch naming.\n- `TARGET_VARIANT` (x64 only): force `modern` or `baseline` for output filename and RUSTFLAGS policy.\n- `CARGO_TARGET_DIR`: respected if set; otherwise the default `target/` dir is used so `Swatinem/rust-cache` can cache cleanly.\n- `RUSTFLAGS`:\n  - if unset and not cross-compiling, script sets:\n    - modern: `-C target-cpu=x86-64-v3`\n    - baseline: `-C target-cpu=x86-64-v2`\n    - non-x64 / no variant: `-C target-cpu=native`\n  - if already set, script does not override.\n\n## Build state/lifecycle transitions\n\n### Build lifecycle (`build-native.ts`)\n\n1. **Init**: parse env, resolve target tuple, cross/local mode, profile label.\n2. **Variant resolve**:\n   - non-x64 → no variant;\n   - x64 + `TARGET_VARIANT` → explicit variant;\n   - x64 cross-build without `TARGET_VARIANT` → hard error;\n   - x64 local build without override → detect host AVX2.\n3. **CPU policy**: set `RUSTFLAGS` for the resolved variant unless the caller already provided one.\n4. **Compile**: run napi-rs against `crates/pi-natives` into an isolated output directory.\n5. **Locate artifact**: accept the canonical filename or a single napi-rs-generated `pi_natives.<platform>-<arch>*.node` candidate.\n6. **Install**: copy/rename addon into `packages/natives/native`.\n7. **Install generated bindings**: copy `index.js`/`index.d.ts` if needed.\n8. **Patch enums**: append generated enum runtime exports.\n9. **Cleanup**: remove the temporary build output directory.\n\nFailure exits have explicit error text for invalid variants, failed napi build, missing/multiple output artifacts, generated binding install failure, and install/rename failure.\n\n### Embed lifecycle (`embed-native.ts`)\n\n1. **Init**: compute platform tag from `TARGET_PLATFORM`/`TARGET_ARCH` or host values.\n2. **Candidate set**:\n   - x64 looks for `modern` and `baseline` files;\n   - non-x64 looks for one default file.\n3. **Validate availability**: at least one expected file must exist in `packages/natives/native`.\n4. **Generate manifest** (`native/embedded-addon.js`) with Bun `file` imports and package version.\n5. **Runtime extraction ready** for compiled mode.\n\n`--reset` writes the null manifest stub (`embeddedAddon = null`) without validating addon availability.\n\n## Dev workflow vs shipped/compiled behavior\n\n## Local development workflow\n\nTypical local loop:\n\n1. Build addon: `bun --cwd=packages/natives run build`.\n2. Loader resolves package-local `native/` candidates, then executable-dir fallback candidates.\n3. Generated declarations in `native/index.d.ts` describe the public TS API.\n\n## Shipped/compiled binary workflow\n\nIn compiled mode (`GJC_COMPILED`, Bun embedded URL markers, or populated embedded manifest):\n\n1. Loader computes versioned cache dir: `<getNativesDir()>/<packageVersion>`.\n2. If embedded manifest matches current platform+version, loader may extract the selected embedded file into that versioned dir.\n3. Runtime candidate order includes:\n   - versioned cache dir,\n   - legacy compiled-binary dir (`%LOCALAPPDATA%/gjc` on Windows, `~/.local/bin` elsewhere),\n   - package/executable directories.\n4. First successfully loaded addon is returned.\n\nThis is why packaging + runtime loader expectations must align: filenames, platform tags, CPU variants, and embedded manifest version must match what `native/index.js` probes.\n\n## JS API ↔ Rust export mapping (build sanity subset)\n\nGenerated declarations currently include exports from these Rust modules:\n\n| Area                   | Representative JS exports                                                                         | Rust source                                                                             |\n| ---------------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |\n| Search                 | `grep`, `search`, `hasMatch`, `fuzzyFind`, `glob`, `invalidateFsScanCache`                        | `grep.rs`, `fd.rs`, `glob.rs`, `fs_cache.rs`                                            |\n| AST                    | `astGrep`, `astEdit`                                                                              | `ast.rs`                                                                                |\n| Text/highlight         | `visibleWidth`, `truncateToWidth`, `highlightCode`                                                | `text.rs`, `highlight.rs`                                                               |\n| Shell/PTY/process/keys | `executeShell`, `Shell`, `PtySession`, `killTree`, `parseKey`                                     | `shell.rs`, `pty.rs`, `ps.rs`, `keys.rs`                                                |\n| Media/system           | `encodeSixel`, clipboard, macOS appearance/power, `getWorkProfile`, iso overlay    | `sixel.rs`, `clipboard.rs`, `appearance.rs`, `power.rs`, `prof.rs`, `iso.rs`            |\n\n## Failure behavior and diagnostics\n\n## Build-time failures\n\n- Invalid variant configuration:\n  - `TARGET_VARIANT` set on non-x64 → immediate error.\n  - unsupported `TARGET_VARIANT` value → immediate error.\n  - x64 cross-build without explicit `TARGET_VARIANT` → immediate error.\n- napi-rs build failure: script surfaces non-zero exit and stderr.\n- Artifact not found or ambiguous: script prints expected/candidate filenames and output directory contents.\n- Install failure: explicit message; Windows includes locked-file hint.\n- Generated binding install failure: explicit source/destination message.\n\n## Runtime loader failures (`native/index.js`)\n\n- Unsupported platform tag: throws with supported platform list after probing fails.\n- No candidate could load: throws with full candidate error list and mode-specific remediation hints.\n- Embedded extraction problems: extraction mkdir/write errors are recorded and included in final diagnostics if load fails.\n\n## Troubleshooting matrix\n\n| Symptom                                                                | Likely cause                                                                                | Verify                                                            | Fix                                                                                           |\n| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |\n| `Cannot find module` or dynamic library load error for every candidate | Missing release artifact, wrong platform tag, or stale compiled cache                       | Inspect loader error list and `packages/natives/native` filenames | Build correct target/variant; delete stale cache for the package version                      |\n| Export is missing at runtime but present in TypeScript                 | Stale `.node` loaded, generated declarations newer than binary, or Rust export not compiled | Require the actual candidate and inspect `Object.keys(mod)`       | Rebuild native package and remove stale candidate/cache paths                                 |\n| x64 machine loads baseline when modern expected                        | `GJC_NATIVE_VARIANT=baseline`, no AVX2 detected, or modern file unavailable                  | Check env and filenames in `native/`                              | Build modern variant (`TARGET_VARIANT=modern ... build`) and ship it                          |\n| Cross-build produces wrong-labeled binary                              | Mismatch between `CROSS_TARGET` and `TARGET_PLATFORM`/`TARGET_ARCH`, or missing x64 variant | Confirm env tuple and output filename                             | Re-run with consistent env values and explicit x64 `TARGET_VARIANT`                           |\n| Compiled binary fails after upgrade                                    | Stale extracted cache or embedded manifest version mismatch                                 | Inspect `<getNativesDir()>/<version>` and loader error list       | Delete versioned cache for the package version; regenerate embedded manifest during packaging |\n| `embed:native` fails with `No native addons found`                     | Required platform artifact was not built before embedding                                   | Check expected list in error text                                 | Build at least one expected artifact for the target, then rerun `embed:native`                |\n\n## Operational commands\n\n```bash\n# Release artifact for current host\nbun --cwd=packages/natives run build\n\n# Build explicit x64 variants\nTARGET_VARIANT=modern bun --cwd=packages/natives run build\nTARGET_VARIANT=baseline bun --cwd=packages/natives run build\n\n# Generate embedded addon manifest from built native files\nbun --cwd=packages/natives run embed:native\n\n# Reset embedded manifest to null stub\nbun --cwd=packages/natives run embed:native -- --reset\n```\n",
 	"natives-media-system-utils.md": "# Natives media + system utilities\n\nThis document covers the media/system/conversion exports in `@gajae-code/natives`: sixel encoding, HTML conversion, clipboard access, macOS appearance/power helpers, and work profiling.\n\n## Implementation files\n\n- `crates/pi-natives/src/sixel.rs`\n\n> Note: `PhotonImage` was removed from the addon; image decode/transform/encode now runs through `Bun.Image` in TypeScript (`packages/coding-agent/src/utils/image-resize.ts`). `encodeSixel` remains a native export.\n- `crates/pi-natives/src/html.rs`\n- `crates/pi-natives/src/clipboard.rs`\n- `crates/pi-natives/src/appearance.rs`\n- `crates/pi-natives/src/power.rs`\n- `crates/pi-natives/src/prof.rs`\n- `crates/pi-natives/src/task.rs`\n- `packages/natives/native/index.d.ts`\n\n> Note: there is no `crates/pi-natives/src/work.rs`; work profiling is implemented in `prof.rs` and fed by instrumentation in `task.rs`.\n\n## JS API ↔ Rust export/module mapping\n\n| JS export                                           | Rust N-API export              | Rust module         |\n| --------------------------------------------------- | ------------------------------ | ------------------- |\n| `encodeSixel(bytes, targetWidthPx, targetHeightPx)` | `encode_sixel`                 | `sixel.rs`          |\n| `htmlToMarkdown(html, options?)`                    | `html_to_markdown`             | `html.rs`           |\n| `copyToClipboard(text)`                             | `copy_to_clipboard`            | `clipboard.rs`      |\n| `readImageFromClipboard()`                          | `read_image_from_clipboard`    | `clipboard.rs`      |\n| `detectMacOSAppearance()`                           | `detect_mac_os_appearance`     | `appearance.rs`     |\n| `MacAppearanceObserver.start(callback)`             | `MacAppearanceObserver::start` | `appearance.rs`     |\n| `MacOSPowerAssertion.start(options?)`               | `MacOSPowerAssertion::start`   | `power.rs`          |\n| `isoProbe/isoStart/isoStop`                         | `iso_probe` / `iso_start` / `iso_stop` | `iso.rs`    |\n| `getWorkProfile(lastSeconds)`                       | `get_work_profile`             | `prof.rs`           |\n\n## Data format boundaries and conversions\n\n### Image (`image`)\n\n- **JS input boundary**: `Uint8Array` encoded image bytes for `encodeSixel`.\n- **Output boundary**:\n  - `encodeSixel(...)` returns a SIXEL escape string synchronously.\n\n\nEncoding behavior:\n\n- Invalid dimensions for SIXEL (`0` width or height) fail with `Target SIXEL dimensions must be greater than zero`.\n\n### HTML conversion (`html`)\n\n- **JS input boundary**: HTML `string` + optional `{ cleanContent?: boolean; skipImages?: boolean }`.\n- **Rust conversion boundary**: conversion is scheduled through `task::blocking(\"html_to_markdown\", (), ...)`.\n- **Output boundary**: Markdown `string` promise.\n\nConversion behavior:\n\n- `cleanContent` defaults to `false`.\n- When `cleanContent=true`, preprocessing uses `PreprocessingPreset::Aggressive` and hard-removal flags for navigation/forms.\n- `skipImages` defaults to `false`.\n\n### Clipboard (`clipboard`)\n\n- `copyToClipboard(text)` is a synchronous native call using `arboard::Clipboard::set_text`.\n- `readImageFromClipboard()` runs in `task::blocking(\"clipboard.read_image\", (), ...)`.\n- Image read returns `null`/`undefined` when `arboard` reports `ContentNotAvailable`.\n- Successful image read re-encodes clipboard RGBA data as PNG and returns `{ data: Uint8Array, mimeType: \"image/png\" }`.\n- Clipboard access or image encoding failures reject/throw as native errors.\n\nThere is no current `packages/natives` TS wrapper that emits OSC52, handles Termux, or suppresses native clipboard failures. Any best-effort clipboard policy must live in consumers.\n\n### macOS appearance and power helpers\n\n- `detectMacOSAppearance()` returns `\"dark\"`, `\"light\"`, or `null` on non-macOS.\n- `MacAppearanceObserver.start(callback)` returns a handle with `stop()`; on macOS it uses distributed notifications plus a 2-second polling fallback, and on non-macOS it is a no-op observer.\n- `MacOSPowerAssertion.start(options?)` returns a handle with `stop()`; on macOS it acquires an IOKit assertion, and on other platforms it is a no-op handle.\n\n### Windows ProjFS (through the iso backend)\n\nProjFS is no longer a standalone export set. It is one backend of the iso overlay API:\n\n- `isoProbe(kind?)` reports whether a backend is available; pass `IsoBackendKind.Projfs` to probe ProjFS specifically.\n- `isoStart(...)` / `isoStop(...)` manage an overlay session.\n- `isoBackend()` reports the backend actually selected.\n\nThe ProjFS implementation lives in the `pi-iso` crate (`crates/pi-iso/src/projfs.rs`), ported out of the former `pi_natives::projfs_overlay`. It is platform-specific; probe before relying on overlay behavior.\n\n### Work profiling (`work`)\n\n- **Collection boundary**: profiling samples are produced by `profile_region(tag)` guards in `task::blocking` and `task::future`.\n- **Storage format**: fixed-size circular buffer (`MAX_SAMPLES = 10_000`) storing stack path, duration, and timestamp.\n- **Output boundary**: `getWorkProfile(lastSeconds)` returns:\n  - `folded`: folded-stack text (flamegraph input)\n  - `summary`: markdown table summary\n  - `svg`: optional flamegraph SVG\n  - `totalMs`, `sampleCount`\n\n## Lifecycle and state transitions\n\n### Image lifecycle\n\n1. `encodeSixel(...)` decodes the input bytes, optionally resizes to exact target dimensions with Lanczos3, and returns SIXEL text synchronously.\n\nFailure transitions:\n\n- Format detection or decode failure throws from SIXEL encoding.\n- Invalid SIXEL dimensions throw.\n\n### HTML lifecycle\n\n1. `htmlToMarkdown(html, options)` schedules a blocking conversion task.\n2. Conversion runs with defaulted options (`cleanContent=false`, `skipImages=false`) unless specified.\n3. Returns markdown string or rejects.\n\n### Clipboard lifecycle\n\n- Text copy constructs an `arboard::Clipboard` and calls `set_text` synchronously.\n- Image read constructs an `arboard::Clipboard`, calls `get_image`, encodes PNG on success, maps `ContentNotAvailable` to `None`, and rejects other errors.\n\n### Work profiling lifecycle\n\n1. No explicit start: profiling is active when task helpers execute.\n2. Every instrumented task scope records one sample on guard drop.\n3. Samples overwrite oldest entries after buffer capacity is reached.\n4. `getWorkProfile(lastSeconds)` reads a time window and derives folded/summary/svg artifacts.\n\nFailure transitions:\n\n- SVG generation failure is soft (`svg` omitted/undefined), while folded and summary still return.\n- Empty sample windows return empty folded data and no SVG, not an error.\n\n## Unsupported operations and error propagation\n\n### Image\n\n- Unsupported decode input or corrupted bytes: strict failure.\n- Invalid SIXEL target dimensions: strict failure.\n- No JS fallback path in the natives package.\n\n### HTML\n\n- Conversion errors are strict failures.\n- Option omission is defaulting, not failure.\n\n### Clipboard\n\n- Text copy is strict at the native API surface.\n- Image read distinguishes \"no image\" (`null`/`undefined`) from operational failure (rejection).\n\n### Work profiling\n\n- Retrieval is strict for the function call itself.\n- Flamegraph SVG generation is nullable/optional.\n- Buffer truncation is expected ring-buffer behavior.\n\n## Platform caveats\n\n- Clipboard access depends on OS/session support exposed through `arboard`.\n- macOS appearance and power helpers intentionally return no-op/null behavior on unsupported platforms.\n- ProjFS is Windows-specific and should be gated by `isoProbe(IsoBackendKind.Projfs)`.\n",
 	"natives-rust-task-cancellation.md": "# Native Rust task execution and cancellation (`pi-natives`)\n\nThis document describes how `crates/pi-natives` schedules native work and how cancellation flows from JS options (`timeoutMs`, `AbortSignal`) into Rust execution.\n\n## Implementation files\n\n- `crates/pi-natives/src/task.rs`\n- `crates/pi-natives/src/grep.rs`\n- `crates/pi-natives/src/glob.rs`\n- `crates/pi-natives/src/fd.rs`\n- `crates/pi-natives/src/ast.rs`\n- `crates/pi-natives/src/shell.rs`\n- `crates/pi-natives/src/pty.rs`\n- `crates/pi-natives/src/html.rs`\n- `crates/pi-natives/src/clipboard.rs`\n- `crates/pi-natives/src/text.rs`\n- `crates/pi-natives/src/ps.rs`\n\n## Core primitives (`task.rs`)\n\n`task.rs` defines:\n\n1. `task::blocking(tag, cancel_token, work)`\n   - Wraps `napi::AsyncTask` / `Task`.\n   - `compute()` runs on libuv worker threads.\n   - Returns a JS `Promise<T>` for exported functions.\n   - Records a profiling sample through `profile_region(tag)`.\n\n2. `task::future(env, tag, work)`\n   - Wraps `env.spawn_future(...)`.\n   - Runs async work on Tokio's runtime.\n   - Returns `PromiseRaw<'env, T>`.\n   - Records a profiling sample through `profile_region(tag)`.\n\n3. `CancelToken` / `AbortToken` / `AbortReason`\n   - `CancelToken::new(timeout_ms, signal)` combines an optional deadline and optional JS `AbortSignal` converted from `Unknown`.\n   - `CancelToken::heartbeat()` is cooperative cancellation for blocking loops.\n   - `CancelToken::wait()` asynchronously waits for signal, timeout, or Ctrl-C.\n   - `CancelToken::emplace_abort_token()` creates an abortable flag when a later `Shell.abort()`/internal bridge needs one.\n   - `AbortToken::abort(reason)` lets external code request abort.\n\n## `blocking` vs `future`: execution model and selection\n\n### Use `task::blocking`\n\nUse when work is CPU-heavy or fundamentally synchronous/blocking:\n\n- regex/file scanning (`grep`, `glob`, `fuzzyFind`)\n- ast-grep search/edit worker work\n- PTY loop internals through `tokio::task::spawn_blocking`\n- image decode/resize/encode\n- HTML conversion\n- clipboard image read\n\nBehavior:\n\n- Work closure receives a cloned `CancelToken`.\n- Cancellation is only observed where code checks `ct.heartbeat()?`.\n- Closure `Err(...)` rejects the JS promise.\n\n### Use `task::future`\n\nUse when work must `await` async operations:\n\n- shell session orchestration (`Shell.run`, `executeShell`)\n- PTY outer promise (`PtySession.start`) before it enters `spawn_blocking`\n- task racing (`tokio::select!`) between completion and cancellation\n\nBehavior:\n\n- Future code can race normal completion against `ct.wait()`.\n- On cancel path, async implementations typically cancel subordinate machinery and may force-abort after a grace timeout.\n\n## JS API ↔ Rust export mapping (task/cancel relevant)\n\n| JS-facing API                           | Rust export                          | Scheduler                                                      | Cancellation hookup                                                                      |\n| --------------------------------------- | ------------------------------------ | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |\n| `grep(options, onMatch?)`               | `grep`                               | `task::blocking(\"grep\", ct, ...)`                              | `CancelToken::new(options.timeoutMs, options.signal)` + heartbeat checks                 |\n| `glob(options, onMatch?)`               | `glob`                               | `task::blocking(\"glob\", ct, ...)`                              | `CancelToken::new(...)` + heartbeat checks                                               |\n| `fuzzyFind(options)`                    | `fuzzy_find`                         | `task::blocking(\"fuzzy_find\", ct, ...)`                        | `CancelToken::new(...)` + heartbeat checks                                               |\n| `astGrep(options)` / `astEdit(options)` | ast exports                          | blocking worker path                                           | timeout/signal fields are accepted by options and checked cooperatively in worker loops  |\n| `Shell#run(options, onChunk?)`          | `Shell::run`                         | `task::future(env, \"shell.run\", ...)`                          | `ct.wait()` raced against run task; bridges to Tokio cancellation token and `AbortToken` |\n| `executeShell(options, onChunk?)`       | `execute_shell`                      | `task::future(env, \"shell.execute\", ...)`                      | same cancel race and 2s graceful window                                                  |\n| `PtySession#start(options, onChunk?)`   | `PtySession::start`                  | `task::future(env, \"pty.start\", ...)` + inner `spawn_blocking` | `CancelToken` checked in sync PTY loop via `heartbeat()`                                 |\n| `htmlToMarkdown(html, options?)`        | `html_to_markdown`                   | `task::blocking(\"html_to_markdown\", (), ...)`                  | none (`()` token)                                                                        |\n| `readImageFromClipboard()`              | `read_image_from_clipboard`          | `task::blocking(\"clipboard.read_image\", (), ...)`              | none (`()` token)                                                                        |\n\n`text.rs`, `keys.rs`, most `ps.rs` functions, and synchronous utility exports do not use `task::blocking`/`task::future` and therefore do not participate in this cancellation path.\n\n## Cancellation lifecycle and state transitions\n\n### `CancelToken` lifecycle\n\n```text\nCreated\n  ├─ no signal + no timeout  -> passive token\n  ├─ signal registered        -> AbortSignal callback can set AbortReason::Signal\n  └─ deadline set             -> timeout check becomes active\n\nRunning\n  ├─ heartbeat()/wait() sees signal   -> AbortReason::Signal\n  ├─ heartbeat()/wait() sees deadline -> AbortReason::Timeout\n  ├─ wait() sees Ctrl-C               -> AbortReason::User\n  └─ no abort                         -> continue\n\nAborted\n  └─ flag stores first observed cause for waiters; heartbeat formats it as \"Aborted: <reason>\"\n```\n\n### Before-start vs mid-execution cancellation\n\n- **Before start / before first cancellation check**:\n  - `task::future` users that race on `ct.wait()` can resolve cancellation once they enter `select!`.\n  - `task::blocking` users only observe cancellation when closure code reaches `heartbeat()`.\n\n- **Mid-execution**:\n  - `blocking`: next `heartbeat()` returns `Err(\"Aborted: ...\")`.\n  - `future`: `ct.wait()` branch wins `select!`, then code cancels subordinate async machinery.\n  - shell: cancellation triggers a Tokio cancellation token, waits up to 2 seconds, then aborts the task if needed.\n  - PTY: heartbeat failure or `kill()` terminates PTY child/process tree and drains output briefly.\n\n## Heartbeat expectations for long-running loops\n\n`heartbeat()` must run at predictable cadence in loops with unbounded or large work sets.\n\nObserved patterns:\n\n- `glob` filtering checks entries during scan/filter work.\n- `fd` scoring checks scanned candidates.\n- `grep` checks before/during expensive search and passes tokens into shared scan/cache helpers.\n- `run_pty_sync` checks every loop tick with a maximum 16ms wait cadence.\n\nPractical rule: no loop over external-size input should exceed a short bounded interval without a heartbeat.\n\n## Failure behavior and error propagation to JS\n\n### Blocking tasks\n\nError path:\n\n1. Closure returns `Err(napi::Error)` (including `heartbeat()` abort).\n2. `Task::compute()` returns `Err`.\n3. `AsyncTask` rejects JS promise.\n\nTypical error strings:\n\n- `Aborted: Timeout`\n- `Aborted: Signal`\n- domain errors (`Failed to decode image: ...`, `Conversion error: ...`, etc.)\n\n### Future tasks\n\nError path:\n\n1. Async body returns `Err(napi::Error)` or join failure is mapped (`... task failed: {err}`).\n2. `task::future`-spawned promise rejects.\n3. Shell and PTY command APIs model cancellation as structured results instead of rejection when the cancellation path wins: `exitCode` omitted, `cancelled` or `timedOut` set.\n\n### Cancellation reporting split\n\n- **Abort as error**: blocking exports using `heartbeat()?`.\n- **Abort as typed result**: shell/PTY command APIs that model cancellation in result structs.\n\nChoose one model per API and document it explicitly.\n\n## Common pitfalls\n\n1. **Missing heartbeat in blocking loops**\n   - Symptom: timeout/signal appears ignored until loop ends.\n   - Fix: add `ct.heartbeat()?` at loop top and before expensive per-item steps.\n\n2. **Long uncancelable sections**\n   - Symptom: cancellation latency spikes during single large call (decode, sort, compression, parser invocation, etc.).\n   - Fix: split work into chunks with heartbeat boundaries; if impossible, document latency.\n\n3. **Blocking async executor**\n   - Symptom: async API stalls when sync-heavy code runs directly in future.\n   - Fix: move CPU/sync blocks to `task::blocking` or `tokio::task::spawn_blocking`.\n\n4. **Inconsistent cancel semantics**\n   - Symptom: one API rejects on cancel, another resolves with flags, confusing callers.\n   - Fix: standardize per domain and keep docs aligned.\n\n5. **Forgetting cancellation bridge in nested async tasks**\n   - Symptom: outer token is cancelled but inner readers/subprocess tasks keep running.\n   - Fix: bridge cancellation to inner token/signal and enforce grace timeout + forced abort fallback.\n\n## Checklist for new cancellable exports\n\n1. Classify work correctly:\n   - CPU-bound or sync blocking -> `task::blocking`.\n   - async I/O / `await` orchestration -> `task::future`.\n\n2. Expose cancel inputs when needed:\n   - include `timeoutMs` and `signal` in `#[napi(object)]` options,\n   - create `let ct = task::CancelToken::new(timeout_ms, signal);`.\n\n3. Wire cancellation through all layers:\n   - blocking loops: `ct.heartbeat()?` at stable intervals,\n   - async orchestration: race with `ct.wait()` and cancel sub-tasks/tokens.\n\n4. Decide cancellation contract:\n   - reject promise with abort error, or\n   - resolve typed `{ cancelled, timedOut, ... }`,\n   - keep this contract consistent for the API family.\n\n5. Propagate failures with context:\n   - map errors via `Error::from_reason(format!(\"...: {err}\"))`,\n   - include stage-specific prefixes (`spawn`, `decode`, `wait`, etc.).\n\n6. Handle before-start and mid-flight cancellation:\n   - cancellation check/await must happen before expensive body and during long execution.\n\n7. Validate no executor misuse:\n   - no long sync work directly inside async futures without `spawn_blocking`/blocking task wrapper.\n",
-	"natives-shell-pty-process.md": "# Natives Shell, PTY, Process, and Key Internals\n\nThis document covers the execution/process/terminal primitives in `@gajae-code/natives`: `shell`, `pty`, `ps`, and `keys`, using the architecture terms from `docs/natives-architecture.md`.\n\n## Implementation files\n\n- `crates/pi-natives/src/shell.rs`\n- `crates/pi-natives/src/shell/windows.rs` (Windows-only PATH enrichment)\n- `crates/pi-natives/src/pty.rs`\n- `crates/pi-natives/src/ps.rs`\n- `crates/pi-natives/src/keys.rs`\n- `crates/pi-natives/src/task.rs`\n- `packages/natives/native/index.d.ts`\n\n## Layer ownership\n\n- **Package entrypoint** (`packages/natives/native/index.js`): loads the `.node` addon and exports generated N-API bindings.\n- **Rust N-API module layer** (`crates/pi-natives/src/*`): shell/PTY process execution, process-tree traversal/termination, and key-sequence parsing.\n- **Consumers** (`packages/coding-agent`, `packages/tui`): higher-level session policy, output artifact/minimizer handling, render policy, and UI key handling.\n\n## Shell subsystem (`shell`)\n\n### API model\n\nTwo execution modes are exposed:\n\n1. **One-shot** via `executeShell(options, onChunk?)`.\n2. **Persistent session** via `new Shell(options?)` then `shell.run(...)` repeatedly.\n\nBoth stream output through a threadsafe callback and return `{ exitCode?, cancelled, timedOut, minimized? }`.\n\n`ShellOptions` supports `sessionEnv`, `snapshotPath`, and optional output `minimizer`. `ShellExecuteOptions` supports command-scoped `env`, session-level `sessionEnv`, `snapshotPath`, timeout/signal, and optional minimizer. `ShellRunOptions` supports command, cwd, command-scoped env, timeout, and signal.\n\n### Session creation and environment model\n\nRust creates `brush_core::Shell` with:\n\n- non-interactive, non-login mode,\n- `no_profile` and `no_rc`,\n- `do_not_inherit_env: true`,\n- bash-mode builtins, with `exec` and `suspend` disabled,\n- explicit environment reconstruction from host env,\n- skip-list for shell-sensitive vars (`PS1`, `PWD`, `SHLVL`, bash function exports, etc.).\n\nSession env behavior:\n\n- `ShellOptions.sessionEnv` / one-shot `sessionEnv` is applied at session creation.\n- `ShellRunOptions.env` / one-shot `env` is command-scoped (`EnvironmentScope::Command`) and popped after the command.\n- `PATH` is merged specially on Windows with case-insensitive dedupe.\n- Windows-only path enrichment (`shell/windows.rs`) appends discovered Git-for-Windows paths when present and not already included.\n- `snapshotPath`, when present, is sourced during session creation with stdout/stderr/stdin wired to null files.\n\n### Runtime lifecycle and state transitions\n\nPersistent shell (`Shell.run`) uses this state machine:\n\n- **Idle/Uninitialized**: `session: None`.\n- **Running**: first `run()` lazily creates a session, stores an abort token, executes command.\n- **Completed + keepalive**: if execution control flow is normal, abort state is cleared and session is reused.\n- **Completed + teardown**: if control flow is loop/script/shell-exit related, session is dropped.\n- **Cancelled/Timed out**: run task is cancelled, grace wait is 2 seconds, task may be force-aborted, session is dropped if lock can be acquired.\n- **Error**: session is dropped.\n\nOne-shot shell (`executeShell`) always creates and drops a fresh session per call.\n\n### Streaming/output and minimizer behavior\n\n- Stdout/stderr are routed into a shared pipe and read concurrently.\n- Reader decodes UTF-8 incrementally; invalid byte sequences emit `U+FFFD` replacement chunks.\n- The command runs in a new process group policy.\n- Optional minimizer configuration can capture and rewrite output. When minimization occurs, the result includes `minimized` with filter name, replacement text, original text, and byte counts.\n- Consumers are responsible for persisting or displaying minimizer artifacts; the native result only carries the data.\n\n### Cancellation, timeout, and abort\n\n- `CancelToken` is constructed from `timeoutMs` and optional `AbortSignal`.\n- On cancellation/timeout, shell cancellation token is triggered, then task gets a 2-second graceful window before forced abort.\n- Structured result flags are used:\n  - timeout -> `exitCode` omitted, `timedOut: true`.\n  - abort signal / `Shell.abort()` -> `exitCode` omitted, `cancelled: true`.\n\n`Shell.abort()` behavior:\n\n- aborts the current running command for that `Shell` instance through the stored `AbortToken`,\n- resolves successfully even when nothing is running.\n\n### Failure behavior\n\nCommon surfaced errors include:\n\n- session init failures (`Failed to initialize shell`),\n- cwd errors (`Failed to set cwd`),\n- env set/pop failures,\n- snapshot source failures (`Failed to source snapshot`),\n- pipe creation/clone failures,\n- execution failure (`Shell execution failed: ...`),\n- task wrapper failures (`Shell execution task failed: ...`).\n\n## PTY subsystem (`pty`)\n\n### API model\n\n`new PtySession()` exposes:\n\n- `start(options, onChunk?) -> Promise<{ exitCode?, cancelled, timedOut }>`\n- `write(data)`\n- `resize(cols, rows)`\n- `kill()`\n\n`PtyStartOptions` supports `command`, optional `cwd`, optional `env`, `timeoutMs`, `signal`, `cols`, and `rows`.\n\n### Runtime lifecycle and state transitions\n\n`PtySession` state machine:\n\n- **Idle**: `core: None`.\n- **Reserved**: `start()` installs control channel synchronously (`core: Some`) before async work begins, so `write/resize/kill` become immediately valid.\n- **Running**: blocking PTY loop handles child state, reader events, cancellation heartbeat, and control messages.\n- **Terminal closed / drain**: child exit or cancellation starts a short reader drain window.\n- **Finalized**: `core` is always reset to `None` after start task completion (success or error).\n\nConcurrency guard:\n\n- starting while already running returns `PTY session already running`.\n\n### Spawn/attach/write/read/terminate patterns\n\n- PTY opened via `portable_pty::native_pty_system().openpty(...)`.\n- Command currently runs as `sh -lc <command>` with optional `cwd` and env overrides.\n- Default size is `120x40`; dimensions are clamped (`cols 20..400`, `rows 5..200`).\n- `write()` sends raw bytes to PTY stdin.\n- `resize()` sends a control message and clamps dimensions again.\n- `kill()` sends a control message that marks the run cancelled and terminates the child/process tree.\n\nOutput path:\n\n- dedicated reader thread reads master stream,\n- incremental UTF-8 decode emits `U+FFFD` for invalid bytes,\n- chunks forwarded through N-API threadsafe callback.\n\nTermination path:\n\n- Unix: terminate process group when known, terminate child tree, call child kill, then repeat with SIGKILL.\n- Non-Unix: terminate child tree, call child kill, then repeat with SIGKILL-equivalent process-tree helper.\n\n### Cancellation and timeout semantics\n\n- `timeoutMs` and `AbortSignal` feed a `CancelToken`.\n- Loop calls `ct.heartbeat()` periodically with a 16ms maximum wait cadence.\n- Timeout classification is based on the heartbeat error string containing `Timeout`.\n- Cancellation/kill starts a 300ms post-cancel drain window; normal child exit starts a 300ms post-exit drain window.\n\n### Failure behavior\n\nError surfaces include:\n\n- PTY allocation/open failure,\n- PTY spawn failure,\n- writer/reader acquisition failure,\n- child status/wait failures,\n- lock poisoning,\n- control-channel disconnection (`PTY session is no longer available`).\n\nControl call failures when not running:\n\n- `write/resize/kill` return `PTY session is not running`.\n\n## Process-tree subsystem (`ps`)\n\n### API model\n\n- `killTree(pid, signal) -> number`\n- `listDescendants(pid) -> number[]`\n\n### Platform-specific implementation\n\n- **Linux**: recursively reads `/proc/<pid>/task/<pid>/children`.\n- **macOS**: uses `libproc` `proc_listchildpids`.\n- **Windows**: snapshots process table with `CreateToolhelp32Snapshot`, builds parent->children map, terminates with `OpenProcess(PROCESS_TERMINATE)` + `TerminateProcess`.\n\n### Kill-tree behavior\n\n- Descendants are collected recursively.\n- Kill order is bottom-up (deepest descendants first).\n- Root pid is killed last.\n- Return value is count of successful terminations.\n\nSignal behavior:\n\n- POSIX: provided `signal` is passed to `kill`.\n- Windows: `signal` is ignored; termination is unconditional process terminate.\n\n### Failure behavior\n\nThis module is intentionally non-throwing at API surface for ordinary process misses:\n\n- missing/inaccessible process tree branches are skipped,\n- per-pid kill failures are counted as unsuccessful,\n- lookup miss typically yields `[]` from `listDescendants` and `0` from `killTree`.\n\n## Key parsing subsystem (`keys`)\n\n### API model\n\nExposed helpers:\n\n- `parseKey(data, kittyProtocolActive)`\n- `matchesKey(data, keyId, kittyProtocolActive)`\n- `parseKittySequence(data)`\n- `matchesKittySequence(data, expectedCodepoint, expectedModifier)`\n- `matchesLegacySequence(data, keyName)`\n\n### Parsing model\n\nThe parser combines:\n\n- direct single-byte mappings (`enter`, `tab`, `ctrl+<letter>`, printable ASCII),\n- O(1) legacy escape-sequence lookup (PHF map),\n- xterm `modifyOtherKeys` parsing,\n- Kitty protocol parsing (`CSI u`, `CSI ~`, `CSI 1;...<letter>`),\n- normalization to key IDs (`ctrl+c`, `shift+tab`, `pageUp`, `f5`, etc.).\n\nModifier handling:\n\n- only shift/alt/ctrl bits are compared for key matching,\n- lock bits are masked out before comparisons.\n\nLayout behavior:\n\n- base-layout fallback is intentionally constrained so remapped layouts do not create false matches for ASCII letters/symbols.\n\n### Failure behavior\n\n- Unrecognized or invalid sequences produce `null` from parse functions.\n- Match functions return `false` on parse failure or mismatch.\n- No thrown error surface for malformed key input.\n\n## JS API ↔ Rust export mapping\n\n### Shell + PTY + Process\n\n| JS API                            | Rust N-API export                      | Notes                                     |\n| --------------------------------- | -------------------------------------- | ----------------------------------------- |\n| `executeShell(options, onChunk?)` | `executeShell` (`execute_shell`)       | One-shot shell execution                  |\n| `new Shell(options?)`             | `Shell` class                          | Persistent shell session                  |\n| `shell.run(options, onChunk?)`    | `Shell::run`                           | Reuses session on keepalive control flow  |\n| `shell.abort()`                   | `Shell::abort`                         | Aborts active run for that shell instance |\n| `new PtySession()`                | `PtySession` class                     | Stateful PTY session                      |\n| `pty.start(options, onChunk?)`    | `PtySession::start`                    | Interactive PTY run                       |\n| `pty.write(data)`                 | `PtySession::write`                    | Raw stdin passthrough                     |\n| `pty.resize(cols, rows)`          | `PtySession::resize`                   | Clamped terminal dimensions               |\n| `pty.kill()`                      | `PtySession::kill`                     | Force-kills active PTY child              |\n| `killTree(pid, signal)`           | `killTree` (`kill_tree`)               | Children-first process tree termination   |\n| `listDescendants(pid)`            | `listDescendants` (`list_descendants`) | Recursive descendants listing             |\n\n### Keys\n\n| JS API                                         | Rust N-API export                                   | Notes                           |\n| ---------------------------------------------- | --------------------------------------------------- | ------------------------------- |\n| `matchesKittySequence(data, cp, mod)`          | `matchesKittySequence` (`matches_kitty_sequence`)   | Kitty codepoint+modifier match  |\n| `parseKey(data, kittyProtocolActive)`          | `parseKey` (`parse_key`)                            | Normalized key-id parser        |\n| `matchesLegacySequence(data, keyName)`         | `matchesLegacySequence` (`matches_legacy_sequence`) | Exact legacy sequence map check |\n| `parseKittySequence(data)`                     | `parseKittySequence` (`parse_kitty_sequence`)       | Structured Kitty parse result   |\n| `matchesKey(data, keyId, kittyProtocolActive)` | `matchesKey` (`matches_key`)                        | High-level key matcher          |\n\n## Abandoned session cleanup and finalization notes\n\n- **Shell persistent session**: if a run is cancelled/timed out/errors/non-keepalive control flow, Rust drops the internal session state. Successful normal runs keep the session for reuse.\n- **PTY session**: `core` is always cleared after `start()` finishes, including failure paths.\n- **No explicit JS finalizer-driven kill contract** is exposed by wrappers; cleanup is primarily tied to run completion/cancellation paths. Callers should use `timeoutMs`, `AbortSignal`, `shell.abort()`, or `pty.kill()` for deterministic teardown.\n",
+	"natives-shell-pty-process.md": "# Natives Shell, PTY, Process, and Key Internals\n\nThis document covers the execution/process/terminal primitives in `@gajae-code/natives`: `shell`, `pty`, `ps`, and `keys`, using the architecture terms from `docs/natives-architecture.md`.\n\n## Implementation files\n\n- `crates/pi-natives/src/shell.rs`\n- `crates/pi-shell/src/windows.rs` (Windows-only PATH enrichment)\n- `crates/pi-natives/src/pty.rs`\n- `crates/pi-natives/src/ps.rs`\n- `crates/pi-natives/src/keys.rs`\n- `crates/pi-natives/src/task.rs`\n- `packages/natives/native/index.d.ts`\n\n## Layer ownership\n\n- **Package entrypoint** (`packages/natives/native/index.js`): loads the `.node` addon and exports generated N-API bindings.\n- **Rust N-API module layer** (`crates/pi-natives/src/*`): shell/PTY process execution, process-tree traversal/termination, and key-sequence parsing.\n- **Consumers** (`packages/coding-agent`, `packages/tui`): higher-level session policy, output artifact/minimizer handling, render policy, and UI key handling.\n\n## Shell subsystem (`shell`)\n\n### API model\n\nTwo execution modes are exposed:\n\n1. **One-shot** via `executeShell(options, onChunk?)`.\n2. **Persistent session** via `new Shell(options?)` then `shell.run(...)` repeatedly.\n\nBoth stream output through a threadsafe callback and return `{ exitCode?, cancelled, timedOut, minimized? }`.\n\n`ShellOptions` supports `sessionEnv`, `snapshotPath`, and optional output `minimizer`. `ShellExecuteOptions` supports command-scoped `env`, session-level `sessionEnv`, `snapshotPath`, timeout/signal, and optional minimizer. `ShellRunOptions` supports command, cwd, command-scoped env, timeout, and signal.\n\n### Session creation and environment model\n\nRust creates `brush_core::Shell` with:\n\n- non-interactive, non-login mode,\n- `no_profile` and `no_rc`,\n- `do_not_inherit_env: true`,\n- bash-mode builtins, with `exec` and `suspend` disabled,\n- explicit environment reconstruction from host env,\n- skip-list for shell-sensitive vars (`PS1`, `PWD`, `SHLVL`, bash function exports, etc.).\n\nSession env behavior:\n\n- `ShellOptions.sessionEnv` / one-shot `sessionEnv` is applied at session creation.\n- `ShellRunOptions.env` / one-shot `env` is command-scoped (`EnvironmentScope::Command`) and popped after the command.\n- `PATH` is merged specially on Windows with case-insensitive dedupe.\n- Windows-only path enrichment (`shell/windows.rs`) appends discovered Git-for-Windows paths when present and not already included.\n- `snapshotPath`, when present, is sourced during session creation with stdout/stderr/stdin wired to null files.\n\n### Runtime lifecycle and state transitions\n\nPersistent shell (`Shell.run`) uses this state machine:\n\n- **Idle/Uninitialized**: `session: None`.\n- **Running**: first `run()` lazily creates a session, stores an abort token, executes command.\n- **Completed + keepalive**: if execution control flow is normal, abort state is cleared and session is reused.\n- **Completed + teardown**: if control flow is loop/script/shell-exit related, session is dropped.\n- **Cancelled/Timed out**: run task is cancelled, grace wait is 2 seconds, task may be force-aborted, session is dropped if lock can be acquired.\n- **Error**: session is dropped.\n\nOne-shot shell (`executeShell`) always creates and drops a fresh session per call.\n\n### Streaming/output and minimizer behavior\n\n- Stdout/stderr are routed into a shared pipe and read concurrently.\n- Reader decodes UTF-8 incrementally; invalid byte sequences emit `U+FFFD` replacement chunks.\n- The command runs in a new process group policy.\n- Optional minimizer configuration can capture and rewrite output. When minimization occurs, the result includes `minimized` with filter name, replacement text, original text, and byte counts.\n- Consumers are responsible for persisting or displaying minimizer artifacts; the native result only carries the data.\n\n### Cancellation, timeout, and abort\n\n- `CancelToken` is constructed from `timeoutMs` and optional `AbortSignal`.\n- On cancellation/timeout, shell cancellation token is triggered, then task gets a 2-second graceful window before forced abort.\n- Structured result flags are used:\n  - timeout -> `exitCode` omitted, `timedOut: true`.\n  - abort signal / `Shell.abort()` -> `exitCode` omitted, `cancelled: true`.\n\n`Shell.abort()` behavior:\n\n- aborts the current running command for that `Shell` instance through the stored `AbortToken`,\n- resolves successfully even when nothing is running.\n\n### Failure behavior\n\nCommon surfaced errors include:\n\n- session init failures (`Failed to initialize shell`),\n- cwd errors (`Failed to set cwd`),\n- env set/pop failures,\n- snapshot source failures (`Failed to source snapshot`),\n- pipe creation/clone failures,\n- execution failure (`Shell execution failed: ...`),\n- task wrapper failures (`Shell execution task failed: ...`).\n\n## PTY subsystem (`pty`)\n\n### API model\n\n`new PtySession()` exposes:\n\n- `start(options, onChunk?) -> Promise<{ exitCode?, cancelled, timedOut }>`\n- `write(data)`\n- `resize(cols, rows)`\n- `kill()`\n\n`PtyStartOptions` supports `command`, optional `cwd`, optional `env`, `timeoutMs`, `signal`, `cols`, and `rows`.\n\n### Runtime lifecycle and state transitions\n\n`PtySession` state machine:\n\n- **Idle**: `core: None`.\n- **Reserved**: `start()` installs control channel synchronously (`core: Some`) before async work begins, so `write/resize/kill` become immediately valid.\n- **Running**: blocking PTY loop handles child state, reader events, cancellation heartbeat, and control messages.\n- **Terminal closed / drain**: child exit or cancellation starts a short reader drain window.\n- **Finalized**: `core` is always reset to `None` after start task completion (success or error).\n\nConcurrency guard:\n\n- starting while already running returns `PTY session already running`.\n\n### Spawn/attach/write/read/terminate patterns\n\n- PTY opened via `portable_pty::native_pty_system().openpty(...)`.\n- Command currently runs as `sh -lc <command>` with optional `cwd` and env overrides.\n- Default size is `120x40`; dimensions are clamped (`cols 20..400`, `rows 5..200`).\n- `write()` sends raw bytes to PTY stdin.\n- `resize()` sends a control message and clamps dimensions again.\n- `kill()` sends a control message that marks the run cancelled and terminates the child/process tree.\n\nOutput path:\n\n- dedicated reader thread reads master stream,\n- incremental UTF-8 decode emits `U+FFFD` for invalid bytes,\n- chunks forwarded through N-API threadsafe callback.\n\nTermination path:\n\n- Unix: terminate process group when known, terminate child tree, call child kill, then repeat with SIGKILL.\n- Non-Unix: terminate child tree, call child kill, then repeat with SIGKILL-equivalent process-tree helper.\n\n### Cancellation and timeout semantics\n\n- `timeoutMs` and `AbortSignal` feed a `CancelToken`.\n- Loop calls `ct.heartbeat()` periodically with a 16ms maximum wait cadence.\n- Timeout classification is based on the heartbeat error string containing `Timeout`.\n- Cancellation/kill starts a 300ms post-cancel drain window; normal child exit starts a 300ms post-exit drain window.\n\n### Failure behavior\n\nError surfaces include:\n\n- PTY allocation/open failure,\n- PTY spawn failure,\n- writer/reader acquisition failure,\n- child status/wait failures,\n- lock poisoning,\n- control-channel disconnection (`PTY session is no longer available`).\n\nControl call failures when not running:\n\n- `write/resize/kill` return `PTY session is not running`.\n\n## Process-tree subsystem (`ps`)\n\n### API model\n\n- `killTree(pid, signal) -> number`\n- `listDescendants(pid) -> number[]`\n\n### Platform-specific implementation\n\n- **Linux**: recursively reads `/proc/<pid>/task/<pid>/children`.\n- **macOS**: uses `libproc` `proc_listchildpids`.\n- **Windows**: snapshots process table with `CreateToolhelp32Snapshot`, builds parent->children map, terminates with `OpenProcess(PROCESS_TERMINATE)` + `TerminateProcess`.\n\n### Kill-tree behavior\n\n- Descendants are collected recursively.\n- Kill order is bottom-up (deepest descendants first).\n- Root pid is killed last.\n- Return value is count of successful terminations.\n\nSignal behavior:\n\n- POSIX: provided `signal` is passed to `kill`.\n- Windows: `signal` is ignored; termination is unconditional process terminate.\n\n### Failure behavior\n\nThis module is intentionally non-throwing at API surface for ordinary process misses:\n\n- missing/inaccessible process tree branches are skipped,\n- per-pid kill failures are counted as unsuccessful,\n- lookup miss typically yields `[]` from `listDescendants` and `0` from `killTree`.\n\n## Key parsing subsystem (`keys`)\n\n### API model\n\nExposed helpers:\n\n- `parseKey(data, kittyProtocolActive)`\n- `matchesKey(data, keyId, kittyProtocolActive)`\n- `parseKittySequence(data)`\n- `matchesKittySequence(data, expectedCodepoint, expectedModifier)`\n- `matchesLegacySequence(data, keyName)`\n\n### Parsing model\n\nThe parser combines:\n\n- direct single-byte mappings (`enter`, `tab`, `ctrl+<letter>`, printable ASCII),\n- O(1) legacy escape-sequence lookup (PHF map),\n- xterm `modifyOtherKeys` parsing,\n- Kitty protocol parsing (`CSI u`, `CSI ~`, `CSI 1;...<letter>`),\n- normalization to key IDs (`ctrl+c`, `shift+tab`, `pageUp`, `f5`, etc.).\n\nModifier handling:\n\n- only shift/alt/ctrl bits are compared for key matching,\n- lock bits are masked out before comparisons.\n\nLayout behavior:\n\n- base-layout fallback is intentionally constrained so remapped layouts do not create false matches for ASCII letters/symbols.\n\n### Failure behavior\n\n- Unrecognized or invalid sequences produce `null` from parse functions.\n- Match functions return `false` on parse failure or mismatch.\n- No thrown error surface for malformed key input.\n\n## JS API ↔ Rust export mapping\n\n### Shell + PTY + Process\n\n| JS API                            | Rust N-API export                      | Notes                                     |\n| --------------------------------- | -------------------------------------- | ----------------------------------------- |\n| `executeShell(options, onChunk?)` | `executeShell` (`execute_shell`)       | One-shot shell execution                  |\n| `new Shell(options?)`             | `Shell` class                          | Persistent shell session                  |\n| `shell.run(options, onChunk?)`    | `Shell::run`                           | Reuses session on keepalive control flow  |\n| `shell.abort()`                   | `Shell::abort`                         | Aborts active run for that shell instance |\n| `new PtySession()`                | `PtySession` class                     | Stateful PTY session                      |\n| `pty.start(options, onChunk?)`    | `PtySession::start`                    | Interactive PTY run                       |\n| `pty.write(data)`                 | `PtySession::write`                    | Raw stdin passthrough                     |\n| `pty.resize(cols, rows)`          | `PtySession::resize`                   | Clamped terminal dimensions               |\n| `pty.kill()`                      | `PtySession::kill`                     | Force-kills active PTY child              |\n| `killTree(pid, signal)`           | `killTree` (`kill_tree`)               | Children-first process tree termination   |\n| `listDescendants(pid)`            | `listDescendants` (`list_descendants`) | Recursive descendants listing             |\n\n### Keys\n\n| JS API                                         | Rust N-API export                                   | Notes                           |\n| ---------------------------------------------- | --------------------------------------------------- | ------------------------------- |\n| `matchesKittySequence(data, cp, mod)`          | `matchesKittySequence` (`matches_kitty_sequence`)   | Kitty codepoint+modifier match  |\n| `parseKey(data, kittyProtocolActive)`          | `parseKey` (`parse_key`)                            | Normalized key-id parser        |\n| `matchesLegacySequence(data, keyName)`         | `matchesLegacySequence` (`matches_legacy_sequence`) | Exact legacy sequence map check |\n| `parseKittySequence(data)`                     | `parseKittySequence` (`parse_kitty_sequence`)       | Structured Kitty parse result   |\n| `matchesKey(data, keyId, kittyProtocolActive)` | `matchesKey` (`matches_key`)                        | High-level key matcher          |\n\n## Abandoned session cleanup and finalization notes\n\n- **Shell persistent session**: if a run is cancelled/timed out/errors/non-keepalive control flow, Rust drops the internal session state. Successful normal runs keep the session for reuse.\n- **PTY session**: `core` is always cleared after `start()` finishes, including failure paths.\n- **No explicit JS finalizer-driven kill contract** is exposed by wrappers; cleanup is primarily tied to run completion/cancellation paths. Callers should use `timeoutMs`, `AbortSignal`, `shell.abort()`, or `pty.kill()` for deterministic teardown.\n",
 	"natives-text-search-pipeline.md": "# Natives Text/Search Pipeline\n\nThis document maps the `@gajae-code/natives` text/search/code surface from generated JS/TS exports to Rust N-API modules and back to JS result objects.\n\nTerminology follows `docs/natives-architecture.md`:\n\n- **Generated binding**: public API in `packages/natives/native/index.d.ts`.\n- **Rust module layer**: N-API exports in `crates/pi-natives/src/*`.\n- **Shared scan cache**: `fs_cache`-backed directory-entry cache used by discovery/search flows.\n\n## Implementation files\n\n- `packages/natives/native/index.d.ts`\n- `crates/pi-natives/src/grep.rs`\n- `crates/pi-natives/src/glob.rs`\n- `crates/pi-natives/src/glob_util.rs`\n- `crates/pi-natives/src/fs_cache.rs`\n- `crates/pi-natives/src/fd.rs`\n- `crates/pi-natives/src/ast.rs`\n- `crates/pi-natives/src/text.rs`\n- `crates/pi-natives/src/highlight.rs`\n\n## JS API ↔ Rust export mapping\n\n| JS API                                                                          | Rust export (`#[napi]`, snake_case -> camelCase) | Rust module    |\n| ------------------------------------------------------------------------------- | ------------------------------------------------ | -------------- |\n| `grep(options, onMatch?)`                                                       | `grep`                                           | `grep.rs`      |\n| `search(content, options)`                                                      | `search`                                         | `grep.rs`      |\n| `hasMatch(content, pattern, ignoreCase?, multiline?)`                           | `hasMatch`                                       | `grep.rs`      |\n| `fuzzyFind(options)`                                                            | `fuzzyFind`                                      | `fd.rs`        |\n| `glob(options, onMatch?)`                                                       | `glob`                                           | `glob.rs`      |\n| `invalidateFsScanCache(path?)`                                                  | `invalidateFsScanCache`                          | `fs_cache.rs`  |\n| `astGrep(options)`                                                              | `astGrep`                                        | `ast.rs`       |\n| `astEdit(options)`                                                              | `astEdit`                                        | `ast.rs`       |\n| `wrapTextWithAnsi(text, width, tabWidth)`                                       | `wrapTextWithAnsi`                               | `text.rs`      |\n| `truncateToWidth(text, maxWidth, ellipsis, pad, tabWidth)`                      | `truncateToWidth`                                | `text.rs`      |\n| `sliceWithWidth(line, startCol, length, strict, tabWidth)`                      | `sliceWithWidth`                                 | `text.rs`      |\n| `extractSegments(line, beforeEnd, afterStart, afterLen, strictAfter, tabWidth)` | `extractSegments`                                | `text.rs`      |\n| `visibleWidth(text, tabWidth)`                                                  | `visibleWidth`                                   | `text.rs`      |\n| `highlightCode(code, lang, colors)`                                             | `highlightCode`                                  | `highlight.rs` |\n| `supportsLanguage(lang)`                                                        | `supportsLanguage`                               | `highlight.rs` |\n| `getSupportedLanguages()`                                                       | `getSupportedLanguages`                          | `highlight.rs` |\n\n## Pipeline overview by subsystem\n\n## 1) Regex search (`grep`, `search`, `hasMatch`)\n\n### Input/options flow\n\n1. Callers invoke generated native exports directly; there is no package-local TS wrapper that renames `search` to `searchContent`.\n2. Rust option structs in `grep.rs` deserialize camelCase fields (`ignoreCase`, `maxCount`, `contextBefore`, `contextAfter`, `maxColumns`, `timeoutMs`).\n3. `grep` creates `CancelToken` from `timeoutMs` + `AbortSignal` and runs inside `task::blocking(\"grep\", ...)`.\n4. `search` and `hasMatch` operate on provided string/`Uint8Array` content and do not scan the filesystem.\n\n### Execution branches\n\n- **In-memory branch**\n  - `search` -> `search_sync` / search helpers over provided content bytes.\n  - `hasMatch` compiles/checks pattern against provided content and returns a boolean.\n  - No filesystem scan, no `fs_cache`.\n- **Single-file branch**\n  - `grep` resolves path, checks metadata is file, and searches that file.\n- **Directory branch**\n  - Optional cache lookup via `fs_cache::get_or_scan` when `cache: true`.\n  - Fresh scan via `fs_cache::force_rescan` when `cache: false`.\n  - Optional empty-result recheck when cached results are older than the empty-result recheck threshold.\n  - Entry filtering: file-only + optional glob filter (`glob_util`) + optional type filter mapping (`js`, `ts`, `rust`, etc.).\n\n### Search/collection semantics\n\n- Regex engine: `grep_regex::RegexMatcherBuilder` with `ignoreCase` and `multiline`.\n- Context resolution:\n  - `contextBefore/contextAfter` override legacy `context`.\n  - Non-content modes do not collect context.\n- Output modes:\n  - `content` -> one `GrepMatch` per hit.\n  - `count` and `filesWithMatches` map to count-style entries (`lineNumber=0`, `line=\"\"`, `matchCount` set).\n- Limits:\n  - Global `offset` and `maxCount` apply across files.\n  - Parallel path is used only when `maxCount` is unset and `offset == 0`; otherwise sequential path preserves deterministic global offset/limit semantics.\n\n### Result shaping back to JS\n\n- Rust `SearchResult`/`GrepResult` fields map to TS interfaces via N-API object conversion.\n- Counters are clamped before crossing N-API where needed.\n- `GrepResult.limitReached` is optional and emitted when true.\n- Streaming callback receives each shaped `GrepMatch` for content or count-style entries.\n\n### Failure behavior\n\n- `search` returns `SearchResult.error` for regex/search failures instead of throwing.\n- `grep` rejects on hard errors such as invalid path, invalid glob/regex, or cancellation timeout/abort.\n- `hasMatch` returns a boolean on success and throws on invalid pattern/UTF-8 conversion errors.\n- File open/search errors in multi-file scans are skipped per-file; scan continues.\n\n### Malformed regex handling\n\n`grep.rs` sanitizes braces before regex compile:\n\n- Invalid repetition-like braces are escaped (`{`/`}` -> `\\{`/`\\}`) when they cannot form `{N}`, `{N,}`, `{N,M}`.\n- This prevents common literal-template fragments (for example `${platform}`) from failing as malformed repetition.\n- Remaining invalid regex syntax still returns a regex error.\n\n## 2) File discovery (`glob`) and fuzzy path search (`fuzzyFind`)\n\n`glob` and `fuzzyFind` share `fs_cache` scans; matching logic differs.\n\n### `glob` flow\n\n1. Caller passes `GlobOptions` directly. `pattern` and `path` are required in the generated type.\n2. Rust resolves the search path and compiles pattern via `glob_util::compile_glob`.\n3. Entry source:\n   - `cache=true` -> `get_or_scan` + optional stale-empty `force_rescan`.\n   - `cache=false` -> `force_rescan(..., store=false)` (fresh only).\n4. Filtering:\n   - skip `.git` always;\n   - skip `node_modules` unless requested (`includeNodeModules`) or pattern mentions `node_modules`;\n   - apply glob match;\n   - apply file-type filter; symlink `file`/`dir` filters resolve target metadata.\n5. Optional sort by mtime descending (`sortByMtime`) before truncating to `maxResults`.\n\n### `fuzzyFind` flow\n\n1. Rust implementation lives in `fd.rs`; generated export is `fuzzyFind`.\n2. Shared scan source from `fs_cache` with the same cache/no-cache split and stale-empty recheck policy.\n3. Scoring:\n   - exact / starts-with / contains / subsequence-based fuzzy score;\n   - separator/punctuation-normalized scoring path;\n   - directory bonus and deterministic tie-break (`score desc`, then `path asc`).\n4. Symlink entries are excluded from fuzzy results.\n\n### Failure behavior\n\n- Invalid glob pattern returns an error from `glob_util::compile_glob`.\n- Search root must resolve to an existing directory for directory discovery flows.\n- Cancellation/timeouts propagate as abort errors via `CancelToken::heartbeat()` checks in loops.\n\n### Malformed glob handling\n\n`glob_util::build_glob_pattern` is tolerant:\n\n- normalizes `\\` to `/`,\n- auto-prefixes simple recursive patterns with `**/` when `recursive=true`,\n- auto-closes unbalanced `{...` alternation groups before compile.\n\n## 3) AST search/edit (`astGrep`, `astEdit`)\n\n`ast.rs` exposes syntax-aware code search and rewrite operations.\n\n- `astGrep(options)` returns matches with byte/line/column coordinates and optional metavariable bindings.\n- `astEdit(options)` returns replacement changes, per-file counts, searched/touched file counts, parse errors, and whether edits were applied.\n- `dryRun` defaults to true for edit options in the generated documentation.\n- Options include language override, path/glob/selector, strictness, limits, parse-error policy, `signal`, and `timeoutMs`.\n\nThese exports are direct native APIs used by tooling; they are not mediated by a TS wrapper in `packages/natives`.\n\n## 4) Shared scan/cache lifecycle (`fs_cache`)\n\n`fs_cache` stores scan results as normalized relative entries (`path`, `fileType`, optional `mtime`) keyed by:\n\n- canonical search root,\n- `include_hidden`,\n- `use_gitignore`.\n\n### Cache state transitions\n\n1. **Miss / disabled**\n   - TTL is `0` or key absent/expired -> fresh collection.\n2. **Hit**\n   - Entry age is within TTL -> return cached entries + `cache_age_ms`.\n3. **Stale-empty recheck**\n   - If query yields zero matches and cache age exceeds the empty-result threshold, force one rescan.\n4. **Invalidation**\n   - `invalidateFsScanCache(path?)`:\n     - no arg: clear all keys;\n     - path arg: remove keys for roots affected by that path.\n\n### Stale-result tradeoff\n\n- Cache favors low-latency repeated scans over immediate consistency.\n- TTL window can return stale positives/negatives.\n- Empty-result recheck reduces stale negatives for older cached scans at the cost of one extra scan.\n- Explicit invalidation is the intended correctness hook after file mutations.\n\n## 5) ANSI text utilities (`text`)\n\nThese are pure, in-memory utilities.\n\n### Boundaries and responsibilities\n\n- `text.rs` owns terminal-cell semantics:\n  - ANSI sequence parsing,\n  - grapheme-aware width and slicing,\n  - wrap/truncate/sanitize behavior,\n  - explicit tab-width parameter on width-sensitive APIs.\n- `grep.rs` line truncation (`maxColumns`) is separate:\n  - simple character-boundary truncation of matched lines with `...`,\n  - not ANSI-state-preserving and not terminal-cell width aware.\n\n### Key behaviors\n\n- `wrapTextWithAnsi`: wraps by visible width, carries active SGR codes across wrapped lines.\n- `truncateToWidth`: visible-cell truncation with ellipsis policy (`Unicode`, `Ascii`, `Omit`), optional right padding.\n- `sliceWithWidth`: column slicing with optional strict width enforcement.\n- `extractSegments`: extracts before/after segments around an overlay while restoring ANSI state for the `after` segment.\n- `sanitizeText` (ANSI/control/surrogate stripping with line-ending normalization) no longer lives in `text.rs`; it moved to `@gajae-code/utils` as a pure-JS implementation in `packages/utils/src/sanitize-text.ts`. The native binding was removed in the same change because the JS version was competitive on the benchmarked workloads, and keeping a Rust copy forced every caller (including `pi-utils`) to pull in `@gajae-code/natives`.\n- `visibleWidth`: counts visible terminal cells using caller-supplied tab width.\n\n### Failure behavior\n\nText functions generally return deterministic transformed output; errors are limited to N-API argument/string conversion boundaries.\n\n## 6) Syntax highlighting (`highlight`)\n\n`highlight.rs` is pure transformation; it does not use the filesystem scan cache.\n\n### Flow\n\n1. Caller passes `code`, optional `lang`, and ANSI color palette.\n2. Rust resolves syntax by token/name lookup, extension lookup, alias table fallback, then plain-text fallback.\n3. Each line is parsed with syntect `ParseState` and scope stack.\n4. Scopes map to semantic color categories and ANSI color codes are injected/reset.\n\n### Failure behavior\n\n- Per-line parse failure does not fail the call: that line is appended unhighlighted and processing continues.\n- Unknown/unsupported language falls back to plain text syntax.\n\n## Pure utility vs filesystem-dependent flows\n\n| Flow                         | Filesystem access | Shared cache         | Notes                                         |\n| ---------------------------- | ----------------- | -------------------- | --------------------------------------------- |\n| `search` / `hasMatch`        | No                | No                   | regex on provided bytes/string only           |\n| `text` module functions      | No                | No                   | ANSI/width/sanitization only                  |\n| `highlight` module functions | No                | No                   | syntax + ANSI coloring only                   |\n| `astGrep` / `astEdit`        | Yes               | No                   | syntax-aware file search/edit                 |\n| `glob`                       | Yes               | Optional             | directory scans + glob filtering              |\n| `fuzzyFind`                  | Yes               | Optional             | directory scans + fuzzy scoring               |\n| `grep` (file/dir path)       | Yes               | Optional in dir mode | ripgrep over files, optional filters/callback |\n\n## End-to-end lifecycle summary\n\n1. Caller invokes generated native export with typed options.\n2. Rust validates/normalizes options and builds matcher/search config.\n3. For filesystem flows, entries are scanned (cache hit/miss/rescan where applicable) then filtered/scored/searched.\n4. Worker loops periodically call cancel heartbeat; timeout/abort can terminate execution.\n5. Rust shapes outputs into N-API objects (`lineNumber`, `matchCount`, `limitReached`, etc.).\n6. Generated bindings return typed JS objects and optional per-match callbacks for `grep`/`glob`.\n",
-	"non-compaction-retry-policy.md": "# Non-compaction auto-retry policy\n\nThis document describes the standard API-error retry path in `AgentSession`.\n\nIt explicitly excludes context-overflow recovery via auto-compaction. Overflow is handled by compaction logic and is documented separately in [`compaction.md`](../docs/compaction.md).\n\n## Implementation files\n\n- [`../src/session/agent-session.ts`](../packages/coding-agent/src/session/agent-session.ts)\n- [`../src/config/settings-schema.ts`](../packages/coding-agent/src/config/settings-schema.ts)\n- [`../src/modes/controllers/event-controller.ts`](../packages/coding-agent/src/modes/controllers/event-controller.ts)\n- [`sdk.md`](./sdk.md) for the external machine interface.\n\n## Scope boundary vs compaction\n\nRetry and compaction are checked from the same `agent_end` path, but they are intentionally separated:\n\n1. `agent_end` inspects the last assistant message.\n2. `#isRetryableError(...)` runs first.\n3. If retry is initiated, compaction checks are skipped for that turn.\n4. Context-overflow errors are hard-excluded from retry classification (`isContextOverflow(...)` short-circuits retry).\n5. Overflow therefore falls through to `#checkCompaction(...)` instead of standard retry.\n\nSo: overload/rate/server/network-style failures use this retry policy; context-window overflow uses compaction recovery.\n\n## Retry classification\n\n`#isRetryableError(...)` requires all of the following:\n\n- assistant `stopReason === \"error\"`\n- `errorMessage` exists\n- message is **not** context overflow\n- `errorMessage` matches transient transport/envelope patterns or `isUsageLimitError(...)`\n\nCurrent retryable inputs are regex/string-classified:\n\n- transient transport/envelope failures, including Anthropic stream-envelope failures before `message_start`\n- overloaded/provider-returned-error wording\n- rate limit / usage limit / too many requests\n- HTTP-like server classes: 429, 500, 502, 503, 504\n- service unavailable / server/internal error\n- provider-suggested retry wording, including OpenAI `retry your request` failures\n- network/connection/socket failures, refused/closed connections, upstream connect/reset-before-headers, socket hang up, timeout/timed out, fetch failed, terminated, retry delay wording, and unexpected socket close messages\n- canonical idle-stream watchdog stalls (`stream stalled while waiting for the next event`); in the legacy single-model path these remain retryable but use the bounded `retry.maxRetries` budget\n- canonical local snapshot failure classification (`errorKind: \"local_snapshot_failure\"`, or the stable `Managed fallback attempt could not produce a serializable event snapshot` message prefix for restored sessions) is recognized, but only so the failure can be routed to its immediate-surface policy below — it is never re-issued\n\nManaged fallback uses structured transport facts and typed provider error codes when available. A structured classification of `other` becomes the bounded `unknown` fallback class; error prose cannot promote it to quota or transient. Regex classification is retained only as a legacy fallback.\n\n### Bare-default admissions\n\nA session with no explicit `retry.*` settings and a single-model default role (no managed fallback) does not use the classification list above on its own. It admits only these content-free failures:\n\n- canonical first-event and idle-stream watchdog aborts, recognized from the typed timeout fact or an exact canonical sentinel message\n- the OpenAI Codex `server_is_overloaded` event, recognized from that provider's typed overload code\n- the generic OpenAI Responses `server_is_overloaded` terminal envelope, recognized from the exact statusless `openaiErrorCode` and matching `providerCode`\n- Anthropic's typed `overloaded_error` envelope, recognized by parsing the error envelope and requiring both the outer `type` and the nested `error.type` to match\n\nOverload admissions therefore require a provider-specific typed signature, while watchdog admissions accept only their canonical sentinel messages. Every admission additionally requires that the attempt carry no assistant text, thinking, or tool call and no conflicting transport facts; a status-bearing or otherwise typed failure surfaces instead. Untyped or noncanonical overload and timeout wording never authorizes a replay.\n\n### Local snapshot failures (surface immediately, no retry)\n\n`local_snapshot_failure` is a local machinery fault, not provider evidence. The retained producer shape is deterministic, so re-streaming the same request only reproduces the same local defect; it is surfaced immediately instead of being amplified across identical retries:\n\n- Surfaces immediately with the original producer-boundary diagnostic, regardless of `retry.*` settings.\n- Never charges the fallback controller (the started attempt's provisional charge is discarded), never advances models, never emits `model_fallback_switched`, and never mutates or rotates credentials.\n\n### Local buffer overflows (surface immediately, no retry)\n\n`local_buffer_overflow` (`errorKind`, or the stable `Managed fallback attempt exceeded the provisional event buffer limit` message prefix for restored sessions) is the sibling local staging fault: the provisional managed-attempt buffer exceeded its cap. Like snapshot failures, re-streaming the same request reproduces the same oversized response, so it is never retried:\n\n- Surfaces immediately with the original local diagnostic, regardless of `retry.*` settings.\n- Like snapshot failures, it never charges the fallback controller (the started attempt's provisional charge is discarded), never advances models, never emits `model_fallback_switched`, and never mutates or rotates credentials.\n\n## Retry lifecycle and state transitions\n\nSession state used by retry:\n\n- `#retryAttempt: number` (`0` means idle)\n- `#retryPromise: Promise<void> | undefined` (tracks in-progress retry lifecycle)\n- `#retryResolve: (() => void) | undefined` (resolves `#retryPromise`)\n- `#retryAbortController: AbortController | undefined` (cancels backoff sleep)\n\nFlow (`#handleRetryableError`):\n\n1. Read `retry` settings group.\n2. If `retry.enabled === false`, stop immediately (`false`, no retry started). Managed provider-fallback failures keep their own chain policy; local snapshot and buffer-overflow failures surface immediately regardless of this setting.\n3. Increment `#retryAttempt`.\n4. Create `#retryPromise` once (first attempt in a chain).\n5. In the legacy single-model path, ordinary transient errors retry without an attempt limit. Typed provider-overload replays, canonical idle-stream watchdog stalls, and unknown/no-code errors stop after `retry.maxRetries`. Managed fallback instead uses its controller's per-entry `fallback.maxAttempts` budget.\n6. Compute exponential full-jitter delay capped at `retry.maxDelayMs`. Managed fallback ignores Retry-After when calculating retry delays and advances when its attempt budget is consumed. Legacy parsed provider retry-after values still override computed backoff and are capped at `retry.maxDelayMs`.\n7. For usage-limit errors, call auth storage (`markUsageLimitReached(...)`); if credential switching succeeds, force delay to `0`, otherwise use the applicable backoff.\n8. Eligible ordered role-array fallback chains advance on entry-budget exhaustion. A selected fallback entry remains sticky until the head selector's rate-limit cooldown expires, when `retry.fallbackRevertPolicy: cooldown-expiry` probes it again on a new turn.\n9. Emit `auto_retry_start`.\n10. Remove the trailing assistant error message from agent runtime state (kept in persisted session history).\n11. Sleep with abort support.\n12. Schedule `agent.continue()` through the post-prompt task scheduler (`delayMs: 1`) for the same prompt generation.\n\n### What resets retry counters\n\n`#retryAttempt` resets to `0` in these cases:\n\n- first successful non-error, non-aborted assistant message after retries started (emits `auto_retry_end { success: true }`)\n- retry cancellation during backoff sleep\n- max retries exceeded path\n\n`#retryPromise` resolves/clears when retry chain ends (success, cancellation, or max-exceeded), via `#resolveRetry()`.\n\n## Preferred credential quota fallback\n\n`--prefer-credential <selector>` gives one active stored OAuth credential first priority without pinning it:\n\n```bash\ngjc --prefer-credential id:15\ngjc --prefer-credential email:name@example.com\ngjc --prefer-credential anthropic/id:15\ngjc --resume --prefer-credential id:15\n```\n\nThe selector works for any provider backed by a multi-account OAuth credential pool; it is not Anthropic-specific. API-key credentials and runtime `--api-key` overrides are intentionally outside this soft-selection path, and `--credential` (the hard pin) and `--prefer-credential` are mutually exclusive.\n\nA usable preferred credential is placed ahead of candidates ordered by the provider's existing balanced/earliest-reset ranking. A content-free quota or rate-limit failure marks that row blocked, switches immediately to another active candidate, and replays the request with zero delay — the same `markUsageLimitReached` credential-switch path documented above under \"What starts a retry\", step 7. The fallback row then remains sticky for the session like any other credential switch. Partial assistant output or tool execution still prevents replay, and exhaustion of every row surfaces the final error without a retry loop, including the earliest stored `blockedUntil` as a `retryable at <ISO-8601>` hint. `403 forbidden` remains an authorization failure and never mutates quota state.\n\nAn unqualified selector (no `provider/` prefix) must match exactly one active OAuth provider's credential pool; an ambiguous match across providers fails startup and asks for an explicit `provider/<selector>` prefix. Once resolved, the model that the session ends up using must belong to that same provider — a default model, restored session model, or explicit `--model` from a different provider fails closed with an error naming both providers, instead of silently stranding the preference.\n\n## Backoff and max-attempt semantics\n\nSettings:\n\n- `retry.enabled` (default `true`)\n- `retry.maxRetries` (default `3`)\n- `retry.baseDelayMs` (default `2000`)\n- `retry.maxDelayMs` (default `300000`)\n- `retry.requestMaxRetries` (default `5`) — provider request retries before a stream is established; counts retries, not the initial request\n- `retry.streamMaxRetries` (default `5`) — provider stream replay retries for replay-safe transient stream failures; counts retries, not the initial stream attempt\n\nAttempt numbering:\n\n- attempt counter is incremented before max-check\n- start events use current attempt (1-based)\n- max-exceeded end event reports `attempt: this.#retryAttempt - 1` (last attempted retry count)\n\nBackoff uses capped exponential full jitter. With default settings the maximum jitter windows are:\n\n- attempt 1: 2000 ms\n- attempt 2: 4000 ms\n- attempt 3: 8000 ms\n\nManaged fallback uses capped exponential full jitter and `fallback.maxAttempts` (including the initial request), not Retry-After, to schedule attempts. Rate-limit selector cooldown is recorded when the entry advances or exhausts, rather than interrupting its remaining attempts. Credential rotation retains its existing policy. `retry.maxDelayMs` caps legacy retry delays including provider hints; zero retains the existing uncapped backoff setting. In the legacy single-model path, transient errors have unbounded attempts except canonical idle-stream watchdog stalls, which are bounded by `retry.maxRetries`; unknown/no-code errors use the same bound.\n\n## Abort mechanics\n\n### Explicit retry abort\n\n`abortRetry()`:\n\n- aborts `#retryAbortController` (if present)\n- resolves retry promise (`#resolveRetry()`) so awaiters are unblocked\n\nIf abort hits while sleeping, catch path emits:\n\n- `auto_retry_end { success: false, finalError: \"Retry cancelled\" }`\n- resets attempt/controller\n\n### Global operation abort interaction\n\n`abort()` calls `abortRetry()` before aborting the active agent stream. This guarantees retry backoff is cancelled when user issues a general abort.\n\n### TUI interaction\n\nOn `auto_retry_start`, EventController:\n\n- swaps `Esc` handler to `session.abortRetry()`\n- renders loader text: `Retrying (attempt/maxAttempts) in Ns… (esc to cancel)`\n\nOn `auto_retry_end`, it restores prior `Esc` handler and clears loader state.\n\n## Streaming and prompt completion behavior\n\n`prompt()` ultimately waits on `#waitForRetry()` after `agent.prompt(...)` returns.\n\nEffect:\n\n- a prompt call does not fully resolve until any started retry chain finishes (success/failure/cancel)\n- retry lifecycle is part of one logical prompt execution boundary\n\nThis prevents callers from treating a retrying turn as complete too early.\n\n## Controls: settings and SDK actions\n\n### Configuration knobs\n\nThe standard retry controls are defined in the settings schema under `retry`:\n\n- `retry.enabled`\n- `retry.maxRetries`\n- `retry.baseDelayMs`\n- `retry.maxDelayMs`\n\nFallback candidates are configured as ordered selector arrays on preset `model_mapping` roles, top-level `modelRoles`, or `task.agentModelOverrides`; `fallback.maxAttempts` controls the total request-time attempts per concrete entry. Resolution-time unavailable, unauthenticated, and unknown entries advance immediately without consuming that budget.\n\nOn settings load, a source-aware one-shot migration still reads legacy `retry.fallbackChains` and combines the effective role chain with its ordered, deduplicated legacy tail into the corresponding role array. The legacy key is ignored after migration; it is not a retry configuration surface.\n\nProgrammatic toggles in session:\n\n- `setAutoRetryEnabled(enabled)` writes `retry.enabled`\n- `autoRetryEnabled` reads `retry.enabled`\n- `isRetrying` reports whether retry lifecycle promise is active\n\n### External control\n\nExternal clients observe retry lifecycle through the [SDK machine interface](./sdk.md). The removed RPC command surface and `RpcClient` helpers are not supported.\n\n## Event emission and failure surfacing\n\nSession-level retry events:\n\n- `auto_retry_start { attempt, maxAttempts, delayMs, errorMessage }`\n- `auto_retry_end { success, attempt, finalError? }`\n- `model_fallback_switched { eventId, from, to, reason, role, scope, activeIndex, chainLength, attemptsUsed }` — emitted once for each real fallback-model switch\n\nPropagation:\n\n- emitted through `AgentSession.subscribe(...)`\n- forwarded to extension runner as extension events\n- exposed to external clients through SDK event subscriptions\n- in the TUI, `model_fallback_switched` updates the fallback-model status/notice and `EventController` consumes retry lifecycle events for loader/error UI\n\nFinal failure surfacing:\n\n- On max-exceeded or cancellation, `auto_retry_end.success === false`\n- TUI shows: `Retry failed after N attempts: <finalError>`\n- Extensions/hooks receive `auto_retry_end` with same fields\n- SDK clients receive the same event stream\n\n## Permanent stop conditions\n\nRetry stops and will not auto-continue when any of these occur:\n\n- `retry.enabled` is false, or legacy retry settings have not been explicitly configured (`legacyRetryConfigured` fail-closed gate) — except for the bare-default admissions listed above\n- error is not retry-classified\n- error is context overflow (delegated to compaction path)\n- max retries exceeded\n- user cancels retry through the session/SDK action or `Esc` during retry loader\n- global abort (`abort`) cancels retry first\n\nA new retry chain can still start later on a future retryable error after counters reset.\n\n## Operational caveats\n\n- Managed fallback uses typed transport facts and provider error codes; regex text matching is limited to the legacy retry path.\n- Retry strips the failing assistant error from **runtime context** before re-continue, but session history still keeps that error entry.\n- SDK clients observe retry state through session events and state updates.\n- Fallback state is driven by the configured ordered role array and remains on a selected fallback entry across later user prompts. A real model change emits the canonical `model_fallback_switched` event rather than a legacy retry-fallback event.\n- Temporary provider-session scopes retain and restore their own fallback controller and provider state when unwound; an authoritative model selection commits those temporary scopes.\n\n## Provider request/stream retry budgets\n\nThe provider budgets are deliberately separate from session auto-retry:\n\n```yaml\nretry:\n  requestMaxRetries: 4\n  streamMaxRetries: 100\n```\n\n`requestMaxRetries` maps to provider SDK/fetch retry counts for request setup failures such as retryable 5xx/408/429/network errors. `streamMaxRetries` maps to provider-specific stream replay loops that are safe to repeat without duplicating visible assistant output. Providers that cannot safely replay a stream continue to surface the terminal error so the session-level auto-retry layer can decide whether to retry the turn.\n\nFail-fast cases stay fail-fast: invalid credentials (after any credential-refresh path is exhausted), unsupported model/provider configuration, malformed requests, context overflow, explicit user aborts, and permanent quota failures are not treated as transient provider budget candidates.\n",
-	"notebook-tool-runtime.md": "# Notebook tool runtime internals\n\nThis document describes the current `notebook` tool implementation and its relationship to the kernel-backed Python runtime.\n\nThe critical distinction: **`notebook` is a JSON notebook editor, not a notebook executor**. It edits `.ipynb` cell sources directly; it does not start or talk to a Python kernel.\n\n## Implementation files\n\n- [`src/tools/notebook.ts`](../packages/coding-agent/src/tools/notebook.ts)\n- [`src/eval/py/executor.ts`](../packages/coding-agent/src/eval/py/executor.ts)\n- [`src/eval/py/kernel.ts`](../packages/coding-agent/src/eval/py/kernel.ts)\n- [`src/session/streaming-output.ts`](../packages/coding-agent/src/session/streaming-output.ts)\n- [`src/tools/eval.ts`](../packages/coding-agent/src/tools/eval.ts)\n\n## 1) Runtime boundary: editing vs executing\n\n## `notebook` tool (`src/tools/notebook.ts`)\n\n- Supports `action: edit | insert | delete` on a `.ipynb` file.\n- Resolves path relative to session CWD (`resolveToCwd`).\n- Loads notebook JSON, validates `cells` array, validates `cell_index` bounds.\n- Applies source edits in-memory and writes full notebook JSON back with `JSON.stringify(notebook, null, 1)`.\n- Returns textual summary + structured `details` (`action`, `cellIndex`, `cellType`, `totalCells`, `cellSource`).\n\nNo kernel lifecycle exists in this tool:\n\n- no gateway acquisition\n- no kernel session ID\n- no `execute_request`\n- no stream chunks from kernel channels\n- no rich display capture (`image/png`, JSON display, status MIME)\n\n## Notebook-like execution path (`src/tools/eval.ts` + `src/eval/py/*`)\n\nWhen the agent needs to run cell-style Python code (sequential cells, persistent state, rich displays), that goes through the **`eval` tool** with `language: \"python\"`, not `notebook`.\n\nThat path is where kernel modes, restart/cancel behavior, chunk streaming, and output artifact truncation live.\n\n## 2) Notebook cell handling semantics (`notebook` tool)\n\n## Source normalization\n\n`content` is split into `source: string[]` with newline preservation:\n\n- each non-final line keeps trailing `\\n`\n- final line has no forced trailing newline\n\nThis mirrors notebook JSON conventions and avoids accidental line concatenation on later edits.\n\n## Action behavior\n\n- `edit`\n  - replaces `cells[cell_index].source`\n  - preserves existing `cell_type`\n- `insert`\n  - inserts at `[0..cellCount]`\n  - `cell_type` defaults to `code`\n  - code cells initialize `execution_count: null` and `outputs: []`\n  - markdown cells initialize only `metadata` + `source`\n- `delete`\n  - removes `cells[cell_index]`\n  - returns removed `source` in details for renderer preview\n\n## Error surfaces\n\nHard failures are thrown for:\n\n- missing notebook file\n- invalid JSON\n- missing/non-array `cells`\n- out-of-range index (insert and non-insert have different valid ranges)\n- missing `content` for `edit`/`insert`\n\nThese become `Error:` tool responses upstream; renderer uses notebook path + formatted error text.\n\n## 3) Kernel session semantics (where they actually exist)\n\nKernel semantics are implemented in `executePython` / `PythonKernel` and apply to the Python backend of the `eval` tool.\n\n## Modes\n\n`PythonKernelMode`:\n\n- `session` (default)\n  - kernels cached in `kernelSessions` map\n  - max 4 sessions; oldest evicted on overflow\n  - idle/dead cleanup every 30s, timeout after 5 minutes\n  - per-session queue serializes execution (`session.queue`)\n- `per-call`\n  - creates kernel for request\n  - executes\n  - always shuts down kernel in `finally`\n\n## Reset behavior\n\n`eval` passes `reset` only for the first cell in a multi-cell Python call; later cells always run with `reset: false`.\n\n## Kernel death / restart / retry\n\nIn session mode (`withKernelSession`):\n\n- dead kernel detected by heartbeat (`kernel.isAlive()` check every 5s) or execute failure.\n- pre-run dead state triggers `restartKernelSession`.\n- execute-time crash path retries once: restart kernel, rerun handler.\n- `restartCount > 1` in same session throws `Python kernel restarted too many times in this session`.\n\nStartup retry behavior:\n\n- shared gateway kernel creation retries once on `SharedGatewayCreateError` with HTTP 5xx.\n\nResource exhaustion recovery:\n\n- detects `EMFILE`/`ENFILE`/\"Too many open files\" style failures\n- clears tracked sessions\n- calls `shutdownSharedGateway()`\n- retries kernel session creation once\n\n## 4) Environment/session variable injection\n\nKernel startup receives the optional session file path from executor:\n\n- `GJC_SESSION_FILE` (session state file path)\n\n`PythonKernel.#initializeKernelEnvironment(...)` then runs init script inside kernel to:\n\n- `os.chdir(cwd)`\n- inject env entries into `os.environ`\n- prepend cwd to `sys.path` if missing\n\nImplication:\n\n- prelude helpers that read session context rely on this env var in Python process state.\n\n## 5) Streaming/chunk and display handling (kernel-backed path)\n\nThe kernel client processes Jupyter protocol messages per execution:\n\n- `stream` -> text chunk to `onChunk`\n- `execute_result` / `display_data` ->\n  - display text chosen by MIME precedence: `text/markdown` > `text/plain` > converted `text/html`\n  - structured outputs captured separately:\n    - `application/json` -> `{ type: \"json\" }`\n    - `image/png` -> `{ type: \"image\" }`\n    - `application/x-gjc-status` -> `{ type: \"status\" }` (no text emission)\n- `error` -> traceback text pushed to chunk stream + structured error metadata\n- `input_request` -> emits stdin warning text, sends empty `input_reply`, marks stdin requested\n- completion waits for both `execute_reply` and kernel `status=idle`\n\nCancellation/timeout:\n\n- abort signal triggers `interrupt()` (REST `/interrupt` + control-channel `interrupt_request`)\n- result marks `cancelled=true`\n- timeout path annotates output with `Command timed out after <n> seconds`\n\n## 6) Truncation and artifact behavior\n\n`OutputSink` in `src/session/streaming-output.ts` is used by kernel execution paths (`executeWithKernel`):\n\n- sanitizes every chunk (`sanitizeText`)\n- tracks total/output lines and bytes\n- optional artifact spill file (`artifactPath`, `artifactId`)\n- when in-memory buffer exceeds threshold (`DEFAULT_MAX_BYTES` unless overridden):\n  - marks truncated\n  - keeps tail bytes in memory (UTF-8 safe boundary)\n  - can spill full stream to artifact sink\n\n`dump()` returns:\n\n- visible output text (possibly tail-truncated)\n- truncation flag + counts\n- artifact ID (for `artifact://<id>` references)\n\n`eval` converts this metadata into result truncation notices and TUI warnings.\n\n`notebook` tool does **not** use `OutputSink`; it has no stream/artifact truncation pipeline because it does not execute code.\n\n## 7) Renderer assumptions and formatting\n\n## Notebook renderer (`notebookToolRenderer`)\n\n- call view: status line with action + notebook path + cell/type metadata\n- result view:\n  - success summary derived from `details`\n  - `cellSource` rendered via `renderCodeCell`\n  - markdown cells set language hint `markdown`; other cells have no explicit language override\n  - collapsed code preview limit is `PREVIEW_LIMITS.COLLAPSED_LINES * 2`\n  - supports expanded mode via shared render options\n  - uses render cache keyed by width + expanded state\n\nError rendering assumption:\n\n- if first text content starts with `Error:`, renderer formats as notebook error block.\n\n## Python renderer (for actual execution output)\n\nKernel-backed execution rendering expects:\n\n- per-cell status transitions (`pending/running/complete/error`)\n- optional structured status event section\n- optional JSON output trees\n- truncation warnings + optional `artifact://<id>` pointer\n\nThis renderer behavior is unrelated to `notebook` JSON editing results except that both reuse shared TUI primitives.\n\n## 8) Divergence from eval Python backend behavior\n\nIf \"plain Python execution\" means the `eval` tool with `language: \"python\"`:\n\n- `eval` executes code in a kernel, persists state by mode, streams chunks, captures rich displays, handles interrupts/timeouts, and supports output truncation/artifacts.\n- `notebook` performs deterministic notebook JSON mutations only; no execution, no kernel state, no chunk stream, no display outputs, no artifact pipeline.\n\nIf a workflow needs both:\n\n1. edit notebook source with `notebook`\n2. execute code cells via `eval` with `language: \"python\"` (manually passing code), not through `notebook`\n\nCurrent implementation does not provide a single tool that both mutates `.ipynb` and executes notebook cells through kernel context.\n",
+	"non-compaction-retry-policy.md": "# Non-compaction auto-retry policy\n\nThis document describes the standard API-error retry path in `AgentSession`.\n\nIt explicitly excludes context-overflow recovery via auto-compaction. Overflow is handled by compaction logic and is documented separately in [`compaction.md`](../docs/compaction.md).\n\n## Implementation files\n\n- [`../src/session/agent-session.ts`](../packages/coding-agent/src/session/agent-session.ts)\n- [`../src/config/settings-schema.ts`](../packages/coding-agent/src/config/settings-schema.ts)\n- [`../src/modes/controllers/event-controller.ts`](../packages/coding-agent/src/modes/controllers/event-controller.ts)\n- [`sdk.md`](./sdk.md) for the external machine interface.\n\n## Scope boundary vs compaction\n\nRetry and compaction are checked from the same `agent_end` path, but they are intentionally separated:\n\n1. `agent_end` inspects the last assistant message.\n2. `#isRetryableError(...)` runs first.\n3. If retry is initiated, compaction checks are skipped for that turn.\n4. Context-overflow errors are hard-excluded from retry classification (`isContextOverflow(...)` short-circuits retry).\n5. Overflow therefore falls through to `#checkCompaction(...)` instead of standard retry.\n\nSo: overload/rate/server/network-style failures use this retry policy; context-window overflow uses compaction recovery.\n\n## Retry classification\n\n`#isRetryableError(...)` requires all of the following:\n\n- assistant `stopReason === \"error\"`\n- `errorMessage` exists\n- message is **not** context overflow\n- `errorMessage` matches transient transport/envelope patterns or `isUsageLimitError(...)`\n\nCurrent retryable inputs are regex/string-classified:\n\n- transient transport/envelope failures, including Anthropic stream-envelope failures before `message_start`\n- overloaded/provider-returned-error wording\n- rate limit / usage limit / too many requests\n- HTTP-like server classes: 429, 500, 502, 503, 504\n- service unavailable / server/internal error\n- provider-suggested retry wording, including OpenAI `retry your request` failures\n- network/connection/socket failures, refused/closed connections, upstream connect/reset-before-headers, socket hang up, timeout/timed out, fetch failed, terminated, retry delay wording, and unexpected socket close messages\n- canonical idle-stream watchdog stalls (`stream stalled while waiting for the next event`); in the legacy single-model path these remain retryable but use the bounded `retry.maxRetries` budget\n- canonical local snapshot failure classification (`errorKind: \"local_snapshot_failure\"`, or the stable `Managed fallback attempt could not produce a serializable event snapshot` message prefix for restored sessions) is recognized, but only so the failure can be routed to its immediate-surface policy below — it is never re-issued\n\nManaged fallback uses structured transport facts and typed provider error codes when available. A structured classification of `other` becomes the bounded `unknown` fallback class; error prose cannot promote it to quota or transient. Regex classification is retained only as a legacy fallback.\n\n### Bare-default admissions\n\nA session with no explicit `retry.*` settings and a single-model default role (no managed fallback) does not use the classification list above on its own. It admits only these content-free failures:\n\n- canonical first-event and idle-stream watchdog aborts, recognized from the typed timeout fact or an exact canonical sentinel message\n- the OpenAI Codex `server_is_overloaded` event, recognized from that provider's typed overload code\n- the generic OpenAI Responses `server_is_overloaded` terminal envelope, recognized from the exact statusless `openaiErrorCode` and matching `providerCode`\n- Anthropic's typed `overloaded_error` envelope, recognized by parsing the error envelope and requiring both the outer `type` and the nested `error.type` to match\n\nOverload admissions therefore require a provider-specific typed signature, while watchdog admissions accept only their canonical sentinel messages. Every admission additionally requires that the attempt carry no assistant text, thinking, or tool call and no conflicting transport facts; a status-bearing or otherwise typed failure surfaces instead. Untyped or noncanonical overload and timeout wording never authorizes a replay.\n\n### Local snapshot failures (surface immediately, no retry)\n\n`local_snapshot_failure` is a local machinery fault, not provider evidence. The retained producer shape is deterministic, so re-streaming the same request only reproduces the same local defect; it is surfaced immediately instead of being amplified across identical retries:\n\n- Surfaces immediately with the original producer-boundary diagnostic, regardless of `retry.*` settings.\n- Never charges the fallback controller (the started attempt's provisional charge is discarded), never advances models, never emits `model_fallback_switched`, and never mutates or rotates credentials.\n\n### Local buffer overflows (surface immediately, no retry)\n\n`local_buffer_overflow` (`errorKind`, or the stable `Managed fallback attempt exceeded the provisional event buffer limit` message prefix for restored sessions) is the sibling local staging fault: the provisional managed-attempt buffer exceeded its cap. Like snapshot failures, re-streaming the same request reproduces the same oversized response, so it is never retried:\n\n- Surfaces immediately with the original local diagnostic, regardless of `retry.*` settings.\n- Like snapshot failures, it never charges the fallback controller (the started attempt's provisional charge is discarded), never advances models, never emits `model_fallback_switched`, and never mutates or rotates credentials.\n\n## Retry lifecycle and state transitions\n\nSession state used by retry:\n\n- `#retryAttempt: number` (`0` means idle)\n- `#retryPromise: Promise<void> | undefined` (tracks in-progress retry lifecycle)\n- `#retryResolve: (() => void) | undefined` (resolves `#retryPromise`)\n- `#retryAbortController: AbortController | undefined` (cancels backoff sleep)\n\nFlow (`#handleRetryableError`):\n\n1. Read `retry` settings group.\n2. If `retry.enabled === false`, stop immediately (`false`, no retry started). Managed provider-fallback failures keep their own chain policy; local snapshot and buffer-overflow failures surface immediately regardless of this setting.\n3. Increment `#retryAttempt`.\n4. Create `#retryPromise` once (first attempt in a chain).\n5. In the legacy single-model path, ordinary transient errors retry without an attempt limit. Typed provider-overload replays, canonical idle-stream watchdog stalls, and unknown/no-code errors stop after `retry.maxRetries`. Managed fallback instead uses its controller's per-entry `fallback.maxAttempts` budget.\n6. Compute exponential full-jitter delay capped at `retry.maxDelayMs`. Managed fallback ignores Retry-After when calculating retry delays and advances when its attempt budget is consumed. Legacy parsed provider retry-after values still override computed backoff and are capped at `retry.maxDelayMs`.\n7. For usage-limit errors, call auth storage (`markUsageLimitReached(...)`); if credential switching succeeds, force delay to `0`, otherwise use the applicable backoff.\n8. Eligible ordered role-array fallback chains advance on entry-budget exhaustion. A selected fallback entry remains sticky until the head selector's rate-limit cooldown expires, when `retry.fallbackRevertPolicy: cooldown-expiry` probes it again on a new turn.\n9. Emit `auto_retry_start`.\n10. Remove the trailing assistant error message from agent runtime state (kept in persisted session history).\n11. Sleep with abort support.\n12. Schedule `agent.continue()` through the post-prompt task scheduler (`delayMs: 1`) for the same prompt generation.\n\n### What resets retry counters\n\n`#retryAttempt` resets to `0` in these cases:\n\n- first successful non-error, non-aborted assistant message after retries started (emits `auto_retry_end { success: true }`)\n- retry cancellation during backoff sleep\n- max retries exceeded path\n\n`#retryPromise` resolves/clears when retry chain ends (success, cancellation, or max-exceeded), via `#resolveRetry()`.\n\n## Preferred credential quota fallback\n\n`--prefer-credential <selector>` gives one active stored OAuth credential first priority without pinning it:\n\n```bash\ngjc --prefer-credential id:15\ngjc --prefer-credential email:name@example.com\ngjc --prefer-credential anthropic/id:15\ngjc --resume --prefer-credential id:15\n```\n\nThe selector works for any provider backed by a multi-account OAuth credential pool; it is not Anthropic-specific. API-key credentials and runtime `--api-key` overrides are intentionally outside this soft-selection path, and `--credential` (the hard pin) and `--prefer-credential` are mutually exclusive.\n\nA usable preferred credential is placed ahead of candidates ordered by the provider's existing balanced/earliest-reset ranking. A content-free quota or rate-limit failure marks that row blocked, switches immediately to another active candidate, and replays the request with zero delay — the same `markUsageLimitReached` credential-switch path documented above under \"What starts a retry\", step 7. The fallback row then remains sticky for the session like any other credential switch. Partial assistant output or tool execution still prevents replay, and exhaustion of every row surfaces the final error without a retry loop, including the earliest stored `blockedUntil` as a `retryable at <ISO-8601>` hint. `403 forbidden` remains an authorization failure and never mutates quota state.\n\nAn unqualified selector (no `provider/` prefix) must match exactly one active OAuth provider's credential pool; an ambiguous match across providers fails startup and asks for an explicit `provider/<selector>` prefix. Once resolved, the model that the session ends up using must belong to that same provider — a default model, restored session model, or explicit `--model` from a different provider fails closed with an error naming both providers, instead of silently stranding the preference.\n\n## Backoff and max-attempt semantics\n\nSettings:\n\n- `retry.enabled` (default `true`)\n- `retry.maxRetries` (default `3`)\n- `retry.baseDelayMs` (default `2000`)\n- `retry.maxDelayMs` (default `300000`)\n- `retry.requestMaxRetries` (default `5`) — provider request retries before a stream is established; counts retries, not the initial request\n- `retry.streamMaxRetries` (default `5`) — provider stream replay retries for replay-safe transient stream failures; counts retries, not the initial stream attempt\n\nAttempt numbering:\n\n- attempt counter is incremented before max-check\n- start events use current attempt (1-based)\n- max-exceeded end event reports `attempt: this.#retryAttempt - 1` (last attempted retry count)\n\nBackoff uses capped exponential full jitter. With default settings the maximum jitter windows are:\n\n- attempt 1: 2000 ms\n- attempt 2: 4000 ms\n- attempt 3: 8000 ms\n\nManaged fallback uses capped exponential full jitter and `fallback.maxAttempts` (including the initial request), not Retry-After, to schedule attempts. Rate-limit selector cooldown is recorded when the entry advances or exhausts, rather than interrupting its remaining attempts. Credential rotation retains its existing policy. `retry.maxDelayMs` caps legacy retry delays including provider hints; zero retains the existing uncapped backoff setting. In the legacy single-model path, transient errors have unbounded attempts except canonical idle-stream watchdog stalls, which are bounded by `retry.maxRetries`; unknown/no-code errors use the same bound.\n\n## Abort mechanics\n\n### Explicit retry abort\n\n`abortRetry()`:\n\n- aborts `#retryAbortController` (if present)\n- resolves retry promise (`#resolveRetry()`) so awaiters are unblocked\n\nIf abort hits while sleeping, catch path emits:\n\n- `auto_retry_end { success: false, finalError: \"Retry cancelled\" }`\n- resets attempt/controller\n\n### Global operation abort interaction\n\n`abort()` calls `abortRetry()` before aborting the active agent stream. This guarantees retry backoff is cancelled when user issues a general abort.\n\n### TUI interaction\n\nOn `auto_retry_start`, EventController:\n\n- swaps `Esc` handler to `session.abortRetry()`\n- renders loader text: `Retrying (attempt/maxAttempts) in Ns… (esc to cancel)`\n\nOn `auto_retry_end`, it restores prior `Esc` handler and clears loader state.\n\n## Streaming and prompt completion behavior\n\nA prompt's full settlement (`#settleEndedInFlight(..., \"full\")`) awaits `#waitForPostPromptRecovery()` after the agent run ends. That helper loops until `#retryPromise`, the TTSR resume promise, and outstanding post-prompt recovery tasks have all settled.\n\nEffect:\n\n- a prompt call does not fully resolve until any started retry chain finishes (success/failure/cancel)\n- retry lifecycle is part of one logical prompt execution boundary\n\nThis prevents callers from treating a retrying turn as complete too early.\n\n## Controls: settings and SDK actions\n\n### Configuration knobs\n\nThe standard retry controls are defined in the settings schema under `retry`:\n\n- `retry.enabled`\n- `retry.maxRetries`\n- `retry.baseDelayMs`\n- `retry.maxDelayMs`\n\nFallback candidates are configured as ordered selector arrays on preset `model_mapping` roles, top-level `modelRoles`, or `task.agentModelOverrides`; `fallback.maxAttempts` controls the total request-time attempts per concrete entry. Resolution-time unavailable, unauthenticated, and unknown entries advance immediately without consuming that budget.\n\nOn settings load, a source-aware one-shot migration still reads legacy `retry.fallbackChains` and combines the effective role chain with its ordered, deduplicated legacy tail into the corresponding role array. The legacy key is ignored after migration; it is not a retry configuration surface.\n\nProgrammatic toggles in session:\n\n- `setAutoRetryEnabled(enabled)` writes `retry.enabled`\n- `autoRetryEnabled` reads `retry.enabled`\n- `isRetrying` reports whether retry lifecycle promise is active\n\n### External control\n\nExternal clients observe retry lifecycle through the [SDK machine interface](./sdk.md). The removed RPC command surface and `RpcClient` helpers are not supported.\n\n## Event emission and failure surfacing\n\nSession-level retry events:\n\n- `auto_retry_start { attempt, maxAttempts, delayMs, errorMessage }`\n- `auto_retry_end { success, attempt, finalError? }`\n- `model_fallback_switched { eventId, from, to, reason, role, scope, activeIndex, chainLength, attemptsUsed }` — emitted once for each real fallback-model switch\n\nPropagation:\n\n- emitted through `AgentSession.subscribe(...)`\n- forwarded to extension runner as extension events\n- exposed to external clients through SDK event subscriptions\n- in the TUI, `model_fallback_switched` updates the fallback-model status/notice and `EventController` consumes retry lifecycle events for loader/error UI\n\nFinal failure surfacing:\n\n- On max-exceeded or cancellation, `auto_retry_end.success === false`\n- TUI shows: `Retry failed after N attempts: <finalError>`\n- Extensions/hooks receive `auto_retry_end` with same fields\n- SDK clients receive the same event stream\n\n## Permanent stop conditions\n\nRetry stops and will not auto-continue when any of these occur:\n\n- `retry.enabled` is false, or legacy retry settings have not been explicitly configured (`legacyRetryConfigured` fail-closed gate) — except for the bare-default admissions listed above\n- error is not retry-classified\n- error is context overflow (delegated to compaction path)\n- max retries exceeded\n- user cancels retry through the session/SDK action or `Esc` during retry loader\n- global abort (`abort`) cancels retry first\n\nA new retry chain can still start later on a future retryable error after counters reset.\n\n## Operational caveats\n\n- Managed fallback uses typed transport facts and provider error codes; regex text matching is limited to the legacy retry path.\n- Retry strips the failing assistant error from **runtime context** before re-continue, but session history still keeps that error entry.\n- SDK clients observe retry state through session events and state updates.\n- Fallback state is driven by the configured ordered role array and remains on a selected fallback entry across later user prompts. A real model change emits the canonical `model_fallback_switched` event rather than a legacy retry-fallback event.\n- Temporary provider-session scopes retain and restore their own fallback controller and provider state when unwound; an authoritative model selection commits those temporary scopes.\n\n## Provider request/stream retry budgets\n\nThe provider budgets are deliberately separate from session auto-retry:\n\n```yaml\nretry:\n  requestMaxRetries: 4\n  streamMaxRetries: 100\n```\n\n`requestMaxRetries` maps to provider SDK/fetch retry counts for request setup failures such as retryable 5xx/408/429/network errors. `streamMaxRetries` maps to provider-specific stream replay loops that are safe to repeat without duplicating visible assistant output. Providers that cannot safely replay a stream continue to surface the terminal error so the session-level auto-retry layer can decide whether to retry the turn.\n\nFail-fast cases stay fail-fast: invalid credentials (after any credential-refresh path is exhausted), unsupported model/provider configuration, malformed requests, context overflow, explicit user aborts, and permanent quota failures are not treated as transient provider budget candidates.\n",
+	"notebook-tool-runtime.md": "# Notebook runtime internals\n\nThis document describes how coding-agent reads and edits Jupyter notebooks (`.ipynb`) and how that relates to Python execution.\n\nThe critical distinction: **there is no dedicated `notebook` tool, and nothing automatically executes notebook cells**. The notebook-aware `read` route and the `replace`, `patch`, `hashline`, and `apply_patch` edit modes convert a notebook to an editable plain-text cell representation and serialize those edits back to notebook JSON; `vim` and `write` use their ordinary text paths described below. Running Python goes through the `eval` tool (`language: \"py\"`) or the `python` tool. Neither automatically loads notebook cells, though supplied Python code can use ordinary filesystem APIs to read or write files.\n\n## Implementation files\n\n- [`src/edit/notebook.ts`](../packages/coding-agent/src/edit/notebook.ts) — notebook JSON ↔ editable text conversion\n- [`src/edit/read-file.ts`](../packages/coding-agent/src/edit/read-file.ts) — edit-mode read/serialize hooks that route `.ipynb` through the converter\n- [`src/tools/read.ts`](../packages/coding-agent/src/tools/read.ts) — `read` tool notebook branch\n- [`src/tools/eval.ts`](../packages/coding-agent/src/tools/eval.ts), [`src/tools/python.ts`](../packages/coding-agent/src/tools/python.ts) — Python execution surfaces (see [`python-repl.md`](python-repl.md))\n\n## 1) Editable cell representation\n\n`notebookToEditableText()` renders each cell as a marker line followed by the cell source, and joins cells with `\\n`:\n\n```text\n# %% [markdown] cell:0\n# Title\n# %% [code] cell:1\nimport pandas as pd\ndf = pd.read_csv(\"data.csv\")\n# %% [raw] cell:2\n```\n\n- Marker format: `# %% [<cell_type>] cell:<index>`, where `<cell_type>` is `code`, `markdown`, or `raw` and `<index>` is the cell's position in the original notebook.\n- A cell with empty source renders as the marker line alone.\n- Only cell sources are shown. On round-trip, top-level notebook fields and metadata on matched original cells are preserved. Existing outputs and execution counts are preserved only for matched cells that remain code cells; changing a matched cell to a non-code type removes those fields. New and removed cells follow the rules in [Round-trip semantics](#3-round-trip-semantics).\n- A cell source that ends with a newline shows as a blank line before the next marker and round-trips with that newline intact.\n\n## 2) Tool integration\n\n### `read`\n\n- A `.ipynb` path is converted with `readEditableNotebookText()` unless the `:raw` selector is used. `:raw` returns the notebook JSON verbatim.\n- Line selectors and multi-range selectors apply to the converted text, not the JSON. Results are labelled as `notebook` content.\n- See [`tools/read.md`](tools/read.md#jupyter-notebooks) for truncation defaults.\n\n### `edit`\n\nFor `.ipynb` updates, the `replace`, `patch`, and `hashline` edit modes and `apply_patch` updates route existing-file content through `readEditFileText()` and serialize edits through `serializeEditFileText()`. An `apply_patch` create operation skips the read step but still uses the serializer when writing the new `.ipynb` file.\n\n- On the existing-file read path, `readEditFileText()` enforces the `MAX_EDIT_FILE_BYTES` (8 MiB) guard **before** notebook conversion, so an oversized notebook fails fast instead of being parsed on the main thread.\n- For `.ipynb`, the edit mode then operates on the editable text, and `serializeEditFileText()` maps the edited text back to notebook JSON via `serializeEditedNotebookText()`.\n- If the notebook does not exist at serialization time (an edit mode creating a new file), edits apply to a new empty notebook (`nbformat` 4, `nbformat_minor` 5).\n- Notebook JSON is written with `JSON.stringify(notebook, null, 1)`.\n\nThe `vim` edit mode reads the file as UTF-8 text and edits the notebook's raw JSON text directly; it does not use the notebook cell converter. Saving follows the ordinary write-through path.\n\n### `write`\n\n`write` does not use the notebook converter. It follows the ordinary write path and does not translate editable cell markers into notebook JSON, so supply valid notebook JSON when the result should remain a notebook.\n\n## 3) Round-trip semantics\n\n`applyNotebookEditableText()` parses the edited text into cells and rebuilds the `cells` array from a deep clone of the original notebook, so notebook-level `metadata`, `nbformat`, and any other top-level keys are preserved.\n\nFor each parsed cell, in order:\n\n- **Marker with `cell:N` that refers to an unused original cell**: that original cell is cloned, keeping its metadata, outputs, and any other keys. Its `cell_type` is set from the marker and its `source` is replaced.\n  - If the result is a `code` cell, missing `execution_count` / `outputs` are initialized to `null` / `[]`; existing values are kept.\n  - If the result is a non-code cell, `execution_count` and `outputs` are removed.\n- **Marker without `cell:N`, with an out-of-range index, or with an index already used earlier in the text**: a new cell is created with `metadata: {}`; new code cells also get `execution_count: null` and `outputs: []`.\n- Original cells whose markers are removed from the text are dropped.\n\nConsequences:\n\n- Deleting a cell = deleting its marker and source.\n- Inserting a cell = adding a marker without an index (for example `# %% [code]`).\n- Moving a cell = moving its marker block; keeping the original `cell:N` preserves its outputs and metadata.\n- Duplicating a marker's index gives the first occurrence the original cell and makes later occurrences new cells.\n\nCell source is stored as a line array with trailing newlines preserved (`splitNotebookSource()`): every line except the last keeps its `\\n`, and the last line has no forced trailing newline.\n\n## 4) Error surfaces\n\nConversion throws for:\n\n- missing file on read: `File not found: <path>` (serialization of a newly created notebook starts from an empty notebook instead)\n- invalid JSON: `Invalid JSON in notebook: <path>`\n- non-object root or missing `cells` array: `Invalid notebook structure (...)`\n- a cell that is not an object or has a `cell_type` other than `code` / `markdown` / `raw`: `Invalid notebook cell <index> in <path>`\n- edited text whose first line is not a cell marker: `Invalid notebook editable representation for <path>: ...`\n\n## 5) Relationship to Python execution\n\nNotebook conversion and Python execution share no code path:\n\n- Notebook-aware `read`/`edit` paths never start a kernel or execute cells. The edit converter preserves or clears output fields according to the round-trip rules above; it does not execute cells to produce new outputs.\n- `eval` (`language: \"py\"`) and `python` run code in a subprocess-backed Python runner (`src/eval/py/`). Kernel lifecycle, session reuse, cancellation, display capture, and output truncation are documented in [`python-repl.md`](python-repl.md).\n\nTo run code from a notebook, read the relevant cells and pass their source to `eval` or `python` explicitly. No built-in notebook-aware path both edits an `.ipynb` document and automatically executes its cells in a kernel.\n",
 	"onboarding-packet.md": "# Gajae-Code Onboarding Packet\n\nThis packet is a docs-only, public-safe context seed for the `gajae-code` repository as inspected on 2026-06-01. It is intentionally a no-new-skill artifact: not a new workflow skill, command, agent, configuration surface, issue template, or runtime behavior.\n\n## Purpose in one paragraph\n\nGajae-Code is the `gjc` coding-agent CLI and supporting monorepo. The product centers on a small public workflow loop: clarify with `deep-interview`, plan with `ralplan`, execute and verify through `ultragoal`, and run goal-directed research missions with `autoresearch`. The main product package is `packages/coding-agent/`; supporting packages provide LLM/provider access, agent runtime, TUI rendering, native helpers, stats, utilities, benchmarks, and SDK machine interfaces.\n\n## Fixed public surface\n\nKeep this invariant front-and-center when onboarding to the repo:\n\n- Default workflow skills: `autoresearch`, `deep-interview`, `ralplan`, `ultragoal`.\n- Public role agents: `executor`, `architect`, `planner`, `critic`.\n- Bundled default workflow skill sources live under `packages/coding-agent/src/defaults/gjc/skills/`.\n- Bundled role-agent prompt sources live under `packages/coding-agent/src/prompts/agents/`.\n- Runtime state, specs, plans, goals, research missions, and local overrides belong under `.gjc/` for the product and `.omx/` only for this agent-run orchestration.\n\nDo not add a fifth default skill, fifth public role agent, new command, new config surface, or feature-intake behavior unless that product decision has already been made and the default-surface gates are updated.\n\n## Primary entrypoints\n\n| Area             | Repo-relative path                                   | Why it matters                                                                                    |\n| ---------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------- |\n| CLI bootstrap    | `packages/coding-agent/src/cli.ts`                   | Registers top-level CLI commands and routes default launch behavior.                              |\n| Session launch   | `packages/coding-agent/src/main.ts`                  | Converts CLI/runtime settings into agent-session creation and mode dispatch.                      |\n| Agent assembly   | `packages/coding-agent/src/sdk/session.ts`           | Loads settings, default skills, rules, tools, auth/model state, system prompt, and agent runtime. |\n| Built-in tools   | `packages/coding-agent/src/tools/index.ts`           | Registers file, shell, edit, search, browser, task/subagent, and related public coding-harness tools. Memory backends are private integrations, not public tools. |\n| Default skills   | `packages/coding-agent/src/defaults/gjc-defaults.ts` | Embeds and installs the four default workflow skills plus deep-interview fragments.               |\n| Role agents      | `packages/coding-agent/src/task/agents.ts`           | Embeds bundled task-agent prompts; tests enforce public role-agent expectations.                  |\n| Product overview | `README.md`                                          | Explains installation, product story, fixed workflow surface, and development entry commands.     |\n| Architecture map | `docs/codebase-overview.md`                          | Public package map and runtime-flow reference.                                                    |\n\n## Package map\n\n- `packages/coding-agent/` — main `gjc` CLI, workflows, session runtime, tool registry, discovery, settings, prompts, and tests.\n- `packages/ai/` — provider/model boundary, streaming, auth, model registry, retries, and provider integrations.\n- `packages/agent/` — stateful agent loop and append-only context runtime.\n- `packages/tui/` — terminal UI framework and rendering primitives.\n- `packages/natives/` plus `crates/*` — native helpers, Rust/N-API bindings, shell/PTY, text search, AST, filesystem, and media utilities.\n- `packages/utils/` — shared TypeScript utilities, logging, formatting, process helpers, JSON/frontmatter, and sanitization.\n- `packages/stats/` — local observability dashboard and session/model usage aggregation.\n- `packages/typescript-edit-benchmark/` — TypeScript edit benchmark tooling.\n- External machine clients use the broker-bound SDK session CLI, Coordinator MCP, or managed adapters documented in `docs/sdk.md`; `--mode rpc`, `--mode rpc-ui`, `--mode bridge`, and `gjc sdk serve` were removed.\n\n## Build, test, and validation commands\n\nPrefer targeted checks first, then broader checks when code changes justify them. For this docs-only packet, lightweight validation is enough.\n\n| Command                                                               | Scope                               | When to use                                                                 |\n| --------------------------------------------------------------------- | ----------------------------------- | --------------------------------------------------------------------------- |\n| `bun install`                                                         | Workspace dependencies              | Initial local setup.                                                        |\n| `bun run install:defaults`                                            | Local default install               | Installs source-bundled default workflow definitions for local development. |\n| `bun packages/coding-agent/src/cli.ts --help`                         | CLI smoke/discovery                 | Fast source checkout CLI sanity check.                                      |\n| `bun run check:ts`                                                    | Type/lint/default UI checks         | Broad TypeScript validation; heavier than docs-only changes.                |\n| `bun run test`                                                        | Full TS + Rust tests                | Broad regression check; use for runtime/product changes.                    |\n| `bun run ci:test:smoke`                                               | CLI version/help/stats worker smoke | Useful before release/install changes.                                      |\n| `bun scripts/check-visible-definitions.ts`                            | Default surface gate                | Required after workflow-definition changes.                                 |\n| `bun scripts/verify-g002-gates.ts`                                    | Rebrand/default-surface gate        | Required after workflow-definition or public-surface changes.               |\n| `bun scripts/rebrand-inventory.ts --strict`                           | Rebrand inventory gate              | Required after workflow-definition or public-surface changes.               |\n| `bun test packages/coding-agent/test/default-gjc-definitions.test.ts` | Four-skills/four-agents contract    | Required after default workflow/agent surface changes.                      |\n\nRepository rule: do not run `tsc` or `npx tsc`; use the Bun scripts above.\n\n## Danger zones\n\n- **Default surface expansion:** `packages/coding-agent/src/defaults/gjc/skills/`, `packages/coding-agent/src/defaults/gjc-defaults.ts`, `packages/coding-agent/src/prompts/agents/`, and model-assignment tests are contract-heavy. Changes here can accidentally alter the fixed four-skills/four-agents shape.\n- **CLI commands:** `packages/coding-agent/src/cli.ts` and `packages/coding-agent/src/commands/` define visible behavior. Adding commands or aliases is a product-surface change.\n- **Runtime/session assembly:** `packages/coding-agent/src/main.ts`, `packages/coding-agent/src/sdk/session.ts`, discovery, settings, tools, and system-prompt paths can affect every session.\n- **TUI/logging:** Avoid `console.log`, `console.warn`, or `console.error` inside `packages/coding-agent/`; use the centralized logger to avoid corrupting TUI rendering.\n- **Secrets/auth/config:** Keep `docs/secrets.md`, auth broker/gateway code, settings, and environment-variable docs public-safe. Do not expose tokens or private infrastructure.\n- **Native/Rust build:** `packages/natives/` and `crates/*` can require platform-specific toolchains and CI artifact behavior.\n- **Generated model data:** Do not edit `packages/ai/src/models.json` directly; update generators/descriptors/resolvers and regenerate with `bun --cwd=packages/ai run generate-models`.\n\n## Unknowns worth preserving\n\n- Which onboarding packet shape will be most useful for future `gjc` context ingestion is still an experiment, not a product contract.\n- Public issue #158 / `gajae-deep-onboarding` context is summarized only from the user-provided prompt in this run; this packet does not add issue intake or feature workflow behavior.\n- Full CI may depend on runner/system dependencies and native artifacts; docs-only changes usually do not need the full matrix locally.\n- Some packages contain internal or hidden utility prompts/agents beyond the four public role agents. Public-facing docs should keep the four-role contract clear.\n\n## First safe tasks for a new contributor or agent\n\n1. Read `README.md`, `docs/codebase-overview.md`, and this packet.\n2. Run `bun packages/coding-agent/src/cli.ts --help` for a fast CLI surface check after dependencies are installed.\n3. For docs-only edits, run formatting/check commands that do not mutate runtime behavior.\n4. For default-surface edits, run the four required gates listed in the command table before claiming completion.\n5. For package code edits, start with the nearest package test, then escalate to `bun run check:ts` or `bun run test` as risk increases.\n6. Before changing `packages/coding-agent/src/defaults/gjc/skills/`, `packages/coding-agent/src/prompts/agents/`, `packages/coding-agent/src/commands/`, or config/settings paths, write down whether the change alters public surface area.\n\n## Context seed checklist\n\nA future agent can use this packet as context if it preserves these constraints:\n\n- Keep changes public-safe and repo-relative.\n- Prefer docs and tests over new runtime abstractions for onboarding experiments.\n- Treat the fixed four-skills/four-agents shape as a product constraint.\n- Verify claims with repo files before summarizing them.\n- Report validation evidence and caveats instead of implying hidden automation.\n",
 	"onboarding-receipt.md": "# Onboarding Packet Receipt\n\n- Date: 2026-06-01\n- Scope: docs-only no-new-skill onboarding packet experiment for this repository.\n- Output files:\n  - `docs/onboarding-packet.md`\n  - `docs/onboarding-receipt.md`\n- Public-safe boundary: no secrets, tokens, hidden prompts, private infrastructure, internal ops, or private paths beyond repo-relative paths.\n- Product boundary: no new skill, command, agent slot, issue, config, or runtime behavior.\n\n## Evidence inspected\n\n- `README.md`\n- `docs/codebase-overview.md`\n- `package.json`\n- `packages/coding-agent/package.json`\n- `packages/coding-agent/src/cli.ts`\n- `packages/coding-agent/src/main.ts`\n- `packages/coding-agent/src/sdk/session.ts`\n- `packages/coding-agent/src/defaults/gjc-defaults.ts`\n- `packages/coding-agent/src/task/agents.ts`\n- `packages/coding-agent/test/default-gjc-definitions.test.ts`\n- `.github/workflows/ci.yml`\n- `.github/workflows/dev-ci.yml`\n\n## Result\n\nThe packet records repo purpose, package layout, main entrypoints, build/test commands, danger zones, unknowns, and first safe tasks without changing the product surface. It is suitable as a public context seed for future onboarding experiments, not as a feature intake mechanism.\n\n## Caveats\n\n- The attempted `omx question --input '<json>' --json` interview round failed before user input because the runtime reported no attached tmux client; no human answer was inferred from that failed call.\n- Public issue context is limited to the user-provided prompt summary for this run.\n- Full CI was not required for the docs-only artifact unless later code/runtime files change.\n",
 	"ooo-bridge-extension-contract.md": "# Ouroboros `ooo` bridge extension contract\n\nGJC exposes the `ooo` bridge through the existing extension input-event surface. It is not a default workflow skill, hook, slash command, or built-in agent.\n\n## Interception surface\n\nExtensions register an `input` handler:\n\n```ts\nimport { createOuroborosOooBridge } from \"@gajae-code/coding-agent/extensibility/extensions\";\n\nexport default function activate(gjc) {\n  gjc.on(\"input\", createOuroborosOooBridge());\n}\n```\n\nThe handler matches only the bare exact prefix:\n\n- `ooo`\n- `ooo ...`\n\nIt does not match embedded or longer-token text such as `please ooo status`, `oooo`, or `/ooo`.\n\nThe extension runner already treats `InputEventResult.handled === true` as terminal: the input is not sent through normal model flow. An empty result (`{}`) means continue/pass-through, preserving existing chained input handlers and normal prompt handling.\n\n## Dispatch and result semantics\n\n`createOuroborosOooBridge()` has two bounded paths:\n\n- `ooo interview [topic]` starts `ouroboros_interview` through a lazily connected `ouroboros mcp serve --runtime gjc` stdio server.\n- While that interview is active, subsequent ordinary interactive input is claimed as an answer with the same `session_id`. A completed result clears the correlation and closes the MCP connection.\n- Other exact-prefix `ooo ...` commands run `ouroboros dispatch --runtime gjc <full-input>` through `createExactPrefixCommandBridge()`.\n- `OUROBOROS_CLI` overrides the executable for both paths; otherwise the command is `ouroboros`.\n\nSuccessful handled text is returned as `{ handled: true, text }`. The interactive input controller renders that text as a visible custom message before clearing the composer, so the first interview question, continuation questions, completion result, and successful non-interview command output reach the user.\n\nCommand-dispatch exit mapping remains:\n\n| Dispatch result | GJC input result |\n| --- | --- |\n| `0` | `{ handled: true, text? }`; render non-empty stdout (or stderr when stdout is empty) and do not send the input to the model. |\n| `78` | `{}`; continue/pass-through so GJC processes the input normally. |\n| any other non-zero | Surface an extension error notification using stderr, then stdout, then a generic exit-code message, and return `{ handled: true }`; the failed `ooo` command is terminal and is not sent to the model. |\n\nMCP interview errors are notified and handled. A non-terminal response must contain a valid `interview_*` session ID in MCP `_meta` (with the visible `Session ...` text accepted as a compatibility fallback); otherwise the bridge fails closed instead of accepting an uncorrelated answer.\n\nRunner timeout aborts the handler context signal. The bridge passes that signal to MCP connection/tool calls and generation-fences every post-await state mutation, so a late settlement cannot recreate correlation after the runner has fallen through. Any MCP connection or tool failure clears the interview session and cached transport before notifying; a later ordinary prompt therefore passes through, while a new explicit `ooo interview` reconnects cleanly.\n\nSlash-prefixed UI commands bypass interview capture. The bare continue controls `.` and `c` also remain GJC controls; other ordinary text remains a valid interview answer.\n\nThe installed example also registers `session_switch` disposal because GJC reuses one `ExtensionRunner` across `/new`, `/drop`, resume, and fork transitions. Session-changing input controls reset immediately, including `/clear`, and the lifecycle hook covers identity changes initiated outside the input path. Interview startup and continuation calls share one FIFO operation chain: a second submission during startup is claimed and waits for the session ID, while overlapping answers issue one MCP call at a time against the latest settled state. Every queue entry is bound to the lifecycle generation at submission, so resets consume predecessor-generation entries—including explicit `ooo interview` starts—without calling MCP in the successor session.\n\n## Recursion guard\n\nBefore command dispatch, the exact-prefix helper increments the Ouroboros bridge recursion-depth environment variable and restores its previous value after dispatch finishes. A current numeric depth of `0` or `1` is dispatchable. A current numeric depth greater than `1`, or any non-empty non-numeric value, returns `{}` without dispatching. The guard also passes through `event.source === \"extension\"` to avoid extension-originated messages re-entering the bridge.\n\n## Installation and discovery\n\n### Runtime status\n\nSession startup loads filesystem extension modules. Unless `options.disableExtensionDiscovery` is set, `createAgentSession` calls `discoverAndLoadExtensions` with the explicit `options.additionalExtensionPaths`, the `extensions` setting, and the canonical native locations below, applying the `disabledExtensions` setting to every form discovery reaches (`disableExtensionDiscovery` keeps its documented opt-out semantics: the explicit `additionalExtensionPaths` load as given, exactly like `cli/list-models.ts`). `options.preloadedExtensions` short-circuits discovery for a caller that already loaded extensions. A discovered module that fails to import is reported through the shared logger and skipped while the remaining modules still load. If discovery itself fails, the session warns, records the failure in `extensionsResult.errors`, and degrades to the explicitly configured paths — and then to no extensions at all — instead of failing session creation; a single unreadable, unresolvable, or pathological configured entry cannot drop the extensions that other sources contribute.\n\nDisabling one module is `disabledExtensions: [\"extension-module:<name>\"]`; the retired `--no-extensions` / `--extension` CLI flags are not a control surface here (ACP-only launch flags).\n\nA bridge installed under the locations below is therefore discovered and activated, and its `input` handler runs. `gjc customize doctor` is read-only and never executes a module, so it reports the module as `[stored-only]` and says why its dynamic registrations remain opaque:\n\n```text\nouroboros-ooo-bridge  [stored-only]  gjc/user  (canonical)\n  reason: managed — Trusted filesystem extension module discovered for session-start\n          loading. Doctor does not execute the module, so its runtime input handlers,\n          tools, commands, and flags remain opaque until a session loads it.\n```\n\nGJC plugin bundles carry `subskills`, `tools`, `hooks`, `mcps`, `system_appendix`, and `agent-appendix` (`docs/gjc-plugins.md`). An `input`-event surface is still outside that set, so a bundle cannot deliver this bridge; the extension module location below is its supported delivery surface.\n\n### Pinned Ouroboros baseline\n\nThis path is verified against [Q00/ouroboros `v0.50.7`](https://github.com/Q00/ouroboros/releases/tag/v0.50.7). Install its MCP profile at the exact version, then configure GJC:\n\n```bash\nuv tool install 'ouroboros-ai[mcp]==0.50.7'\nouroboros setup --runtime gjc\n```\n\n`pipx install 'ouroboros-ai[mcp]==0.50.7'` is equivalent. Do not pipe a mutable branch installer into a shell. Pin source audits to commit `cb658aa819bfabafecbbe91bc36327f10691171b`. The release asset `ouroboros_ai-0.50.7-py3-none-any.whl` has SHA-256 `df42f4ef10e032f2edc3249534bf91e8612dee789dfc3517895a9eb2df7f82c4`; compare a downloaded asset with that digest before installation.\n\n### Verified GJC bridge installation\n\nOuroboros setup installs its own managed GJC bridge. Replace it with the standalone GJC bridge from immutable commit `4311fefd49e9c6781c4d1111b8dd3f758e7d8974`, whose example file has SHA-256 `2b0e1e25ac145331f112da629076875542db6f6e63c3c17adcd6770a4dcaf7bd`:\n\n```bash\ncurl -fL https://raw.githubusercontent.com/Yeachan-Heo/gajae-code/4311fefd49e9c6781c4d1111b8dd3f758e7d8974/packages/coding-agent/examples/extensions/ooo-bridge.ts -o /tmp/gjc-ooo-bridge.ts\nshasum -a 256 /tmp/gjc-ooo-bridge.ts\nmkdir -p \"${HOME}/${GJC_CONFIG_DIR:-.gjc}/agent/extensions/ouroboros-ooo-bridge\" && cp /tmp/gjc-ooo-bridge.ts \"${HOME}/${GJC_CONFIG_DIR:-.gjc}/agent/extensions/ouroboros-ooo-bridge/index.ts\"\n```\n\nThe `shasum` output must match the published example digest before the copy. The example has no runtime imports: it obtains the bundled bridge helper from the injected extension API, so the copied file works in compiled GJC binaries without extension-local `node_modules`. For project-only installation, copy the same verified file to `.gjc/extensions/ouroboros-ooo-bridge/index.ts`. Start a new GJC session after installation, then run:\n\n```text\nooo interview \"I want to build a task management CLI\"\n```\n\nSet `OUROBOROS_CLI=/absolute/path/to/ouroboros` when the executable is outside `PATH`.\n\n### Native interview versus external Ouroboros interview\n\n- `/skill:deep-interview` is GJC's bundled native interview workflow. It includes Ouroboros-inspired behavior but does not invoke the external CLI.\n- `ooo interview` is the external integration. It calls Ouroboros's MCP interview tool, renders each question in GJC, correlates ordinary answers by Ouroboros session ID, and stops claiming input when the interview completes.\n\nThe canonical install location is the agent extensions directory discovered by the native GJC provider:\n\n- user-level: `$HOME/${GJC_CONFIG_DIR:-.gjc}/agent/extensions`\n- project-level: `<cwd>/.gjc/extensions`\n\nFor native discovery, install one of:\n\n- `extensions/<name>.ts` or `extensions/<name>.js`\n- `extensions/<name>/index.ts` or `extensions/<name>/index.js`\n- `extensions/<name>/package.json` declaring extension entries\n\nThe loader scans one level under each `extensions` directory. Complex packages should use a package manifest instead of relying on recursive discovery.\n\n`GJC_CONFIG_DIR` selects the **home-relative** config directory name: the config root is `<home>/<GJC_CONFIG_DIR>`, defaulting to `~/.gjc`. It does not select a project directory — the project-level path is the constant `.gjc` (`discovery/helpers.ts`, `getProjectAgentDir()`), so `GJC_CONFIG_DIR` never moves it. `GJC_CODING_AGENT_DIR` overrides the agent directory **path** rather than naming one under `$HOME`; it is resolved with `path.resolve`, so an absolute value is used as-is and a relative value is resolved against the current working directory.\n\nNative discovery honors the selected agent directory profile. With no override it derives the user-level root from `GJC_CONFIG_DIR` (`<home>/<config-dir>/agent`); when `GJC_CODING_AGENT_DIR` is set, extension, skill, rule, hook, settings, and custom-tool discovery use that explicit agent directory. Explicit-home loads still derive or receive their agent directory from the supplied home and never fall back to the process-global profile.\n\nHooks are not the input bridge surface: `packages/coding-agent/src/capability/hook.ts` defines pre/post tool hooks only.\n",
@@ -85,20 +85,21 @@ export const EMBEDDED_DOCS: Readonly<Record<string, string>> = {
 	"prompt-architect-reports/system-prompts.raw.md": "# SystemPrompts recovered raw context\n\nThe original `agent://1-SystemPrompts` result failed. Inspecting the subagent JSONL context recovered broad coverage evidence (106 tool calls) but no `report_finding` entries and no final `yield`.\n\nCanonical recovered artifacts:\n\n- `recovered-context/1-SystemPrompts.recovered.md`\n- `recovered-context/1-SystemPrompts.findings.json` (empty)\n- `recovery-summary.md`\n\nNo valid system-prompt verdict was emitted before the session died on stalls/429.\n",
 	"prompt-architect-reports/tool-prompts.raw.md": "# ToolPrompts recovered raw report\n\nThe original `agent://0-ToolPrompts` result surfaced as failed, but inspecting the subagent JSONL context recovered 34 structured `report_finding` entries before the session died on stalls/429.\n\nCanonical recovered artifacts:\n\n- `recovered-context/0-ToolPrompts.recovered.md`\n- `recovered-context/0-ToolPrompts.findings.json`\n- `recovery-summary.md`\n\nRecovered severity breakdown: P1 = 4, P2 = 18, P3 = 12. No final `yield` or grade was emitted.\n",
 	"provider-streaming-internals.md": "# Provider streaming internals\n\nThis document explains how token/tool streaming is normalized in `@gajae-code/ai`, then propagated through `@gajae-code/agent-core` and `coding-agent` session events.\n\n## End-to-end flow\n\n1. `streamSimple()` (`packages/ai/src/stream.ts`) maps generic options and dispatches to a provider stream function.\n2. Provider stream functions translate provider-native stream events into the unified `AssistantMessageEvent` sequence. Current built-ins include Anthropic, OpenAI Responses/Completions/OpenAI code/Azure Responses, Google Gemini/Gemini CLI/Vertex, Bedrock Converse, Ollama, Cursorand GitLab Duo/Kimi wrappers.\n3. Each provider pushes events into `AssistantMessageEventStream` (`packages/ai/src/utils/event-stream.ts`), which throttles delta events and exposes:\n   - async iteration for incremental updates\n   - `result()` for final `AssistantMessage`\n4. `agentLoop` (`packages/agent/src/agent-loop.ts`) consumes those events, mutates in-flight assistant state, and emits `message_update` events carrying the raw `assistantMessageEvent`.\n5. `AgentSession` (`packages/coding-agent/src/session/agent-session.ts`) subscribes to agent events, persists messages, and applies session behaviors (retry, compaction, TTSR, streaming-edit abort checks).\n\n## Unified stream contract in `@gajae-code/ai`\n\nAll providers emit the same shape (`AssistantMessageEvent` in `packages/ai/src/types.ts`):\n\n- `start`\n- content block lifecycle triplets:\n  - text: `text_start` → `text_delta`\\* → `text_end`\n  - thinking: `thinking_start` → `thinking_delta`\\* → `thinking_end`\n  - tool call: `toolcall_start` → `toolcall_delta`\\* → `toolcall_end`\n- terminal event:\n  - `done` with `reason: \"stop\" | \"length\" | \"toolUse\"`\n  - or `error` with `reason: \"aborted\" | \"error\"`\n\n`AssistantMessageEventStream` guarantees:\n\n- final result is resolved by terminal event (`done` or `error`)\n- deltas are batched/throttled (~50ms)\n- buffered deltas are flushed before non-delta events and before completion\n\n## Delta throttling and harmonization behavior\n\n`AssistantMessageEventStream` treats `text_delta`, `thinking_delta`, and `toolcall_delta` as mergeable events:\n\n- buffered deltas are merged only when **type + contentIndex** match\n- merge keeps the latest `partial` snapshot\n- non-delta events force immediate flush\n\nThis smooths high-frequency provider streams for TUI/event consumers, but is not provider backpressure: providers still produce at full speed, while the local stream buffers.\n\n## Provider normalization details\n\n## Anthropic (`anthropic-messages`)\n\nSource: `packages/ai/src/providers/anthropic.ts`\n\nNormalization points:\n\n- `message_start` initializes usage (input/output/cache tokens)\n- `content_block_start` maps to text/thinking/toolcall starts\n- `content_block_delta` maps:\n  - `text_delta` → `text_delta`\n  - `thinking_delta` → `thinking_delta`\n  - `input_json_delta` → `toolcall_delta`\n  - `signature_delta` updates `thinkingSignature` only (no event)\n- `content_block_stop` emits corresponding `*_end`\n- `message_delta.stop_reason` maps via `mapStopReason()`\n\nTool-call argument streaming:\n\n- each tool block carries internal `partialJson`\n- every JSON delta appends to `partialJson`\n- `arguments` are reparsed on each delta via `parseStreamingJson()`\n- `toolcall_end` reparses once more, then strips `partialJson`\n\n## OpenAI Responses family (`openai-responses`, `openai-code-responses`, `azure-openai-responses`)\n\nSources: `packages/ai/src/providers/openai-responses.ts`, `openai-code-responses.ts`, and `azure-openai-responses.ts`\n\nNormalization points:\n\n- `response.output_item.added` starts reasoning/text/function-call blocks\n- reasoning summary events (`response.reasoning_summary_text.delta`) become `reasoning_summary_delta` and update the message's thinking block\n- output/refusal deltas become `text_delta`\n- `response.function_call_arguments.delta` becomes `toolcall_delta`\n- `response.output_item.done` emits `thinking_end` / `text_end` / `toolcall_end`\n- `response.completed` maps status to stop reason and usage\n\nTool-call argument streaming:\n\n- same `partialJson` accumulation pattern as Anthropic\n- providers that send only `response.function_call_arguments.done` still populate final args\n- tool call IDs are normalized as `\"<call_id>|<item_id>\"`\n\n## Google Generative AI (`google-generative-ai`)\n\nSource: `packages/ai/src/providers/google.ts`\n\nNormalization points:\n\n- iterates `candidate.content.parts`\n- text parts are split into thinking vs text by `isThinkingPart(part)`\n- block transitions close previous block before starting a new one\n- `part.functionCall` is treated as a complete tool call (start/delta/end emitted immediately)\n- finish reason mapped by `mapStopReason()` from `google-shared.ts`\n\nTool-call argument streaming:\n\n- function call args arrive as structured object, not incremental JSON text\n- implementation emits one synthetic `toolcall_delta` containing `JSON.stringify(arguments)`\n- no partial JSON parser needed for Google in this path\n\n## Partial tool-call JSON accumulation and recovery\n\nShared behavior for Anthropic/OpenAI Responses uses `parseStreamingJson()` (`packages/ai/src/utils/json-parse.ts`):\n\n1. try `JSON.parse`\n2. fallback to `partial-json` parser for incomplete fragments\n3. if both fail, return `{}`\n\nImplications:\n\n- malformed or truncated argument deltas do not crash stream processing immediately\n- in-progress `arguments` may temporarily be `{}`\n- later valid deltas can recover structured arguments because parsing is retried on every append\n- final `toolcall_end` performs one more parse attempt before emission\n\n## Stop reasons vs transport/runtime errors\n\nProvider stop reasons are mapped to normalized `stopReason`:\n\n- Anthropic: `end_turn`→`stop`, `max_tokens`→`length`, `tool_use`→`toolUse`, safety/refusal cases→`error`\n- OpenAI Responses: `completed`→`stop`, `incomplete`→`length`, `failed/cancelled`→`error`\n- Google: `STOP`→`stop`, `MAX_TOKENS`→`length`, safety/prohibited/malformed-function-call classes→`error`\n\nError semantics are split in two stages:\n\n1. **Model completion semantics** (provider reported finish reason/status)\n2. **Transport/runtime failure** (network/client/parser/abort exceptions)\n\nIf provider stream throws or signals failure, each provider wrapper catches and emits terminal `error` event with:\n\n- `stopReason = \"aborted\"` when abort signal is set\n- otherwise `stopReason = \"error\"`\n- `errorMessage = formatErrorMessageWithRetryAfter(error)`\n\n## Malformed chunk / SSE parse failure behavior\n\nFor these provider paths, chunk/SSE framing is handled by vendor SDK streams (Anthropic SDK, OpenAI SDK, Google SDK). This code does not implement a custom SSE decoder here.\n\nObserved behavior in current implementation:\n\n- malformed chunk/SSE parsing at SDK level surfaces as an exception or stream `error` event\n- provider wrapper converts that into unified terminal `error` event\n- no provider-specific resume/retry inside the stream function itself\n- higher-level retries are handled in `AgentSession` auto-retry logic (message-level retry, not stream-chunk replay)\n\n## Cancellation boundaries\n\nCancellation is layered:\n\n- AI provider request: `options.signal` is passed into provider client stream call.\n- Provider wrapper: after stream loop, aborted signal forces error path (`\"Request was aborted\"`).\n- Agent loop: checks `signal.aborted` before handling each provider event and can synthesize an aborted assistant message from the latest partial.\n- Session/agent controls: `AgentSession.abort()` -> `agent.abort()` -> shared abort controller cancellation.\n\nTool execution cancellation is separate from model stream cancellation:\n\n- tool runners use `AbortSignal.any([agentSignal, steeringAbortSignal])`\n- steering interrupts can abort remaining tool execution while preserving already-produced tool results\n\n## Backpressure boundaries\n\nThere is no hard backpressure mechanism between provider SDK stream and downstream consumers:\n\n- `EventStream` uses in-memory queues with no max size\n- throttling reduces UI update rate but does not slow provider intake\n- if consumers lag significantly, queued events can grow until completion\n\nCurrent design favors responsiveness and simple ordering over bounded-buffer flow control.\n\n## How stream events surface as agent/session events\n\n`agentLoop.streamAssistantResponse()` bridges `AssistantMessageEvent` to `AgentEvent`:\n\n- on `start`: pushes placeholder assistant message and emits `message_start`\n- on block events (`text_*`, `thinking_*`, `reasoning_summary_*`, `toolcall_*`): updates last assistant message, emits `message_update` with raw `assistantMessageEvent`\n- on terminal (`done`/`error`): resolves final message from `response.result()`, emits `message_end`\n\nFor ordinary unmanaged turns, the first content event publishes the provisional\nnonterminal lifecycle, including reasoning-only and tool-only streams. Subsequent\nupdates are delivered live without waiting for text, response completion, or an\ninterrupt. This is presentation, not tool acceptance: terminal validation and the\nconsumer drain still precede execution. A legacy guarded call that has already\nbeen published receives an explicit rejection instead of silently disappearing\nthrough same-turn resampling; unpublished terminal-only attempts can still retry.\nManaged fallback attempts retain atomic publication/discard semantics and do not\nuse this unmanaged early-publication path.\n\n`AgentSession` then consumes those events for session-level behaviors:\n\n- TTSR watches `message_update.assistantMessageEvent` for `text_delta`, `thinking_delta`, and `toolcall_delta`\n- streaming edit guard inspects `toolcall_delta`/`toolcall_end` on `edit` calls and can abort early\n- persistence writes finalized messages at `message_end`\n- auto-retry examines assistant `stopReason === \"error\"` plus `errorMessage` heuristics\n\n## Unified vs provider-specific responsibilities\n\nUnified (common contract):\n\n- event shape (`AssistantMessageEvent`)\n- final result extraction (`done`/`error`)\n- delta throttling + merge rules\n- agent/session event propagation model\n\nProvider-specific (not fully abstracted):\n\n- upstream event taxonomies and mapping logic\n- stop-reason translation tables\n- tool-call ID conventions\n- reasoning/thinking block semantics and signatures\n- usage token semantics and availability timing\n- message conversion constraints per API\n\n## Implementation files\n\n- [`../../ai/src/stream.ts`](../packages/ai/src/stream.ts) — provider dispatch, option mapping, API key/session plumbing, custom API dispatch, and provider-specific credential handling.\n- [`../../ai/src/utils/event-stream.ts`](../packages/ai/src/utils/event-stream.ts) — generic stream queue + assistant delta throttling.\n- [`../../ai/src/utils/json-parse.ts`](../packages/ai/src/utils/json-parse.ts) — partial JSON parsing for streamed tool arguments.\n- [`../../ai/src/providers/anthropic.ts`](../packages/ai/src/providers/anthropic.ts) — Anthropic event translation and tool JSON delta accumulation.\n- [`../../ai/src/providers/openai-responses.ts`](../packages/ai/src/providers/openai-responses.ts), [`openai-code-responses.ts`](../packages/ai/src/providers/openai-code-responses.ts), [`azure-openai-responses.ts`](../packages/ai/src/providers/azure-openai-responses.ts) — Responses-family event translation and status mapping.\n- [`../../ai/src/providers/google.ts`](../packages/ai/src/providers/google.ts), [`google-gemini-cli.ts`](../packages/ai/src/providers/google-gemini-cli.ts), [`google-vertex.ts`](../packages/ai/src/providers/google-vertex.ts) — Gemini stream chunk-to-block translation variants.\n- [`../../ai/src/providers/google-shared.ts`](../packages/ai/src/providers/google-shared.ts) — Gemini finish-reason mapping and shared conversion rules.\n- [`../../ai/src/providers/amazon-bedrock.ts`](../packages/ai/src/providers/amazon-bedrock.ts), [`openai-completions.ts`](../packages/ai/src/providers/openai-completions.ts), [`ollama.ts`](../packages/ai/src/providers/ollama.ts), [`cursor.ts`](../packages/ai/src/providers/cursor.ts) — additional built-in stream adapters using the same event contract.\n- [`../../agent/src/agent-loop.ts`](../packages/agent/src/agent-loop.ts) — provider stream consumption and `message_update` bridging.\n- [`../src/session/agent-session.ts`](../packages/coding-agent/src/session/agent-session.ts) — session-level handling of streaming updates, abort, retry, and persistence.\n",
-	"python-repl.md": "# Eval Tool Python Backend\n\nThis document describes the Python execution stack in `packages/coding-agent`.\nIt covers tool behavior, runner lifecycle, environment handling, execution semantics, output rendering, supported magics, and operational failure modes.\n\n## Scope and Key Files\n\n- Tool surface: `src/tools/eval.ts`\n- Session/per-call kernel orchestration: `src/eval/py/executor.ts`\n- Subprocess kernel client: `src/eval/py/kernel.ts`\n- Python wrapper / NDJSON server: `src/eval/py/runner.py`\n- Prelude helpers loaded into every kernel: `src/eval/py/prelude.py`\n- MIME bundle renderer (text + structured outputs): `src/eval/py/display.ts`\n- Interactive-mode renderer for user-triggered Python runs: `src/modes/components/eval-execution.ts`\n- Runtime/env filtering and Python resolution: `src/eval/py/runtime.ts`\n\n## What eval's Python backend is\n\nThe `eval` tool executes one or more Python cells inside a long-lived `python3` subprocess that speaks NDJSON over stdin/stdout. No Jupyter, no kernel gateway, no extra pip dependencies — a vanilla Python 3.8+ interpreter is enough. Rich `display()` output (PIL, pandas, plotly, matplotlib figures) keeps working because the wrapper reimplements the MIME-bundle dispatch that IPython previously provided.\n\nTool params:\n\n```ts\n{\n  cells: Array<{ code: string; title?: string }>;\n  timeout?: number; // seconds, clamped to 1..600, default 30\n  reset?: boolean; // reset selected runtime before the first cell only\n}\n```\n\nThe tool is `concurrency = \"exclusive\"` for a session, so calls do not overlap.\n\n## Kernel lifecycle\n\nEach kernel is a single Python subprocess: `python -u <runner.py>`. The bundled runner is materialized once per GJC process in a process-private temporary directory and file, then reused only by subsequent spawns within that process.\n\nKernel startup sequence:\n\n1. Availability check (`checkPythonKernelAvailability`) — verifies that a Python interpreter resolves and runs.\n2. Spawn `python -u runner.py` with filtered env and `cwd`.\n3. Send an init request that runs `os.chdir(cwd)`, injects env entries, and adds `cwd` to `sys.path`.\n4. Execute `PYTHON_PRELUDE` (idempotent — only initializes once per process).\n\nKernel shutdown:\n\n- Send `{\"type\": \"exit\"}` over stdin.\n- Wait for process exit with `SHUTDOWN_GRACE_MS` budget.\n- Escalate to `SIGTERM` and finally `SIGKILL` if the process does not exit in time.\n\n## Wire protocol (NDJSON, host ↔ runner)\n\nOne JSON object per line, UTF-8, `\\n` terminated.\n\nHost → runner:\n\n```jsonc\n{\"id\": \"<reqId>\", \"code\": \"<source>\", \"silent\": false, \"storeHistory\": true}\n{\"type\": \"exit\"}\n```\n\nRunner → host:\n\n```jsonc\n{\"type\": \"started\",  \"id\": \"<reqId>\"}\n{\"type\": \"stdout\",   \"id\": \"<reqId>\", \"data\": \"...\"}\n{\"type\": \"stderr\",   \"id\": \"<reqId>\", \"data\": \"...\"}\n{\"type\": \"display\",  \"id\": \"<reqId>\", \"bundle\": {<mime>: <value>}}\n{\"type\": \"result\",   \"id\": \"<reqId>\", \"bundle\": {<mime>: <value>}}\n{\"type\": \"error\",    \"id\": \"<reqId>\", \"ename\": \"...\", \"evalue\": \"...\", \"traceback\": [\"...\"]}\n{\"type\": \"done\",     \"id\": \"<reqId>\", \"status\": \"ok\"|\"error\", \"executionCount\": N, \"cancelled\": false}\n```\n\nStatus events the prelude emits (e.g. `_emit_status(\"find\", count=…)`) ship inside display bundles under `application/x-gjc-status` so the existing TUI status renderer keeps working.\n\n## Magics\n\nThe runner's source transformer rewrites IPython-style magics to plain Python calls before parsing. Supported set:\n\n| Magic | Effect |\n| --- | --- |\n| `%pip <args>` | `python -m pip <args>` with live streaming output. Newly installed packages are evicted from `sys.modules` so the next `import` picks up the fresh install. |\n| `%cd <path>` | `os.chdir(path)` (with `~` expansion); emits status event. |\n| `%pwd` | Returns `os.getcwd()`. |\n| `%ls [path]` | Returns `sorted(os.listdir(path))`. |\n| `%env [KEY[=VAL]]` | List, read, or set env vars (matches prelude `env()` semantics). |\n| `%set_env KEY VALUE` | Set `os.environ[KEY]`. |\n| `%time <expr>` / `%timeit <expr>` | Time the expression; emits status event with elapsed ms. |\n| `%who` / `%whos` | List user-namespace names. |\n| `%reset` | Clear user globals and re-inject prelude. |\n| `%load <path>` | Read a file into a fresh cell and execute. |\n| `%run <path>` | `runpy.run_path` and merge globals back. |\n| `%%bash` / `%%sh` | Run the cell body via `bash`/`sh`. |\n| `%%capture [name]` | Run body with stdout/stderr captured into `name`. |\n| `%%timeit` | Time the cell body. |\n| `%%writefile <path>` | Write body to file. |\n| `!cmd` / `var = !cmd` | Run command via subprocess shell; returns an SList-style result with `.n` / `.s` helpers. |\n| `var = %name args` | Assignment forms work for line magics and `!cmd`. |\n\nUnknown magic names raise `NameError: UsageError: ...` inside the cell.\n\n## Session persistence semantics\n\n`python.kernelMode` controls retained kernel reuse:\n\n- `session` (default)\n  - Reuses kernel sessions keyed by session file plus cwd when a session file exists; otherwise by cwd.\n  - Execution is serialized per session via a queue.\n  - Idle sessions are evicted after 5 minutes.\n  - At most 4 sessions; oldest is evicted on overflow.\n  - Heartbeat checks detect dead kernels.\n  - Auto-restart allowed once; repeated crash ⇒ hard failure.\n- `per-call`\n  - Spawns a fresh subprocess for each request.\n  - Shuts the subprocess down after the request.\n  - No cross-call state persistence.\n\n### Kernel ownership\n\nRetained kernels are keyed by an **owner id**, and there are two kinds of owner:\n\n- **Session-owned** (the `eval` tool) — derived from the session file plus cwd as described above. Reaped when the session disposes.\n- **Explicitly-owned** (the `python` tool) — the caller supplies `kernelOwnerId`, which is `python:<session-id>`. This is deliberately distinct from the session's eval owner id so the two never alias and a Python REPL kernel is never reaped as collateral of eval cleanup.\n\n`disposeKernelSessionsByOwner(ownerId)` disposes every retained kernel for one owner and is idempotent, so disposing an owner twice is not a double free.\n\nOwner-scoped kernels are reaped on all three exits:\n\n- the owning tool's own teardown action (for `python`, `action: \"clear\"`),\n- session cleanup, which also handles session identity transitions,\n- signal exit (Ctrl-C), via `disposeChildSubprocesses`, which also drains both registries inside a single bounded budget.\n\n`gjc autoresearch clear` clears autoresearch state only; it does not dispose a Python kernel.\n\nA tool registering through the SDK's `registerSessionCleanup` lands in the **transition** cleanup registry, not the session one. Draining only the session registry on signal exit left explicitly-owned kernels running after Ctrl-C while graceful dispose looked correct.\n\n### Multi-cell behavior in a single tool call\n\nCells run sequentially in the same kernel instance for that tool call.\n\nIf an intermediate cell fails:\n\n- Earlier cell state remains in memory.\n- Tool returns a targeted error indicating which cell failed.\n- Later cells are not executed.\n\n`reset=true` only applies to the first cell execution in that call.\n\n## Environment filtering and runtime resolution\n\nEnvironment is filtered before launching the runner:\n\n- Allowlist includes core vars like `PATH`, `HOME`, locale vars, `VIRTUAL_ENV`, `PYTHONPATH`, etc.\n- Allow-prefixes: `LC_`, `XDG_`, `GJC_`\n- Denylist strips common API keys (OpenAI/Anthropic/Gemini/etc.)\n\nRuntime selection order:\n\n1. Active/located venv (`VIRTUAL_ENV`, then `<cwd>/.venv`, `<cwd>/venv`)\n2. Managed venv at `~/.gjc/python-env`\n3. `python` or `python3` on PATH\n\nWhen a venv is selected, its bin/Scripts path is prepended to `PATH`.\n\nThe runner additionally receives `PYTHONUNBUFFERED=1` and `PYTHONIOENCODING=utf-8` so streamed output reaches the host promptly.\n\n## Tool availability and mode selection\n\n`eval.py` / `eval.js` (both default `true`) plus optional `GJC_PY` override controls eval backend exposure:\n\n- Python backend only (`eval.py=true`, `eval.js=false`)\n- JavaScript backend only (`eval.py=false`, `eval.js=true`)\n- both backends\n\n`GJC_PY` accepted values:\n\n- `0` / `bash` → JavaScript backend only\n- `1` / `py` → Python backend only\n- `mix` / `both` → both backends\n\nIf Python preflight fails and `eval.js` is enabled, `eval` remains available and dispatches to JavaScript unless `language: \"python\"` is explicitly requested.\n\n## Execution flow and cancellation/timeout\n\n### Tool-level timeout\n\n`eval` timeout is in seconds, default 30, clamped to `1..600`. The tool combines caller abort signal and timeout signal with `AbortSignal.any(...)`.\n\n### Kernel execution cancellation\n\nOn abort/timeout:\n\n- The host sends `kill(\"SIGINT\")` to the runner subprocess.\n- The runner's exec-time signal handler raises `KeyboardInterrupt` inside the user code.\n- Result includes `cancelled=true`; timeout path annotates output as `Command timed out after <n> seconds`.\n- Between requests the runner installs `SIG_IGN` for SIGINT so a stray cancel does not tear down the kernel.\n\nIf a second cancel is required (runner stuck in C code), the host escalates to `SIGTERM` and the session restarts on the next call.\n\n### stdin behavior\n\nInteractive stdin is not supported. The runner does not forward `input()` prompts; user code that calls `input()` blocks until cancellation.\n\n## Output capture and rendering\n\n### Captured output classes\n\nFrom runner frames:\n\n- `stdout` / `stderr` → plain text chunks\n- `display` / `result` → rich display handling (MIME bundle)\n- `error` → traceback text\n- `application/x-gjc-status` MIME inside `display` → structured status events\n\nDisplay MIME precedence:\n\n1. `text/markdown`\n2. `text/plain`\n3. `text/html` (converted to basic markdown)\n\nAdditionally captured as structured outputs:\n\n- `application/json` → JSON tree data\n- `image/png` / `image/jpeg` → image payloads\n- `application/x-gjc-status` → status events\n\n### Matplotlib\n\nThe runner sets `MPLBACKEND=Agg` as an environ default so figures render off-screen. After every cell, `pyplot.get_fignums()` is iterated; each figure is saved to PNG, emitted as an `image/png` display, and closed.\n\n### Storage and truncation\n\nOutput is streamed through `OutputSink` and may be persisted to artifact storage. Tool results can include truncation metadata and `artifact://<id>` for full output recovery.\n\n### Renderer behavior\n\n- Tool renderer (`eval.ts`):\n  - shows code-cell blocks with per-cell status\n  - collapsed preview defaults to 10 lines\n  - supports expanded mode for full output and richer status detail\n- Interactive renderer (`eval-execution.ts`):\n  - used for user-triggered Python execution in TUI\n  - collapsed preview defaults to 20 lines\n  - clamps very long individual lines to 4000 chars for display safety\n  - shows cancellation/error/truncation notices\n\n## Operational troubleshooting\n\n- **Python backend not available** — Check `eval.py`, `GJC_PY`, and that `python`/`python3` is on PATH. If preflight fails and `eval.js` is enabled, omit `language` or pass `language: \"js\"` to use JavaScript.\n- **No Python on PATH** — Install a system Python 3.8+ or place a venv at `~/.gjc/python-env`. `gjc setup python --check` reports the resolved interpreter.\n- **Execution hangs then times out** — Increase tool `timeout` (max 600s) if workload is legitimate. For stuck native code, cancellation triggers `SIGINT` first then escalates; the session restarts on the next request.\n- **stdin/input prompts in Python code** — `input()` is not supported; pass data programmatically.\n- **Working directory errors** — Tool validates `cwd` exists and is a directory before execution.\n\n## Relevant environment variables\n\n- `GJC_PY` — tool exposure override\n- `GJC_PYTHON_SKIP_CHECK=1` — bypass Python preflight/warm checks\n- `GJC_PYTHON_INTEGRATION=1` — enable gated integration tests that spawn a real Python\n- `GJC_PYTHON_IPC_TRACE=1` — log NDJSON frames exchanged with the runner subprocess\n",
+	"python-repl.md": "# Eval Tool Python Backend\n\nThis document describes the Python execution stack in `packages/coding-agent`.\nIt covers tool behavior, runner lifecycle, environment handling, execution semantics, output rendering, supported magics, and operational failure modes.\n\n## Scope and Key Files\n\n- Tool surface: `src/tools/eval.ts`\n- Session/per-call kernel orchestration: `src/eval/py/executor.ts`\n- Subprocess kernel client: `src/eval/py/kernel.ts`\n- Python wrapper / NDJSON server: `src/eval/py/runner.py`\n- Prelude helpers loaded into every kernel: `src/eval/py/prelude.py`\n- MIME bundle renderer (text + structured outputs): `src/eval/py/display.ts`\n- Interactive-mode renderer for user-triggered Python runs: `src/modes/components/eval-execution.ts`\n- Runtime/env filtering and Python resolution: `src/eval/py/runtime.ts`\n\n## What eval's Python backend is\n\nThe `eval` tool executes one or more Python cells inside a long-lived `python3` subprocess that speaks NDJSON over stdin/stdout. No Jupyter, no kernel gateway, no extra pip dependencies — a vanilla Python 3.8+ interpreter is enough. Rich `display()` output (PIL, pandas, plotly, matplotlib figures) keeps working because the wrapper reimplements the MIME-bundle dispatch that IPython previously provided.\n\nTool params:\n\n```ts\n{\n  cells: Array<{\n    language: \"py\" | \"js\";\n    code: string;\n    title?: string;\n    timeout?: number; // per-cell seconds, 1..600, default 30\n    reset?: boolean; // wipe this cell's language kernel before running it\n  }>;\n}\n```\n\nThe tool is `concurrency = \"exclusive\"` for a session, so calls do not overlap.\n\n## Kernel lifecycle\n\nEach kernel is a single Python subprocess: `python -u <runner.py>`. The bundled runner is materialized once per GJC process in a process-private temporary directory and file, then reused only by subsequent spawns within that process.\n\nKernel startup sequence:\n\n1. Availability check (`checkPythonKernelAvailability`) — verifies that a Python interpreter resolves and runs.\n2. Spawn `python -u runner.py` with filtered env and `cwd`.\n3. Send an init request that runs `os.chdir(cwd)`, injects env entries, and adds `cwd` to `sys.path`.\n4. Execute `PYTHON_PRELUDE` (idempotent — only initializes once per process).\n\nKernel shutdown:\n\n- Send `{\"type\": \"exit\"}` over stdin.\n- Wait for process exit with `SHUTDOWN_GRACE_MS` budget.\n- Escalate to `SIGTERM` and finally `SIGKILL` if the process does not exit in time.\n\n## Wire protocol (NDJSON, host ↔ runner)\n\nOne JSON object per line, UTF-8, `\\n` terminated.\n\nHost → runner:\n\n```jsonc\n{\"id\": \"<reqId>\", \"code\": \"<source>\", \"silent\": false, \"storeHistory\": true}\n{\"type\": \"exit\"}\n```\n\nRunner → host:\n\n```jsonc\n{\"type\": \"started\",  \"id\": \"<reqId>\"}\n{\"type\": \"stdout\",   \"id\": \"<reqId>\", \"data\": \"...\"}\n{\"type\": \"stderr\",   \"id\": \"<reqId>\", \"data\": \"...\"}\n{\"type\": \"display\",  \"id\": \"<reqId>\", \"bundle\": {<mime>: <value>}}\n{\"type\": \"result\",   \"id\": \"<reqId>\", \"bundle\": {<mime>: <value>}}\n{\"type\": \"error\",    \"id\": \"<reqId>\", \"ename\": \"...\", \"evalue\": \"...\", \"traceback\": [\"...\"]}\n{\"type\": \"done\",     \"id\": \"<reqId>\", \"status\": \"ok\"|\"error\", \"executionCount\": N, \"cancelled\": false}\n```\n\nStatus events the prelude emits (e.g. `_emit_status(\"find\", count=…)`) ship inside display bundles under `application/x-gjc-status` so the existing TUI status renderer keeps working.\n\n## Magics\n\nThe runner's source transformer rewrites IPython-style magics to plain Python calls before parsing. Supported set:\n\n| Magic | Effect |\n| --- | --- |\n| `%pip <args>` | `python -m pip <args>` with live streaming output. Newly installed packages are evicted from `sys.modules` so the next `import` picks up the fresh install. |\n| `%cd <path>` | `os.chdir(path)` (with `~` expansion); emits status event. |\n| `%pwd` | Returns `os.getcwd()`. |\n| `%ls [path]` | Returns `sorted(os.listdir(path))`. |\n| `%env [KEY[=VAL]]` | List, read, or set env vars (matches prelude `env()` semantics). |\n| `%set_env KEY VALUE` | Set `os.environ[KEY]`. |\n| `%time <expr>` / `%timeit <expr>` | Time the expression; emits status event with elapsed ms. |\n| `%who` / `%whos` | List user-namespace names. |\n| `%reset` | Clear user globals and re-inject prelude. |\n| `%load <path>` | Read a file into a fresh cell and execute. |\n| `%run <path>` | `runpy.run_path` and merge globals back. |\n| `%%bash` / `%%sh` | Run the cell body via `bash`/`sh`. |\n| `%%capture [name]` | Run body with stdout/stderr captured into `name`. |\n| `%%timeit` | Time the cell body. |\n| `%%writefile <path>` | Write body to file. |\n| `!cmd` / `var = !cmd` | Run command via subprocess shell; returns an SList-style result with `.n` / `.s` helpers. |\n| `var = %name args` | Assignment forms work for line magics and `!cmd`. |\n\nUnknown magic names raise `NameError: UsageError: ...` inside the cell.\n\n## Session persistence semantics\n\n`python.kernelMode` controls retained kernel reuse:\n\n- `session` (default)\n  - Reuses kernel sessions keyed by session file plus cwd when a session file exists; otherwise by cwd.\n  - Execution is serialized per session via a queue.\n  - There is no idle eviction, session cap, or heartbeat; retained kernels live until reset, owner cleanup, or process shutdown.\n  - A kernel found dead (`isAlive()` false) before a cell runs is replaced. If a cell fails for a reason other than cancellation and leaves the kernel dead, the kernel is replaced and the cell is retried once.\n- `per-call`\n  - Spawns a fresh subprocess for each request.\n  - Shuts the subprocess down after the request.\n  - No cross-call state persistence.\n\n### Kernel ownership\n\nRetained kernels are keyed by an **owner id**, and there are two kinds of owner:\n\n- **Session-owned** (the `eval` tool) — derived from the session file plus cwd as described above. Reaped when the session disposes.\n- **Explicitly-owned** (the `python` tool) — the caller supplies `kernelOwnerId`, which is `python:<session-id>`. This is deliberately distinct from the session's eval owner id so the two never alias and a Python REPL kernel is never reaped as collateral of eval cleanup.\n\n`disposeKernelSessionsByOwner(ownerId)` disposes every retained kernel for one owner and is idempotent, so disposing an owner twice is not a double free.\n\nOwner-scoped kernels are reaped on all three exits:\n\n- the owning tool's own teardown action (for `python`, `action: \"clear\"`),\n- session cleanup, which also handles session identity transitions,\n- signal exit (Ctrl-C), via `disposeChildSubprocesses`, which also drains both registries inside a single bounded budget.\n\n`gjc autoresearch clear` clears autoresearch state only; it does not dispose a Python kernel.\n\nA tool registering through the SDK's `registerSessionCleanup` lands in the **transition** cleanup registry, not the session one. Draining only the session registry on signal exit left explicitly-owned kernels running after Ctrl-C while graceful dispose looked correct.\n\n### Multi-cell behavior in a single tool call\n\nCells run sequentially in the same kernel instance for that tool call.\n\nIf an intermediate cell fails:\n\n- Earlier cell state remains in memory.\n- Tool returns a targeted error indicating which cell failed.\n- Later cells are not executed.\n\n`reset` is per cell: a Python cell with `reset: true` disposes that session's kernel before it runs, and later Python cells in the same call reuse the fresh kernel.\n\n## Environment filtering and runtime resolution\n\nEnvironment is filtered before launching the runner:\n\n- Allowlist includes core vars like `PATH`, `HOME`, locale vars, `VIRTUAL_ENV`, `PYTHONPATH`, etc.\n- Allow-prefixes: `LC_`, `XDG_`, `GJC_`\n- Denylist strips common API keys (OpenAI/Anthropic/Gemini/etc.)\n\nRuntime selection order:\n\n1. Active/located venv (`VIRTUAL_ENV`, then `<cwd>/.venv`, `<cwd>/venv`)\n2. Managed venv at `~/.gjc/python-env`\n3. `python` or `python3` on PATH\n\nWhen a venv is selected, its bin/Scripts path is prepended to `PATH`.\n\nThe runner additionally receives `PYTHONUNBUFFERED=1` and `PYTHONIOENCODING=utf-8` so streamed output reaches the host promptly.\n\n## Tool availability and mode selection\n\n`eval.py` / `eval.js` (both default `true`) plus optional `GJC_PY` override controls eval backend exposure:\n\n- Python backend only (`eval.py=true`, `eval.js=false`)\n- JavaScript backend only (`eval.py=false`, `eval.js=true`)\n- both backends\n\n`GJC_PY` accepted values:\n\n- `0` / `bash` → JavaScript backend only\n- `1` / `py` → Python backend only\n- `mix` / `both` → both backends\n\nIf Python preflight fails and `eval.js` is enabled, `eval` remains available for JavaScript cells. A cell with `language: \"py\"` throws a `ToolError`; there is no automatic fallback to JavaScript.\n\n## Execution flow and cancellation/timeout\n\n### Tool-level timeout\n\n`eval` timeout is in seconds, default 30, clamped to `1..600`. The tool combines caller abort signal and timeout signal with `AbortSignal.any(...)`.\n\n### Kernel execution cancellation\n\nOn abort/timeout:\n\n- The host sends `SIGINT` to the runner's process group (the runner is spawned detached as a group leader).\n- The runner's exec-time signal handler raises `KeyboardInterrupt` inside the user code.\n- Result includes `cancelled=true`. A timeout annotates the output with `eval cell timed out after <n>s; kernel interrupted but remains running. ...`, or with a kernel-killed notice when escalation was needed (`formatKernelTimeoutAnnotation()`). A deadline that expires before the kernel returns a result (for example while waiting for the session queue) yields a `Command timed out` notice instead.\n- Between requests the runner installs `SIG_IGN` for SIGINT so a stray cancel does not tear down the kernel.\n\nIf the runner has not finished 5s after `SIGINT` (for example, stuck in C code), the host shuts the kernel down (`exit` request, then `SIGTERM`, then `SIGKILL`) and marks the cell as kernel-killed; the next call starts a new kernel.\n\n### stdin behavior\n\nInteractive stdin is not supported. The runner does not forward `input()` prompts; user code that calls `input()` blocks until cancellation.\n\n## Output capture and rendering\n\n### Captured output classes\n\nFrom runner frames:\n\n- `stdout` / `stderr` → plain text chunks\n- `display` / `result` → rich display handling (MIME bundle)\n- `error` → traceback text\n- `application/x-gjc-status` MIME inside `display` → structured status events\n\nDisplay MIME precedence:\n\n1. `text/markdown`\n2. `text/plain`\n3. `text/html` (converted to basic markdown)\n\nAdditionally captured as structured outputs:\n\n- `application/json` → JSON tree data\n- `image/png` / `image/jpeg` → image payloads\n- `application/x-gjc-status` → status events\n\n### Matplotlib\n\nThe runner sets `MPLBACKEND=Agg` as an environ default so figures render off-screen. After every cell, `pyplot.get_fignums()` is iterated; each figure is saved to PNG, emitted as an `image/png` display, and closed.\n\n### Storage and truncation\n\nOutput is streamed through `OutputSink` and may be persisted to artifact storage. Tool results can include truncation metadata and `artifact://<id>` for full output recovery.\n\n### Renderer behavior\n\n- Tool renderer (`eval.ts`):\n  - shows code-cell blocks with per-cell status\n  - collapsed preview defaults to 10 lines\n  - supports expanded mode for full output and richer status detail\n- Interactive renderer (`eval-execution.ts`):\n  - used for user-triggered Python execution in TUI\n  - collapsed preview defaults to 20 lines\n  - clamps very long individual lines to 4000 chars for display safety\n  - shows cancellation/error/truncation notices\n\n## Operational troubleshooting\n\n- **Python backend not available** — Check `eval.py`, `GJC_PY`, and that `python`/`python3` is on PATH. If preflight fails and `eval.js` is enabled, pass `language: \"js\"` to use JavaScript.\n- **No Python on PATH** — Install a system Python 3.8+ or place a venv at `~/.gjc/python-env`. `gjc setup python --check` reports the resolved interpreter.\n- **Execution hangs then times out** — Increase tool `timeout` (max 600s) if workload is legitimate. For stuck native code, cancellation triggers `SIGINT` first then escalates; the session restarts on the next request.\n- **stdin/input prompts in Python code** — `input()` is not supported; pass data programmatically.\n- **Working directory errors** — Tool validates `cwd` exists and is a directory before execution.\n\n## Relevant environment variables\n\n- `GJC_PY` — tool exposure override\n- `GJC_PYTHON_SKIP_CHECK=1` — bypass Python preflight/warm checks\n- `GJC_PYTHON_INTEGRATION=1` — enable gated integration tests that spawn a real Python\n- `GJC_PYTHON_IPC_TRACE=1` — log NDJSON frames exchanged with the runner subprocess\n",
 	"release-0.13.3-integration.md": "# Release 0.13.3 integration record\n\n## Authority and immutable base\n\n- Integration branch: `release/0.13.3`\n- Authorized repository: `Yeachan-Heo/gajae-code`\n- Exact base: `origin/main` at `5666472818b71a1c37615408d9b4d3b5a77b7fa3`\n- Delivery mode: coherent cherry-pick groups pushed directly to the existing release branch\n- Explicitly not authorized here: version bump, `main` mutation, PR creation, tag, publish, or release execution\n\n## Included scope and dependency decisions\n\n### Original hotfixes\n\n| Candidate | Decision | Dependency boundary |\n| --- | --- | --- |\n| `0bd4898d` / #4437 | Include | Isolated Rust text wrapping termination fix and regression tests. No provider, auth, SDK lifecycle, or settings dependency. |\n| `38f3b407` / supplied #4509 anchor (commit subject references #4481) | Include | Bounded TUI overlay geometry and dedicated capture regressions. Changes stay in TUI rendering plus diagnostic scripts. |\n| `b5ef23f5` / #4446 | Include | Print-mode process termination and postmortem draining. Embedding and ACP ownership are explicitly preserved by the change. |\n\n### Bounded utilities\n\n| Candidate | Decision | Dependency boundary |\n| --- | --- | --- |\n| `6080b983` / #4453 | Include | Narrow `todo_write` positional-handle diagnostics and tests. No routing or model-contract change. |\n| `8eb8127e` / #4424 | Include | Narrow terminal image scrollback preservation. Shares `tui.ts` with the overlay hotfix, so it is integrated before the geometry hardening and tested together. |\n| `c06f4f5` / #4451 | Skip | Candidate directly modifies `src/autoresearch/dashboard.ts`; autoresearch is explicitly excluded. Its render-cache work is not cherry-picked partially because the commit couples the cache contract to excluded autoresearch and several controller/component migrations. |\n\n### Session, storage, retry, and crash resilience\n\n| Candidate | Decision | Dependency boundary |\n| --- | --- | --- |\n| `c81614fc` / #4396 | Include | Managed-output publication/reaping plus the minimum native path-identity binding needed by that storage implementation. No SDK notification/lifecycle architecture change. |\n| `8d6784cb` / #4411 | Include | Managed transcript size proactive/reactive recovery and compaction signal. Changes are limited to agent compaction and coding-agent session persistence. |\n| `515f1c7c` / #4421 | Include | Missing managed transcript recovery in session manager. |\n| `ffa07d6c` / #4450 | Include | Missing predecessor recovery in managed session storage. Applied after #4396 because both touch the same storage implementation and #4450 is the later semantic correction. |\n| `0a736b17` / #4470 | Include | Crash-index compaction/read compatibility fix. Applied before #4495 so the later broader recovery work retains this invariant. |\n| `7a6b0d13` / #4495 | Include | Crash journal/index recovery hardening. Scoped to crash persistence and record loading. |\n\n### Pet features\n\n| Candidate | Decision | Dependency boundary |\n| --- | --- | --- |\n| `d2f6e8a4` / #4468 | Include with strict pet-only settings allowance | Ouroboros pet/theme requires a bounded settings schema enum, pet/theme selectors, theme registration, and UI verification updates. These are accepted only as the minimum cohesive dependency of the pet feature; no general settings migration, MCP, customization migration, provider, model, or auth contract is admitted. |\n| `dfb1081c` / #4499 | Include | iTerm2 pet rendering is applied after #4468 because both update the pet widget and TUI pet renderer. It does not alter auth/provider/model or SDK lifecycle contracts. |\n\n## Owner-authorized expansion after the original audit\n\nThe owner subsequently authorized a bounded provider/preset and stability expansion on the existing release branch. The following exact changes were added without importing the broader `dev` architecture:\n\n### Stability and security\n\n- #4385 Synthetic login validation: use the provider models endpoint instead of a retired hard-coded Kimi probe (`6de4096025`, changelog `e14189ec82`).\n- #4302 image-generation provider error hardening: redact credentials and bound response bodies (`08e3e4de22`, `b3ce4bb584`).\n- #4452 status-line scratch-root resolution at render time (`d27175a1c3`).\n- #4373 Windows replacement-receipt reconciliation over the release branch's existing managed-session storage fixes (`bc9417f4eb`).\n\n### Providers and presets\n\n- #4304 native TypeScript Kiro OAuth/CodeWhisperer provider (`7913ce221a`).\n- #4294 Muse Spark 1.2 open-weight catalog, profile, reasoning, cache-normalization, and routing closure (`6ff17fe082` through `efd850df86`).\n- #4377 direct xAI Grok 4.6 catalog and role profiles (`cb3eba7a93`, `8c7170a212`).\n- #4462 bundled Grok CLI 4.6 catalog and bounded effort parsing (`0ce9f10436`, `5a931cc529`, `4b15d708bf`).\n\nCHANGELOG conflicts were resolved by retaining the released 0.13.2 history and existing release entries while adding only the new Unreleased provider/preset records. Generated model data was merged with its source generators and must pass reproducibility tests before the release cut.\n\n## Explicit exclusions\n\n- General settings, MCP, or customization migrations beyond the minimum cohesive pet dependencies listed above\n- SDK lifecycle or notification architecture\n- GJC master/supervisor work\n- Autorouting\n- Autoresearch\n- macOS TCC/signing change #4275 pending dedicated release-build and permission-identity validation\n- Version bump, release metadata cut, tag, publish, release execution, PR creation, or `main` mutation\n\n## Integration order\n\n1. Record this scope and boundary decision.\n2. Original hotfixes and bounded TUI utilities: #4437, #4424, supplied #4509 anchor/#4481 commit, #4446, #4453.\n3. Session/storage resilience: #4396, #4411, #4421, #4450.\n4. Crash recovery resilience: #4470, #4495.\n5. Pet: #4468, then #4499.\n6. Run focused tests after each coherent group, followed by branch-wide checks, build, test, and install/package smoke.\n\n## Validation evidence\n\nThis section is updated as groups are integrated. Exact commands, outcomes, skips, and environmental blockers are recorded before final delivery.\n",
 	"release-0.14.2-handoff.md": "# Release 0.14.2 — maintainer handoff\n\nPatch release assembled per the deep-interview spec (`.gjc/_session-*/specs/deep-interview-release-0-14-2-patch-scope.md`). Scope: patch-like changes only, **zero team → autoresearch cutover content** (PR #4430 and dependents stay on dev for a later minor).\n\n## What is on this branch\n\n- Base: `main` tip `d49c40a6` (v0.14.1). The branch was reset there before any picks.\n- 54 cherry-picked commits: 53 from `dev`, plus the crash-relay provenance fix `c1428d9a27` sourced from `origin/owner/issue-4715-crash-relay-gaps` (its parent is the dev tip) — all selected by the frozen dependency-aware manifest at `artifacts/release-0.14.2/manifest.json` (allowlist + negative list + blocked).\n- 33 dev commits dropped as already shipped on main (28 patch-id duplicates + 5 subject-provenance backports).\n- 1 commit blocked: `7869dd256f` (fix(acp)) depends on `collectModelCatalogAndActiveProviders` from the excluded `perf(acp)` commits; an alternate form exists on `origin/probepark/perf/acp-session-new-catalog` (`014a679f2d`).\n- Changelogs rebuilt once from the manifest ledger (no cherry-picked changelog hunks).\n- **No version bump on this branch** — `bun run release` performs the 0.14.2 bump on main.\n\n## Verification evidence (pre-promotion, all four layers)\n\nRecorded under `artifacts/release-0.14.2/gate/`:\n\n1. **Branch-vs-manifest proof** — every allowlisted SHA's change is present in branch history; blocked/dropped sets recorded.\n2. **Legacy-surface scan** — `scripts/check-visible-definitions.ts` passes with the pre-cutover surface (`deep-interview, ralplan, team, ultragoal`); new public autoresearch surface files absent; zero autoresearch references in the shipped-source diff (`packages/*/src`; the only autoresearch strings on the branch are audit text in this document); team runtime/command/skill present.\n3. **Full check suite + targeted tests** — `bun run check` green; targeted suites: team-runtime checkpoint classifier, ralplan worktree-root, postmortem/handled-error (crash relay).\n4. **Version + changelog consistency** — `package.json` still 0.14.1 on branch; `[Unreleased]` bullets map 1:1 to shipped SHAs; no cutover bullets.\n\n## Split-run release procedure (maintainer, after this PR merges)\n\n`bun run release` is main-only and pushes atomically; its own `ci:check:full` does not cover the full gate, and tag CI skips the main check/test graph. To cover the release-generated commit (version bump, changelog cut, lockfiles, native sentinel, regenerated plugins/schemas):\n\n1. Merge this PR to `main` and check out a clean `main`.\n2. Run the release generation locally (`bun run release` up to the point it would commit/push — interrupt before the atomic push, or use its dry-run/staging flow if available).\n3. On the generated tree, run the full gate: `bun run check` plus the targeted tests above.\n4. Only if green, allow the push/tag of `v0.14.2` to proceed.\n\n## v0.14.2-nightly tag disposition\n\nThe pre-existing `v0.14.2-nightly.20260818150120.32217566985.gd49c40a6c3c0` tag points at the unpatched main tip. It does **not** block the exact stable `v0.14.2` tag (release tooling and CI treat suffix-bearing tags as non-stable). Decision: **leave it untouched** — do not move, retag, or delete; nightly-tag hygiene belongs to the nightly workflow owner, not this release.\n\n## Terminal-review dispositions\n\nTwo behavioral findings from the terminal review concern code that is **byte-identical to `dev`** (zero diff). To preserve cherry-pick fidelity, they are accepted as upstream issues for `dev` follow-up rather than patched divergently in this release:\n\n- `packages/coding-agent/src/utils/herdr-pane.ts` (`persistSequenceFloor`/`nextSequence`): best-effort Herdr state reports perform synchronous fs calls (`readFileSync`/`mkdirSync`/`writeFileSync`/`renameSync`) that can block the event loop under slow or contended temp storage, contradicting the path's \"never blocks\" contract.\n- `packages/utils/src/postmortem.ts` (`handleFatalError`): `describeFatal(reason)` runs twice (once for the local snapshot, once inside `recordFatalCrash`), so a throwable with stateful or throwing getters can produce mismatched crash fingerprints between stderr and the persisted record.\n",
 	"render-mermaid.md": "# RenderMermaid\n\n`RenderMermaid` is an optional built-in tool that renders Mermaid source to terminal-friendly text.\n\n## Enable it\n\nDisabled by default. Turn it on in `/settings` under **Tools → Render Mermaid**, or in `~/.gjc/agent/config.yml`:\n\n```yaml\nrenderMermaid:\n  enabled: true\n```\n\n## What it does\n\n- Tool name: `render_mermaid`\n- Input: Mermaid source in the required `mermaid` field\n- Output: rendered ASCII/Unicode text, not SVG or PNG\n- Storage: when artifact storage is available, the full render is also saved as an `artifact://...`\n\nThere are no model-specific or environment-variable prerequisites. Once enabled, any model that can call built-in tools can use it.\n\n## Parameters\n\n```json\n{\n  \"mermaid\": \"graph TD\\n  A[Start] --> B[Stop]\",\n  \"config\": {\n    \"useAscii\": false,\n    \"paddingX\": 2,\n    \"paddingY\": 2,\n    \"boxBorderPadding\": 0\n  }\n}\n```\n\nAvailable `config` fields:\n\n- `useAscii` — `true` for plain ASCII, `false` for Unicode box-drawing characters (default and usually more readable)\n- `paddingX` — horizontal spacing between nodes\n- `paddingY` — vertical spacing between nodes\n- `boxBorderPadding` — inner padding inside node boxes\n\n## Current limitations\n\n`RenderMermaid` uses the `beautiful-mermaid` ASCII renderer. It works best for flowcharts and small diagrams.\n\nComplex sequence diagrams, especially with `alt` / `else` blocks, can become very wide in a terminal. That is current renderer behavior, not a provider or model configuration problem.\n\nIf a sequence diagram is hard to read:\n\n1. Keep Unicode output (`useAscii: false`)\n2. Reduce spacing with a tighter config such as `paddingX: 2`, `paddingY: 2`, `boxBorderPadding: 0`\n3. Prefer smaller sub-diagrams over one large sequence diagram\n4. Open the saved artifact if the inline preview is truncated in the TUI\n\n## Example\n\nInput:\n\n```mermaid\ngraph TD\n  A[Start] --> B{Decision}\n  B -->|Yes| C[Action]\n  B -->|No| D[End]\n```\n\nTypical result:\n\n```text\n┌─────┐\n│Start│\n└─────┘\n   │\n   ▼\n┌────────┐\n│Decision│\n└────────┘\n```\n",
 	"research-plan-ledger.md": "# Research plan items and evidence ledger\n\nResearch/deep-research workflows need a planning contract that is stronger than an execution-order checklist. A plan item should name the claim under investigation, the uncertainty around it, what evidence is required, what counterexamples would falsify it, and how a verifier should handle source conflicts.\n\nThis document defines the public product-facing spike for issue #932. It intentionally avoids private operator, session, channel, and routing internals.\n\n## Research plan item schema\n\n```ts\ntype ResearchPlanConfidence = \"low\" | \"medium\" | \"high\";\n\ntype ResearchPlanItem = {\n  claim: string;\n  confidence: ResearchPlanConfidence;\n  unknowns: string[];\n  evidenceNeeded: string[];\n  counterexampleQueries: string[];\n  sourceConflictPolicy: string;\n  dropCondition: string;\n  verifierChecks: string[];\n};\n```\n\nField intent:\n\n- `claim`: The smallest claim that can survive or fail verification.\n- `confidence`: Planner's initial confidence before evidence collection.\n- `unknowns`: Known gaps the final answer must resolve or explicitly carry forward.\n- `evidenceNeeded`: Evidence workers must collect before the claim can be accepted.\n- `counterexampleQueries`: Directed search prompts for evidence that would weaken or falsify the claim.\n- `sourceConflictPolicy`: How the verifier treats conflicting sources, stale sources, or mismatched methodology.\n- `dropCondition`: The explicit condition that removes this claim from the final answer.\n- `verifierChecks`: Checklist the verifier applies before accepting the claim.\n\n## Evidence ledger schema\n\n```ts\ntype ResearchEvidenceVerdict = \"support\" | \"contradict\" | \"uncertain\";\n\ntype ResearchEvidenceEntry = {\n  claim: string;\n  source: string;\n  confidence: ResearchPlanConfidence;\n  verdict: ResearchEvidenceVerdict;\n  notes?: string;\n};\n\ntype ResearchLedgerVerdict = {\n  claim: string;\n  finalVerdict: \"accepted\" | \"rejected\" | \"uncertain\";\n  survivingSources: ResearchEvidenceEntry[];\n  rejectReason?: string;\n  unresolvedUnknowns: string[];\n};\n```\n\nThe ledger is claim-centric. Workers add evidence entries against plan-item claims; the verifier reduces those entries into a final verdict. Accepted claims can be cited in the final answer. Rejected claims are named with `rejectReason`. Uncertain claims are either excluded or marked explicitly as unresolved.\n\n## Ralplan/research workflow shape\n\n1. Planner emits `ResearchPlanItem[]` alongside the normal plan narrative when the task is research-heavy.\n2. Workers gather independent evidence for each item, including counterexample-oriented searches.\n3. Verifier checks contradictions, source quality, stale information, and unresolved uncertainty using the item's `verifierChecks`, `sourceConflictPolicy`, and `dropCondition`.\n4. The final answer cites accepted claims, lists rejected claims with reasons, and marks any surviving uncertainty.\n\n## Example\n\n```ts\nconst item: ResearchPlanItem = {\n  claim: \"Model X reduces latency by 30% on production-like workloads\",\n  confidence: \"medium\",\n  unknowns: [\"production workload mix\"],\n  evidenceNeeded: [\"benchmark with production-like fixture\", \"baseline comparison\"],\n  counterexampleQueries: [\"regression on long-context workload\", \"cold-start latency increase\"],\n  sourceConflictPolicy: \"Reject the claim when any credible counterexample contradicts the benchmark.\",\n  dropCondition: \"Drop if a counterexample contradicts the claim or key unknowns remain unresolved.\",\n  verifierChecks: [\"check source freshness\", \"compare benchmark harness\", \"inspect counterexample evidence\"],\n};\n```\n\nIf the ledger contains a supporting benchmark and a credible long-context counterexample, the verifier rejects the broad claim instead of letting a plausible summary survive by vibes.\n\n## Current spike\n\nThe first implementation spike lives in `packages/coding-agent/src/research-plan/ledger.ts` and provides:\n\n- TypeScript interfaces for research plan items, evidence entries, and final verdicts.\n- Validators for product-facing plan/evidence objects.\n- A deterministic verifier helper that rejects plausible claims when counterexample/source-conflict/drop-condition evidence applies.\n- Regression tests in `packages/coding-agent/test/research-plan-ledger.test.ts`.\n\nFuture runtime integration can make `/skill:ralplan` emit these structures as a fenced JSON block or structured sidecar in the persisted ralplan artifact. The spike keeps the schema independent from private session state so it can be exposed in docs and tests safely.\n",
 	"research/unlazy-evaluation/REPORT.md": "# Research: evaluating the unlazy depth-tree method for Gajae-Code\n\n- **Issue:** #4844\n- **Source request:** Discord playground-ko message 1540980632572788817\n- **Verdict receipt:** `f76e2db6-fbf3-4e74-a17e-a9b2f2fa95b8` (autoresearch ledger, this session)\n- **Scope:** research only. No product code, dependency, package manifest, or benchmark binary was changed. The research evidence manifest is part of this docs bundle; nothing from the external repository was executed or copied into product code. Verbatim upstream snapshots are retained for review with attribution under the upstream MIT license, whose text is pinned in `snapshots/unlazy-LICENSE.txt.snapshot`, and whose local integrity is covered by `MANIFEST.sha256`.\n- **External project state when inspected:** `Leonxlnx/unlazy`, pinned to main commit `754d9a68109e39b836cc72a39fb9a823f9d6b613` and v1 commit `baf39ef9b6e71077fa6056bcf8715e09fe6d7462`, both inspected read-only via the GitHub API. The upstream `LICENSE` blob is `48a2f6640b81ff8eca9ce7f6a96337692713ef5b`; its text is retained in the license snapshot.\n\n## Executive summary\n\n**Reject the unlazy depth-tree method. Propose two narrow ideas for separate product decisions and record one low-priority future consideration.**\n\nThe Discord request asks about \"the depth-tree method\" that \"splits a task N layers deep and gives every leaf the full time budget of the whole task, so effort multiplies with depth.\" That claim is the **v1 (2026-08-09) version of unlazy**, and the project's own current documentation **explicitly retracts it**:\n\n> \"Do not treat depth as an arithmetic promise about effort or tokens. The original v1 method claimed that each binary split multiplied effort. A small maintainer-run comparison later suggested that agents treated depth as a thoroughness cue rather than following that arithmetic. The repository does not contain the raw artifacts needed to reproduce those historical figures, so treat them as design history, not benchmark evidence.\"\n> — `references/method.md` (v2, current `main`) — see `snapshots/unlazy-method.md.snapshot:5`\n\nThe GitHub repository **description** still advertises the retracted arithmetic (\"…so effort multiplies with depth\"), which is presumably what the Discord message saw. The `v1` branch README goes further: \"`tree 3` is 4 units of work, `tree 5` is 16, `tree 7` is 64… Effort multiplies with depth. It never divides.\" (`snapshots/unlazy-README-v1.md.snapshot:9,111`). Both the multiplication claim and the \"every leaf gets the full budget T\" rule are gone from v2.\n\nWhat v2 actually is: a **completion-discipline system** — acceptance-gate ledgers written before work, runnable checks with exit-code+marker evidence, parent re-verification, branch integration gates, ownership leases, and an optional Claude Code Stop hook that blocks stop while gates are unmet, with a bounded no-progress release. In GJC terms, this is not a foreign paradigm; it is a peer implementation of machinery GJC already has. Comparing the two:\n\n| unlazy v2 concept | Gajae-Code equivalent today | Delta |\n|---|---|---|\n| Depth Tree decomposition (layer 1 = task; leaves = coherent deliverables; contracts before fan-out) | Ultragoal `create-goals` brief→stories, ralplan consensus planning, per-slice coordination contracts | overlap — GJC adds planner/architect/critic consensus to unlazy's one-shot contract checklist |\n| Gates-before-work (`GATES.md` with `CHECK:`/`EXPECT:`) | Ultragoal quality gates (`--quality-gate-json`), `gjc ultragoal quality-gate validate` | none in concept; GJC gates verify after work, unlazy gates are authored *before* work |\n| Leaf/branch/root completion hierarchy (leaf self-check → parent reverify → branch integration → root remeasure) | Ultragoal boundary cohort: cleaner→architect→QA lanes on a frozen `sourceHash`, terminal critic gate, validation batches | overlap — GJC adds frozen-source and joined-lane enforcement beyond the retained unlazy hierarchy |\n| Runnable-gate success contract (exit 0 **and** `EXPECT:` marker) | quality-gate surface evidence (cli-replay invariants, live-surface artifacts) | similar intent; GJC's is surface-typed, unlazy's is one marker contract |\n| Ownership leases (`OWNS:` claim/release) | per-slice coordination contracts (target files, conflict-escalation rule) + `task` isolation worktrees | none — GJC additionally has real worktree isolation, unlazy leases are explicitly \"coordination, not isolation\" |\n| Stop hook blocking stop while gates unmet | native GJC Stop hook (`hooks/skill-state.ts`) blocking on active workflow state, ultragoal durable completion, stale mode-state, uncrystallized deep-interview | **one real delta:** unlazy's block is bounded (6 consecutive no-progress blocks → release); GJC's block path has no equivalent no-progress release |\n| Bounded ceilings (ralplan `maxIterations=5`, ultragoal `nudgeBudget=10`, critic ceiling 5, review-blocker cap 3) | GJC has these per-workflow | GJC's ceilings bound *work*, not *stop attempts* |\n| Abandonment (`ABANDON:` with non-empty reason, surfaced in report) | ultragoal `record-review-blockers` / `classify-blocker` + terminal critic | partial — GJC keeps review blockers active and uses `classify-blocker` for human-only pause decisions rather than an identical abandonment handoff |\n| \"Final report audit: re-measure every number before reporting\" | autoresearch verdict contract (status/evidence/caveats/evaluator) + ultragoal receipts | none in concept |\n\nSo the honest answer to \"compare unlazy with Gajae-Code and identify reusable ideas\" is: **the method's headline claim is dead upstream, and many v2 mechanisms overlap with what GJC's four workflow skills already enforce — with one mechanical safety idea and a few gate-authoring rules worth considering.**\n\n## Findings\n\n### F1. The time-budget multiplication claim is retracted by its own author (P0 — dispositive)\n\n- v1 (`SKILL-v1.md:24`, `README-v1.md:111`): \"every leaf gets the FULL budget T… Depth therefore multiplies total effort by 2 to the power of N minus 1. That multiplication is the entire point of the method.\"\n- v2 (`references/method.md:5`): \"Do not treat depth as an arithmetic promise about effort or tokens… treat them as design history, not benchmark evidence.\"\n- `references/token-economy.md:39`: \"Earlier unlazy documentation gave exact token and effort ratios from a six-run exploratory comparison. The raw prompts, traces, outputs, and scoring records are not present in this repository, so those numbers are not reproducible here. Do not use them as product guarantees.\"\n- `research/validation-protocol.md:81`: the deterministic test suite \"validate[s] implementation behavior; they do not validate broad claims about model psychology or task productivity.\"\n- The current GitHub repo **description** nonetheless still says \"so effort multiplies with depth\" (`snapshots/unlazy-repo-description.txt.snapshot`). The Discord request cites the retracted framing.\n\nIndependent grounds for rejection, beyond the upstream retraction:\n\n1. **Arithmetic cannot compel effort.** A prompt rule \"every leaf gets the full T\" does not create compute. If a model completes a leaf in 0.2T, nothing forces it to spend the remaining 0.8T on non-work; the observed v1-era behavior (per upstream's own comparison) was that depth acts as a *thoroughness cue*, i.e., an ordinary prompt-level effect wearing arithmetic clothing.\n2. **It optimizes the wrong objective.** Even if it worked, multiplying effort by 2^N−1 multiplies cost identically. GJC's engineering principles (\"avoid speculative work\", \"smallest version that works end to end\") and the overthinking literature unlazy itself cites (`arXiv 2604.10739`, `2508.13141`) both point the other way: effort should be risk-proportional, which is exactly what GJC's `docs/workflow-recovery-and-risk-proportional-validation.md` and ultragoal's boundary-vs-deferred gate split already implement.\n3. **GJC's product surface is deliberately small.** AGENTS.md fixes the public workflow surface at exactly four default skills and four role agents. An \"unlazy\" fifth default skill is not a research question; it violates the surface contract.\n\n### F2. Stop/verification mechanisms and runaway-work risk (the actual engineering content)\n\nunlazy v2's enforcement stack:\n\n1. **Gates before work.** `GATES.md` authored from a template before implementation; one observable outcome per gate; runnable gates carry indented `CHECK:` (shell) and `EXPECT:` (success-only marker); manual gates allowed only when no command can decide the outcome. Parser rejects zero-gate ledgers, duplicate ids, incomplete runnable gates, abandonment without reason.\n2. **Two-step check execution.** `--status` parses without executing. A normal run on an unapproved oracle prints the resolved command/cwd/shell/`PATH` and leaves it unexecuted. `--approve` records consent, keyed to a content hash over the *exact* `CHECK`/`EXPECT`/resolved CWD/resolved shell/timeout/output+regex limits/platform/full inherited `PATH` (`gate-check.mjs:312-394`). Approval storage must live outside the repository root (fail-closed guard at `gate-check.mjs:337-338`). This is a genuinely careful design for inherited-ledger hostile-repo scenarios, and their `SECURITY.md` is explicit that approval \"is consent, not a sandbox.\"\n3. **Success = exit 0 AND marker match**, with regex expectations executed in a Worker with a 250 ms timeout (`gate-check.mjs:406-423`) to bound catastrophic-backtracking checks. Evidence records resolved shell, cwd, exit status, a `PATH` fingerprint, and decisive (not full-log) output.\n4. **Leaf → branch → root verification hierarchy.** Leaf self-check is explicitly \"self-certification\"; parent must `--reverify` (re-execute, never trust prior evidence — \"old evidence is not re-execution\"); branch gates prove integration; root remeasures final claims.\n5. **Stop hook with bounded release.** While the resolved pipeline has unmet gates, the hook returns Claude Code's `decision: \"block\"`. The anti-trap guard: session-keyed state, and after **6 consecutive blocks without ledger progress** (content hash of outstanding items unchanged) the hook *releases* with an explanatory message (`stop-hook.mjs:11,93-131`). This bounds the runaway case where an agent cannot make progress and the block loop would otherwise burn unbounded continuation budget.\n\n**Runaway-work comparison.** Both projects treat \"agent stops early\" and \"agent never stops\" as dual failure modes. unlazy bounds stop-blocks by counting no-progress blocks; GJC bounds *work* by per-workflow ceilings (ralplan iteration cap 5 with `PLANNING-STUCK` terminal; ultragoal nudge budget 10; terminal-critic run-level ceiling 5; review-blocker recursion cap 3) and gates stop itself through `skill-state.ts` (active workflow state, ultragoal durable completion, stale mode-state coherence, uncrystallized deep-interview). What GJC does **not** have is the third leg: a bounded release for its own stop-block when the blocked agent makes no progress. Today, a wedged-but-active workflow skill (e.g., ultragoal with an unwinnable quality gate and an operator absent) can block stop indefinitely; every exit requires either real progress or an explicit operator action (`record-critic-gate-override`, `gjc state clear`). That is a defensible fail-closed choice, but it has a known cost.\n\n### F3. Interaction with Gajae-Code's existing workflows\n\n- **Ultragoal.** unlazy's orchestrated mode is a structurally simpler peer of Ultragoal: `PLAN.md` + leaf ledgers + rolling dispatch ≈ `goals.json` + `ledger.jsonl` + leader-owned slices; unlazy's \"finish one line of attack\"/four-pass leaf loop overlaps with ultragoal's cohort generation loop with delta-only re-review. Two unlazy details have no Ultragoal counterpart: (a) gates authored *before* implementation (Ultragoal gates are constructed at checkpoint time from evidence that already exists); (b) the bounded stop-block release (F2.5).\n- **Ralplan.** unlazy has no planning/consensus phase — its contract checklist is the primitive ralplan replaces. No interaction. One borrowed-authoring rule (below) would land in ralplan-adjacent gate guidance if adopted.\n- **Deep Interview.** No overlap. unlazy assumes a given task; deep-interview exists to decide what the task is. (unlazy's own \"do not create gates for a trivial edit or factual reply\" is a weak cousin of deep-interview's do-not-use-when list.)\n- **Autoresearch.** unlazy's \"audit the final report: re-measure every number and completion claim immediately before reporting\" is the same discipline as the autoresearch verdict contract (status/evidence/caveats/evaluator, self-issued with optional distinct critic receipt). No gap.\n- **Hooks surface.** unlazy's Stop hook is Claude-Code-shaped; GJC already normalizes `Stop`/`agent_end` across conventions (`hooks/events.ts`, `codex-native-hooks-config.ts`), so a GJC-native equivalent of the bounded release would not need any new event plumbing.\n\n## Reusable ideas (explicitly separated from any product change)\n\nResearch conclusions only — each item below names a *candidate*, not an approved change. Any actual adoption is a separate, explicitly proposed product decision (see \"Proposal boundary\").\n\n### R1 — Candidate for separate decision: bounded no-progress release for the GJC skill stop-hook block\n\nAdd an unlazy-style escape hatch to `buildSkillStopOutput` (`packages/coding-agent/src/hooks/skill-state.ts`): when the same active-workflow stop block fires N consecutive times with no durable-state progress (ledger append, checkpoint, state-write), release the block with an operator-visible message instead of blocking forever. Upstream evidence: `stop-hook.mjs` `MAX_BLOCKS = 6`, session-keyed, content-hash progress detection, release message that still names the outstanding items. This is small, mechanical, fail-open-at-the-edge, and addresses a real wedged-session mode GJC currently resolves only through operator intervention. Prerequisite: define \"progress\" against GJC's durable artifacts (`ledger.jsonl` appends, mode-state mtime/content) rather than unlazy's ledger text hash.\n\n### R2 — Candidate for separate decision (guidance, not machinery): gate-authoring rules\n\nTwo authoring rules from `references/gates.md:95-100` are cheap to fold into existing GJC gate/verification guidance (ultragoal quality-gate docs, `docs/` verification guidance) without any runtime change:\n\n1. **Negative controls**: before trusting an absence/negative assertion (e.g., \"no regressions\", \"no slop left\"), run the same check against a known positive fixture and confirm it fails. GJC gates currently encode positive evidence well; absence claims are the weak spot.\n2. **Supplied-number independence**: never let a number copied from the brief become its own `EXPECT:`; the check must compute the figure from source data. GJC's \"never hand-compute a hash\" rule is the same instinct; extending it to all measured figures in gate evidence is a one-line documentation change.\n\n### R3 — Consider (low priority): pre-authored acceptance gates\n\nunlazy's \"write gates before real work\" ordering (gates authored at plan time, then executed) versus GJC's gates-assembled-at-checkpoint-time. Pre-authoring makes gates a plan artifact reviewers can attack during ralplan consensus, and prevents post-hoc gate shaping to match whatever was built. Cost: gates written before implementation are often wrong and need revision, which reintroduces the exact drift problem. Verdict: **interesting, not urgent**; if desired, the natural seam is ralplan final artifacts carrying an acceptance-gate section that Ultragoal checkpoints must satisfy or explicitly amend (an amendment ledger entry, never silent weakening).\n\n### Rejected, with reasons\n\n- **R — Depth-tree effort multiplication / full-budget-per-leaf** (F1): retracted upstream; not reproducible; optimizes spend over correctness; contradicts risk-proportional validation.\n- **R — \"tree N\" depth semantics or an `unlazy` default skill**: violates the four-skill public-surface contract (AGENTS.md); adds a fifth workflow with no capability the existing four lack.\n- **R — unlazy's `gate-check.mjs`/`stop-hook.mjs` as code or dependency**: vendor surface overlapping GJC-native machinery; GJC already has quality-gate validation, cohort sourceHash freezing, and surface-typed evidence, so copying would duplicate mechanisms. Also violates \"do not copy code from the untrusted reference.\"\n- **R — `GATES.md` markdown ledger format**: GJC's structured `--quality-gate-json` + `ledger.jsonl` receipts are machine-checkable and freshness-scoped; a second prose ledger format would be regression, not addition.\n- **R — Ownership leases as a new mechanism**: GJC already has per-slice coordination contracts plus real worktree isolation; unlazy's leases are explicitly not isolation.\n- **R — `--jobs N` parallel gate execution**: GJC already has parallel cohort lanes on frozen snapshots, which is a safer parallelism primitive (immutable source vs. concurrent command execution).\n\n## Proposal boundary (not implemented here)\n\nAny change above requires a separate maintainer-approved product decision with its own issue/plan; this lane is research-only. If R1 is pursued, the natural shape is: a counter on consecutive stop-blocks per `(session, skill)` in hook state, progress defined as durable-state change, release threshold ~6 with an operator-visible message mirroring upstream's phrasing, and tests in `packages/coding-agent/test/` covering (a) release after N no-progress blocks, (b) counter reset on progress, (c) cross-session isolation, (d) no release for handoff-required phases where an explicit user-facing step is the correct exit. R2 needs no runtime change; R3 would be a ralplan/Ultragoal artifact-schema discussion.\n\n## Prerequisites and product risks (for any future adoption lane)\n\n- **R1 risk**: a no-progress release weakens the fail-closed guarantee that active workflows never vanish silently. Mitigation: release must be loud (system message naming outstanding work), and handoff-required phases (deep-interview interviewing, ultragoal handoff) should stay unreleaseable — their correct exit is a user-facing step, not a timeout.\n- **R1 prerequisite**: a durable \"progress\" signal that cannot be advanced by noise (unlazy hashes outstanding-gate content; GJC would hash ledger/state content similarly).\n- **R2 risk**: none identified (documentation-only).\n- **General**: nothing in unlazy is a dependency candidate; all ideas above are re-implementable natively in GJC terms.\n\n## Method and evidence integrity\n\n- All external-repository evidence was captured read-only via the GitHub REST API on 2026-08-23 into `snapshots/` (18 files, including both `main` and `v1` variants of SKILL/README, the security policy cited in F2, and the upstream MIT license notice). No unlazy script was executed at any point. The bundle intentionally omits the upstream changelog because it is not evidence for a report claim; the remaining snapshots cover every quoted or behavior-critical source.\n- The prior autoresearch session receipt reports a claim-verification harness (`autoresearch.sh`) covering 10 claims (5 external, 5 GJC-side) with deterministic exit-0 output. That retired harness is not part of this PR or the current checkout, so this review treats the receipt as provenance rather than independently reproducible evidence.\n- GJC-side citations are to `packages/coding-agent/src/hooks/skill-state.ts`, `packages/coding-agent/src/hooks/events.ts`, `packages/coding-agent/src/gjc-runtime/autoresearch-runtime.ts`, `packages/coding-agent/src/defaults/gjc/skills/{ultragoal,ralplan,deep-interview,autoresearch}/SKILL.md`, and `AGENTS.md` at base `d06a42e53a9d6363d152a88c8168b5d6b2ab345e`.\n- **Limitations:** no live benchmark of the depth-tree method against GJC workloads was run — the multiplication claim is rejected on upstream's own retraction plus internal-consistency grounds, not new measurements, which matches the request's research-only boundary. unlazy has no tagged releases, so findings are pinned to the inspected commit SHAs rather than a version.\n",
 	"resolve-tool-runtime.md": "# Resolve tool runtime internals\n\nThis document explains how preview/apply workflows are modeled in coding-agent and how built-in or custom tools can participate via the tool-choice queue and `pushPendingAction`.\n\n## Scope and key files\n\n- [`src/tools/resolve.ts`](../packages/coding-agent/src/tools/resolve.ts)\n- [`src/tools/ast-edit.ts`](../packages/coding-agent/src/tools/ast-edit.ts)\n- [`src/extensibility/custom-tools/types.ts`](../packages/coding-agent/src/extensibility/custom-tools/types.ts)\n- [`src/extensibility/custom-tools/loader.ts`](../packages/coding-agent/src/extensibility/custom-tools/loader.ts)\n- [`src/sdk/session.ts`](../packages/coding-agent/src/sdk/session.ts)\n\n## What `resolve` does\n\n`resolve` is a hidden tool that finalizes a pending preview action.\n\n- `action: \"apply\"` executes the queued action's `apply(reason)` callback and returns that result with resolve metadata.\n- `action: \"discard\"` invokes `reject(reason)` if provided; otherwise returns `Discarded: <label>. Reason: <reason>`.\n\nIf no pending action exists, `resolve` fails with:\n\n- `No pending action to resolve. Nothing to apply or discard.`\n\n## Pending actions use the tool-choice queue\n\nPreview producers call `queueResolveHandler(...)`, which pushes a one-shot forced `resolve` directive onto the session tool-choice queue and adds a `resolve-reminder` steering message.\n\nRuntime behavior:\n\n- the queued handler owns the pending `apply`/`reject` callbacks,\n- `resolve` looks up the current queue invoker with `session.peekQueueInvoker()`,\n- if the model rejects the forced tool choice, the queue directive is requeued,\n- `resolve` does not maintain a separate pending-action stack.\n\nMultiple pending previews therefore follow the active tool-choice queue ordering, not an independent pending-action store.\n\n## Built-in producer example (`ast_edit`)\n\n`ast_edit` previews structural replacements first. When the preview has replacements and is not applied yet, it queues a resolve handler that contains:\n\n- label (human-readable summary)\n- `sourceToolName` (`ast_edit`)\n- `apply(reason: string)` callback that reruns AST edit with `dryRun: false`\n\n`resolve(action=\"apply\", reason=\"...\")` passes `reason` into this callback.\n\n## Custom tools: `pushPendingAction`\n\nCustom tools can register resolve-compatible pending actions through `CustomToolAPI.pushPendingAction(...)`. The custom tool loader forwards these actions to `queueResolveHandler(...)` when that hook is available.\n\n`CustomToolPendingAction`:\n\n- `label: string` (required)\n- `apply(reason: string): Promise<AgentToolResult<unknown>>` (required) — invoked on apply; `reason` is the string passed to `resolve`\n- `reject?(reason: string): Promise<AgentToolResult<unknown> | undefined>` (optional) — invoked on discard; return value replaces the default \"Discarded\" message if provided\n- `details?: unknown` exists on the public custom-tool type but is not currently forwarded by the loader into resolve metadata\n- `sourceToolName?: string` (optional, defaults to `\"custom_tool\"`)\n\n### Minimal usage example\n\n```ts\nimport type { CustomToolFactory } from \"@gajae-code/coding-agent\";\n\nconst factory: CustomToolFactory = (pi) => ({\n  name: \"batch_rename_preview\",\n  label: \"Batch Rename Preview\",\n  description: \"Previews renames and defers commit to resolve\",\n  parameters: pi.zod.object({\n    files: pi.zod.array(pi.zod.string()),\n  }),\n\n  async execute(_toolCallId, params) {\n    const previewSummary = `Prepared rename plan for ${params.files.length} files`;\n\n    pi.pushPendingAction({\n      label: `Batch rename: ${params.files.length} files`,\n      sourceToolName: \"batch_rename_preview\",\n      apply: async (reason) => {\n        // apply writes here\n        return {\n          content: [\n            { type: \"text\", text: `Applied batch rename. Reason: ${reason}` },\n          ],\n        };\n      },\n      reject: async (reason) => {\n        // optional: cleanup or notify on discard\n        return {\n          content: [\n            { type: \"text\", text: `Discarded batch rename. Reason: ${reason}` },\n          ],\n        };\n      },\n    });\n\n    return {\n      content: [\n        {\n          type: \"text\",\n          text: `${previewSummary}. Call resolve to apply or discard.`,\n        },\n      ],\n    };\n  },\n});\n\nexport default factory;\n```\n\n## Runtime availability and failures\n\n`pushPendingAction` is wired by the custom tool loader through the active session's resolve queue hook.\n\nIf the runtime did not provide the resolve queue hook, `pushPendingAction` throws:\n\n- `Pending action store unavailable for custom tools in this runtime.`\n\n## Tool-choice behavior\n\nWhen `queueResolveHandler(...)` registers a preview, the agent runtime forces a one-shot `resolve` tool choice so pending previews are explicitly finalized before normal tool flow continues.\n\n## Developer guidance\n\n- Use pending actions only for destructive or high-impact operations that should support explicit apply/discard.\n- Keep `label` concise and specific; it is shown in resolve renderer output.\n- Ensure `apply(reason)` is deterministic and idempotent enough for one-shot execution; `reason` is informational and should not change behavior.\n- Implement `reject(reason)` when the discard needs cleanup (temp state, locks, notifications); omit it for stateless previews where the default message suffices.\n- If your tool can stage multiple previews, remember they are mediated by the tool-choice queue rather than a separate pending-action stack.\n",
-	"rulebook-matching-pipeline.md": "# Rulebook Matching Pipeline\n\nThis document describes how coding-agent discovers rules from supported config formats, normalizes them into a single `Rule` shape, resolves precedence conflicts, and splits the result into:\n\n- **Rulebook rules** (available to the model via system prompt + `rule://` URLs)\n- **TTSR rules** (time-travel stream interruption rules)\n\nIt reflects the current implementation, including partial semantics and metadata that is parsed but not enforced.\n\n## Implementation files\n\n- [`../src/capability/rule.ts`](../packages/coding-agent/src/capability/rule.ts)\n- [`../src/capability/index.ts`](../packages/coding-agent/src/capability/index.ts)\n- [`../src/discovery/index.ts`](../packages/coding-agent/src/discovery/index.ts)\n- [`../src/discovery/helpers.ts`](../packages/coding-agent/src/discovery/helpers.ts)\n- [`../src/discovery/builtin.ts`](../packages/coding-agent/src/discovery/builtin.ts)\n- [`../src/discovery/cursor.ts`](../packages/coding-agent/src/discovery/cursor.ts)\n- [`../src/discovery/windsurf.ts`](../packages/coding-agent/src/discovery/windsurf.ts)\n- [`../src/discovery/cline.ts`](../packages/coding-agent/src/discovery/cline.ts)\n- [`../src/sdk/session.ts`](../packages/coding-agent/src/sdk/session.ts)\n- [`../src/system-prompt.ts`](../packages/coding-agent/src/system-prompt.ts)\n- [`../src/internal-urls/rule-protocol.ts`](../packages/coding-agent/src/internal-urls/rule-protocol.ts)\n- [`../src/utils/frontmatter.ts`](../packages/coding-agent/src/utils/frontmatter.ts)\n\n## 1. Canonical rule shape\n\nAll providers normalize source files into `Rule`:\n\n```ts\ninterface Rule {\n  name: string;\n  path: string;\n  content: string;\n  globs?: string[];\n  alwaysApply?: boolean;\n  description?: string;\n  condition?: string[];\n  scope?: string[];\n  interruptMode?: \"never\" | \"prose-only\" | \"tool-only\" | \"always\";\n  _source: SourceMeta;\n}\n```\n\nCapability identity is `rule.name` (`ruleCapability.key = rule => rule.name`).\n\nConsequence: precedence and deduplication are **name-based only**. Two different files with the same `name` are considered the same logical rule.\n\n## 2. Discovery sources and normalization\n\n`src/discovery/index.ts` auto-registers providers. For `rules`, current providers are:\n\n- `native` (priority `100`)\n- `cursor` (priority `50`)\n- `windsurf` (priority `50`)\n- `cline` (priority `40`)\n\n### Native provider (`builtin.ts`)\n\nLoads `.gjc` rules from:\n\n- project: `<cwd>/.gjc/rules/*.{md,mdc}`\n- user: `~/.gjc/agent/rules/*.{md,mdc}`\n\nNormalization:\n\n- `name` = filename without `.md`/`.mdc`\n- frontmatter parsed via `parseFrontmatter`\n- `content` = body (frontmatter stripped)\n- `globs`, `alwaysApply`, `description`, `condition`/legacy `ttsr_trigger`, `scope`, and `interruptMode` are parsed by `buildRuleFromMarkdown`\n\nImportant caveat: `condition` values that look like file globs are converted into `tool:edit(...)` / `tool:write(...)` scope shorthands with catch-all condition `.*`.\n\n### Cursor provider (`cursor.ts`)\n\nLoads from:\n\n- user: `~/.cursor/rules/*.{mdc,md}`\n- project: `<cwd>/.cursor/rules/*.{mdc,md}`\n\nNormalization (`transformMDCRule`):\n\n- `description`: kept only if string\n- `alwaysApply`: only `true` is preserved (`false` becomes `undefined`)\n- `globs`: accepts array (string elements only) or single string\n- `condition`/legacy `ttsr_trigger`, `scope`, and `interruptMode` are parsed by shared rule helpers\n- `name` from filename without extension\n\n### Windsurf provider (`windsurf.ts`)\n\nLoads from:\n\n- user: `~/.codeium/windsurf/memories/global_rules.md` (fixed rule name `global_rules`)\n- project: `<cwd>/.windsurf/rules/*.md`\n\nNormalization:\n\n- `globs`: array-of-string or single string\n- `alwaysApply`, `description`, `condition`/legacy `ttsr_trigger`, `scope`, and `interruptMode` parsed by shared rule helpers\n- `name` is fixed to `global_rules` for the user global file and derived from filename for project rules\n\n### Cline provider (`cline.ts`)\n\nSearches upward from `cwd` for nearest `.clinerules`:\n\n- if directory: loads `*.md` inside it\n- if file: loads single file as rule named `clinerules`\n\nNormalization:\n\n- `globs`: array-of-string or single string\n- `alwaysApply`, `description`, `condition`/legacy `ttsr_trigger`, `scope`, and `interruptMode` parsed by shared rule helpers\n- `name` is fixed to `clinerules` for a `.clinerules` file and derived from filename for `.clinerules/*.md`\n\n## 3. Frontmatter parsing behavior and ambiguity\n\nAll providers use `parseFrontmatter` (`utils/frontmatter.ts`) with these semantics:\n\n1. Frontmatter is parsed only when content starts with `---` and has a closing `\\n---`.\n2. Body is trimmed after frontmatter extraction.\n3. If YAML parse fails:\n   - warning is logged,\n   - parser falls back to simple `key: value` line parsing (`^(\\w+):\\s*(.*)$`).\n\nAmbiguity consequences:\n\n- Fallback parser does not support arrays, nested objects, quoting rules, or hyphenated keys.\n- Fallback values become strings (for example `alwaysApply: true` becomes string `\"true\"`), so providers requiring boolean/string types may drop metadata.\n- `ttsr_trigger` works in fallback (underscore key); keys like `thinking-level` would not.\n- Files without valid frontmatter still load as rules with empty metadata and full content body.\n\n## 4. Provider precedence and deduplication\n\n`loadCapability(\"rules\")` (`capability/index.ts`) merges provider outputs and then deduplicates by `rule.name`.\n\n### Precedence model\n\n- Providers are ordered by priority descending.\n- Equal priority keeps registration order (`cursor` before `windsurf` from `discovery/index.ts`).\n- Dedup is first-wins: first encountered rule name is kept; later same-name items are marked `_shadowed` in `all` and excluded from `items`.\n\nEffective rule provider order is currently:\n\n1. `native` (100)\n2. `cursor` (50)\n3. `windsurf` (50)\n4. `cline` (40)\n\n### Intra-provider ordering caveat\n\nWithin a provider, item order comes from `loadFilesFromDir` glob result ordering plus explicit push order. This is deterministic enough for normal use but not explicitly sorted in code.\n\nNotable source-order differences:\n\n- `native` appends project then user config dirs.\n- `cursor` appends user then project results.\n- `windsurf` appends user `global_rules` first, then project rules.\n- `cline` loads only nearest `.clinerules` source.\n\n## 5. Split into Rulebook, Always-Apply, and TTSR buckets\n\nAfter rule discovery in `createAgentSession` (`sdk.ts`):\n\n1. All discovered rules are scanned.\n2. Rules with `condition` entries are registered into `TtsrManager`; legacy `ttsr_trigger` / `ttsrTrigger` are accepted during rule parsing as condition fallbacks.\n3. A separate `rulebookRules` list is built with this predicate:\n\n```ts\n!isTtsrRule && rule.alwaysApply !== true && !!rule.description;\n```\n\n4. An `alwaysApplyRules` list is built:\n\n```ts\n!isTtsrRule && rule.alwaysApply === true;\n```\n\n### Bucket behavior\n\n- **TTSR bucket**: any rule with a non-empty parsed `condition` that `TtsrManager.addRule(...)` accepts. Takes priority over other buckets.\n- **Always-apply bucket**: `alwaysApply === true`, not TTSR. Full content injected into system prompt. Resolvable via `rule://`.\n- **Rulebook bucket**: must have description, must not be TTSR, must not be `alwaysApply`. Listed in system prompt by name+description; content read on demand via `rule://`.\n- A rule with both `condition` and `alwaysApply` goes to TTSR only (TTSR takes priority).\n- A rule with both `alwaysApply` and `description` goes to always-apply only (not rulebook).\n\n## 6. How metadata affects runtime surfaces\n\n### `description`\n\n- Required for inclusion in rulebook.\n- Rendered in system prompt `<rules>` block.\n- Missing description means rule is not available via `rule://` and not listed in system prompt rules.\n\n### `globs`\n\n- Carried through on `Rule`.\n- Rendered as `<glob>...</glob>` entries in the system prompt rules block.\n- Exposed in rules UI state (`extensions` mode list).\n- **Not enforced for automatic matching in this pipeline.** There is no runtime glob matcher selecting rules by current file/tool target.\n\n### `alwaysApply`\n\n- Parsed and preserved by providers.\n- Used in UI display (`\"always\"` trigger label in extensions state manager).\n- Used as an exclusion condition from `rulebookRules`.\n- **Full rule content is auto-injected into the system prompt** (before the rulebook rules section).\n- Rule is also addressable via `rule://<name>` for re-reading.\n\n### `condition`, `scope`, and `interruptMode`\n\n- `condition` is the current TTSR trigger field; legacy `ttsr_trigger` / `ttsrTrigger` are accepted as fallback inputs during parsing.\n- `scope` narrows TTSR matching scope. A condition token that looks like a file glob becomes `tool:edit(<glob>)` and `tool:write(<glob>)` scope entries plus catch-all condition `.*`.\n- `interruptMode` can override the global TTSR interrupt mode for the rule.\n\n## 7. System prompt inclusion path\n\n`buildSystemPromptInternal` receives both `rules` (rulebook) and `alwaysApplyRules`.\n\nAlways-apply rules are rendered first, injecting their raw content directly into the prompt.\n\nRulebook rules are rendered in a `# Rules` section with:\n\n- `Read rule://<name> when working in matching domain`\n- Each rule's `name`, `description`, and optional `<glob>` list\n\nThis is advisory/contextual: prompt text asks the model to read applicable rules, but code does not enforce glob applicability.\n\n## 8. `rule://` internal URL behavior\n\n`RuleProtocolHandler` is registered with:\n\n```ts\nnew RuleProtocolHandler({\n  getRules: () => [...rulebookRules, ...alwaysApplyRules],\n});\n```\n\nImplications:\n\n- `rule://<name>` resolves against both **rulebookRules** and **alwaysApplyRules**.\n- TTSR-only rules and rules with no description and no `alwaysApply` are not addressable via `rule://`.\n- Resolution is exact name match.\n- Unknown names return error listing available rule names.\n- Returned content is raw `rule.content` (frontmatter stripped), content type `text/markdown`.\n\n## 9. Known partial / non-enforced semantics\n\n1. Provider descriptions mention legacy files (`.cursorrules`, `.windsurfrules`), but current loader code paths do not actually read those files.\n2. `globs` metadata is surfaced to prompt/UI but not enforced by rule selection logic.\n3. Rule selection for `rule://` includes rulebook and always-apply rules, but not TTSR-only rules.\n4. Discovery warnings (`loadCapability(\"rules\").warnings`) are produced but `createAgentSession` does not currently surface/log them in this path.\n",
+	"rulebook-matching-pipeline.md": "# Rulebook Matching Pipeline\n\nThis document describes how coding-agent discovers rules from supported config formats, normalizes them into a single `Rule` shape, resolves precedence conflicts, and splits the result into:\n\n- **Rulebook rules** (available to the model via system prompt + `rule://` URLs)\n- **TTSR rules** (time-travel stream interruption rules)\n\nIt reflects the current implementation, including partial semantics and metadata that is parsed but not enforced.\n\n## Implementation files\n\n- [`../src/capability/rule.ts`](../packages/coding-agent/src/capability/rule.ts)\n- [`../src/capability/index.ts`](../packages/coding-agent/src/capability/index.ts)\n- [`../src/discovery/index.ts`](../packages/coding-agent/src/discovery/index.ts)\n- [`../src/discovery/helpers.ts`](../packages/coding-agent/src/discovery/helpers.ts)\n- [`../src/discovery/builtin.ts`](../packages/coding-agent/src/discovery/builtin.ts)\n- [`../src/discovery/cursor.ts`](../packages/coding-agent/src/discovery/cursor.ts)\n- [`../src/discovery/windsurf.ts`](../packages/coding-agent/src/discovery/windsurf.ts)\n- [`../src/discovery/cline.ts`](../packages/coding-agent/src/discovery/cline.ts)\n- [`../src/sdk/session.ts`](../packages/coding-agent/src/sdk/session.ts)\n- [`../src/system-prompt.ts`](../packages/coding-agent/src/system-prompt.ts)\n- [`../src/internal-urls/rule-protocol.ts`](../packages/coding-agent/src/internal-urls/rule-protocol.ts)\n- [`packages/utils/src/frontmatter.ts`](../packages/utils/src/frontmatter.ts)\n\n## 1. Canonical rule shape\n\nAll providers normalize source files into `Rule`:\n\n```ts\ninterface Rule {\n  name: string;\n  path: string;\n  content: string;\n  globs?: string[];\n  alwaysApply?: boolean;\n  description?: string;\n  condition?: string[];\n  scope?: string[];\n  interruptMode?: \"never\" | \"prose-only\" | \"tool-only\" | \"always\";\n  _source: SourceMeta;\n}\n```\n\nCapability identity is `rule.name` (`ruleCapability.key = rule => rule.name`).\n\nConsequence: precedence and deduplication are **name-based only**. Two different files with the same `name` are considered the same logical rule.\n\n## 2. Discovery sources and normalization\n\n`src/discovery/index.ts` auto-registers providers. For `rules`, current providers are:\n\n- `native` (priority `100`)\n- `cursor` (priority `50`)\n- `windsurf` (priority `50`)\n- `cline` (priority `40`)\n\n### Native provider (`builtin.ts`)\n\nLoads `.gjc` rules from:\n\n- project: `<cwd>/.gjc/rules/*.{md,mdc}`\n- user: `~/.gjc/agent/rules/*.{md,mdc}`\n\nNormalization:\n\n- `name` = filename without `.md`/`.mdc`\n- frontmatter parsed via `parseFrontmatter`\n- `content` = body (frontmatter stripped)\n- `globs`, `alwaysApply`, `description`, `condition`/legacy `ttsr_trigger`, `scope`, and `interruptMode` are parsed by `buildRuleFromMarkdown`\n\nImportant caveat: `condition` values that look like file globs are converted into `tool:edit(...)` / `tool:write(...)` scope shorthands with catch-all condition `.*`.\n\n### Cursor provider (`cursor.ts`)\n\nLoads from:\n\n- user: `~/.cursor/rules/*.{mdc,md}`\n- project: `<cwd>/.cursor/rules/*.{mdc,md}`\n\nNormalization (`transformMDCRule`):\n\n- `description`: kept only if string\n- `alwaysApply`: only `true` is preserved (`false` becomes `undefined`)\n- `globs`: accepts array (string elements only) or single string\n- `condition`/legacy `ttsr_trigger`, `scope`, and `interruptMode` are parsed by shared rule helpers\n- `name` from filename without extension\n\n### Windsurf provider (`windsurf.ts`)\n\nLoads from:\n\n- user: `~/.codeium/windsurf/memories/global_rules.md` (fixed rule name `global_rules`)\n- project: `<cwd>/.windsurf/rules/*.md`\n\nNormalization:\n\n- `globs`: array-of-string or single string\n- `alwaysApply`, `description`, `condition`/legacy `ttsr_trigger`, `scope`, and `interruptMode` parsed by shared rule helpers\n- `name` is fixed to `global_rules` for the user global file and derived from filename for project rules\n\n### Cline provider (`cline.ts`)\n\nSearches upward from `cwd` for nearest `.clinerules`:\n\n- if directory: loads `*.md` inside it\n- if file: loads single file as rule named `clinerules`\n\nNormalization:\n\n- `globs`: array-of-string or single string\n- `alwaysApply`, `description`, `condition`/legacy `ttsr_trigger`, `scope`, and `interruptMode` parsed by shared rule helpers\n- `name` is fixed to `clinerules` for a `.clinerules` file and derived from filename for `.clinerules/*.md`\n\n## 3. Frontmatter parsing behavior and ambiguity\n\nAll providers use `parseFrontmatter` (`utils/frontmatter.ts`) with these semantics:\n\n1. Frontmatter is parsed only when content starts with `---` and has a closing `\\n---`.\n2. Body is trimmed after frontmatter extraction.\n3. If YAML parse fails:\n   - warning is logged,\n   - parser falls back to simple `key: value` line parsing (`^(\\w+):\\s*(.*)$`).\n\nAmbiguity consequences:\n\n- Fallback parser does not support arrays, nested objects, quoting rules, or hyphenated keys.\n- Fallback values become strings (for example `alwaysApply: true` becomes string `\"true\"`), so providers requiring boolean/string types may drop metadata.\n- `ttsr_trigger` works in fallback (underscore key); keys like `thinking-level` would not.\n- Files without valid frontmatter still load as rules with empty metadata and full content body.\n\n## 4. Provider precedence and deduplication\n\n`loadCapability(\"rules\")` (`capability/index.ts`) merges provider outputs and then deduplicates by `rule.name`.\n\n### Precedence model\n\n- Providers are ordered by priority descending.\n- Equal priority keeps registration order (`cursor` before `windsurf` from `discovery/index.ts`).\n- Dedup is first-wins: first encountered rule name is kept; later same-name items are marked `_shadowed` in `all` and excluded from `items`.\n\nEffective rule provider order is currently:\n\n1. `native` (100)\n2. `cursor` (50)\n3. `windsurf` (50)\n4. `cline` (40)\n\n### Intra-provider ordering caveat\n\nWithin a provider, item order comes from `loadFilesFromDir` glob result ordering plus explicit push order. This is deterministic enough for normal use but not explicitly sorted in code.\n\nNotable source-order differences:\n\n- `native` appends project then user config dirs.\n- `cursor` appends user then project results.\n- `windsurf` appends user `global_rules` first, then project rules.\n- `cline` loads only nearest `.clinerules` source.\n\n## 5. Split into Rulebook, Always-Apply, and TTSR buckets\n\nAfter rule discovery in `createAgentSession` (`sdk.ts`):\n\n1. All discovered rules are scanned.\n2. Rules with `condition` entries are registered into `TtsrManager`; legacy `ttsr_trigger` / `ttsrTrigger` are accepted during rule parsing as condition fallbacks.\n3. A separate `rulebookRules` list is built with this predicate:\n\n```ts\n!isTtsrRule && rule.alwaysApply !== true && !!rule.description;\n```\n\n4. An `alwaysApplyRules` list is built:\n\n```ts\n!isTtsrRule && rule.alwaysApply === true;\n```\n\n### Bucket behavior\n\n- **TTSR bucket**: any rule with a non-empty parsed `condition` that `TtsrManager.addRule(...)` accepts. Takes priority over other buckets.\n- **Always-apply bucket**: `alwaysApply === true`, not TTSR. Full content injected into system prompt. Resolvable via `rule://`.\n- **Rulebook bucket**: must have description, must not be TTSR, must not be `alwaysApply`. Listed in system prompt by name+description; content read on demand via `rule://`.\n- A rule with both `condition` and `alwaysApply` goes to TTSR only (TTSR takes priority).\n- A rule with both `alwaysApply` and `description` goes to always-apply only (not rulebook).\n\n## 6. How metadata affects runtime surfaces\n\n### `description`\n\n- Required for inclusion in rulebook.\n- Rendered in system prompt `<rules>` block.\n- Missing description means rule is not available via `rule://` and not listed in system prompt rules.\n\n### `globs`\n\n- Carried through on `Rule`.\n- Rendered as `<glob>...</glob>` entries in the system prompt rules block.\n- Exposed in rules UI state (`extensions` mode list).\n- **Not enforced for automatic matching in this pipeline.** There is no runtime glob matcher selecting rules by current file/tool target.\n\n### `alwaysApply`\n\n- Parsed and preserved by providers.\n- Used in UI display (`\"always\"` trigger label in extensions state manager).\n- Used as an exclusion condition from `rulebookRules`.\n- **Full rule content is auto-injected into the system prompt** (before the rulebook rules section).\n- Rule is also addressable via `rule://<name>` for re-reading.\n\n### `condition`, `scope`, and `interruptMode`\n\n- `condition` is the current TTSR trigger field; legacy `ttsr_trigger` / `ttsrTrigger` are accepted as fallback inputs during parsing.\n- `scope` narrows TTSR matching scope. A condition token that looks like a file glob becomes `tool:edit(<glob>)` and `tool:write(<glob>)` scope entries plus catch-all condition `.*`.\n- `interruptMode` can override the global TTSR interrupt mode for the rule.\n\n## 7. System prompt inclusion path\n\n`buildSystemPromptInternal` receives both `rules` (rulebook) and `alwaysApplyRules`.\n\nAlways-apply rules are rendered first, injecting their raw content directly into the prompt.\n\nRulebook rules are rendered in a `# Rules` section with:\n\n- `Read rule://<name> when working in matching domain`\n- Each rule's `name`, `description`, and optional `<glob>` list\n\nThis is advisory/contextual: prompt text asks the model to read applicable rules, but code does not enforce glob applicability.\n\n## 8. `rule://` internal URL behavior\n\n`RuleProtocolHandler` is registered with:\n\n```ts\nnew RuleProtocolHandler({\n  getRules: () => [...rulebookRules, ...alwaysApplyRules],\n});\n```\n\nImplications:\n\n- `rule://<name>` resolves against both **rulebookRules** and **alwaysApplyRules**.\n- TTSR-only rules and rules with no description and no `alwaysApply` are not addressable via `rule://`.\n- Resolution is exact name match.\n- Unknown names return error listing available rule names.\n- Returned content is raw `rule.content` (frontmatter stripped), content type `text/markdown`.\n\n## 9. Known partial / non-enforced semantics\n\n1. Provider descriptions mention legacy files (`.cursorrules`, `.windsurfrules`), but current loader code paths do not actually read those files.\n2. `globs` metadata is surfaced to prompt/UI but not enforced by rule selection logic.\n3. Rule selection for `rule://` includes rulebook and always-apply rules, but not TTSR-only rules.\n4. Discovery warnings (`loadCapability(\"rules\").warnings`) are produced but `createAgentSession` does not currently surface/log them in this path.\n",
+	"rust-porting-inventory.md": "# Rust porting inventory\n\nTracks every candidate for moving gjc hot paths and TypeScript implementations\ninto the native addon (`crates/pi-natives` via `@gajae-code/natives`), whether\nvendored from upstream or hand-ported after profiling.\n\nUpstream pin: `can1357/oh-my-pi@a85bd5228d9f0f619deade1db78fa49420a721e1`\n\n- Upstream sources are read only at this commit\n  (`https://raw.githubusercontent.com/can1357/oh-my-pi/<pin>/<path>`), never from `main`.\n- Every vendored file carries an attribution header naming this commit, unless its\n  row below records a per-row bump made by the PR that needed newer code.\n- Upstream is MIT licensed; vendored crates keep their `LICENSE` and are listed in `NOTICE.md`.\n- `docs/rust-porting/upstream-workspace-deps@a85bd522.toml` is a verbatim snapshot of the\n  upstream root `[workspace.dependencies]` at the pin. `bun scripts/verify-rust-porting-inventory.ts --deps`\n  checks the local workspace against it.\n\n## Status vocabulary\n\n| Status | Meaning |\n|---|---|\n| `candidate` | Listed, not started. |\n| `in-progress` | PR open, or crate landed but some consumers are not wired yet. |\n| `adopted` | Merged with parity, benchmark, and rehearsal evidence; replaced TS deleted with no fallback. |\n| `rejected` | Not adopted; `reason` is mandatory. |\n| `keep-local` | gjc-only Rust that a re-sync must not overwrite; guarded by named tests. |\n\n## Phase log\n\n| Phase | Status | PR | Rehearsal run | Notes |\n|---|---|---|---|---|\n| 0 — toolchain and shared deps at pin | in-progress | | | `nightly-2026-08-12`; shared workspace deps aligned to the pin. |\n\n## Inventory tables\n\nTables A–E (upstream-only crates, upstream-only `pi-natives` modules, overlap drift,\nkeep-local ledger, hot-path candidates) are written in Phase 1b.\n",
 	"sdk-app-guide.md": "# Building Applications on the Gajae-Code SDK\n\nA beginner-friendly guide to using Gajae-Code as the **agent runtime for your own\napplication** — mobile apps, desktop apps, custom web frontends, chat bots, and\nvertical AI products.\n\n> Proof that this works in production: the bundled **Telegram, Discord, and Slack\n> integrations are SDK-core managed adapters**. They use opaque Router attachments\n> and provider-neutral presentation contracts rather than private endpoint credentials.\n\nRelated references:\n\n- [SDK wire protocol & machine interfaces](./sdk.md) — internal wire semantics and supported managed adapters\n- [Embedding SDK](./sdk-embedding.md) — the in-process TypeScript API\n- [External control readiness](./external-control-readiness.md) — supported surfaces\n\n## Why build on Gajae-Code?\n\nEvery vertical AI app ends up needing the same backend pieces: an agentic loop,\ntool execution, session persistence, model/auth management, streaming, retries,\nand compaction. Some also need a configured remote-notification integration.\nTeams keep rebuilding these from scratch.\n\nGajae-Code packages the runtime as a reusable component:\n\n- **Drop the agentic loop from your codebase.** `createAgentSession()` gives you\n  a production agent loop (tools, retries, compaction, session files, model\n  fallback chains) in one call.\n- **A managed machine interface is available.** Top-level sessions host an internal\n  loopback endpoint, while SDK-core `SessionRouter` retains its discovery record,\n  credentials, replay cursor, and exact attachment authority. Applications use\n  Coordinator MCP, the SDK session CLI, or a configured managed adapter rather\n  than opening that endpoint directly.\n- **Many subscribers, one session.** In-process subscribers and configured managed\n  adapters can observe the same session without sharing endpoint credentials.\n- **Not just for coding.** Tools, skills, rules, and the system prompt are all\n  injectable, so the same runtime powers legal assistants, research agents,\n  data-analysis products — any vertical.\n\n\n## The two supported integration surfaces\n\n| | Embedding SDK (in-process) | Managed external control |\n| --- | --- | --- |\n| What it is | Import `@gajae-code/coding-agent` as a library | Use Coordinator MCP, SDK session CLI, or a configured Telegram/Discord/Slack adapter |\n| Language | TypeScript / Bun (Node-compatible) | Any client capable of the selected MCP/CLI/provider interface |\n| Telemetry | Full token deltas, tool events, and session events | Curated provider-neutral frames and queries |\n| Trust model | Your process hosts the runtime | SDK core retains endpoint credentials and issues exact opaque attachments |\n| Typical consumer | Your app UI and business logic | Bots, dashboards, and orchestrators |\n\nA common production shape combines an in-process UI with one or more configured\nmanaged adapters. Applications never discover endpoint records or open raw session\nWebSockets.\n\n\n## Quick start: embed the runtime\n\n```bash\nbun add @gajae-code/coding-agent\n```\n\n```ts\nimport { createAgentSession } from \"@gajae-code/coding-agent\";\n\nconst { session } = await createAgentSession();\n\nsession.subscribe((event) => {\n  if (\n    event.type === \"message_update\" &&\n    event.assistantMessageEvent.type === \"text_delta\"\n  ) {\n    process.stdout.write(event.assistantMessageEvent.delta); // token-level stream\n  }\n});\n\nawait session.prompt(\"Summarize this repository in 3 bullets.\");\nawait session.dispose();\n```\n\n`createAgentSession()` follows *provide to override, omit to discover*: with no\noptions it auto-discovers auth, models, settings, tools, context files, and a\nfile-backed session store. Everything is overridable.\n\n## Customizing the runtime for your vertical\n\nThis is the part that turns Gajae-Code from \"a coding agent\" into a general\nexecution runtime. All of the following are `createAgentSession()` options; see\nthe [Embedding SDK](./sdk-embedding.md) for the public API.\n\n### Restrict or drop tools\n\n```ts\nconst { session } = await createAgentSession({\n  // Allowlist of built-ins — everything else is dropped.\n  toolNames: [\"read\", \"grep\", \"find\"],\n  // Optionally restrict bash to specific command prefixes.\n  bashAllowedPrefixes: [\"git status\", \"git log\"],\n});\n```\n\nRuntime changes are also supported: `session.getActiveToolNames()`,\n`session.getAllToolNames()`, `session.setActiveToolsByName(names)` — the system\nprompt is rebuilt automatically.\n\n### Add custom tools\n\n```ts\nconst { session } = await createAgentSession({\n  toolNames: [\"read\"],\n  customTools: [myDomainTool], // CustomTool | ToolDefinition\n  // Or bring tools from an MCP server you own:\n  mcpConfigPath: \"/abs/path/to/mcp-config.json\",\n});\n```\n\n### Inject skills, rules, and identity\n\n```ts\nconst { session } = await createAgentSession({\n  skills: myVerticalSkills,        // replaces bundled skill discovery\n  rules: myRules,\n  contextFiles: [{ path: \"DOMAIN.md\", content: domainKnowledge }],\n  systemPrompt: (defaults) => [...defaults, myVerticalPromptBlock],\n  promptTemplates: myTemplates,\n});\n```\n\n### Isolate state for request-scoped agents\n\n```ts\nimport { SessionManager, Settings } from \"@gajae-code/coding-agent\";\n\nconst { session } = await createAgentSession({\n  sessionManager: SessionManager.inMemory(), // no filesystem persistence\n  settings: Settings.isolated({ \"compaction.enabled\": true }),\n});\n```\n\n### Structured-output subagents\n\n`outputSchema`, `requireYieldTool`, `taskDepth`, and `parentTaskPrefix` support\norchestrator patterns where a session must return machine-readable results.\n\n### Observability\n\nPass `telemetry: {}` to enable OpenTelemetry GenAI-semantic-convention spans\n(no-op unless an OTEL SDK is registered in your host).\n\n## Attach from another process\n\nProcess-isolated integrations use an SDK-core adapter backed by `SessionRouter`. Endpoint discovery records and bearer tokens are internal implementation details; applications must not read them or open raw session WebSockets.\n\nManaged adapters receive opaque `SessionAttachment` capabilities for live controls and submit lifecycle mutations through `SessionLifecycleService`. See [sdk.md](./sdk.md) for the ownership and adapter contract.\n\nThe `models.list/current` (Q10) catalog also lists model profiles as synthetic\n`gajae-code/<profile>` entries (e.g. `gajae-code/codex-eco`). Treat them as\nlogical selections, not API providers: sending the id back through `model.set`\nactivates the profile for the live session only. Persisting remains an explicit\nTUI choice. Request Q27 (`models.profiles.list`) when you need the\nfull profile catalog including unavailable profiles and their `available`\nstatus. See [Model profiles as synthetic models](./sdk.md#model-profiles-as-synthetic-models-gajae-codeprofile).\n\n## Creating and supervising sessions\n\nEmbedding creates a session directly with `createAgentSession()`. For an\nexternal controller that needs lifecycle operations, use Coordinator MCP or the\nSDK session CLI. A lifecycle CLI request names the `global` action,\nprovides its operation and JSON input, and supplies a caller-chosen idempotency\nkey:\n\n```bash\ngjc sdk session raw global --op session.create \\\n  --idempotency-key <unique-key> \\\n  --json-input '{\"cwd\":\"/absolute/path/to/repo\"}'\n```\n\nThe CLI connects to the broker as needed; broker bootstrap is not an embedder\nAPI. See the [external controller integration guide](./bot-integration.md#integration-surfaces)\nfor the supported controller surfaces and lifecycle constraints.\n\nFor an in-process application queue, treat `session.prompt()` as a bounded full\nturn and keep request identity and transport completion in the application.\nUse `steer`/`followUp` for live conversational controls, not as a durable queue\nreceipt: admission can complete before a message is consumed, a follow-up can\nshare the current run, and `waitForIdle()` does not by itself promise that every\ninput queue is empty. See [Queued input lifecycle](./sdk-embedding.md#queued-input-lifecycle)\nfor the admission, consumption, promotion, and terminal boundaries.\n\n\n## Application recipes\n\n- **Vertical AI app.** Embed with `toolNames`, `customTools`, `skills`, and a domain\n  `systemPrompt`. Subscribe in-process for full-fidelity streaming.\n- **Custom web app or dashboard.** Keep the agent runtime in your backend process;\n  expose your own authenticated product API, or use Coordinator MCP for supported\n  external orchestration. Do not relay the internal session endpoint.\n- **Mobile or desktop companion.** Pair through a configured managed notification\n  adapter for actions and approvals, or call an application backend that embeds GJC.\n- **Fleet orchestrator.** Use Coordinator MCP or daemon-session lifecycle operations\n  to create and supervise worktree-scoped sessions.\n\n## External interface constraints\n\n- Endpoint records, bearer tokens, and raw session WebSockets are private SDK-core\n  implementation details.\n- `config.patch` rejects secret fields, and `session.get_endpoint` is prohibited on\n  public adapters.\n- Full-fidelity token deltas remain an in-process embedding capability.\n- Action identity is fail-closed: stale IDs never regain authority.\n\nDestructive operations (`session.delete`, `context.clear`) require\n`confirm: true`.\n\n## FAQ\n\n**Is embedding a subprocess?** No — it is a library import; the agent loop runs\nin your process. Process-isolated control uses Coordinator MCP, SDK session CLI,\nor a configured managed adapter.\n\n**Can multiple consumers watch one session?** Yes. In-process subscribers and\nmanaged adapters are additive; replies to asks remain first-valid-wins.\n\n**Can the TUI and my code share a session?** Use in-process embedding for code that\nhosts the runtime, or Coordinator MCP/managed adapters for process-isolated control.\nSession files remain resumable through canonical lifecycle operations.\n\n**I need another language.** Use Coordinator MCP or your own authenticated backend\naround the TypeScript embedding SDK. Dedicated embedding-like Rust/Python SDKs are\nroadmap work, not raw endpoint contracts.\n",
-	"sdk-embedding.md": "# SDK\n\nFor managed control and notification attachment policy, see [the Gajae-Code SDK](./sdk.md).\n\nThe SDK is the in-process integration surface for `@gajae-code/coding-agent`.\nUse it when you want direct access to agent state, event streaming, tool wiring, and session control from your own Bun/Node process.\n\nFor process-isolated control, use a managed SDK-core adapter backed by `SessionRouter`; raw endpoint discovery and direct WebSocket clients are not public integration surfaces.\n\n## Installation\n\n```bash\nbun add @gajae-code/coding-agent\n```\n\n\n## Entry points\n\n`@gajae-code/coding-agent/sdk` is the canonical entry point for embedders. The package root exports the same SDK APIs for convenience.\n\nCore exports for embedders:\n\n- `createAgentSession`\n- `SessionManager`\n- `Settings`\n- `AuthStorage`\n- `ModelRegistry`\n- `discoverAuthStorage`\n- Discovery helpers for retained context/prompt surfaces (`discoverContextFiles`, `discoverPromptTemplates`)\n- Tool factory surface (`createTools`, `BUILTIN_TOOLS`, tool classes)\n\n## Quick start (auto-discovery defaults)\n\n```ts\nimport { createAgentSession } from \"@gajae-code/coding-agent\";\n\nconst { session, modelFallbackMessage } = await createAgentSession();\n\nif (modelFallbackMessage) {\n  process.stderr.write(`${modelFallbackMessage}\\n`);\n}\n\nconst unsubscribe = session.subscribe((event) => {\n  if (\n    event.type === \"message_update\" &&\n    event.assistantMessageEvent.type === \"text_delta\"\n  ) {\n    process.stdout.write(event.assistantMessageEvent.delta);\n  }\n});\n\nawait session.prompt(\"Summarize this repository in 3 bullets.\");\nunsubscribe();\nawait session.dispose();\n```\n\n## What `createAgentSession()` discovers by default\n\n`createAgentSession()` follows “provide to override, omit to discover”.\n\nIf omitted, it resolves:\n\n- `cwd`: `getProjectDir()`\n- `agentDir`: `~/.gjc/agent` (via `getAgentDir()`)\n- `authStorage`: `discoverAuthStorage(agentDir)`\n- `modelRegistry`: `new ModelRegistry(authStorage)` + background `refreshInBackground()` when the registry is not provided\n- `settings`: `await Settings.init({ cwd, agentDir })`\n- `sessionManager`: `SessionManager.create(cwd)` (file-backed)\n- context files and prompt templates\n- built-in tools via `createTools(...)`\n- LSP integration (enabled by default)\n- `eventBus`: new `EventBus()` unless supplied\n\n### Required vs optional inputs\n\nTypically you must provide only what you want to control:\n\n- **Must provide**: nothing for a minimal session\n- **Usually provide explicitly** in embedders:\n  - `sessionManager` (if you need in-memory or custom location)\n  - `authStorage` + `modelRegistry` (if you own credential/model lifecycle)\n  - `model` or `modelPattern` (if deterministic model selection matters)\n  - `settings` (if you need isolated/test config)\n\n## Session manager behavior (persistent vs in-memory)\n\n`AgentSession` always uses a `SessionManager`; behavior depends on which factory you use.\n\n### File-backed (default)\n\n```ts\nimport { createAgentSession, SessionManager } from \"@gajae-code/coding-agent\";\n\nconst { session } = await createAgentSession({\n  sessionManager: SessionManager.create(process.cwd()),\n});\n\nconsole.log(session.sessionFile); // absolute .jsonl path\n```\n\n- Persists conversation/messages/state deltas to session files.\n- Supports resume/open/list/fork workflows.\n- `session.sessionFile` is defined.\n\n### In-memory\n\n```ts\nimport { createAgentSession, SessionManager } from \"@gajae-code/coding-agent\";\n\nconst { session } = await createAgentSession({\n  sessionManager: SessionManager.inMemory(),\n});\n\nconsole.log(session.sessionFile); // undefined\n```\n\n- No filesystem persistence.\n- Useful for tests, ephemeral workers, request-scoped agents.\n- Session methods still work, but persistence-specific behaviors (file resume/fork paths) are naturally limited.\n\n### Resume/open/list helpers\n\n```ts\nimport { SessionManager } from \"@gajae-code/coding-agent\";\n\nconst recent = await SessionManager.continueRecent(process.cwd());\nconst listed = await SessionManager.list(process.cwd());\nconst opened = listed[0] ? await SessionManager.open(listed[0].path) : null;\n```\n\n## Model and auth wiring\n\n`createAgentSession()` uses `ModelRegistry` + `AuthStorage` for model selection and API key resolution.\n\n### Explicit wiring\n\n```ts\nimport {\n  createAgentSession,\n  discoverAuthStorage,\n  ModelRegistry,\n  SessionManager,\n} from \"@gajae-code/coding-agent\";\n\nconst authStorage = await discoverAuthStorage();\nconst modelRegistry = new ModelRegistry(authStorage);\nawait modelRegistry.refresh();\n\nconst available = modelRegistry.getAvailable();\nif (available.length === 0)\n  throw new Error(\"No authenticated models available\");\n\nconst { session } = await createAgentSession({\n  authStorage,\n  modelRegistry,\n  model: available[0],\n  thinkingLevel: \"medium\",\n  sessionManager: SessionManager.inMemory(),\n});\n```\n\n### Selection order when `model` is omitted\n\nWhen no explicit `model`/`modelPattern` is provided:\n\n1. restore model from existing session (if restorable + key available)\n2. settings default model role (`default`)\n3. first available model with valid auth\n\nIf restore fails, `modelFallbackMessage` explains fallback.\n\n### Auth priority\n\n`AuthStorage.getApiKey(...)` resolves in this order:\n\n1. runtime override (`setRuntimeApiKey`)\n2. stored credentials in `agent.db`\n3. provider environment variables\n4. custom-provider resolver fallback (if configured)\n\n## Event subscription model\n\nSubscribe with `session.subscribe(listener)`; it returns an unsubscribe function.\n\n```ts\nconst unsubscribe = session.subscribe((event) => {\n  switch (event.type) {\n    case \"agent_start\":\n    case \"turn_start\":\n    case \"tool_execution_start\":\n      break;\n    case \"message_update\":\n      if (event.assistantMessageEvent.type === \"text_delta\") {\n        process.stdout.write(event.assistantMessageEvent.delta);\n      }\n      break;\n  }\n});\n```\n\n`AgentSessionEvent` includes core `AgentEvent` plus session-level events:\n\n- `auto_compaction_start` / `auto_compaction_end`\n- `auto_retry_start` / `auto_retry_end`\n- `agent_failed` (diagnostic failure for the current attempt; the correlated\n  terminal `agent_end` still follows and remains the lifecycle boundary)\n- `retry_fallback_applied` / `retry_fallback_succeeded`\n- `ttsr_triggered`\n- `todo_reminder` / `todo_auto_clear`\n- `irc_message`\n\n## Prompt lifecycle\n\n`session.prompt(text, options?)` is the primary entry point.\n\nFailure consumers should handle `agent_failed` as an additive diagnostic event,\nnot as terminal completion. It carries only the sanitized `{ code, message }`\ndiagnostic for the correlated attempt — never the raw provider/local error —\nso consumers must not depend on provider-specific detail or raw error objects;\ncontinue waiting for `agent_end` before releasing prompt ownership, deadlines,\nor transport resources. This ordering also applies when the run is canceled or\nenters a maintenance continuation.\n\nBehavior:\n\n1. optional command/template expansion (`/` commands, custom commands, file slash commands, prompt templates)\n2. if currently streaming:\n   - requires `streamingBehavior: \"steer\" | \"followUp\"`\n   - queues instead of throwing work away\n3. if idle:\n   - validates model + API key\n   - appends user message\n   - starts agent turn\n\n### Queued input lifecycle\n\nKeep admission, consumption, and completion separate when embedding the SDK:\n\n| Session state | Admission | Consumption | Completion |\n| --- | --- | --- | --- |\n| Fresh or settled idle with an assistant tail | `prompt()` starts a turn; an explicit `followUp` is accepted into the executable queue | The next turn consumes the queued message and normally starts its own run | That run publishes its own terminal `agent_end` |\n| Live model/tool loop | `steer` may be consumed by the current run; `followUp` waits for the next turn | The live loop can consume the message before its terminal boundary | The message may share the current run and terminal; it is not necessarily a separate model call |\n| Prompt unwind after the Agent loop emitted `agent_end` | An explicit `followUp` is still accepted | The SDK schedules a queued-only successor after the unwind finishes; it is not left waiting for an unrelated prompt | The successor owns a new run and terminal boundary |\n| Paused, cancelled, or a non-resumable non-assistant tail | The message can remain queued | No automatic successor is promised until a supported resume/abort path makes the queue deliverable | The admission is not completion; clear/remove the queue or resume it explicitly |\n| Existing queued input ahead of a new submission | The new message is ordered behind the existing queue | Queue order is preserved; later plain prompts do not overtake an earlier follow-up | Each consumed message is correlated at its actual dequeue boundary |\n\n`session.waitForIdle()` waits for active Agent work, session settlement, and\ncontinuations that the SDK has scheduled. It is **not** a receipt that every\nsteering/follow-up queue is empty. Inspect `pendingMessageCounts` or use the\nqueue APIs when queue state matters. A queued follow-up can also share the\npredecessor's run and terminal when the live loop consumes it; do not equate\none accepted submission with one model call or one `agent_end` event.\n\nFor generic embedders, prefer an application-owned queue of bounded full turns\nsubmitted through `session.prompt()`, and use `steer`/`followUp` only for live\nconversational controls. When a queued control must remain pending until its\nexact ownership is known, use `submitUserMessage()`:\n\n```ts\nconst submission = await session.submitUserMessage(\"refresh the status\", {\n  deliverAs: \"followUp\",\n  queuePolicy: \"sequential\",\n  trackSubmission: true,\n});\n\nawait submission.admitted;\nconst execution = await submission.execution;\n// execution.disposition is \"joined-current-run\", \"promoted-to-run\", or \"removed\".\n// For execution, attemptScope identifies the run that owns the terminal boundary.\nawait submission.terminal;\n```\n\n`submissionId` is generated per call, so identical message text remains\nindependently correlatable. `admitted` resolves only after the exact queue\nentry exists. `execution` resolves at same-run consumption, successor-run\npromotion, or exact removal. `terminal` resolves at the owning run's\n`agent_end` boundary, or immediately for removal. `submission.cancel()` removes\nthe entry when it is still queued; it returns `false` after execution or\nremoval. `queuePolicy: \"sequential\"` preserves FIFO delivery one queued input\nat a time, including when the session's configured follow-up/steering mode is\n`\"all\"`.\n\nThe ordinary `sendUserMessage` promise retains its delivery-mode-dependent\ncompletion semantics:\n\n- An ordinary idle submission with no `deliverAs` queues nothing and awaits the\n  prompt turn, including its terminal completion.\n- An explicit queued `steer`/`followUp`, or a submission diverted into a queue\n  because a live turn is active, resolves when the submission is admitted to\n  that delivery path. Use `submitUserMessage` when later consumption,\n  completion, and cancellation must be correlated to one exact submission.\n\nNeither promise is a generic queue-drained receipt. Do not build a generic\nembedder contract around internal dispatch or promotion-correlation hooks.\n\nRelated APIs:\n\n- `sendUserMessage(content, { deliverAs? })`\n- `steer(text, images?)`\n- `followUp(text, images?)`\n- `sendCustomMessage({ customType, content, ... }, { deliverAs?, triggerTurn? })`\n- `abort()`\n\n## Tools integration\n\n### Built-ins and filtering\n\n- Built-ins come from `createTools(...)` and `BUILTIN_TOOLS`.\n- `toolNames` acts as an allowlist for built-ins.\n- Hidden tools (for example `yield`) are opt-in unless required by options.\n\n```ts\nconst { session } = await createAgentSession({\n  toolNames: [\"read\", \"search\", \"find\", \"write\"],\n  requireYieldTool: true,\n});\n```\n\n### Runtime tool set changes\n\n`AgentSession` supports runtime activation updates:\n\n- `getActiveToolNames()`\n- `getAllToolNames()`\n- `setActiveToolsByName(names)`\n\nSystem prompt is rebuilt to reflect active tool changes.\n\n## Discovery helpers\n\nUse these when you want partial control without recreating internal discovery logic:\n\n- `discoverAuthStorage(agentDir?)`\n- `discoverContextFiles(cwd?, _agentDir?)`\n- `discoverPromptTemplates(cwd?, agentDir?)`\n- `buildSystemPrompt(options?)`\n\n## Subagent-oriented options\n\nFor SDK consumers building orchestrators (similar to task executor flow):\n\n- `outputSchema`: passes structured output expectation into tool context\n- `requireYieldTool`: forces `yield` tool inclusion\n- `taskDepth`: recursion-depth context for nested task sessions\n- `parentTaskPrefix`: artifact naming prefix for nested task outputs\n\nThese are optional for normal single-agent embedding.\n\n## `createAgentSession()` return value\n\n```ts\ntype CreateAgentSessionResult = {\n  session: AgentSession;\n  setToolUIContext: (uiContext: ExtensionUIContext, hasUI: boolean) => void;\n  modelFallbackMessage?: string;\n  lspServers?: Array<{\n    name: string;\n    status: \"ready\" | \"error\";\n    fileTypes: string[];\n    error?: string;\n  }>;\n  eventBus: EventBus;\n};\n```\n\nUse `setToolUIContext(...)` only if your embedder provides UI capabilities that tools should call into.\n\n## Startup performance\n\n`createAgentSession()` runs two background optimizations to overlap I/O with the rest of session setup:\n\n- **Model-host preconnect.** As soon as the model is resolved, the SDK fires a best-effort `fetch.preconnect(model.baseUrl)` so DNS + TCP + TLS + HTTP/2 to the provider's host happens in parallel with tool registry build, and system-prompt assembly. The first real `fetch(...)` then reuses the warm connection, saving 100–300 ms on transcontinental hops (e.g. residential IP → `api.anthropic.com`). Implementation lives in `preconnectModelHost()` in `packages/coding-agent/src/sdk/session.ts`. If `fetch.preconnect` is unavailable (non-Bun runtime) or the call throws, the optimization is silently skipped — never a hard dependency. Applies to interactive, print, and ACP modes.\n- **Conditional LSP warmup.** Startup LSP servers (those returned by `discoverStartupLspServers(cwd)`) are only warmed when **all** of these hold:\n  - `enableLsp !== false` on the session options, **and**\n  - `options.hasUI === true` (interactive TUI), **and**\n  - the `lsp.diagnosticsOnWrite` setting is enabled.\n\n  Print, script, and ACP invocations (`hasUI=false`) skip the warmup entirely: they don't render the warmup status indicator and typically finish before the language servers would stabilize, so warming them just spends CPU parsing big `initialize` responses concurrently with the LLM stream consumer and jitters perceived latency. Tools that actually need an LSP server still spin one up on demand through `getOrCreateClient()` — only the *startup* warmup is skipped. The returned `lspServers` field in `CreateAgentSessionResult` is therefore `undefined` (not an empty array) whenever the warmup branch was bypassed.\n\n## Minimal controlled embed example\n\n```ts\nimport {\n  createAgentSession,\n  discoverAuthStorage,\n  ModelRegistry,\n  SessionManager,\n  Settings,\n} from \"@gajae-code/coding-agent\";\n\nconst authStorage = await discoverAuthStorage();\nconst modelRegistry = new ModelRegistry(authStorage);\nawait modelRegistry.refresh();\n\nconst settings = Settings.isolated({\n  \"compaction.enabled\": true,\n  \"retry.enabled\": true,\n});\n\nconst { session } = await createAgentSession({\n  authStorage,\n  modelRegistry,\n  settings,\n  sessionManager: SessionManager.inMemory(),\n  toolNames: [\"read\", \"search\", \"find\", \"edit\", \"write\"],\n  enableLsp: true,\n});\n\nsession.subscribe((event) => {\n  if (\n    event.type === \"message_update\" &&\n    event.assistantMessageEvent.type === \"text_delta\"\n  ) {\n    process.stdout.write(event.assistantMessageEvent.delta);\n  }\n});\n\nawait session.prompt(\"Find all TODO comments in this repo and propose fixes.\");\nawait session.dispose();\n```\n",
+	"sdk-embedding.md": "# SDK\n\nFor managed control and notification attachment policy, see [the Gajae-Code SDK](./sdk.md).\n\nThe SDK is the in-process integration surface for `@gajae-code/coding-agent`.\nUse it when you want direct access to agent state, event streaming, tool wiring, and session control from your own Bun/Node process.\n\nFor process-isolated control, use a managed SDK-core adapter backed by `SessionRouter`; raw endpoint discovery and direct WebSocket clients are not public integration surfaces.\n\n## Installation\n\n```bash\nbun add @gajae-code/coding-agent\n```\n\n\n## Entry points\n\n`@gajae-code/coding-agent/sdk` is the canonical entry point for embedders. The package root exports the same SDK APIs for convenience.\n\nCore exports for embedders:\n\n- `createAgentSession`\n- `SessionManager`\n- `Settings`\n- `AuthStorage`\n- `ModelRegistry`\n- `discoverAuthStorage`\n- Discovery helpers for retained context/prompt surfaces (`discoverContextFiles`, `discoverPromptTemplates`)\n- Tool factory surface (`createTools`, `BUILTIN_TOOLS`, tool classes)\n\n## Quick start (auto-discovery defaults)\n\n```ts\nimport { createAgentSession } from \"@gajae-code/coding-agent\";\n\nconst { session, modelFallbackMessage } = await createAgentSession();\n\nif (modelFallbackMessage) {\n  process.stderr.write(`${modelFallbackMessage}\\n`);\n}\n\nconst unsubscribe = session.subscribe((event) => {\n  if (\n    event.type === \"message_update\" &&\n    event.assistantMessageEvent.type === \"text_delta\"\n  ) {\n    process.stdout.write(event.assistantMessageEvent.delta);\n  }\n});\n\nawait session.prompt(\"Summarize this repository in 3 bullets.\");\nunsubscribe();\nawait session.dispose();\n```\n\n## What `createAgentSession()` discovers by default\n\n`createAgentSession()` follows “provide to override, omit to discover”.\n\nIf omitted, it resolves:\n\n- `cwd`: `getProjectDir()`\n- `agentDir`: `~/.gjc/agent` (via `getAgentDir()`)\n- `authStorage`: `discoverAuthStorage(agentDir)`\n- `modelRegistry`: `new ModelRegistry(authStorage)` + background `refreshInBackground()` when the registry is not provided\n- `settings`: `await Settings.init({ cwd, agentDir })`\n- `sessionManager`: `SessionManager.create(cwd)` (file-backed)\n- context files and prompt templates\n- built-in tools via `createTools(...)`\n- LSP integration (enabled by default)\n- `eventBus`: new `EventBus()` unless supplied\n\n### Required vs optional inputs\n\nTypically you must provide only what you want to control:\n\n- **Must provide**: nothing for a minimal session\n- **Usually provide explicitly** in embedders:\n  - `sessionManager` (if you need in-memory or custom location)\n  - `authStorage` + `modelRegistry` (if you own credential/model lifecycle)\n  - `model` or `modelPattern` (if deterministic model selection matters)\n  - `settings` (if you need isolated/test config)\n\n## Session manager behavior (persistent vs in-memory)\n\n`AgentSession` always uses a `SessionManager`; behavior depends on which factory you use.\n\n### File-backed (default)\n\n```ts\nimport { createAgentSession, SessionManager } from \"@gajae-code/coding-agent\";\n\nconst { session } = await createAgentSession({\n  sessionManager: SessionManager.create(process.cwd()),\n});\n\nconsole.log(session.sessionFile); // absolute .jsonl path\n```\n\n- Persists conversation/messages/state deltas to session files.\n- Supports resume/open/list/fork workflows.\n- `session.sessionFile` is defined.\n\n### In-memory\n\n```ts\nimport { createAgentSession, SessionManager } from \"@gajae-code/coding-agent\";\n\nconst { session } = await createAgentSession({\n  sessionManager: SessionManager.inMemory(),\n});\n\nconsole.log(session.sessionFile); // undefined\n```\n\n- No filesystem persistence.\n- Useful for tests, ephemeral workers, request-scoped agents.\n- Session methods still work, but persistence-specific behaviors (file resume/fork paths) are naturally limited.\n\n### Resume/open/list helpers\n\n```ts\nimport { SessionManager } from \"@gajae-code/coding-agent\";\n\nconst recent = await SessionManager.continueRecent(process.cwd());\nconst listed = await SessionManager.list(process.cwd());\nconst opened = listed[0] ? await SessionManager.open(listed[0].path) : null;\n```\n\n## Model and auth wiring\n\n`createAgentSession()` uses `ModelRegistry` + `AuthStorage` for model selection and API key resolution.\n\n### Explicit wiring\n\n```ts\nimport {\n  createAgentSession,\n  discoverAuthStorage,\n  ModelRegistry,\n  SessionManager,\n} from \"@gajae-code/coding-agent\";\n\nconst authStorage = await discoverAuthStorage();\nconst modelRegistry = new ModelRegistry(authStorage);\nawait modelRegistry.refresh();\n\nconst available = modelRegistry.getAvailable();\nif (available.length === 0)\n  throw new Error(\"No authenticated models available\");\n\nconst { session } = await createAgentSession({\n  authStorage,\n  modelRegistry,\n  model: available[0],\n  thinkingLevel: \"medium\",\n  sessionManager: SessionManager.inMemory(),\n});\n```\n\n### Selection order when `model` is omitted\n\nWhen no explicit `model`/`modelPattern` is provided:\n\n1. restore model from existing session (if restorable + key available)\n2. settings default model role (`default`)\n3. first available model with valid auth\n\nIf restore fails, `modelFallbackMessage` explains fallback.\n\n### Auth priority\n\n`AuthStorage.getApiKey(...)` resolves in this order:\n\n1. runtime override (`setRuntimeApiKey`)\n2. stored credentials in `agent.db`\n3. provider environment variables\n4. custom-provider resolver fallback (if configured)\n\n## Event subscription model\n\nSubscribe with `session.subscribe(listener)`; it returns an unsubscribe function.\n\n```ts\nconst unsubscribe = session.subscribe((event) => {\n  switch (event.type) {\n    case \"agent_start\":\n    case \"turn_start\":\n    case \"tool_execution_start\":\n      break;\n    case \"message_update\":\n      if (event.assistantMessageEvent.type === \"text_delta\") {\n        process.stdout.write(event.assistantMessageEvent.delta);\n      }\n      break;\n  }\n});\n```\n\n`AgentSessionEvent` includes core `AgentEvent` plus session-level events:\n\n- `auto_compaction_start` / `auto_compaction_end`\n- `auto_retry_start` / `auto_retry_end`\n- `agent_failed` (diagnostic failure for the current attempt; the correlated\n  terminal `agent_end` still follows and remains the lifecycle boundary)\n- `retry_fallback_applied` / `retry_fallback_succeeded`\n- `ttsr_triggered`\n- `todo_reminder` / `todo_auto_clear`\n- `irc_message`\n\n## Prompt lifecycle\n\n`session.prompt(text, options?)` is the primary entry point.\n\nFailure consumers should handle `agent_failed` as an additive diagnostic event,\nnot as terminal completion. It carries only the sanitized `{ code, message }`\ndiagnostic for the correlated attempt — never the raw provider/local error —\nso consumers must not depend on provider-specific detail or raw error objects;\ncontinue waiting for `agent_end` before releasing prompt ownership, deadlines,\nor transport resources. This ordering also applies when the run is canceled or\nenters a maintenance continuation.\n\nBehavior:\n\n1. optional command/template expansion (`/` commands, custom commands, file slash commands, prompt templates)\n2. if currently streaming:\n   - requires `streamingBehavior: \"steer\" | \"followUp\"`\n   - queues instead of throwing work away\n3. if idle:\n   - validates model + API key\n   - appends user message\n   - starts agent turn\n\n### Queued input lifecycle\n\nKeep admission, consumption, and completion separate when embedding the SDK:\n\n| Session state | Admission | Consumption | Completion |\n| --- | --- | --- | --- |\n| Fresh or settled idle with an assistant tail | `prompt()` starts a turn; an explicit `followUp` is accepted into the executable queue | The next turn consumes the queued message and normally starts its own run | That run publishes its own terminal `agent_end` |\n| Live model/tool loop | `steer` may be consumed by the current run; `followUp` waits for the next turn | The live loop can consume the message before its terminal boundary | The message may share the current run and terminal; it is not necessarily a separate model call |\n| Prompt unwind after the Agent loop emitted `agent_end` | An explicit `followUp` is still accepted | The SDK schedules a queued-only successor after the unwind finishes; it is not left waiting for an unrelated prompt | The successor owns a new run and terminal boundary |\n| Paused, cancelled, or a non-resumable non-assistant tail | The message can remain queued | No automatic successor is promised until a supported resume/abort path makes the queue deliverable | The admission is not completion; clear/remove the queue or resume it explicitly |\n| Existing queued input ahead of a new submission | The new message is ordered behind the existing queue | Queue order is preserved; later plain prompts do not overtake an earlier follow-up | Each consumed message is correlated at its actual dequeue boundary |\n\n`session.waitForIdle()` waits for active Agent work, session settlement, and\ncontinuations that the SDK has scheduled. It is **not** a receipt that every\nsteering/follow-up queue is empty. Inspect `pendingMessageCounts` or use the\nqueue APIs when queue state matters. A queued follow-up can also share the\npredecessor's run and terminal when the live loop consumes it; do not equate\none accepted submission with one model call or one `agent_end` event.\n\nFor generic embedders, prefer an application-owned queue of bounded full turns\nsubmitted through `session.prompt()`, and use `steer`/`followUp` only for live\nconversational controls. When a queued control must remain pending until its\nexact ownership is known, use `submitUserMessage()`:\n\n```ts\nconst submission = await session.submitUserMessage(\"refresh the status\", {\n  deliverAs: \"followUp\",\n  queuePolicy: \"sequential\",\n  trackSubmission: true,\n});\n\nawait submission.admitted;\nconst execution = await submission.execution;\n// execution.disposition is \"joined-current-run\", \"promoted-to-run\", or \"removed\".\n// For execution, attemptScope identifies the run that owns the terminal boundary.\nawait submission.terminal;\n```\n\n`submissionId` is generated per call, so identical message text remains\nindependently correlatable. `admitted` resolves only after the exact queue\nentry exists. `execution` resolves at same-run consumption, successor-run\npromotion, or exact removal. `terminal` resolves at the owning run's\n`agent_end` boundary, or immediately for removal. `submission.cancel()` removes\nthe entry when it is still queued; it returns `false` after execution or\nremoval. `queuePolicy: \"sequential\"` preserves FIFO delivery one queued input\nat a time, including when the session's configured follow-up/steering mode is\n`\"all\"`.\n\nThe ordinary `sendUserMessage` promise retains its delivery-mode-dependent\ncompletion semantics:\n\n- An ordinary idle submission with no `deliverAs` queues nothing and awaits the\n  prompt turn, including its terminal completion.\n- An explicit queued `steer`/`followUp`, or a submission diverted into a queue\n  because a live turn is active, resolves when the submission is admitted to\n  that delivery path. Use `submitUserMessage` when later consumption,\n  completion, and cancellation must be correlated to one exact submission.\n\nNeither promise is a generic queue-drained receipt. Do not build a generic\nembedder contract around internal dispatch or promotion-correlation hooks.\n\nRelated APIs:\n\n- `sendUserMessage(content, { deliverAs? })`\n- `steer(text, images?)`\n- `followUp(text, images?)`\n- `sendCustomMessage({ customType, content, ... }, { deliverAs?, triggerTurn? })`\n- `abort()`\n\n## Tools integration\n\n### Built-ins and filtering\n\n- Built-ins come from `createTools(...)` and `BUILTIN_TOOLS`.\n- `toolNames` acts as an allowlist for built-ins.\n- Hidden tools (for example `yield`) are opt-in unless required by options.\n\n```ts\nconst { session } = await createAgentSession({\n  toolNames: [\"read\", \"search\", \"find\", \"write\"],\n  requireYieldTool: true,\n});\n```\n\n### Runtime tool set changes\n\n`AgentSession` supports runtime activation updates:\n\n- `getActiveToolNames()`\n- `getAllToolNames()`\n- `setActiveToolsByName(names)`\n\nSystem prompt is rebuilt to reflect active tool changes.\n\n## Discovery helpers\n\nUse these when you want partial control without recreating internal discovery logic:\n\n- `discoverAuthStorage(agentDir?)`\n- `discoverContextFiles(cwd?, _agentDir?)`\n- `discoverPromptTemplates(cwd?, agentDir?)`\n- `buildSystemPrompt(options?)`\n\n## Subagent-oriented options\n\nFor SDK consumers building orchestrators (similar to task executor flow):\n\n- `outputSchema`: passes structured output expectation into tool context\n- `requireYieldTool`: forces `yield` tool inclusion\n- `taskDepth`: recursion-depth context for nested task sessions\n- `parentTaskPrefix`: artifact naming prefix for nested task outputs\n\nThese are optional for normal single-agent embedding.\n\n## `createAgentSession()` return value\n\n```ts\ntype CreateAgentSessionResult = {\n  session: AgentSession;\n  setToolUIContext: (uiContext: ExtensionUIContext, hasUI: boolean) => void;\n  modelFallbackMessage?: string;\n  lspServers?: Array<{\n    name: string;\n    status: \"ready\" | \"error\";\n    fileTypes: string[];\n    error?: string;\n  }>;\n  eventBus: EventBus;\n};\n```\n\nUse `setToolUIContext(...)` only if your embedder provides UI capabilities that tools should call into.\n\n## Startup performance\n\n`createAgentSession()` runs two background optimizations to overlap I/O with the rest of session setup:\n\n- **Model-host preconnect.** As soon as the model is resolved, the SDK fires a best-effort `fetch.preconnect(model.baseUrl)` so DNS + TCP + TLS + HTTP/2 to the provider's host happens in parallel with tool registry build, and system-prompt assembly. The first real `fetch(...)` then reuses the warm connection, saving 100–300 ms on transcontinental hops (e.g. residential IP → `api.anthropic.com`). `packages/coding-agent/src/sdk/session.ts` triggers it through the `startup.networkPrewarm` runtime service (`packages/coding-agent/src/runtime/network-prewarm-service.ts`); setting `startup.networkPrewarm: false` skips it. If `fetch.preconnect` is unavailable (non-Bun runtime) or the call throws, the optimization is skipped (failures are logged at debug level) — never a hard dependency. Applies to interactive, print, and ACP modes.\n- **Conditional LSP warmup.** Startup LSP servers (those returned by `discoverStartupLspServers(cwd)`) are only warmed when **all** of these hold:\n  - `enableLsp !== false` on the session options, **and**\n  - `options.hasUI === true` (interactive TUI), **and**\n  - the `lsp.diagnosticsOnWrite` setting is enabled.\n\n  Print, script, and ACP invocations (`hasUI=false`) skip the warmup entirely: they don't render the warmup status indicator and typically finish before the language servers would stabilize, so warming them just spends CPU parsing big `initialize` responses concurrently with the LLM stream consumer and jitters perceived latency. Tools that actually need an LSP server still spin one up on demand through `getOrCreateClient()` — only the *startup* warmup is skipped. The returned `lspServers` field in `CreateAgentSessionResult` is therefore `undefined` (not an empty array) whenever the warmup branch was bypassed.\n\n## Minimal controlled embed example\n\n```ts\nimport {\n  createAgentSession,\n  discoverAuthStorage,\n  ModelRegistry,\n  SessionManager,\n  Settings,\n} from \"@gajae-code/coding-agent\";\n\nconst authStorage = await discoverAuthStorage();\nconst modelRegistry = new ModelRegistry(authStorage);\nawait modelRegistry.refresh();\n\nconst settings = Settings.isolated({\n  \"compaction.enabled\": true,\n  \"retry.enabled\": true,\n});\n\nconst { session } = await createAgentSession({\n  authStorage,\n  modelRegistry,\n  settings,\n  sessionManager: SessionManager.inMemory(),\n  toolNames: [\"read\", \"search\", \"find\", \"edit\", \"write\"],\n  enableLsp: true,\n});\n\nsession.subscribe((event) => {\n  if (\n    event.type === \"message_update\" &&\n    event.assistantMessageEvent.type === \"text_delta\"\n  ) {\n    process.stdout.write(event.assistantMessageEvent.delta);\n  }\n});\n\nawait session.prompt(\"Find all TODO comments in this repo and propose fixes.\");\nawait session.dispose();\n```\n",
 	"sdk-owned-session-lifecycle-handoff.md": "# SDK-owned session lifecycle handoff\n\n## Status\n\n- Branch: `refactor/sdk-owned-session-lifecycle`\n- Worktree: `../gajae-code.gajae-code-worktrees/refactor-sdk-owned-session-lifecycle`\n- Base: `origin/dev` at `31c00c2d5bb462464046208a94a4597c27260a4c`\n- Review target: `dev`\n- Verdict: sound direction, with a required ownership qualification\n\n## Decision\n\nGJC SDK core must be the sole authority for coding-agent session lifecycle and external session attachments. Provider daemons must not create, resume, close, delete, signal, recover, or allocate identities for GJC sessions.\n\n> SDK core owns session lifecycle and attachment authority. Provider supervisors own provider transport authority.\n\nTelegram `getUpdates`, Slack Socket Mode, Discord Gateway, provider cursors, rate limits, and provider topic/thread/message state remain provider-owned because they are external transport and presentation resources, not AgentSession lifecycle resources.\n\n## Problem\n\nThe Broker and per-session SDK runtime already provide lifecycle idempotency, target serialization, a durable lifecycle ledger, startup admission, process-incarnation fencing, effect markers, readiness proof, endpoint-generation checks, exact cleanup evidence, and honest `terminal_uncertain` outcomes.\n\nThe chat-daemon path nevertheless has a second set of session authorities:\n\n- daemon-owned lifecycle control server, credential, pending table, and sequence;\n- chat lifecycle ledger and audit path;\n- tmux/session spawn, close, and resume effects;\n- intended session-ID allocation before Broker creation;\n- notification-root registration as the provider discovery universe;\n- direct endpoint discovery, credentials, reconnect, and action routing.\n\nA provider crash can therefore occur between provider-ledger persistence, Broker-ledger persistence, process effects, endpoint publication, and topic binding. Authority is divided by ingress process instead of by the mutated resource.\n\n## Non-goals\n\n- Do not move provider transport ownership into the Broker.\n- Do not weaken incarnation, generation, effect-marker, readiness, or exact-cleanup checks.\n- Do not add a compatibility lifecycle executor or dual writer.\n- Do not infer completion from terminal output, tmux, or provider delivery state.\n- Do not make topic/thread cleanup part of session lifecycle terminality.\n\n## Current ownership\n\n### Broker and lifecycle executor\n\nPrimary files:\n\n- `packages/coding-agent/src/sdk/broker/broker.ts`\n- `packages/coding-agent/src/sdk/broker/lifecycle.ts`\n\nRetain and strengthen:\n\n- Broker root lock/discovery/heartbeat;\n- `SessionIndex` and `LifecycleLedger`;\n- lifecycle idempotency and target serialization;\n- create/fork/resume/close/delete execution;\n- worktree, transcript, and managed-session validation;\n- effect marker and process-incarnation evidence;\n- readiness and endpoint-generation proof;\n- close escalation and exact cleanup reconciliation.\n\nThe Broker lifecycle executor becomes the only executor and durable terminal authority for session lifecycle mutations.\n\n### Per-session SDK runtime\n\nPrimary file: `packages/coding-agent/src/sdk/host/session-runtime.ts`.\n\nRetain:\n\n- AgentSession-local host/transport startup and shutdown;\n- endpoint URL, token, and generation publication;\n- control, query, event, replay, and reverse-provider semantics;\n- readiness and activation;\n- exact generation registration and unregistration with Broker.\n\nThe runtime owns live local resources; Broker owns the global transaction and permission to create or retire the runtime.\n\n### Provider-owned transport and presentation\n\nRetain outside SDK session lifecycle:\n\n- provider credential/account fingerprint;\n- one active provider poller or connection;\n- cursor, conflict handling, rate limit, retry, and backoff;\n- topic/thread/message/callback/attachment state;\n- provider delivery receipts and presentation reconciliation;\n- provider process lease, heartbeat, restart, and shutdown.\n\n### Authority to remove from Telegram/chat daemon\n\nPrimary files:\n\n- `packages/coding-agent/src/sdk/bus/telegram-daemon.ts`\n- `packages/coding-agent/src/sdk/bus/lifecycle-orchestrator.ts`\n\nRemove:\n\n- lifecycle control server ownership;\n- lifecycle endpoint credential and pending request ownership;\n- chat-owned lifecycle outcome ledger;\n- tmux/process lifecycle effects;\n- logical SessionId allocation or preallocation;\n- direct endpoint credentials and endpoint discovery;\n- provider-owned session discovery roots;\n- provider-specific endpoint-generation and reconnect authority.\n\nProvider update IDs may remain idempotency inputs, but not a second lifecycle result ledger.\n\n## Target architecture\n\n```text\nProvider boundary\n┌─────────────────────────────────────────────────────────────┐\n│ ChatDaemonSupervisor                                        │\n│  provider lease, poller/connection, cursor, retry/rate limit│\n│                                                             │\n│ ProviderAdapter                                             │\n│  provider update → ChatIntent                               │\n│  PresentationEvent → provider payload                       │\n│  topic/thread/message/callback mappings                     │\n└────────────────────────┬────────────────────────────────────┘\n                         │ opaque intents/events\n                         ▼\nSDK core\n┌─────────────────────────────────────────────────────────────┐\n│ SessionRouter                                               │\n│  Broker-index discovery, endpoint credential custody,       │\n│  SDK connections, replay/reconnect, attachment leases,      │\n│  prompt and ask-answer routing                              │\n│                                                             │\n│ SessionLifecycleService                                     │\n│  actor/capability authorization, canonical requests,        │\n│  idempotency namespace, lifecycle certainty                 │\n│                                                             │\n│ Broker                                                      │\n│  one ledger, one executor, index, process/effect recovery   │\n│                                                             │\n│ SessionSdkSessionRuntime                                    │\n│  AgentSession, endpoint generation, controls/events/teardown│\n└─────────────────────────────────────────────────────────────┘\n```\n\nDependency direction:\n\n```text\nProviderAdapter\n  → SessionRouter\n  → SessionLifecycleService\n  → Broker\n  → SessionSdkSessionRuntime\n```\n\nForbidden paths:\n\n- Broker/runtime depending on provider concepts;\n- provider adapter calling Broker lifecycle internals;\n- provider adapter invoking tmux or process signals for session lifecycle;\n- provider adapter reading endpoint files or tokens;\n- provider adapter generating SessionIds;\n- provider state participating in Broker recovery proof.\n\n## Target components\n\n### SessionLifecycleService\n\nRecommended under `packages/coding-agent/src/sdk/lifecycle/`. It is a provider-neutral facade over existing Broker operations, not another state machine or ledger.\n\nResponsibilities:\n\n- authenticated actor and explicit capability input;\n- operation-specific authorization;\n- canonical lifecycle request normalization;\n- idempotency derived from actor namespace, caller request key, operation, and target;\n- invocation of the existing Broker path;\n- bounded lifecycle result and certainty;\n- no provider, topic, thread, tmux, or shell concepts.\n\n### SessionRouter\n\nRecommended under `packages/coding-agent/src/sdk/router/`.\n\nResponsibilities:\n\n- consume Broker `SessionIndex` snapshots and index sequence;\n- resolve exact endpoint authority through Broker;\n- remain the sole non-runtime holder of endpoint credentials;\n- own SDK connections, event replay, and reconnect;\n- revoke attachment leases when endpoint/index/router generation changes;\n- route provider-neutral prompts and answers through standard SDK operations;\n- reconcile prompt acceptance and terminal outcomes;\n- emit provider-neutral presentation events;\n- never perform process lifecycle effects.\n\nAttachment authority must bind session identity, endpoint generation/incarnation, and router epoch. Its provider representation should be opaque.\n\n### ChatDaemonSupervisor\n\nOwns only the provider-account process lease, poller/connection, cursor, API retry/backoff/rate limits, and independent provider restart/shutdown. It never creates, resumes, closes, or signals a GJC session.\n\n### ProviderAdapter\n\nValidates inbound provider identity, normalizes `ChatIntent`, renders `PresentationEvent`, owns provider-created presentation bindings and delivery receipts, and stores returned SessionIds only as opaque mapping keys.\n\n## Ownership matrix\n\n| Authority | Creator | Mutator/retirer | Persistence | Provider role |\n|---|---|---|---|---|\n| Logical SessionId | Broker lifecycle | Broker lifecycle | Broker/managed session | Store returned opaque ID |\n| Lifecycle idempotency | Service derives, Broker records | Broker ledger | `LifecycleLedger` | Supply stable request identity |\n| Broker root lease | Broker | Exact owner | lock/discovery/heartbeat | None |\n| Effect marker | Broker | Broker | ledger/lifecycle artifacts | None |\n| Process incarnation | OS, observed by core | Immutable | effect evidence | None |\n| Endpoint URL/token/generation | Session runtime | Session runtime | endpoint/index | Must not receive |\n| Attachment lease | SessionRouter | SessionRouter | Prefer ephemeral | Use opaque handle |\n| Provider transport lease | Supervisor | Supervisor | provider state | Full owner |\n| Provider cursor/rate state | Supervisor | Supervisor | provider state | Full owner |\n| Topic/thread/message binding | Adapter | Adapter CAS | provider mapping | Full owner |\n| Session lifecycle result | Broker | Broker ledger | `LifecycleLedger` | Read only |\n| Provider delivery result | Adapter | Adapter | provider delivery state | Cannot alter lifecycle |\n\n## Lifecycle flows\n\n### Create\n\n1. Adapter validates provider identity and policy.\n2. Existing topic/thread adoption creates a provider-local reservation keyed by `providerRequestKey`, not a SessionId.\n3. Adapter sends a create intent to Router.\n4. Router calls lifecycle service with actor, capability, target, and stable idempotency.\n5. Broker begins the sole ledger entry, allocates SessionId, records effect identity, spawns, and proves readiness.\n6. Router attaches to the exact endpoint authority.\n7. Adapter CAS-binds its reservation to the returned SessionId.\n8. Retry of the same provider request returns the same Broker result and cannot spawn another session.\n\n### Attach\n\nRouter reads Broker index, resolves exact generation/incarnation, opens the authenticated SDK connection, replays from its cursor, and issues an attachment lease. Provider stores only the opaque attachment and presentation mapping.\n\n### Prompt and ask answer\n\nAdapter sends an authenticated intent with provider request identity and attachment lease. Router validates authority and invokes standard SDK controls. Runtime reconciliation remains authoritative for accepted, in-flight, terminal, unknown, and one-shot answer outcomes. Provider retries query/replay rather than duplicate effects.\n\n### Close\n\nAdapter submits intent only. Lifecycle service authorizes and Broker persists the effect, uses the exact endpoint first, escalates only with incarnation/effect fencing, and requires unregister, endpoint removal, and process-exit proof. Router revokes attachments. Provider presentation cleanup happens afterward and cannot make a confirmed close uncertain.\n\n### Resume and endpoint rotation\n\nBroker validates saved-session ownership and returns an exact live endpoint or performs canonical spawn/readiness. Runtime owns token/generation rotation and Broker registration. Router revokes old leases, resolves the new endpoint, reconnects, and replays. Provider never receives old or new credentials.\n\n### Provider restart\n\nSupervisor reacquires only provider transport authority and reloads cursor/presentation state. Router reconstructs attachments from Broker index. Provider restart alone never creates, resumes, closes, or mutates a session. Submitted operations replay through the same Broker idempotency identity.\n\n### Broker/runtime recovery\n\nBroker reconciles only from its ledger, effect markers, process incarnation, endpoint/index registration, readiness/failure records, and exact cleanup evidence. Provider records are never lifecycle proof. Unprovable effects remain `terminal_uncertain`.\n\n## Migration plan\n\nEach stage cuts over one authority and deletes the obsolete path in the same logical change. No dual writers or fallback executors.\n\n### Stage 1: canonical lifecycle service\n\n- Add provider-neutral lifecycle service over existing Broker operations.\n- Define actor/capability, canonical request, idempotency, and certainty contracts.\n- Reuse `Broker.handleRequest`, `executeLifecycle`, and `LifecycleLedger`.\n- Add focused authorization, replay, conflict, and uncertainty tests.\n\n### Stage 2: chat lifecycle cutover\n\n- Route Telegram create/close/resume through Router and lifecycle service.\n- Preserve provider parsing, authentication, policy, and rendering.\n- Remove daemon lifecycle server, token, client, pending table, request sequence, chat lifecycle ledger/audit, and tmux/process effects.\n- Verify one chat operation creates one Broker ledger identity.\n\n### Stage 3: remove provider SessionId allocation\n\n- Replace `intendedSessionId` with a provider-local reservation keyed by provider request identity.\n- CAS-bind the provider resource to the Broker-returned SessionId.\n- Test crashes before Broker call, after Broker intent, after readiness, and before binding.\n\n### Stage 4: SDK-owned SessionRouter\n\n- Route discovery through Broker index and exact endpoint resolution.\n- Move credentials, connections, replay, reconnect, and attachment generation into Router.\n- Introduce opaque attachment leases.\n- Remove notification-root registration, provider root scanning, and direct endpoint access.\n\n### Stage 5: provider supervisor/adapter boundary\n\n- Retain provider lease, cursor, connection, retry/backoff, rate limits, delivery, mappings, callbacks, and attachments.\n- Apply the Router contract to Telegram, Discord, and Slack.\n- Remove provider edges to lifecycle execution, tmux, process signaling, Broker cleanup, and endpoint credentials.\n\n### Stage 6: singular recovery and deletion\n\n- Broker owns lifecycle recovery.\n- Router reconstructs attachments.\n- Provider supervisor reconstructs only transport and presentation.\n- Delete obsolete lifecycle orchestrator/control-runtime modules.\n- Leave no feature flag, dual writer, silent fallback, or compatibility shim.\n\n## Required invariants\n\n1. Only Broker lifecycle may spawn, signal, close, resume, delete, or persist lifecycle terminality.\n2. Provider retry cannot create two sessions or effects.\n3. Stale endpoint/router/attachment authority cannot submit prompt or answer.\n4. Provider transport failure or restart cannot mutate session lifecycle.\n5. Provider presentation state is recoverable but non-authoritative.\n6. Endpoint credentials remain inside runtime, Broker resolution, and Router.\n7. Provider cleanup failure cannot rewrite a lifecycle result.\n8. Recovery cannot signal or delete a successor process, endpoint, or transcript.\n9. Prompt acceptance remains distinct from completion.\n10. Timeout never invents success or failure.\n\n## Verification\n\n### Static architecture gates\n\nFail provider modules that import lifecycle execution internals, tmux/session process lifecycle, process signals for session lifecycle, direct endpoint discovery/credentials, or logical SessionId generation.\n\n### Crash matrix\n\nInject provider-triggered create failures after reservation, lifecycle admission, Broker ledger begin, effect persistence, child spawn, endpoint publication, readiness/index registration, and provider binding. Retry must produce one SessionId, one effect identity, at most one live owned process, and one Broker result.\n\n### Endpoint rotation\n\nRender work under generation N, rotate to N+1, reject the N lease, reconnect through Broker exact resolution, and replay without duplicate prompt or answer effects.\n\n### Provider restart\n\nRestart the supervisor during active prompt, unanswered ask, create, close, and endpoint rotation. Broker/process/runtime evidence changes only for operations already submitted; provider delivery alone is reconciled.\n\n### Close and cleanup\n\nConfirm close independently of topic/thread deletion. Exercise PID reuse, endpoint replacement, stale index generation, and exact cleanup races. Preserve `terminal_uncertain` when proof is unavailable.\n\n### Credential boundary\n\nRouter/adapter payloads and provider state must not contain endpoint URL/token, Broker token, or lifecycle effect credentials.\n\nStart focused verification with `packages/coding-agent/test/sdk-broker-lifecycle-e2e.test.ts`, Telegram ownership/lifecycle/restart/reconciliation suites, SDK host/runtime lifecycle tests, Coordinator lifecycle/idempotency tests, and ACP create/load/resume/cancel tests when shared paths change.\n\n## Implementation order\n\nPrefer atomic commits:\n\n1. lifecycle-service contract and tests;\n2. Telegram lifecycle cutover and old server/ledger deletion;\n3. provider reservation and Broker-owned SessionId;\n4. Router contract and direct endpoint-access removal;\n5. Telegram supervisor/adapter split;\n6. Discord and Slack Router adoption;\n7. obsolete-path deletion, architecture gates, and docs.\n\nDo not mix provider rendering, topic UX, or unrelated notification features into this migration.\n\n## Primary files\n\nExpected existing files:\n\n- `packages/coding-agent/src/sdk/broker/broker.ts`\n- `packages/coding-agent/src/sdk/broker/lifecycle.ts`\n- `packages/coding-agent/src/sdk/host/session-runtime.ts`\n- `packages/coding-agent/src/sdk/bus/telegram-daemon.ts`\n- `packages/coding-agent/src/sdk/bus/lifecycle-orchestrator.ts`\n- shared chat-daemon/session-control modules under `packages/coding-agent/src/sdk/bus/`\n- Coordinator and ACP adapters where they consume the same core contracts\n\nExpected new core areas:\n\n- `packages/coding-agent/src/sdk/lifecycle/`\n- `packages/coding-agent/src/sdk/router/`\n\nMove or rename existing services where possible instead of introducing parallel abstractions.\n\n## Risks\n\n- **High:** temporary dual authority during cutover.\n- **High:** provider, Router, and Broker idempotency namespace drift.\n- **High:** endpoint credential duplication or leakage.\n- **High:** successor destruction if existing fences are simplified.\n- **Medium:** crash-safe reservation-to-session binding.\n- **Medium:** event replay duplication versus effect duplication.\n- **Medium:** Telegram-specific requirements leaking into SDK core.\n\n## Definition of done\n\n- TUI, CLI, ACP, Coordinator, Telegram, Discord, and Slack lifecycle mutations enter one Broker path.\n- One durable ledger determines lifecycle terminality.\n- Provider daemons cannot allocate SessionIds, signal session processes, or read endpoint credentials.\n- Providers retain only transport and presentation ownership.\n- Router is the sole external attachment authority and credential-bearing SDK client manager.\n- Provider restart cannot create, resume, close, or mutate a session by itself.\n- Stale attachments fail closed.\n- Crash, retry, rotation, and cleanup tests pass.\n- Obsolete lifecycle server, chat lifecycle ledger, root scanning, and compatibility paths are removed.\n- SDK, bot integration, notification, ACP, and Coordinator docs describe the final ownership model consistently.\n",
 	"sdk-rpc-parity-audit.md": "# SDK v3 RPC parity audit\n\n**Status:** internal, closed-inventory audit. This is a comparison of the retired\nRPC contract at `6e147d58~1:docs/rpc.md` with SDK v3; it is not an event-plane\nparity claim. The CLI rejects the retired `--mode rpc`, `rpc-ui`, and `bridge`\nmodes and directs external control to the SDK (`packages/coding-agent/src/cli/args.ts:117-127`).\n\nThe historical issue files (01–08, 11–21) are archived under `issues/archive/` as provenance only. Their current disposition is recorded in `issues/README.md`: implementation findings are resolved, retired RPC documentation findings are obsolete, and persistent-session/registry items (09/10) remain deferred architectural follow-ups. Do not treat this closed audit as an active implementation backlog.\n\n## Method and classifications\n\nThe inventory below is **closed**. Command, frame, and sub-protocol rows were\nrecovered from `git show 6e147d58~1:docs/rpc.md`; the supplemental\n`rpc-sessions` registry and `--listen` Unix-socket rows were recovered from\nparent-commit source because they do not appear in that document:\n`6e147d58~1:packages/coding-agent/src/cli/args.ts:157-158`,\n`6e147d58~1:packages/coding-agent/src/modes/rpc/rpc-mode.ts:892-907,984-992`,\nand\n`6e147d58~1:packages/coding-agent/src/modes/shared/agent-wire/session-registry.ts:1-53`.\n`SDK equivalent` means a current operation or documented SDK protocol covers the\ncontrol/query intent, not that its transport or event semantics are identical.\n`transport-gap — retired` means the direct `gjc sdk serve` relay and standalone transport clients were removed when `SessionRouter` became the sole external attachment authority.\n`phase-2-gap` means no equivalent has been implemented by this audit.\n\nOperation names and their stated roles are from\n`packages/coding-agent/src/sdk/protocol/operation-registry.ts:66-166`; dispatch\ncoverage is from `packages/coding-agent/src/sdk/host/control/dispatch.ts:138-253`.\nSDK protocol and lifecycle references use stable heading references in\n`docs/sdk.md`. Command, frame, and sub-protocol rows cite\n`6e147d58~1:docs/rpc.md`; the two supplemental rows cite the parent-commit\nsources above.\n\n## Closed command inventory\n\n| Retired family | Retired command | SDK v3 equivalent or classification | Evidence |\n| --- | --- | --- | --- |\n| Prompting | `prompt` | `turn.prompt` | retired doc; registry:67; dispatch:139-140 |\n| Prompting | `steer` | Partial SDK equivalent: `turn.steer` is text-only and loses retired `images` | `6e147d58~1:docs/rpc.md:77`; registry:68; dispatch:141-142 |\n| Prompting | `follow_up` | Partial SDK equivalent: `turn.follow_up` is text-only and loses retired `images` | `6e147d58~1:docs/rpc.md:78`; registry:69; dispatch:143-144 |\n| Prompting | `abort` | `turn.abort` | retired doc; registry:70; dispatch:145-146 |\n| Prompting | `abort_and_prompt` | `turn.abort_and_prompt` | retired doc; registry:71; dispatch:147-148 |\n| Prompting | `new_session` | Partial SDK equivalent: `session.new` takes no input and loses retired `parentSession` | `6e147d58~1:docs/rpc.md:81`; registry:93; dispatch:196-197 |\n| State | `get_state` | Partial SDK equivalent: query bundle `context.get` (includes `systemPrompt`), `tools.list` (Q20), `models.list/current`, `todo.list`, `queue.messages.list`, `session.metadata`, and `session.stats`; no one-shot legacy-shaped snapshot, no retired `dumpTools` include-toggle/exact dump schema, and some legacy snapshot fields remain absent | `6e147d58~1:docs/rpc.md:85,169-222`; registry:132-152; sdk/bus/index.ts:1804-1808,1852-1855; host/query/handlers.ts:91,116; docs/sdk.md “Protocol” and “Model catalog query (Q10)” |\n| State | `set_todos` | `todo.replace` | retired doc; registry:78; dispatch:166-167 |\n| State | `set_host_tools` | Partial SDK equivalent — provider-only/machine attachment; not installed on the ordinary per-session endpoint: `host_tools.register` | `6e147d58~1:docs/rpc.md:87,255-291`; registry:105,164; dispatch:220-221; sdk/bus/index.ts:1654,1726-1738,2325-2327 |\n| State | `set_host_uri_schemes` | Partial SDK equivalent — provider-only/machine attachment; not installed on the ordinary per-session endpoint: `host_uri.register` | `6e147d58~1:docs/rpc.md:88,293-323`; registry:106,165; dispatch:222-223; sdk/bus/index.ts:1654,1726-1738,2325-2327 |\n| State | `workflow_gate_response` | `workflow.gate_answer` (durable Q12 gate ID) | retired doc; registry:73; dispatch:151-157; docs/sdk.md “Durable workflow controls and Q12” |\n| Model | `set_model` | `model.set` | retired doc; registry:79; dispatch:168-169 |\n| Model | `set_default_model_selection` | `model.set` with `thinkingLevel`; equivalent active-model/default-selection intent, not the retired durable-selector response envelope | retired doc; registry:79; dispatch:168-169; docs/sdk.md “Model catalog query (Q10)” |\n| Model | `cycle_model` | `model.cycle` | retired doc; registry:80; dispatch:170-171 |\n| Model | `get_available_models` | `models.list/current` / Q10 | retired doc; registry:141; docs/sdk.md “Model catalog query (Q10)” |\n| Thinking | `set_thinking_level` | `thinking.set` | retired doc; registry:81; dispatch:172-173 |\n| Thinking | `cycle_thinking_level` | `thinking.cycle` | retired doc; registry:82; dispatch:174-175 |\n| Queue modes | `set_steering_mode` | `queue.steering_mode.set` | retired doc; registry:84; dispatch:178-179 |\n| Queue modes | `set_follow_up_mode` | `queue.follow_up_mode.set` | retired doc; registry:85; dispatch:180-181 |\n| Queue modes | `set_interrupt_mode` | `queue.tool_interrupt_policy.set` | retired doc; registry:86; dispatch:182-183; renamed from `queue.interrupt_mode.set` (values `abort_tools` / `finish_tools`) |\n| Compaction | `compact` | Partial SDK equivalent: `compaction.run` takes no input and loses retired `customInstructions` | `6e147d58~1:docs/rpc.md:111`; registry:87; dispatch:184-185 |\n| Compaction | `set_auto_compaction` | `compaction.auto.set` | retired doc; registry:88; dispatch:186-187 |\n| Retry | `set_auto_retry` | `retry.auto.set` | retired doc; registry:89; dispatch:188-189 |\n| Retry | `abort_retry` | `retry.abort` | retired doc; registry:90; dispatch:190-191 |\n| Bash | `bash` | `bash.execute` | retired doc; registry:91; dispatch:192-193 |\n| Bash | `abort_bash` | `bash.abort` | retired doc; registry:92; dispatch:194-195 |\n| Session | `get_session_stats` | `session.stats` | retired doc; registry:146; docs/sdk.md “Protocol” |\n| Session | `export_html` | Partial SDK equivalent: `session.export_html` takes no input and loses retired `outputPath` | `6e147d58~1:docs/rpc.md:127`; registry:101; dispatch:212-213 |\n| Session | `switch_session` | Partial SDK equivalent: retired `switch_session` was path-addressed (`sessionPath`), while `session.switch` is ID-addressed | `6e147d58~1:docs/rpc.md:128`; registry:97; dispatch:204-205 |\n| Session | `branch` | `session.branch` | retired doc; registry:98; dispatch:206-207 |\n| Session | `get_branch_messages` | `session.branch_candidates` plus `transcript.list`/`transcript.body`; no identical combined payload | retired doc; registry:132-133,147; docs/sdk.md “Protocol” |\n| Session | `get_last_assistant_text` | `session.last_assistant` | retired doc; registry:148; docs/sdk.md “Protocol” |\n| Session | `set_session_name` | `session.rename` | retired doc; registry:99; dispatch:208-209 |\n| Messages | `get_messages` | `transcript.list` and `transcript.body`; no identical monolithic payload | retired doc; registry:132-133; docs/sdk.md “Protocol” |\n\n## Closed framing, sub-protocol, registry, and transport inventory\n\n| Retired family | Retired frame, protocol, or transport | SDK v3 equivalent or classification | Evidence |\n| --- | --- | --- | --- |\n| Outbound frame | `ready` | transport-gap — closed by Phase 1; WebSocket connection/authentication replaces JSONL readiness | retired doc; docs/sdk.md §Endpoint discovery |\n| Outbound frame | `response` | transport-gap — closed by Phase 1; SDK control request/response replaces JSONL `RpcResponse` | retired doc; registry:66-119; dispatch:138-253 |\n| Outbound frame | canonical `event` | phase-2-gap; no renderer-grade canonical `AgentSessionEvent` stream | retired doc; docs/sdk.md §Protocol |\n| Outbound frame | `workflow_gate` | Partial SDK equivalent: `action_needed` with `workflowGateId`, plus Q12; not the retired frame/schema | retired doc; docs/sdk.md §Server → client, §Durable workflow controls and Q12 |\n| Outbound frame | `extension_ui_request` | phase-2-gap for extension UI methods; `action_needed` covers only generic asks | retired doc; docs/sdk.md §Server → client |\n| Outbound frame | `host_tool_call`, `host_tool_cancel` | Partial SDK equivalent — provider-only/machine attachment; not installed on the ordinary per-session endpoint: reverse `host_tool.invoke/cancel/update/result` with `host_tools.register` | `6e147d58~1:docs/rpc.md:45-46,357`; registry:105,164; dispatch:220-221; sdk/bus/index.ts:1654,1726-1738,2325-2327 |\n| Outbound frame | `host_uri_request`, `host_uri_cancel` | Partial SDK equivalent — provider-only/machine attachment; not installed on the ordinary per-session endpoint: reverse `host_uri.read/write/cancel/result` with `host_uri.register` | `6e147d58~1:docs/rpc.md:46,357`; registry:106,165; dispatch:222-223; sdk/bus/index.ts:1654,1726-1738,2325-2327 |\n| Outbound frame | `extension_error` | phase-2-gap; no SDK extension-error frame contract | retired doc; docs/sdk.md §Protocol |\n| Inbound frame | `RpcCommand` | SDK control and query operations | retired doc; registry:66-157; dispatch:138-253 |\n| Inbound frame | `workflow_gate_response` | `workflow.gate_answer` | retired doc; registry:73; docs/sdk.md “Durable workflow controls and Q12” |\n| Inbound frame | `extension_ui_response` | phase-2-gap except generic `reply` for an `action_needed` ask | retired doc; docs/sdk.md §Client → server |\n| Inbound frame | `host_tool_update`, `host_tool_result` | Partial SDK equivalent — provider-only/machine attachment; not installed on the ordinary per-session endpoint: reverse `host_tool.invoke/cancel/update/result` | `6e147d58~1:docs/rpc.md:54`; registry:164; dispatch:220-221; sdk/bus/index.ts:1654,1726-1738,2325-2327 |\n| Inbound frame | `host_uri_result` | Partial SDK equivalent — provider-only/machine attachment; not installed on the ordinary per-session endpoint: reverse `host_uri.read/write/cancel/result` | `6e147d58~1:docs/rpc.md:55`; registry:165; dispatch:222-223; sdk/bus/index.ts:1654,1726-1738,2325-2327 |\n| Workflow gate sub-protocol | `workflow_gate` / `workflow_gate_response` with schema and durable broker semantics | Partial SDK equivalent: `action_needed`, `reply`, Q12 `workflow.gates.list`, and `workflow.gate_answer`; IDs and authority rules differ | retired doc; registry:73,143; docs/sdk.md “Answer semantics” and “Durable workflow controls and Q12” |\n| Extension UI sub-protocol | select/confirm/input/editor/cancel/notify/status/widget/title/editor-text | phase-2-gap; generic action presentation is not extension UI parity | retired doc; docs/sdk.md §Server → client |\n| Host tool sub-protocol | registration, call/cancel, update/result | Partial SDK equivalent — provider-only/machine attachment; not installed on the ordinary per-session endpoint: `host_tools.register` plus reverse callback operations | `6e147d58~1:docs/rpc.md:45,54,255-291,357`; registry:105,164; dispatch:220-221; sdk/bus/index.ts:1654,1726-1738,2325-2327 |\n| Host URI sub-protocol | scheme registration, read/write/cancel/result | Partial SDK equivalent — provider-only/machine attachment; not installed on the ordinary per-session endpoint: `host_uri.register` plus reverse callback operations | `6e147d58~1:docs/rpc.md:46,55,293-323,357`; registry:106,165; dispatch:222-223; sdk/bus/index.ts:1654,1726-1738,2325-2327 |\n| Unattended sub-protocol | `negotiate_unattended` declaration/budget/scopes/allowlist | phase-2-gap | retired doc; docs/sdk.md §Coordinator MCP question pull loop |\n| `rpc-sessions` registry | Cross-process session registry and reattach semantics | phase-2-gap. Per-session discovery files are only partial endpoint location, not a registry/reattach protocol | parent source: `6e147d58~1:packages/coding-agent/src/modes/rpc/rpc-mode.ts:892-907,984-992`; `6e147d58~1:packages/coding-agent/src/modes/shared/agent-wire/session-registry.ts:1-53`; docs/sdk.md §Endpoint discovery, §Architecture |\n| Transport | stdio JSONL | retired. Direct stdio relay was removed; managed clients use Router-owned capabilities. | parent source: `6e147d58~1:packages/coding-agent/src/modes/rpc/rpc-mode.ts:892-907,984-992`; removal evidence: SDK-owned session lifecycle handoff |\n| Transport | `--listen` Unix socket | retired. Direct Unix-socket relay was removed; managed clients use Router-owned capabilities. | parent source: `6e147d58~1:packages/coding-agent/src/cli/args.ts:157-158`; removal evidence: SDK-owned session lifecycle handoff |\n\n## Five-gap reduction verdict\n\nSDK v3 has broad control/query coverage: the operation registry includes turn,\nmodel, thinking, queue, compaction, retry, bash, session, host callback, and\nworkflow operations (`operation-registry.ts:66-166`), and control dispatch\nimplements the control path (`dispatch.ts:138-253`). That does **not** erase the\nuser-perceived reduction. It is **REAL** across five dimensions:\n\n1. **stdio JSONL and Unix-socket transports.** The interim `gjc sdk serve` relay was retired; external attachment now requires Router-owned opaque capabilities and never forwards endpoint credentials.\n2. **Typed Python client.** The interim public Python transport client was retired with the direct relay; cross-process integrations require Router-owned capabilities.\n3. **`negotiate_unattended`.** No fail-closed unattended negotiation with the\n   retired declaration, budget, scope, and allowlist exists: this remains Phase 2.\n4. **Cross-process session registry/reattach.** Discovery files locate a live\n   endpoint but do not provide the retired registry or reattach lifecycle: this\n   remains Phase 2.\n5. **Renderer-grade full event stream.** SDK v3's minimal frames and optional\n   threaded-client frames are not the retired canonical session event stream.\n   **No event-plane parity is claimed.**\n\n## Ranked Phase-2 follow-up register — NOT implemented\n\n1. **Unattended negotiation equivalent — NOT implemented.** Add a fail-closed\n   equivalent to `negotiate_unattended` only with explicit actor, budget, scopes,\n   allowlist, and audit enforcement. Partial equivalent only: Q12\n   `workflow.gates.list` plus the Coordinator MCP pull loop can enumerate and\n   answer durable workflow gates; they are not unattended negotiation\n   (`docs/sdk.md §Coordinator MCP question pull loop`).\n2. **Reattachment semantics — implemented in SDK core.** `SessionRouter` exclusively resolves private endpoint publication, retains credentials, reconnects, replays, rotates transports, and issues exact opaque attachment capabilities. External adapters do not consume discovery files or raw endpoint credentials.\n3. **Full event stream — NOT implemented.** Define a renderer-grade session\n   event contract only if consumers require it. Partial equivalent only:\n   `action_needed`, `action_resolved`, `reply_rejected`, and optional threaded\n   frames such as `turn_stream` exist, but there is **no `onSessionEvent`-style\n   SDK equivalent** (`docs/sdk.md §Server → client`).\n\n## Completeness checklist\n\n- [x] Prompting — every retired command represented.\n- [x] State — every retired command represented.\n- [x] Model — every retired command represented.\n- [x] Thinking — every retired command represented.\n- [x] Queue modes — every retired command represented.\n- [x] Compaction — every retired command represented.\n- [x] Retry — every retired command represented.\n- [x] Bash — every retired command represented.\n- [x] Session — every retired command represented.\n- [x] Messages — every retired command represented.\n- [x] Outbound and inbound frame categories — every retired category represented.\n- [x] Workflow gate sub-protocol represented.\n- [x] Extension UI sub-protocol represented.\n- [x] Host tool sub-protocol represented.\n- [x] Host URI sub-protocol represented.\n- [x] `negotiate_unattended` sub-protocol represented.\n- [x] `rpc-sessions` registry represented from parent-commit source (supplemental to the recovered document inventory).\n- [x] stdio JSONL represented from the recovered document inventory; `--listen` Unix-socket transport represented from parent-commit source.\n",
-	"sdk-session-cli.md": "# SDK session CLI\n\n`gjc sdk session` is the broker-bound command family for operating live GJC SDK\nsessions from the terminal. It replaces the removed `gjc daemon session` route.\n\nThe command family has seven semantic verbs — `list`, `inspect`,\n`send`, `status`, `tail`, `close`, and `retire` — plus the explicit `raw` hatch that dispatches one\nSDK operation as `control`, `query`, or `global`.\n\nThe session CLI is advisory tooling over the SDK: every semantic verb resolves\nsessions through the SDK broker, and output is rendered through a versioned,\ncredential-free DTO. Endpoint credentials are never printed.\n\n## Command-local help\n\nDiscovery is static and inert for every public SDK and daemon parent, leaf and\nalias; it does not initialize a broker, settings, transport or evidence store.\nUse the deepest known command for its arguments, applicable options and risks:\n\n```sh\ngjc sdk session raw query --help --json\ngjc daemon reload --help --help-section options --help-page 1\n```\n\n`-h` is equivalent to `--help`. Sections traverse in this fixed order:\n`overview`, `usage`, `children`, `arguments`, `options`, `examples`, `recovery`.\nThe defaults are `overview` and page `1`; an empty section has a valid page 1.\nEach response includes only the selected node and, in `children`, its immediate\nchildren. Follow the returned `next.argv` unchanged, including\n`--help-revision <sha256>`, section, page and `--json` when selected. A changed\nrevision requires a new traversal; do not merge pages from different revisions.\n\nValued selectors accept separate or `=` operands. Pages are positive decimal\nsafe integers. Repeated/invalid selectors, selectors without actual help, and\nunknown descendants fail with usage exit 2 at the nearest known command.\n`--help=json` is unsupported. Option values and tokens after `--` do not activate\nhelp or JSON mode. Syntax containing `<placeholders>` is documentation, not a\nready-to-run recovery command.\n\nText and `gjc.command-help` version 1 JSON responses are each at most 8192 UTF-8\nbytes including the newline. Text escapes controls and labels display literals;\nnever paste escaped display text as shell argv. Complete entries have stable\nIDs. Oversized values use non-executable base64 fragments: concatenate contiguous\n`offsetBytes` ranges, verify `totalBytes` and `sha256`, then decode the complete\nUTF-8 JSON value. `sectionComplete` ends a section; only `documentComplete: true`\nwith `next: null` ends traversal. Help paging never reruns an operation.\n\n## Broker authority\n\n`list`, `inspect`, `send`, `status`, and `tail` resolve sessions through the\nSDK broker and Router. The Router validates indexed endpoint authority and keeps\nthe connection credential in SDK core; the CLI receives only credential-free\nresults. The broker is started on demand (`ensureBroker`) when discovery is\nabsent, and an unavailable broker fails closed with a typed operational error\n(exit 1).\n\n`--agent-dir` selects the broker state directory. It may appear at the session\nfamily level before the verb (`gjc sdk session --agent-dir <dir> list`) or on a\nleaf command. `--repo` selects the workspace directory for scoped listing or\nsaved-session resolution (default: the current directory). For compatibility,\n`inspect`, `send`, `status`, and `raw query` also accept `--repo`, but ignore it:\nthe exact session ID selects the broker target. Successful calls print a\npath-free warning to stderr. Failed `--json` calls keep stderr empty and return\ntheir structured error; command-local help identifies `--repo` as compatibility-only.\n\n## Semantic verbs\n\n### list\n\n`gjc sdk session list` queries the broker `session.list` global and projects\nevery indexed session into the versioned row DTO (`SESSION_ROWS_VERSION`). Each\nrow is credential-free and carries:\n\nThe list is fully paginated before scope filtering. By default its effective\nscope is `repo`. Select a scope with:\n\n```sh\ngjc sdk session list --scope repo|cwd|worktree|all [--repo <path>]\n```\n\n`--repo` is the selected workspace path and defaults to the process cwd. The\nresult reports the effective `scope` and a bounded credential-free `selection`\ndescriptor containing the canonical selected path and, for Git selections,\nthe canonical worktree root and Git common directory.\n\n- `repo` matches the canonical Git common directory, so the main checkout and\n  linked worktrees are included while another repository is excluded.\n- `worktree` matches only the selected path's canonical containing worktree.\n- `cwd` matches only the exact canonical selected workspace; nested directories\n  do not match.\n- `all` preserves the complete unfiltered Broker listing.\n\nFor a path outside Git, `repo` and `worktree` fail with the typed\n`not_a_repository` operational error and an actionable suggestion to use\n`cwd` or `all`; they never broaden the result. `cwd` remains available for an\nexact canonical path match. Unreadable or removed row workspaces are excluded\nfrom Git scopes deterministically and reported in `warnings`.\n\nThe raw global `session.list` route remains unfiltered, and `inspect`, `send`,\n`status`, `tail`, `close`, `retire`, and raw control/query behavior is unchanged.\n\nFor a process-isolated caller that needs bounded discovery, request exactly one\nBroker page instead of the semantic all-pages list:\n\n```sh\ngjc sdk session raw global --op session.list --page --limit 20 \\\n  --agent-dir <agent-dir>\ngjc sdk session raw global --op session.list --page --cursor <opaque-cursor> \\\n  --limit 20 --agent-dir <agent-dir>\n```\n\n`--page` preserves the Broker page envelope, including `indexSeq`, `warnings`,\nthe bounded `sessions` array, and the opaque `continuationCursor`. The cursor\nis a snapshot continuation: pass it back unchanged, with the same `--limit`,\nand never restart from the first page or locally slice an all-pages result.\nSemantic `gjc sdk session list` remains the fully paginated, scope-filtered\noperation.\n\n- `sessionId` and the `locator` (`cwd`, `worktreeRoot`, `stateRoot`), where `cwd`\n  is the canonical workspace directory and `worktreeRoot` is the canonical Git\n  worktree root or `null` outside a worktree;\n- `endpointGeneration`, `pid`, `live`, `deleted` (tombstone), `indexSeq`;\n- `hostIncarnation` and `identityProvenance` (`composite` | `legacy`);\n- `activity` (`{state: active|idle, at}`) and `lastHeartbeatAt`;\n- `terminalUncertain`, `lifecycleRequestId`, `endpointMtimeMs`;\n- `ambiguous` when the same `sessionId` has more than one unresolved\n  authority-fencing `stateRoot` (cross-repo duplicate). A proven non-endpoint\n  bookkeeping registration (the direct-session GC fence row, endpoint\n  generation 0) stays indexed without fencing endpoint attachment; every other\n  unresolved root, including an unproven generation-0 `lifecycle_terminal`\n  claim, still fences.\n\n### inspect\n\n`gjc sdk session inspect <sessionId>` renders one indexed row from the broker.\nIt never reads endpoint discovery records directly: a missing or unavailable\nbroker fails closed rather than exposing endpoint authority outside SDK core.\n\n### send\n\n`gjc sdk session send <sessionId> --text <prompt>` submits an ordered\n`turn.prompt` carrying a caller-chosen operation reference (a ULID by default,\nor `--op-ref`). The result envelope reports `accepted` with the receipt and the\noperation reference used for later reconciliation.\n\n- `--wait` polls `turn.result` with `kind: \"prompt\"` until the prompt reaches a\n  terminal state or the wait window (`--timeout-ms`, default 30s) elapses.\n  `send --wait` never cancels a running turn; a window that elapses before a\n  terminal state is reported as `wait_timeout` with the last observed status.\n\n- `--text` and the JSON input sources (`--json-input`,\n  `--json-input-file` — which must be a `0600` regular file —\n  `--json-input-stdin`) are mutually exclusive for the prompt body.\n- File input is read through one descriptor, rejects symlink/replacement races,\n  and is capped at 4 MiB before JSON parsing.\n\n### status\n\n`gjc sdk session status <sessionId> <opRef>` performs a lossless `turn.result`\nlookup with `kind: \"prompt\"` for a previously submitted operation reference and\nreturns the full reconciliation record plus a `summary.completed` flag.\nSee [lossless prompt results](#lossless-prompt-results).\n\n\n### tail\n\n`gjc sdk session tail <sessionId>` replays the retained transcript from the\ndurable checkpoint and then follows the live event-ring frames, emitting the\ndefault tail kinds (session lifecycle and turn lifecycle events) plus retained\ntranscript entries.\n\n- `--strict` fails closed with `retention_gap` (exit 1) when retained history\n  or the event ring dropped entries before the checkpoint.\n- `--until-idle` exits once the current turn reaches a terminal state; a session\n  close exits any tail as `terminal: true`, while a bare live tail otherwise\n  remains attached until `--timeout-ms`. Each item carries `revision` (the durable checkpoint revision); the triple `(revision,generation,seq)` is unique for the session, while `generation:seq` alone is revision-local and restarts each accepted prompt — key idempotency on the triple. Lifecycle\n  events that carry a `(generation, seq)` position are reconciled and emitted in\n  that canonical order rather than arrival order, so a retained terminal event\n  from an earlier turn does not complete a newer turn that is still running, and\n  a terminal event observed live is not undone by replayed history that arrives\n  after it. Positioned event items are emitted canonically ahead of an\n  arrival-ordered segment of events that carry no position; such an event stays\n  visible but cannot supersede a positioned turn state. Different lifecycle\n  kinds claiming the same `(generation, seq)` fail closed with `protocol_error`\n  (exit 1) because no order between them can be proven, and that conflict\n  outranks an otherwise successful idle or close completion. A canonical\n  position is a pair of non-negative safe integers. A replayed event-ring row that\n  states either coordinate property must state both validly; a row claiming only\n  one coordinate, or a null, negative, fractional, non-finite, or\n  unsafe-integer coordinate, fails closed with `protocol_error` rather than\n  being treated as unpositioned. Only a row that states neither coordinate is\n  unpositioned. Retained transcript entries are deduplicated independently of\n  event-ring rows and are not event-ring authority, so a transcript row that\n  projects the same kind and position as a real event never suppresses it. For a\n  specific prompt operation, `status <sessionId> <opRef>` remains the lossless\n  authority.\n- `--all-events` widens the emitted set to every event-ring kind.\n- `--cursor` resumes from a saved signed checkpoint claim. `session.checkpoint`\n  verifies the unexpired claim and exchanges it for a fresh connection-owned\n  cursor pinned to the exact prior revision; direct cross-connection cursor\n  consumption remains rejected, so reconnect never echoes or rewinds a cursor.\n- `--after-transcript-id` selects the caller's last observed transcript row;\n  live resumes require it alongside `--cursor`, while offline tails may use the\n  boundary directly. The boundary is recoverable: an unknown row leaves the\n  retained snapshot intact, while a boundary older than the retained window\n  fails closed with a retention gap.\n- `--timeout-ms` bounds live follow; a session whose lifecycle already ended\n  (terminal or `terminalUncertain`) replays retained history and exits instead\n  of hanging.\n\nA deleted session has no tail (`session_deleted`). A stopped session replays\nits retained transcript without an endpoint (offline source), bounded to the\nmost recent retained entries.\n\n### close\n\n`gjc sdk session close <sessionId>` is the official semantic wrapper for the\n`session.close` broker global. It ends one live session: the broker validates\nindexed authority, asks the host to shut down gracefully, escalates to SIGTERM\nagainst the durably identified session process when graceful teardown exceeds\nthe bounded deadline, and appends terminal `session_closed` evidence. A session\nwhose ownership is `terminalUncertain` is refused rather than signalled — that\nis what `retire` is for.\n\n```sh\ngjc sdk session close <sessionId> [--agent-dir <agent-dir>] [--idempotency-key <key>]\n```\n\nClosing never attaches to the session. A Router attachment registers the\ncalling process as a live client and renews the host's abandonment window,\nwhich is the opposite of the intent, so the lifecycle mutation is answered by\nthe broker over its own client.\n\n`--idempotency-key` is optional here, unlike the raw `session.close` global. The\ndefault request key is derived from the session id and the current endpoint\ngeneration/incarnation. A retry against the same live host replays the same\nlifecycle request; a host resumed under the same session id receives a fresh\nrequest identity and is closed by a new lifecycle operation. Pass\n`--idempotency-key` explicitly to supply a caller-chosen attempt key.\n\n### retire\n\n`gjc sdk session retire <sessionId>` is the official semantic wrapper for the\n`session.reconcile_uncertain` broker global. It retires an indexed\n`terminalUncertain` create effect only when exactly one matching uncertain\ncreate identity exists, the recorded host is proven exited, the endpoint is\nabsent, and any lifecycle marker/readiness leftovers are regular files bound to\nthat same PID and incarnation. The broker removes only those verified\nleftovers, appends terminal `session_closed` evidence, and converts the\nmatching lifecycle receipt to a terminal error. Ambiguous identity, live or\nunverifiable hosts, endpoint presence, malformed leftovers, and mismatches\nrefuse without signalling a process. Supply `--idempotency-key`; the JSON\ninput is read from a `0600` file or stdin when it contains proof material.\n\n## Raw hatch\n\n`gjc sdk session raw <control|query|global>` dispatches exactly one SDK\noperation and returns the broker/host response:\n\n- `raw control <sessionId> --op <operation>` — one control operation with\n  `--json-input*`; `--confirm` confirms destructive control operations.\n- `raw query <sessionId> --query <operation>` — one query; `--cursor` passes a\n  continuation cursor.\n- `raw global --op <operation>` — one broker global. Lifecycle globals\n  (`session.create`, `session.fork`, `session.resume`, `session.close`,\n  `session.delete`, `session.reconcile_uncertain`, `session.lookup`) require\n  `--idempotency-key`.\n\n`session.lookup` is a read-only reconciliation of a previously submitted\n`session.create`. Reuse the caller request key and the same create target that\nwere retained before dispatch; GJC derives the Broker identity and fingerprint\ninside the lifecycle boundary. It never calls `session.create` and never\nreplays session work:\n\n```sh\ngjc sdk session raw global --op session.lookup \\\n  --idempotency-key <create-request-key> \\\n  --json-input '{\"cwd\":\"/absolute/path/to/repo\"}' \\\n  --agent-dir <agent-dir>\n```\n\nThe credential-free result identifies the original operation and request key.\n`status: \"found\"` carries the canonical session result; `pending`,\n`not_found`, `conflict`, `uncertain`, and `terminal` are distinct structured\noutcomes and retain `certainty` and the recovery identity. A missing record is\nnot proof that the create did not execute, so callers must not resubmit solely\nbecause lookup reports `not_found`. Reconciliation failures exit nonzero while\npreserving the structured outcome in JSON.\n\nA separately connected local controller can stop the active turn and its exact\nowned work with an explicitly confirmed operator abort:\n\n```sh\ngjc sdk session raw control <sessionId> \\\n  --op turn.abort \\\n  --json-input '{\"mode\":\"terminal\",\"scope\":\"owned\",\"operator\":true}' \\\n  --idempotency-key '<unique-key>' \\\n  --confirm\n```\n\nThe JSON input accepts only operation fields (`mode`, `scope`, `operator`).\n`--confirm` and `--idempotency-key` are CLI authority inputs, not JSON fields.\nThe exact `operator:true` shape is routed through the local Broker, which\nrevalidates the current endpoint identity and injects a process-bound private\ncapability before dispatch. MCP, ACP, notifications, and ordinary SDK endpoint\nrequests cannot mint operator authority: copying `operator:true` and\n`confirm:true` into a public control frame is rejected. Omitting confirmation,\nomitting the key, or supplying `operator:false` fails closed without invoking\nthe terminal-abort surface. Non-operator terminal abort retains its existing\nconnection-ownership semantics.\n\n`session.get_endpoint` is refused unconditionally: endpoint credentials remain\nan SDK-core implementation detail. The raw hatch validates operation names and\nadapter dispositions up front and never renders endpoint-disclosure results.\n\n## Lossless prompt results\n\n`turn.result` with `kind: \"prompt\"` reports `accepted`, `in_flight`,\n`terminal_ok`, or `failed`; only retained-record capacity eviction yields\n`unknown`. `turn.prompt_status` remains a legacy prompt-only alias. A prompt\nthat is active at process restart is finalized from its durable pending outcome\n(or `prompt_failed` when it has none), so it never reports as `unknown` while a\nrecord exists.\n\n`unknown` means uncertainty, never proof of non-execution: do not reuse an\noperation reference as a retry mechanism (`client_ref_conflict` while the\nrecord is retained; after eviction a reused ref may be admitted again with the\nprior outcome unknown). Use one fresh operation reference per logical prompt\nand reconcile with `status`.\n\n## Checkpoint gaps\n\n`tail` reports a `retention_gap` when retained history or the event ring\ndropped entries before the durable checkpoint: the gap carries the missing\nsequence range (`missing.from`/`missing.to`) and a `resync` checkpoint.\n`--strict` turns any gap into `retention_gap` with exit 1; without `--strict`,\ntail continues from the resync position and reports the gap in the envelope.\n\n\n## Migration from the removed daemon session route\n\n`gjc daemon session` is removed and no alias is provided. Migrate:\n\n| Removed route | Replacement |\n| --- | --- |\n| `gjc daemon session list` | `gjc sdk session list` |\n| `gjc daemon session inspect <sessionId>` | `gjc sdk session inspect <sessionId>` |\n| `gjc daemon session send <sessionId> --text <prompt>` | `gjc sdk session send <sessionId> --text <prompt>` |\n| `gjc daemon session tail <sessionId>` | `gjc sdk session tail <sessionId>` |\n| raw control/query dispatch | `gjc sdk session raw control|query|global` |\n\nThe broker-bound surface replaces the daemon-owned routing: sessions are\nresolved through the SDK broker with validated endpoint identity instead of\ndirect discovery-file reads, and output is versioned and credential-free.\n\n## Exit codes and error envelope\n\nSession verbs exit `0` and keep their existing successful JSON stdout contract,\nincluding when `--json` is absent. **Machine callers must explicitly add\n`--json` for machine-readable failures.** Ordinary failures otherwise write\nbounded text to stderr only. With `--json`, failure writes exactly one\n`gjc.command-error` version 1 envelope and newline to stdout, with empty stderr.\nBoth modes are limited to 8192 UTF-8 bytes including formatting and newline.\nUsage errors exit `2`; operation failures (including unavailable broker/session,\nretention gaps and `send --wait` timeouts) exit `1`. A live `session tail` wait\nwindow is a bounded observation rather than an operational failure: it exits `0`\nwith `terminal: false` and all items observed before the deadline.\n\nThe envelope preserves `command`, `error.code`, `category`, `retryability`,\n`outcomeCertainty`, allowlisted `references` and evidence-based `nextSteps`, plus\n`omittedOptional`, `complete`, `evidence` and `continuation`. Safe fields are\nexplicitly projected; arbitrary exception messages, request bodies, credentials\nand stacks are not public error evidence. Do not infer non-execution from a\nnonzero exit or timeout: `wait_timeout` after acceptance means applied work,\nwhereas `uncertain_after_send` means the outcome is unknown. Preserve session,\noperation, idempotency, claim, command and turn references when supplied.\n\nError guidance performs no additional probes, status calls, retries, restarts or\nkills. Execute an appropriate explicit observation only when the task warrants\nit; reconcile before considering replay. `retire` is a proof-bound mutation,\nnot a generic status check, and requires confirmed intent and actual applicable\nproof. Daemon `stop`/`restart` interrupt work; `--force` permits SIGKILL escalation.\nDaemon kinds are `telegram`, `discord`, `slack` (default `telegram`); `daemon`\ndefaults to `status`, and `reload` aliases `restart`. There is no\n`gjc daemon restart sdk` recovery command. Never repeat successful mutations\nwhen a multi-target daemon result contains failures.\n\n### Retained error evidence\n\nWhen essential sanitized reconciliation references do not fit inline, the CLI\nmay retain them locally, but advertises `evidence.status: \"retained\"` and a\ncontinuation only after successful publication and read-back verification.\nRetrieval is an explicit family-root operation, not an operation retry:\n\n```text\ngjc sdk --error-ref <32-lowercase-hex-id> --error-sha256 <64-lowercase-hex> [--error-page <N>] [--error-agent-dir <dir>] [--json]\ngjc daemon --error-ref <32-lowercase-hex-id> --error-sha256 <64-lowercase-hex> [--error-page <N>] [--error-agent-dir <dir>] [--json]\n```\n\nUse the actual returned argv rather than constructing a locator. Ref and digest\nare required together; page defaults to 1 and is a positive decimal safe integer.\nSelectors support separate/equals forms; duplicates are invalid. Retrieval is\nexclusive with help, operation positionals and operation flags. Scope/page\nselectors require retrieval. `--error-agent-dir` is distinct from SDK operation\n`--agent-dir`; daemon worker `--agent-dir` is private. Retrieval uses only the\nexplicit/default root and checks the stored family, never scans other roots.\n\nThe store is `<effective-agent-dir>/cli-error-evidence-v1`. Records expire exactly\n24 hours after creation, without sliding reads. Expiry refuses retrieval; lazy\ncleanup is not a promise of immediate secure erasure. Limits are 64 committed\nrecords, 1 MiB per record and 16 MiB committed aggregate, plus at most one 1 MiB\npending file and one 4096-byte lock: at most 66 files and 17 MiB + 4096 bytes of\nlogical payload (filesystem allocation overhead is separate). Unexpired records\nare not evicted to make space. POSIX owner-only permissions are verified; an\nunsupported secure permission mechanism fails closed. No success/help output\ninitializes the store and there is no background cleanup service.\n\nSuccessful retrieval is `gjc.command-error-evidence` version 1 on stdout, exit 0,\nwith each text/JSON page bounded to 8192 bytes. It means retrieval succeeded, not\nthat the original operation did. Follow the pinned digest/scope/mode continuation;\nreassemble contiguous base64 bytes and verify total length and SHA256 before\nUTF-8/JSON decoding or using references. Pages contain immutable retained evidence,\nnot resampled runtime state.\n\nDisk, permissions, quota, lock contention or verification failure may prevent\nretention. The original failure remains nonzero with its original outcome\ncertainty and retryability: `complete: false`, `evidence.status: \"unavailable\"`,\nand `continuation: null`, with the explicit warning that necessary evidence\ncould not be retained and **do not blindly retry the original operation**.\nMissing essential evidence is not described as optional, and no invented path,\nID, digest or fallback store is advertised. Lossless retrieval is guaranteed only\nfor successfully published records within their retention lifetime; expiry,\ndeletion or corruption can make later retrieval unavailable.\n\nThese bounds do not paginate successful session/search/spawn/guides results.\nSearch outside Git retains its successful exit-0 result; observing an unhealthy\ndaemon is still a successful status operation. Serve preflight errors use the\nordinary failure contract; after relay ownership, protocol framing and termination\nremain unchanged, without CLI error envelopes injected into the stream.\n\n## Scoped search (`gjc sdk search`)\n\n`gjc sdk search [--scope repo|pwd|global] [--limit N] [--cursor <token>] [--json]`\nlists broker-visible sessions inside one exact scope. The default scope is\n`repo`: the identical canonical Git worktree of the invoking directory, never a\npath prefix or subtree. `pwd` matches the exact canonical working directory and\n`global` covers every broker-visible row.\n\nEvery result — table and JSON, populated and empty — carries a scope/status\nenvelope: the requested scope, the canonical resolved scope, a status\n(`populated`, `empty`, `not-in-git-worktree`, `unavailable`), and the\nobservation time. Running `--scope repo` outside a Git worktree is a successful\nempty result (`not-in-git-worktree`, exit 0) and never falls back to `pwd` or\n`global`. Broker unavailability keeps the locally resolved scope, exits\nnon-zero, and stays credential-free. Continuation cursors are frozen: a\ncontinuation that supplies a different scope or anchor fails with\n`scope_cursor_mismatch` instead of re-scoping.\n\nRows are probed only after scope filtering, through broker/router-owned\ncredential-free attachments, yielding `reachable`, `unreachable`, or `stale`.\n\n## Local-only spawn (`gjc sdk spawn`)\n\n`gjc sdk spawn --cwd <dir> --prompt <task> [--model <selector>] [--profile <name>] [--json]`\ncreates one task-seeded background child session through the broker. It is\nlegal only inside a live interactive `gjc --master` session: the command needs\nthe master's transient capability (threaded through the master session\nenvironment) and the broker verifies it against the live effective master host\nbefore any effect. Spawn is prohibited on MCP, ACP, daemon CLI/raw session CLI,\nTelegram, Discord, and Slack surfaces.\n\nEach invocation uses a fresh idempotency identity. One identity produces at\nmost one child substrate and one seed prompt; repeated requests replay the\nstored outcome. A semantically new task requires a new invocation, never a\nretry of an old identity. `spawn_in_progress` and `terminal_uncertain` are\nhonest durable states: inspect with `gjc sdk search` or session status instead\nof retrying blindly.\n\nThe task text and master capability never persist anywhere in broker state —\nno plaintext, hash, or derived verifier appears in the lifecycle ledger, spawn\nauthority journal, receipts, logs, or output. Spawn output renders only safe\nfields: result code, claim id, child session id, substrate kind, and opaque\nseed facts.\n\nClose spawned children through the standard `session.close` path; the broker\ncloses only an exactly re-proven substrate and retains uncertainty on identity\nmismatch. Children orphaned by confirmed master loss are reaped after\n`sdk.masterOrphanGraceMs` (default 120000 ms, bounded 60000..3600000), with the\norphan clock preserved across broker restarts.\n",
-	"sdk.md": "# Gajae-Code SDK\n\nFor embedding GJC in-process, see [the embedding SDK guide](./sdk-embedding.md).\nFor a beginner-friendly application development guide (recipes, customization, and surface selection), see [Building applications on the SDK](./sdk-app-guide.md).\n\n<p align=\"center\">\n  <img src=\"../assets/telegram-mobile-hero.png\" alt=\"Gajae Code mobile answers for coding agents hero illustration\" width=\"100%\" />\n</p>\n\nThe SDK exposes a generic action/reply protocol without requiring integrations to scrape the terminal. SDK core owns all managed attachment discovery and credential-bearing clients through `SessionRouter`; Telegram, Discord, Slack, ACP, MCP, and CLI adapters receive only capability-scoped operations and never endpoint credentials.\n\n> Status: the Rust core (`crates/gjc-sdk`) provides the session-local wire protocol and endpoint record. TypeScript SDK core provides Broker lifecycle authority and `SessionRouter` attachment authority. Endpoint records and tokens are internal implementation details, not an external attachment surface.\n\n## External attachment policy\n\nExternal and managed integrations attach through SDK-core surfaces only:\n\n- lifecycle mutations use `SessionLifecycleService` and the Broker lifecycle ledger;\n- read-only uncertain-create reconciliation uses the public `session.lookup` lifecycle operation with the original request key and target;\n- live session controls use opaque `SessionAttachment` capabilities issued by `SessionRouter`;\n- endpoint URL/token discovery, raw WebSocket relays, and `gjc sdk serve` are not public attachment mechanisms;\n- lifecycle-equivalent per-session controls are prohibited on Telegram, Discord, Slack, ACP, MCP, and daemon CLI adapters.\n\nFor terminal-side session operation, use the broker-bound [SDK session CLI](./sdk-session-cli.md):\n`gjc sdk session list|inspect|send|status|tail|close|retire` plus the explicit `raw`\n`control|query|global` hatch. The CLI resolves the exact attachment through SDK\ncore and emits credential-free JSON on success. Add `--json` explicitly for\nmachine failures; default ordinary failures are text on stderr, not JSON stdout.\n\n### Public CLI discovery and recovery\n\nUse `gjc sdk --help` or deepest local help such as\n`gjc sdk session raw query --help --json` and `gjc daemon reload --help`.\nHelp covers only public paths and immediate children, never worker-only actions\nor flags. `--help-section overview|usage|children|arguments|options|examples|recovery`\nand `--help-page <N>` select bounded static pages; follow `next.argv` with its\n`--help-revision <sha256>` and mode intact. `-h` is accepted, `--help=json` is not.\nSelectors require actual help, valid positive decimal pages and no duplicates.\nHelp is inert and never initializes runtime services or storage.\n\nOrdinary errors use `gjc.command-error` version 1: with `--json`, one stdout\nJSON envelope and empty stderr; otherwise stderr text. Help, errors and explicit\nerror-evidence pages are bounded to 8192 UTF-8 bytes including newline. Existing\nsuccessful result shapes and serve frames after relay ownership are unchanged.\nDo not treat a timeout as proof that work was not applied; preserve returned\nreferences and reconcile rather than blindly replaying a mutation.\n\nOversized essential sanitized error evidence may be retained for exactly 24\nhours in `<effective-agent-dir>/cli-error-evidence-v1`: 64 committed records,\n1 MiB each, 16 MiB committed aggregate, with one additional pending file up to\n1 MiB and a lock up to 4096 bytes. Follow a verified continuation using\n`gjc sdk` or `gjc daemon` with `--error-ref <id> --error-sha256 <digest>`, optional\n`--error-page <N> --error-agent-dir <dir>`, and `--json` for machine output.\nRetrieval is root-only, exclusive with help/operations, and never searches other\nroots or replays the original operation. Reconstruct contiguous base64 fragments\nand verify length/digest before decoding; fragments are not executable commands.\nPublication failure reports incomplete/unavailable evidence and no continuation,\nnot fabricated recovery. Availability is conditional on successful publication\nand the retention lifetime, not a promise to overcome disk failure or deletion.\n\nRecovery hints perform no extra probes or automatic recovery. Daemon targets are\n`telegram`, `discord`, `slack`, not the SDK broker: never suggest\n`gjc daemon restart sdk`. `reload` aliases `restart`; stop/restart interrupt work\nand `--force` permits hard-kill escalation. Session retirement requires actual\nproof and confirmed intent, not merely an uncertain result. See the\n[full help, error and evidence contract](./sdk-session-cli.md#command-local-help).\n\n## Migration from removed external transports\n\nThe retired `--mode rpc`, `rpc-ui` and `bridge` transports have no replacement\nwire client. The existing `gjc sdk serve` relay remains discoverable CLI tooling,\nnot an external SDK attachment API. Process-isolated controllers use Coordinator\nMCP, `gjc sdk session`, or a configured managed adapter. In-process applications\nuse the [embedding SDK](./sdk-embedding.md).\n\n## External-agent SDK skills\n\nThe generated `sdk-skills/` bundle provides host-neutral guidance for scripts\nthat invoke the broker-bound session CLI. It is intentionally separate from\nGJC's four internal workflow skills, the coordinator MCP plugin, and the SDK MCP\nadapter. Its TypeScript and Python templates do not discover endpoints or create\ntransport clients.\n\nThe bundle owns exactly six files:\n\n- `manifest.json`\n- `gjc-sdk-discover/SKILL.md`\n- `gjc-sdk-operate/SKILL.md`\n- `gjc-sdk-author/SKILL.md`\n- `gjc-sdk-author/templates/direct-sdk.ts`\n- `gjc-sdk-author/templates/direct-sdk.py`\n\nRegenerate with `bun run generate-sdk-skills`; CI checks byte-for-byte content\nand rejects unexpected files with `bun run check:sdk-skills`.\n\n### Bundle format version\n\n`manifest.json` is the versioned root of the on-disk bundle contract. It\nidentifies `formatVersion` (currently `1`) and the exact relative file closure\nthat regeneration owns. Consumers must treat a bundle whose manifest is missing,\nmalformed, or declares an unsupported version as unreadable and fail closed. The\nskill prompts are authored as static Markdown sources under\n`scripts/gjc-sdk-skills/prompts/`; the generator copies them verbatim and\n`check:sdk-skills` proves the committed bundle matches the generated artifacts.\n\n### Trust boundary\n\nThe templates invoke only the broker-bound CLI. `SessionRouter` keeps endpoint\nresolution, credentials, SDK clients, replay, reconnect, and rotation inside SDK\ncore. The templates' fixed allowlists and nonce-bound approval are trusted-local\nprocedural safeguards, not capability isolation; lifecycle and attachment\nauthority remain enforced by Broker and Router.\n\nNo renderer-grade cross-process event stream is exposed to external scripts.\nUse managed adapters or Coordinator MCP for event-driven orchestration; see the\n[RPC-to-SDK v3 parity audit](./sdk-rpc-parity-audit.md) for remaining gaps.\n\n## Architecture\n\n```\nBroker lifecycle → Session runtime endpoint → SessionRouter → opaque adapter capability\n```\n\nThe Broker is the sole lifecycle executor and durable terminal authority. `SessionRouter` is the sole credential-bearing external attachment manager. Provider supervisors own only provider transport and presentation state.\n\n- **One endpoint per top-level session.** Each top-level session runs its own loopback WebSocket server. Subagents do not host endpoints. The Broker index is the authoritative live-session catalog, and `SessionRouter` multiplexes managed provider attachments across indexed sessions.\n- **Hosted by default.** SDK hosting is independent of notification configuration. Set `GJC_SDK_DISABLE=1` to opt out of hosting for a top-level session.\n- **Notification delivery is optional.** Configure and enable a managed notification adapter only when remote delivery is needed; the SDK endpoint remains available without one.\n- **Managed integrations use opaque attachments.** Telegram, Discord, Slack, ACP, MCP, and CLI adapters compose SDK-core services; they do not discover endpoint files or receive URL/token credentials.\n- **Zero wire-protocol change.** New transports do not require changes to `crates/gjc-sdk` or the JSON protocol.\n- **tmux-agnostic.** The endpoint behaves identically with or without tmux.\n\n## Internal endpoint publication\n\nA running session publishes an implementation-private credential record for Broker resolution. `SessionRouter` is the sole consumer of the resolved URL/token pair and the sole owner of per-session SDK clients, replay, reconnect, rotation, prepared activation, and opaque attachment capabilities.\n\nThe record path, schema, credential transport, and handshake are not public client contracts. ACP, MCP, Coordinator, CLI, provider daemons, extensions, and integrations must use Router-issued attachments or Broker lifecycle services; they must not scan state roots, parse discovery files, retain endpoint credentials, or open raw per-session WebSockets. Broker and Router validate process identity, endpoint generation, incarnation, and file integrity before attachment, and fail closed on stale or uncertain state.\n\n### Internal broker launch isolation\n\nWhen the SDK starts its default internal broker or session host from the published TypeScript source, GJC uses a fixed Bun launch policy: `--no-env-file`, a product-owned empty `bunfig.toml`, absolute product entrypoint paths, and no inherited `BUN_OPTIONS` or mutable compiled-mode markers. The broker bootstraps from the product SDK directory rather than the caller project; a session host still runs with the lifecycle-authorized workspace as its process cwd.\n\nThis boundary prevents a child from newly loading caller-cwd or user-global Bun preload/dotenv policy. It cannot determine how a value already present in the parent environment was originally loaded, so ordinary provider/GJC environment values remain inherited. Default internal children, including compiled self-spawns, remove inherited `BUN_OPTIONS` so parent eval/test/inspect/debug/runtime options cannot be replayed into a detached child. Compiled binaries otherwise retain their existing self-spawn command contract, corroborated by a dedicated embedded marker and exact anchored Bun virtual-filesystem identity. The explicit `GJC_SDK_SESSION_COMMAND` session-host override remains a trusted legacy operator boundary and is not parsed as a shell-safe general command API. There is no broker-command override.\n\nBroker and per-session discovery tokens remain in their authoritative private discovery files for SDK-core resolution. Launch errors, logs, and diagnostics redact those tokens and never include the child environment or isolation configuration contents.\n\n## Internal protocol\n\nThe following frame shapes are SDK-core implementation details for maintainers.\nExternal integrations must not construct these frames, attach to session\ntransports, or receive endpoint credentials; use a Router-issued attachment, the\nbroker-bound CLI, or Coordinator MCP instead.\n\n### Server → client\n\n`action_needed` — something needs attention:\n\n```json\n{ \"type\": \"action_needed\", \"id\": \"act_9e31\", \"kind\": \"ask\",\n  \"sessionId\": \"sess-1\", \"workflowGateId\": \"wg_run_stage_1\",\n  \"question\": \"Proceed?\", \"options\": [\"Yes\", \"No\"], \"recommendedIndex\": 1 }\n```\n\n```json\n{ \"type\": \"action_needed\", \"id\": \"act_a42f\", \"kind\": \"ask\",\n  \"sessionId\": \"sess-1\", \"question\": \"Choose a target\", \"options\": [\"A\", \"B\"] }\n```\n\n```json\n{ \"type\": \"action_needed\", \"id\": \"idle-sess-1-7\", \"kind\": \"idle\",\n  \"sessionId\": \"sess-1\", \"summary\": \"finished refactor; awaiting next step\" }\n```\n\n- `id` is an opaque, transient presentation/action ID. It is the **only** authority accepted by generic `reply.id` through the current Router-issued attachment. It is not a durable workflow ID.\n- `workflowGateId?: string` is optional, additive SDK v3 correlation metadata, present only for the active presentation of a durable workflow gate. When present, it equals that gate's Q12 `gate_id`. Its public correlation key is `(sessionId, workflowGateId)` on the current Router-issued attachment; it never authorizes generic `reply`.\n- `kind: \"ask\"` is answerable in interactive/TUI and SDK workflow-gate sessions. `kind: \"idle\"` is notify-only and ephemeral (not replayed to attachments that start later). Ordinary asks and idle frames omit `workflowGateId`.\n- `recommendedIndex?: number` is optional, zero-based display metadata for `options`. Clients must validate that it is an in-range integer and ignore malformed values. Raw option labels and reply indices remain authoritative; never decorate submitted answers or infer a recommendation from position. The additive field is wire-compatible, but Rust consumers constructing the public `ActionNeeded` struct by literal must provide `recommended_index: None` when no recommendation exists.\n- This corrects the pre-v3 documentation invariant that `action_needed.id == gate_id`: they are deliberately different values. Clients must not preserve that invariant, infer a relationship from question/options/order, or retain private route, claim, receipt, epoch, token, or endpoint-generation maps.\n\n`action_resolved` — a pending action is now terminal and **non-repliable**:\n\n```json\n{ \"type\": \"action_resolved\", \"id\": \"act_9e31\", \"resolvedBy\": \"local\" }\n```\n\n`resolvedBy` is `local` (a local/direct control retired the presentation), `client` (a remote generic reply won), or `timeout`.\n\n`reply_rejected` — sent only to the client whose reply failed:\n\n```json\n{ \"type\": \"reply_rejected\", \"id\": \"act_9e31\", \"reason\": \"already_answered\" }\n```\n\nReasons: `already_answered`, `unknown_action`, `invalid_answer`,\n`resolver_unavailable`, `idempotency_conflict`, `unauthorized`.\n\n`bash_folded` — a foreground bash wait left the foreground and became a background job. Emitted once per fold into the replayable session event ring (so late-connecting clients receive it on `event_replay`), with `generic_safe` adapter disposition:\n\n```json\n{ \"type\": \"bash_folded\", \"sessionId\": \"sess-1\", \"jobId\": \"bg_3\", \"generation\": \"bg_3:1\", \"reason\": \"steer\" }\n```\n\n- `reason` is `steer` (a user steer arrived while the command had run past the 2 s grace window), `chord` (the `app.tool.backgroundFold` keybinding), `timer` (`bash.autoBackground`), or `sdk_control` (the `bash.background` control).\n- A replayed frame may describe a job that has since finished. `runtime.jobs.list` is the source of truth: each running/recent job carries `metadata.backgrounded` and, whenever it is `true` because of a fold, `metadata.foldReason` with the same values. The `bash.background` control (C52) returns `{ backgrounded: true, jobId }` on a fresh fold, `already_backgrounded` when no wait is foldable but a running job of this session was already folded (by steer, chord, timer, or a prior control call), `no_active_bash` when nothing is running or foldable, and `not_foldable` when a live wait refused the fold.\n- A `turn.steer` that folds a running bash behaves exactly like a TUI steer: the steer is consumed by the same turn at the tool boundary immediately after the fold result; `turn.steer_status` is unchanged.\n\nThe frames above are the internal transport contract implemented by SDK-core attachments. Managed adapters may receive optional server → client frames they can render or ignore: `identity_header` (one-time per-session repo/branch/machine header; Telegram topic-capable sessions additionally carry `telegramTopicsEnabled`), `context_update` (last message, task, goal, token usage, model, diff), `turn_stream` (live/finalized turn output), `image_attachment` (agent-produced images), `activity` (busy/idle, drives the typing indicator), `inbound_ack` (delivery state of an injected user message), `session_closed` (endpoint teardown; threaded adapters may delete/archive the remote conversation), `config_update` (current verbosity/redact), `hello` (server capability/version), and `pong`.\n\n### Internal inbound frames\n\nSDK core creates inbound frames only after Router attachment checks. External\nintegrations must not construct or persist them. Managed adapters use their\nopaque `SessionAttachment`, and process-isolated scripts use `gjc sdk session`;\nneither path receives transport credentials.\n\n## Model catalog query (Q10)\n\nThe SDK exposes the model catalog through the paged Q10 registry query. `Q10`,\n`models.list/current`, `models.list`, and `models.current` are exact aliases:\neach returns the same paged registry array, not a current-model singleton or a\nfiltered list. Continue using the returned cursor until `page.complete` is\ntrue.\n\nEach row preserves the five legacy fields (`provider`, `id`, `name`,\n`contextWindow`, and `maxTokens`) and additively includes `reasoning`,\n`thinking`, and `current`. `currentThinkingLevel` appears only on the current\nrow when the live session has a thinking level. The exported DTO types are\n`Q10Model`, `Q10ThinkingCapabilities`, `Q10ThinkingEffort`,\n`Q10SettableThinkingLevel`, `Q10CurrentThinkingLevel`, and\n`Q10ThinkingMode`, all from `@gajae-code/coding-agent/sdk`; there is no public\n`/sdk/models` subpath.\n\n```json\n{\n  \"provider\": \"runtime-provider\",\n  \"id\": \"reasoning-model\",\n  \"name\": \"Reasoning Model\",\n  \"contextWindow\": 128000,\n  \"maxTokens\": 8192,\n  \"reasoning\": true,\n  \"thinking\": {\n    \"validLevels\": [\"off\", \"minimal\", \"low\", \"medium\", \"high\"],\n    \"minLevel\": \"minimal\",\n    \"maxLevel\": \"high\",\n    \"mode\": \"effort\",\n    \"defaultLevel\": \"low\"\n  },\n  \"current\": true,\n  \"currentThinkingLevel\": \"high\"\n}\n```\n\n`thinking.validLevels` is always present and starts with `\"off\"`; it is the\ncanonical menu for `model.set` and never contains `\"inherit\"`. For a\nnon-reasoning model it is exactly `[\"off\"]`. Successful reasoning rows always\ninclude `minLevel`, `maxLevel`, and `mode`; only `defaultLevel` and raw `levels`\nare optional. Raw `levels` deliberately keeps its descriptor order and\nduplicates, while `validLevels` is the canonical, deduplicated menu clients\nshould render. `\"inherit\"` is a current-state readback value only and is rejected\nas a `model.set` input.\n\nMalformed reasoning descriptors are not client-recoverable catalog data. The\nquery returns the SDK's safe `internal` error rather than exposing a partially\nformed row or descriptor details.\n### Model profiles as synthetic models (`gajae-code/<profile>`)\n\nThe Q10 catalog also exposes model profiles as logical synthetic models under\nthe reserved provider namespace `gajae-code`, e.g. `gajae-code/codex-eco`.\nThese rows let clients (such as ACP model pickers) offer presets like ordinary\nmodels without provider-specific metadata:\n\n```json\n{\n  \"provider\": \"gajae-code\",\n  \"id\": \"codex-eco\",\n  \"name\": \"Codex Eco\",\n  \"contextWindow\": 222222,\n  \"maxTokens\": 8888,\n  \"reasoning\": false,\n  \"thinking\": { \"validLevels\": [\"off\"] },\n  \"current\": false\n}\n```\n\n- `gajae-code/<profile>` is a **logical namespace, not a callable provider**. No\n  API transport, credentials, or streaming route is registered for it; send the\n  value back through the generic `model.set` control (or the ACP `Model`\n  select) to activate the profile.\n- Synthetic rows are **availability-filtered**: only profiles whose required and\n  alternative providers have usable stored credentials are listed. The profile\n  id suffix is parsed losslessly after the first namespace slash, so profile ids\n  containing additional slashes or punctuation round-trip exactly.\n- `contextWindow`/`maxTokens` mirror the profile's resolvable default model when\n  available and otherwise fall back to the shared unknown-model constants\n  (222222 / 8888); the profile's real default model remains authoritative.\n- Synthetic rows are non-reasoning with `validLevels: [\"off\"]`: a `model.set`\n  on a synthetic id with any thinking level other than `off` is rejected with\n  `invalid_input`, and only an absent or `off` level is forwarded as a session\n  override.\n- **Current-state semantics:** while a profile is active for the session, exactly\n  the synthetic row carries `current: true` with `currentThinkingLevel:\n  \"inherit\"`, and the underlying concrete row is not marked current. A persisted\n  `modelProfile.default` alone (without an in-session active marker) never\n  creates a synthetic current row. Selecting a concrete `provider/model` clears\n  the active marker and restores concrete current semantics.\n- **Selecting a synthetic profile is session-scoped.** `model.set` with\n  `gajae-code/<profile>` activates the full profile in the live session without\n  writing `modelProfile.default`, `modelRoles`, or\n  `task.agentModelOverrides`. Persisting a profile remains an explicit TUI\n  choice (`/model` → default), mirroring `gjc --mpreset <profile> --default`.\n  Unknown or ambiguous synthetic ids fail with `invalid_input`; missing profile\n  credentials fail with the existing authentication-required error.\n- `gajae-code` is **reserved**: a user-defined `models.yml` provider of the same\n  name disables the synthetic facade (rows are omitted and synthetic selection\n  is rejected) rather than being silently shadowed. Q27 (`models.profiles.list`)\n  remains the full profile catalog with explicit `available` status; Q10 is the\n  availability-aware facade for client selection.\n`config.patch` mutations are serialized through the same session admission\nboundary as profile activation and default-model selection, so a patch racing\na synthetic `gajae-code/*` selection (or another patch) is applied in a\ndeterministic order and is never lost or clobbered by an activation rollback.\nThe cost is the same as `model.set`: an external `config.patch` queues behind\nany in-flight prompt admission rather than applying mid-turn.\n\n## Prompt acceptance, termination, and reconciliation (Q26)\n\n`runtime.capabilities.promptTerminalOutcomeVersion` is `1` when this contract is available. Its normalized TypeScript terminal outcome is:\n\n```ts\ntype SdkPromptTerminalOutcome =\n\t| {\n\t\t\tkind: \"stopped\";\n\t\t\treason: \"end_turn\" | \"max_tokens\" | \"max_turn_requests\" | \"refusal\" | \"cancelled\";\n\t\t\tprovenance: \"agent\" | \"client_cancel\";\n\t  }\n\t| {\n\t\t\tkind: \"failed\";\n\t\t\tcode: \"prompt_failed\" | \"prompt_deadline_exceeded\";\n\t\t\tmessage: string;\n\t\t\tprovenance: \"agent_failed\" | \"deadline\";\n\t  };\n```\n\n`turn.prompt` returns `{ accepted: true, commandId, turnId, clientRef? }` only after\nits asynchronous preflight accepts the prompt. That receipt is a durable,\n**non-terminal pending claim**, not a process-durable terminal result. The SDK\nlater finalizes that claim with exactly one `SdkPromptTerminalOutcome`; cleanup\nmay follow only after the claim is durable.\n\nThe authoritative public reconciliation query is `Q26` / `turn.result`, scoped\nto the same live session runtime. Callers supply `kind: \"prompt\"`; its `outcome`\nfield is exposed only after finalization. A pending claim is never represented\nor exposed as a terminal outcome. `turn.prompt_status` remains a legacy\nprompt-only alias that injects the same `kind`.\n\nEvery prompt and skill status response includes `receiptState`: active records are `absent`; terminal records are `present`, `missing`, or `unknown`; unknown lookup is `unknown`. Ordinary success requires `status: \"terminal_ok\"`, `receiptState: \"present\"`, and readable non-empty text or an artifact path. A failed execution may retain a partial `present` receipt. Legacy version-1 reconciliation records without this additive field remain readable and project `unknown` rather than optimistic success.\n\nCallers that must recover from a lost acknowledgement should assign one fresh\n`clientRef` (a trimmed, non-empty string of at most 128 characters) to each\nlogical prompt, then reconcile through the broker-bound CLI:\n\n```sh\ngjc sdk session raw query <sessionId> --query turn.result \\\n  --json-input '{\"kind\":\"prompt\",\"clientRef\":\"request-018f\"}'\n```\n\nThe alternate selector uses the same `kind` with\n`{\"kind\":\"prompt\",\"commandId\":\"command-id\",\"turnId\":\"turn-id\"}` as its JSON input.\n\nThe result status is `accepted`, `in_flight`, `terminal_ok`, `failed`, or\n`unknown`. Known records include `acceptedAt`; in-flight and terminal records add\n`startedAt` and/or `terminalAt`; finalized records include `outcome`; failed records\nalso include a bounded sanitized `error.code` and `error.message`. Cursors, partial\ngenerated-ID pairs, mixed selectors, and extra selector fields are rejected.\n\nCorrelated `agent_end` and `agent_failed` frames carry the same finalized\n`outcome`. Clients must correlate those frames and Q26 by the prompt identifiers,\nnot infer terminality from stream activity or an earlier pending claim.\n\nReconciliation state survives client disconnect/reconnect. With the session-private durable store (`.sdk-reconciliation/`), accepted and terminal prompt records also survive **GJC session-process restart** for the same session identity within capacity, subject to crash-consistent fsync. A non-terminal prompt record at restart finalizes its pending outcome and receipt state. A stopped prompt without receipt evidence becomes `terminal_ok + missing`; failed prompt or skill settlement without body evidence becomes `unknown`. Eviction or absence still returns honest `unknown`; that means the prior outcome is unknowable, not that execution did not occur. Active records are capped at 128 per kind and are never aged into terminal. Terminal records are capped at 256 per kind and evicted oldest-terminal first, with no age-based eviction. Reconciliation stores no prompt, transcript, credential, or provider-response body.\n\n`turn.prompt` remains ordered and non-idempotent. Its envelope `idempotencyKey`\ndoes not replay a response or produce `idempotency_conflict`. A retained duplicate\n`clientRef` fails before execution with `client_ref_conflict`, but callers must not\nreuse a `clientRef` as a retry mechanism: after eviction the same value can identify\na new prompt while the old outcome remains unknown.\n\n`turn.abort` returns a typed disposition. A caller that does not own the target\nreceives `resource_gone`; it must not treat that result as cancellation of another\nprompt.\n\n`sdk.promptDeadlineMs` defaults to `3_600_000`. It accepts only safe integers in\n`[60_000, 86_400_000]`; there is no disable value. The SDK snapshots the setting\nwhen the prompt is durably accepted as the initial inactivity lease. Fresh\n**attributable** progress for the exact accepted `commandId`/`turnId` — `tool_execution_start` /\n`tool_execution_update` / `tool_execution_end` observed at the prompt/agent runtime boundary — renews the deadline to\n`lastProgressAt + sdk.promptDeadlineMs`, bounded by the hard maximum `sdk.promptMaxRuntimeMs`\n(default `21_600_000`, same `60_000–86_400_000` range). Only tool-execution events for the\naccepted turn count — including a running tool's partial-result `tool_execution_update`, so a\nlong-running tool that streams output (e.g. a multi-minute compile) keeps renewing the lease mid-run;\nheartbeats, streaming text/thinking deltas, retries, other turns/sessions, and\nunrelated session noise do not renew the lease, and out-of-order delivery never shortens it. The\nhard maximum is never unbounded: every renewal is capped at `acceptedAt + sdk.promptMaxRuntimeMs` so a\nwedged or continuously noisy prompt still reaches a deterministic terminal outcome. Terminalization then has a fixed `10_000` ms\ngrace period, which is not configurable. A controlled terminal failure reaches ACP\nas JSON-RPC `-32603` with `data.code` of `prompt_failed` or\n`prompt_deadline_exceeded`.\n\n## Skill invoke reconciliation\n\n`skill.invoke` accepts optional `clientRef` and returns an early accepted receipt\n`{ accepted: true, commandId, turnId, clientRef?, name, path, lineCount?, args? }` after\ndurable/preflight accept (SDK control path), not after skill completion. Query prior\nstatus with `Q26` / `turn.result` and `kind: \"skill\"`. `skill.invoke_status`\nremains a legacy skill-only alias that injects the same `kind`. Kind-scoped indexes\nmean prompt and skill `clientRef` values never collide. Skill records use the same\ncapacity/retention limits, but an active skill record at restart settles with\n`error.code = process_restart`.\n\n## Correlated steer acknowledgement (Q30)\n\n`turn.steer` accepts an optional `clientRef` (trimmed, non-empty, at most 128 characters). When present, GJC hashes the exact validated steer text with SHA-256 and durably reserves `dispatching` before queueing. The result contains `sessionId`, `clientRef`, `status: accepted | rejected | uncertain`, known `acceptedAt` or `terminalAt`, and bounded error metadata; it never echoes text.\n\nReplay the same `clientRef` with the same text to recover the retained result without dispatching again. Reuse with different text returns `client_ref_conflict`. A live `dispatching` record and a restart during dispatch both project `uncertain`; GJC never automatically redispatches an ordered control whose first effect is unknowable. Query the same session with:\n\n```json\n{ \"type\": \"query_request\", \"query\": \"turn.steer_status\", \"input\": { \"clientRef\": \"steer-018f\" } }\n```\n\nQ31 returns `accepted`, `rejected`, `uncertain`, or `unknown` and never dispatches work. Settled steer records share the 256-record oldest-terminal-first capacity bound with no age-based eviction; live dispatching records are not terminal-evicted. Existing uncorrelated `turn.steer` calls retain their legacy non-idempotent behavior. Version-1 reconciliation remains additive, and only digest plus bounded metadata is stored—never steer text.\n\n## Model profile discovery and validation (Q27)\n\n`Q27` / `models.profiles.list` pages the effective model-profile catalog owned by\nthe attached session. Rows are sorted by exact ID and contain only:\n\n```json\n{ \"id\": \"codex-medium\", \"displayName\": \"codex-medium\", \"source\": \"builtin\" }\n```\n\n`source` is `builtin` or `configured`. Profiles from `<agentDir>/models.yml`\noverride built-ins with the same exact ID, including their display label. Profile\nIDs are not trimmed, case-folded, sanitized, or restricted to safe-token names;\ndiscover the exact ID and send it unchanged. The retired `codex-standard` alias is\nfallback-only and never shadows a configured profile with that exact ID.\n\nQ27 uses retained-revision, connection-bound pagination. Continue an issued cursor\nto finish its stable snapshot; a fresh cursorless query observes the current\nregistry. The query accepts no root, path, or selector input. An invalid or\nunreadable `models.yml` fails closed with `model_profile_registry_error` rather\nthan returning a plausible built-ins-only catalog.\n\nBroker `session.create`, `session.fork`, and `session.resume` validate `modelPreset`\nbefore spawning against the same `<broker.settings.agentDir>/models.yml` authority\nthat the child receives through `GJC_AGENT_DIR` / `GJC_CODING_AGENT_DIR`. Unknown\nIDs return `unknown_model_profile`. Both typed errors include bounded `details`\nwith `requestedProfile` where applicable, whole exact `availableProfiles` entries\nthat fit the detail budget, and `discoveryQuery: \"models.profiles.list\"`. The\ndiscovery pointer is authoritative when the bounded error cannot include every ID.\n\nThe same lifecycle operations accept an optional `modelId`: an explicit\n`provider/model` pin with `gjc --model` grammar (#4707). Coordinators resolve it\nagainst the full model registry (the CLI `--model` surface, not the\nauthenticated-only subset) before sending the create request, so unknown ids are\nrejected before any session exists. The broker guards only its shape; the child\napplies it exactly like a CLI `--model` selection, which also means an explicit\n`modelId` wins over `modelPreset` when both are supplied — the same precedence as\n`gjc --mpreset <profile> --model <model>`. The full effective order is:\n\n```\nmodelId pin  >  modelPreset  >  configured modelProfile.default  >  role/resume/default\n```\n\nThe pin is a guarantee, not a preference. The coordinator validates against its\nown registry and the child owns the registry that actually serves requests, so\nthe two can drift (a model removed, a provider disabled, an extension that\nfailed to register). On drift the child fails session construction before\nreadiness and before any profile application, disposes the partial session, and\nreports an error naming the pinned selector — it never publishes success on a\nsubstituted model. Coordinator validation refreshes the registry per request\n(offline, from the on-disk discovery cache) so ids added or removed after an\nearlier pin are judged against current contents.\n\n### Active provider query (Q29)\n\n`Q29` / `providers.list/active` pages the providers currently eligible for model\nselection through the same authenticated, retained-snapshot envelope as Q10. Each\nrow is the non-secret DTO `{ provider, connectionKind }`, where `connectionKind`\nis `credential` or `credentialless`.\n\nProvider IDs are returned exactly as they appear in Q10 `model.provider`: existing\nmixed-case, spaced, punctuated, and long custom IDs are preserved without aliases\nor normalization. Rows are deduplicated and ordered by UTF-8 provider bytes.\nJoin Q29 to Q10 by exact provider ID; Q10 remains the full configured catalog.\n\nA credentialed discovery-only provider appears only after fresh discovery proves\nthe exact model is usable. Static configured models can appear without a network\nprobe. The query never invokes a model, refreshes credentials, probes a remote\naccount, or exposes credentials, account metadata, paths, or provider responses.\n\nResolver failures are atomic and return\n`{ \"code\": \"internal\", \"message\": \"Unable to resolve active providers.\" }`.\nThey omit a page and restart metadata. An expired continuation follows the shared\ncursor contract and returns `error.code: \"cursor_expired\"` with\n`error.restartQuery: true`. Malformed cursor strings return `invalid_cursor`;\ncross-query or selector mismatches return `invalid_input`.\n\n## Answer semantics\n\nA remote reply answers a pending ask in every session state:\n\n- **Interactive / TUI mode:** the ask tool races the local selector against the\n  remote reply (first valid answer wins). A client submits generic `reply` using\n  the active presentation `id`; a local answer emits `action_resolved`\n  (`resolvedBy: \"local\"`) and that presentation becomes non-repliable.\n- **SDK workflow gate:** generic `reply` still uses the active presentation\n  `id`, never `workflowGateId`. The resolved gate drives the session the same\n  way a local answer would.\n\nA session has at most one active answerable presentation. Interactive asks and durable workflow gates are serialized; further Q12 gates wait in a durable queue. A same-server reconnect replays the active `action_needed` with the same presentation ID. After a process restart, previously pending or accepted-but-unadvanced records are quarantined diagnostics and a reconstructed workflow remints fresh durable gate and presentation IDs. Terminal, stale, and reissued action IDs never regain authority.\n\nGeneric and direct controls may race. Once the native generic claim is acquired, it wins; a direct control that atomically retires the exact unclaimed active presentation first wins instead. Losing direct controls fail without advancing the gate, and losing generic replies are stale/non-repliable. Clients must not retry by matching text, durable IDs, or presentation history; they must fail closed rather than guess when session or action identity is unsafe or ambiguous.\n\n### Durable workflow controls and Q12\n\n`workflow.gate_answer` and `workflow.plan_approve` operate on the durable Q12\n`gate_id`, not `action_needed.id`. Managed adapters bind `expectedSessionId`\nfrom their current Router-issued attachment. Process-isolated operators use the\nraw-control flow documented in the [SDK session CLI guide](./sdk-session-cli.md); they do not construct protocol frames.\n\n`expectedSessionId` omission remains accepted and audited for the entire SDK v3 line so deployed v3 control clients continue to work; new clients must send it now. It cannot become mandatory, or be removed from the controls, before SDK v4 and at least one full published deprecation release/window with deployed-client notice. A supplied session mismatch is rejected before the gate resolver runs. Neither control accepts a presentation ID, remaps an old ID to a reminted gate, or uses heuristic matching.\n\nQ12 (`workflow.gates.list`) exposes durable query records and additive SDK v3 diagnostics. A pending record preserves its workflow fields including `gate_id` and adds `id: \"pending:<gate_id>\"`, `tag: \"pending\"`, and `answer_recorded: false`. An accepted-answer diagnostic uses `id: \"diagnostic:<gate_id>\"`, `tag: \"accepted\"`, `answer_recorded: true`, and `resolved_at`, plus one `post_accept_disposition` value (`accepted`, `terminalized`, `advanced`, `continuation_lost`, or `unknown`) so an operator can distinguish a gate still waiting for continuation from one whose answer was durably advanced. A restart quarantine diagnostic uses `id: \"diagnostic:<gate_id>\"`, `tag: \"quarantined\"`, `answer_recorded`, and optional `lifecycle` containing `state: \"quarantined\"`, its restart reason, `quarantinedAt`, and an optional `supersededByGateId` after a remint. When available, every record also carries the originating `runtime_turn_id`; raw answers and derived answer values are never exposed. Diagnostics are query-only: they cannot be routed, answered, or promoted. Treat Q12 as the durable status surface, not as generic-reply authority.\n\n### Coordinator MCP question pull loop\n\nThe Coordinator MCP bridge is a separate, public-safe pull surface for external coordinators. `gjc_coordinator_list_questions` requires `session_id` and reconciles pending `workflow.gates.list` rows on every call, returning bounded public `questions`, `diagnostics`, and `reconciliation`. It accepts `status: \"pending\"`; `status: \"open\"` remains a compatibility alias. Multiple pending rows can be returned. A pending row carries its safe question shape, public option ids, and `answer_binding`, never raw/private gate payloads or values.\n\n`gjc_coordinator_submit_question_answer` requires `session_id`, `turn_id`, `question_id`, `answer_binding`, `answer`, `idempotency_key`, and `allow_mutation: true`. It re-lists/revalidates after restart and resolves through `workflow.gate_answer`, not generic `ask.answer`. An incomplete reconciliation returns `terminal_uncertain`; stale, terminal, missing, or ownership-mismatched rows cannot be answered. Re-list after restart rather than retaining old identifiers. An identical retry with the same idempotency key replays the accepted result; conflicting reuse returns `idempotency_conflict`.\n\nThis contract does not change #2549/#2551 or unattended plain-CLI behavior.\n\n### Rust and N-API compatibility\n\nThe Rust `ActionNeeded`, `ServerMessage`, and `register_ask` APIs remain\nlegacy-compatible and uncorrelated. Correlation is available through additive\nRust workflow-frame decoding/current-reader APIs and the workflow registration\npath; consumers that need correlation must opt in explicitly. N-API likewise\nretains `registerAsk`, and adds `registerWorkflowGateAsk` for a correlated wire\nframe plus `registerArbitratedAsk` and `retireIfUnclaimed` for in-process\npresentation arbitration. The arbitration lease and all claim/receipt/epoch\nstate remain private: these APIs do not create a public authority value.\n\n### Runtime and native addon release pairing\n\nThe `@gajae-code/coding-agent` runtime and `@gajae-code/natives` native addon ship from the same source release at exact matching package versions. The native loader requires the matching version sentinel; mixed native/runtime versions are unsupported and must not claim SDK compatibility.\n\n## Minimal provider adapter example\n\nProvider integrations compose SDK core's `SessionRouter`; they never read endpoint files or retain URL/token credentials:\n\n```js\nimport { router } from \"@gajae-code/coding-agent/sdk\";\n\nconst sessionRouter = new router.SessionRouter({\n  agentDir,\n  deps: {\n    onAttachment: (attachment) => provider.bind(attachment.sessionId, attachment),\n    onFrame: (attachment, frame) => provider.render(attachment.sessionId, frame.body),\n    onSessionRemoved: (attachment) => provider.unbind(attachment.sessionId),\n  },\n});\n\nawait sessionRouter.start();\nconst attachment = sessionRouter.attachment(sessionId);\nif (!attachment) throw new Error(\"session attachment unavailable\");\nawait attachment.send({ type: \"reply\", id: actionId, answer });\n```\n\n`SessionRouter` performs exact endpoint resolution, credential custody, replay, reconnect, rotation, and dispatch-time stale-lease rejection.\n\n### Exact fenced session close\n\nCapture the endpoint authority from the original Router binding and pass that\nsame pair to the lifecycle service. The generation and incarnation are one\nauthority: a partial target is rejected before it reaches the Broker.\n\n```ts\nconst authority = await sessionRouter.bindingAuthority(sessionId);\nif (!authority) throw new Error(\"session endpoint authority unavailable\");\n\nconst outcome = await lifecycleService.close({\n  actor,\n  capability: \"session.close\",\n  requestKey: \"close-captured-session\",\n  target: authority,\n});\n```\n\n`bindingAuthority()` returns `undefined` when the Router cannot prove the\ncurrent endpoint and its incarnation. Do not reconstruct the authority from\nendpoint credentials, process metadata, or a later session lookup; a\nreplacement may become current between capture and close.\n\n### Exact generation reconciliation\n\nManaged consumers that close or delete a session can reconcile one previously\npersisted attachment generation without retaining endpoint credentials:\n\n```ts\nconst proof = await sessionRouter.generationStatus(sessionId, endpointGeneration);\n\nswitch (proof.status) {\n  case \"current\":\n    // This exact generation is the current live indexed authority.\n    break;\n  case \"retired\":\n    // A retained host-unregister, close, or delete event positively retired it.\n    break;\n  case \"replaced\":\n    // A different live generation is current; use proof.currentGeneration.\n    break;\n  case \"unknown\":\n    // Do not infer retirement or retry a possibly-applied lifecycle mutation.\n    break;\n}\n```\n\n`generationStatus(sessionId, endpointGeneration)` is credential-free and may be\ncalled after `SessionLifecycleService` returns from `session.close` or\n`session.delete`, and after `SessionRouter.stop()`. Its evidence contains only\n`source: \"session_index\"`, a coherent `observedIndexSeq`, the successful\nstate's `evidenceIndexSeq`, and, for positive retirement, the safe terminal\nevent kind. It never exposes endpoint URL/token data, process IDs, locators,\nprivate Broker responses, or lifecycle cleanup payloads.\n\nThe result is an observation of one locked index reconciliation cut:\n\n- `current` requires the queried generation to be the current live, unambiguous\n  indexed authority.\n- `retired` requires a retained exact-generation `host_unregistered`,\n  `session_closed`, or `session_deleted` event. Missing attachment, missing\n  endpoint publication, Router shutdown, or a dead/unreachable host never imply\n  retirement.\n- `replaced` requires both prior observation of the queried generation and a\n  strictly greater current live generation. Same-generation reconnect remains\n  current; reuse, regression, or safe-integer wrap is classified as unknown\n  rather than manufacturing a successor relationship.\n- `unknown` is fail-closed. Reasons distinguish invalid input, unavailable or\n  incomplete index reconciliation, an unobserved session/generation, ambiguous\n  authority, and detected generation reuse. Consumers must preserve uncertain\n  lifecycle state rather than treating `unknown` as retired. Expired positive\n  evidence is reported specifically as `proof_expired`.\n\nProof survives Broker, Router, and consumer process restart because it is read\nfrom the durable session index, not Router attachment memory. Positive terminal\nproof has the session-index `maxAgeMs` lifetime (30 days by default), even when a\ndelete tombstone is retained longer for audit. Row-bound compaction may evict a\nwhole session sooner. After proof expiry, compaction eviction, or loss of a\ncomplete index, `generationStatus` returns `unknown`, never a synthetic\nretirement proof. This bounds the public proof surface independently of durable\nBroker audit retention.\n\n## Fallback chains\n\nModel-role selectors may be ordered fallback chains; see [Fallback chains](./models.md#fallback-chains) for configuration and retry-budget details. Resolution-time skips do not consume attempts. When a request-time retry advances to another eligible entry, the selected default fallback remains sticky for later prompts in that session until an explicit model selection or a chain reset changes it.\n\n`model_fallback_switched { eventId, from, to, reason, role, scope, activeIndex, chainLength, attemptsUsed }` is the canonical session lifecycle event for every real fallback-model switch. It replaces the legacy `retry_fallback_applied` / `retry_fallback_succeeded` event names. Embedding clients can subscribe to this in-process session event; managed adapters receive only the status projections their SDK-core integration supports.\n\n\n## Managed session-directory adapter guidance\n\nSDK adapters that need to inspect saved sessions must import only the supported public surface from `@gajae-code/coding-agent/sdk`:\n\n```ts\nimport {\n  SESSION_DIRECTORY_API_VERSION,\n  listManagedSessionCandidates,\n  resolveManagedSessionScope,\n} from \"@gajae-code/coding-agent/sdk\";\n\nif (SESSION_DIRECTORY_API_VERSION !== 1) throw new Error(\"Unsupported session-directory API\");\nconst resolved = await resolveManagedSessionScope({ cwd: process.cwd() });\nif (resolved.kind === \"resolved\") {\n  const listing = await listManagedSessionCandidates({ scope: resolved.scope });\n  // Consume only listing.kind === \"complete\" and its owned candidates.\n}\n```\n\nThis is a readonly resolver/listing contract. Do not import `@gajae-code/coding-agent/session/internal/*`, derive `v2-…` names, write bindings, or implement migration/cleanup in an adapter; private internal subpaths are intentionally unavailable from the packaged module. Treat `network_unsupported`, binding/security errors, incomplete listings, invalid candidates, and foreign candidates as non-authoritative results rather than retrying with a guessed path.\n\nThe resolver uses canonical native identity: supported POSIX and Windows local aliases can designate one scope, while UNC/network workspaces are unsupported. Scope digests are collision-resistant identifiers, not injective aliases, credentials, or authentication. The owner-only checks protect managed local storage paths but do not authenticate an adapter or make hostile concurrent filesystem races safe. Adapters that need mutations must use the higher-level lifecycle/session APIs rather than the readonly directory API.\n## Managed notification adapters\n\nGJC ships managed SDK adapters for Telegram, Discord, and Slack. `SessionRouter` resolves one session-owned endpoint per attachment and keeps every endpoint credential inside SDK core. Provider daemons receive only opaque attachment capabilities; they neither change the wire protocol nor expose a remote shell.\n\nThe recommended interactive path is `/settings` → **Notifications**. It owns\nsetup, health, test, recovery, reconnect, local enablement, and Telegram\nremoval without exposing stored credentials.\n`gjc notify setup` remains the authoritative CLI fallback for headless and\nautomated environments.\n\nNotification credentials and `notifications.*` settings are global-only.\nProject notification keys are\nignored and runtime notification overrides are rejected. Telegram pairing\nrevalidates the complete bot-token/chat identity immediately before polling and\nagain before activation. A foreign or unknown owner is never killed, reloaded, or taken over;\nsetup fails closed without saving or exposing the raw token.\n\nConfiguration completeness, provider-local quarantine, durable desired intent, effective enablement, runtime readiness, and delivery outcomes are separate contracts. The global `notifications.enabled` master never erases provider credentials or desired flags. `/settings` edits secrets through explicit `keep`, `replace`, or `remove` actions, commits only the selected provider in one CAS batch, and reports post-commit observer or activation failures without pretending the durable save rolled back. Malformed provider-local values are quarantined for explicit repair while safe sibling providers remain usable; malformed global notification structure remains fail-closed.\n\n`GJC_NOTIFICATIONS=0` suppresses only automatic generic current-session admission. Explicit `/notify on` can opt the current session back in without mutating durable provider state, and direct provider APIs remain governed by provider effectiveness and their own runtime readiness. Telegram, Discord, and Slack attachments are reconstructed through `SessionRouter`; no provider receives the shared endpoint token.\n\n- [Telegram notification onboarding](./telegram-onboarding.md) documents\n  `gjc notify setup` and private-chat pairing.\n- [Discord notification onboarding](./discord-onboarding.md) documents\n  `gjc notify setup discord`, required configuration, thread lifecycle, and\n  least-privilege permissions.\n- [Slack notification onboarding](./slack-onboarding.md) documents\n  `gjc notify setup slack`, Socket Mode configuration, immediate envelope ack,\n  and thread lifecycle.\n\n`gjc notify status` reports provider completeness, repair/quarantine state, desired intent, effective enablement, and masked tokens. Destination identifiers remain visible and may be sensitive. The Discord and Slack setup commands are non-interactive and require their documented identifier and token flags; supply secrets through an approved local mechanism, not examples, committed files, shell history, logs, or chat. `gjc notify health --provider <provider> --probe` performs a provider-owned REST diagnostic even when complete credentials are intentionally inactive, while `gjc notify test --provider <provider>` additionally requires effective enablement and runtime readiness.\n\nSession lifecycle and attachment routing are SDK-core services shared by every\nchat provider. `SessionLifecycleService` authorizes typed create, fork, resume,\nclose, delete, and list requests, derives the Broker idempotency identity, and\nprojects credential-free outcomes. The Broker remains the only lifecycle\nexecutor and durable terminal authority.\n\n`SessionRouter` consumes the Broker `SessionIndex`, resolves exact endpoint\nauthority, retains endpoint credentials and SDK clients, and owns replay,\nreconnect, rotation, and stale-attachment revocation. Telegram, Discord, and\nSlack receive only opaque current-generation attachments. Provider daemons own\ntransport leases, cursors, rate limits, threads/topics/messages, presentation\njournals, and delivery receipts; they cannot read endpoint files or tokens,\nallocate SessionIds, or perform session process lifecycle effects.\n\n\n## Managed Telegram daemon (bundled reference client)\n\nThe managed Telegram client is a provider supervisor and presentation adapter.\nIt owns the single `getUpdates` poller and Telegram topic state, while\n`SessionRouter` reconstructs SDK attachments from Broker state. A provider\nrestart never creates, resumes, closes, or mutates a GJC session by itself.\n\nFor Telegram forum topics, the daemon deletes the presentation topic through\n`deleteForumTopic` (falling back to `closeForumTopic` when deletion is unavailable)\nwhen `SessionRouter` retires the current attachment or when the daemon confirms\nthat no eligible local session still owns the topic. A resumed session creates or\nrebinds a fresh current-generation topic before sending again. Topic cleanup is\nbest-effort and cannot change the Broker lifecycle result.\n\n### Singleton poller and trust model\n\nTelegram `getUpdates` allows only one active long-poll owner per bot token. The\nmanaged daemon enforces **one bot token = one getUpdates poller** with a local\nlock/state file under the agent directory. New sessions attach to the existing\nfresh daemon owner instead of starting another poller, preventing Telegram 409\nconflicts.\n\nThe trust model is intentionally strict:\n\n- setup pairs exactly one private Telegram chat;\n- runtime accepts updates only from that paired chat id;\n- groups, supergroups, channels, and unpaired users never receive session names,\n  action ids, pending status, or configuration hints;\n- daemon state stores a token fingerprint, not the raw bot token.\n\n### Routing in private-chat topics\n\nThe paired private chat prefers Telegram topics for coordinator/lifecycle sessions\n(Threaded Mode). The daemon tags messages by session, stores compact callback\naliases for inline buttons, and routes replies back to the exact session/action.\nOrdinary sessions use flat delivery and do not create topics. A forum-enabled\nsupergroup is no longer required: when the bot owner enables Threaded Mode in\n@BotFather, the daemon creates topics only for admitted orchestration sessions.\nGJC cannot enable Threaded Mode through the Bot API; setup only verifies the\ncapability and guides the manual BotFather toggle.\n\nIf BotFather's per-bot **Bot Settings** menu does not show **Threads Settings**\nor **Threaded Mode**, the supported fallback is the normal private-chat pairing.\nSetup can be saved as `threaded=unverified`/`threaded=unknown`, and the daemon\nstill tries topics when Telegram allows them. When `createForumTopic` is refused,\nthe daemon does not drop the send: it routes the notification to the normal\n(flat) paired private chat and posts a one-time nudge: `Flat Telegram private chat\nsupports outbound notifications and inline ask buttons only. Enable Threaded Mode\nin @BotFather > Bot Settings > Threads Settings for free-text replies and session\ncommands.` Pairing is private-only, so flat delivery stays within the user's own\nprivate DM.\n\nSupported reply paths:\n\n- tap an inline button on an ask notification;\n- reply inside the session's thread/topic (replies are thread-native; the\n  topic identifies the session, so no session tag is needed).\n\nIn threaded mode the user can also adjust per-session behaviour with in-thread\nconfig commands: `/verbose` (per-tool-turn assistant text), `/lean` (settled\nassistant answer at idle plus immediate ask lead-ins; the default),\n`/verbosity <lean|verbose>`, and `/redact <on|off>`. The legacy\n`/answer <session-tag> <answer>` command is removed — replies are routed by the\ntopic they arrive in.\n\nFlat fallback keeps outbound notifications and inline-button answers working, but\nplain free-text never guesses from the global pending-ask set. Free-text replies\nand `/verbose`/`/lean`/`/verbosity`/`/redact` commands are thread-native and\nrequire Threaded Mode/topic routing. Enable Threaded Mode in @BotFather > Bot\nSettings > Threads Settings when you need free-text replies or session commands.\nDo not pair a group, supergroup, or channel to work around a missing BotFather\nmenu; the bundled setup flow is\nprivate-chat only, and non-private chat ids remain fail-closed to avoid session\ndata leaks.\nBecause the flat private chat has no per-session topic, flat idle markers carry\na short session tag (`🟢 Agent idle · <tag>`, last six characters of the session\nid) so concurrent sessions stay distinguishable. The tag never appears on asks\nor in threaded/topic delivery, where the topic itself identifies the session.\n\nUnknown, expired, or restart-unvalidated callback aliases fail closed: the daemon\nsends guidance and does not guess a target session or action.\n\n### Discord and Slack setup\n\nDiscord and Slack use the same internal notification events and reply protocol as\nTelegram. Store only runtime credentials in local GJC settings or environment;\nnever paste bot tokens, webhook URLs, transcripts, prompts, host paths, or raw logs\ninto docs, tests, issues, or PR comments.\n\nConfiguration keys:\n\n```yaml\nnotifications:\n  enabled: true\n  discord:\n    botToken: \"<local Discord bot token>\"\n    applicationId: \"<Discord application id>\"\n    guildId: \"<Discord guild id>\"\n    parentChannelId: \"<Discord parent channel id>\"\n  slack:\n    botToken: \"<local Slack bot token>\"\n    appToken: \"<local Slack app-level token>\"\n    workspaceId: \"<Slack workspace id>\"\n    channelId: \"<Slack channel id>\"\n    authorizedUserId: \"<Slack user id authorized for inbound replies and commands>\"\n  redact: true\n```\n\nThe bundled adapters intentionally render public-safe message bodies and return\nroute metadata only for pending internal actions. They do not own polling,\nsession scans, daemon locks, rate limits, or SDK lifecycle. Production transport\nsenders should consume the adapter payloads and keep all credential-bearing HTTP\nor gateway details outside logged payloads.\n### Redaction\n\n`notifications.redact` strips sensitive content before remote delivery, but\n**asks are exempt**: an ask is an interactive prompt the human must read and\nanswer remotely, so its `question` and `options` are always sent unredacted\n(otherwise it would be unanswerable). When redaction is enabled, `idle`\nsummaries are removed and streamed content frames (`turn_stream`,\n`context_update`, `image_attachment`) are suppressed at their emit sites. When\nredaction is disabled, all content is delivered unchanged.\n\n### Local `/notify`\n\nInside a GJC session, `/notify` controls the current session only:\n\n- `/notify status` reports enabled/disabled state, daemon observation when known,\n  and redaction state without printing secrets;\n- `/notify off` disables the current session's notification endpoint and removes\n  its discovery record without mutating global Settings;\n- `/notify on` re-enables the current session when global setup is complete and\n  `GJC_NOTIFICATIONS=0` is not forcing opt-out.\n\n## Session lifecycle and attachment surfaces\n\nSDK core exposes two related provider-neutral capabilities:\n\n1. **`SessionLifecycleService`** accepts an authenticated actor, an explicit\n   operation capability, a stable caller request key, and a typed target. It\n   derives one Broker idempotency key and invokes the canonical Broker lifecycle\n   operation. Results never expose endpoint URLs, tokens, process identities,\n   cleanup paths, or raw Broker receipts. Successful create, fork, and resume\n   results may include the credential-free `endpointGeneration` plus opaque\n   `endpointIncarnation`; pass both back for an exact close authority rather\n   than deriving a replacement identity from the numeric generation. A supplied\n   saved-session `sessionIdentity` is enforced as the transcript snapshot\n   precondition for resume and fork.\n2. **`SessionRouter`** owns live attachment discovery and transport. It validates\n   the exact indexed endpoint generation, keeps credentials and `SdkClient`\n   instances private, replays from the attachment cursor, reconnects after\n   rotation, and revokes stale capabilities. Provider-facing attachments expose\n   only `sessionId`, `generation`, `isCurrent()`, and `send()`.\n\n### Dispatch-boundary observers (managed router path)\n\n`SessionRouter.request(sessionId, frame, expectedGeneration?, expectedAttachment?, options)`\naccepts two optional synchronous observers in `options` — the supported\ndispatch-boundary surface for transport-close-aware consumers (#4640):\n\n- **`beforeDispatch(context)`** — fires immediately before the wire write.\n  Throwing (or any synchronous failure) aborts the dispatch with nothing on the\n  wire, no sent record, and a retryable rejection carrying the caller's own\n  error. Returning a thenable (e.g. an `async` function) is a contract\n  violation: the dispatch aborts pre-send and the eventual rejection is sunk.\n- **`onDispatch(context)`** — fires synchronously immediately after the frame is\n  handed to the socket, never before. `context.frame.id` is the exact correlated\n  identity a response must carry; from this point a transport close before the\n  response settles the request as `uncertain_after_send`. Observer throws and\n  returned-thenable rejections are sunk; they can neither displace settlement\n  nor reach the process unhandled-rejection channel.\n\nThe observer `context.frame` is a **deep-frozen, credential-redacted copy**: the\ninjected session endpoint `token` (and any other credential field) exists only\non the internal wire frame and is never handed to observer code, and mutation\nattempts throw in strict mode. The raw credential-bearing `SdkClient` remains\nunexported (`./sdk/client` is blocked in the package export map); the router is\nthe only supported path to this boundary.\n\nThere is no daemon-owned lifecycle control endpoint, provider lifecycle ledger,\nnotification-root scanner, or provider-created SessionId. Telegram `/session_*`\ncommands call the SDK lifecycle service directly. A Telegram update or topic\nreservation supplies the stable provider request identity; the Broker allocates\nthe SessionId, and Telegram CAS-binds the returned opaque ID to its presentation\nmapping.\n\n### Lifecycle trust and recovery\n\n- paired provider identity and operation capability are checked before the\n  Broker call;\n- retries reuse the same provider request key, so one request produces one\n  Broker ledger identity and at most one lifecycle effect;\n- `terminal_uncertain` remains uncertain and is reconciled from Broker ledger,\n  effect marker, process incarnation, endpoint/index, readiness, and exact\n  cleanup evidence only;\n- provider transport restart reloads cursor and presentation state, while the\n  Router reconstructs attachments from Broker state;\n- stale endpoint generations and attachments fail closed;\n- provider topic/thread/message cleanup cannot rewrite a confirmed lifecycle\n  outcome.\n\n### Phone test guide (create / close / resume from Telegram)\n\nEnd-to-end manual check once `gjc notify setup` has paired your private chat:\n\n1. Run `gjc notify setup` and start or reload the Telegram provider supervisor.\n   The supervisor owns only the Telegram poller and presentation state.\n2. Send `/session_create path <repo-dir>`, `/session_create worktree <repo>\n   <branch>`, or `/session_create dir <newdir>`. The SDK lifecycle service submits\n   one canonical Broker create request; the bot reports the credential-free\n   outcome.\n3. `/session_recent` lists verified recent managed sessions, marks whether each\n   session is connected or only saved, and includes a resume command for saved\n   sessions.\n4. `/session_close <sessionId>` asks Broker lifecycle to close the exact managed\n   session and preserves history. Inside that session's Telegram topic, omit the\n   ID and use `/session_close`.\n5. `/session_resume <sessionId|prefix>` resolves verified managed history,\n   reattaches a live session or performs canonical Broker resume, and refuses\n   ambiguous prefixes. Inside an existing session topic, including an inactive\n   topic left by a stopped session, omit the ID and use `/session_resume`.\n\nCommands are accepted only from the paired chat. Duplicate Telegram updates and\nreplayed topic reservations reuse their original request identity; they never\nallocate or spawn a second session.\n\n## Master mode surfaces\n\n`gjc --master [--scope repo|pwd|global]` launches an interactive-TUI-only\nmaster session (default scope `repo`). The master receives one bundled\noperating-guidance block appended after custom system-prompt transformation and\nexactly one scoped, no-probe broker peer snapshot immediately before its first\naccepted provider request; idle masters collect nothing.\n\nMaster orchestration is broker-routed and best effort: scoped discovery via\n`gjc sdk search` (result-level scope envelopes, exact worktree/cwd identity,\nno scope fallback) and task-seeded children via the local-only `gjc sdk spawn`\n(see docs/sdk-session-cli.md). The broker is the sole authority for\nmaster-created lifecycle: an opaque idempotency identity serializes each spawn\nbehind a durable create-or-join claim, seed delivery is Q26-correlated (never\nblindly re-sent), close mutates only an exactly re-proven substrate, and\norphaned children converge through ordinary close after\n`sdk.masterOrphanGraceMs`. Task text and master capability are transient\ndispatch inputs and never persist in any durable store, log, or output.\n",
+	"sdk-session-cli.md": "# SDK session CLI\n\n`gjc sdk session` is the broker-bound command family for operating live GJC SDK\nsessions from the terminal. It replaces the removed `gjc daemon session` route.\n\nThe command family has seven semantic verbs — `list`, `inspect`,\n`send`, `status`, `tail`, `close`, and `retire` — plus the explicit `raw` hatch that dispatches one\nSDK operation as `control`, `query`, or `global`.\n\nThe session CLI is advisory tooling over the SDK: every semantic verb resolves\nsessions through the SDK broker, and output is rendered through a versioned,\ncredential-free DTO. Endpoint credentials are never printed.\n\n## Command-local help\n\nDiscovery is static and inert for every public SDK and daemon parent, leaf and\nalias; it does not initialize a broker, settings, transport or evidence store.\nUse the deepest known command for its arguments, applicable options and risks:\n\n```sh\ngjc sdk session raw query --help --json\ngjc daemon reload --help --help-section options --help-page 1\n```\n\n`-h` is equivalent to `--help`. Sections traverse in this fixed order:\n`overview`, `usage`, `children`, `arguments`, `options`, `examples`, `recovery`.\nThe defaults are `overview` and page `1`; an empty section has a valid page 1.\nEach response includes only the selected node and, in `children`, its immediate\nchildren. Follow the returned `next.argv` unchanged, including\n`--help-revision <sha256>`, section, page and `--json` when selected. A changed\nrevision requires a new traversal; do not merge pages from different revisions.\n\nValued selectors accept separate or `=` operands. Pages are positive decimal\nsafe integers. Repeated/invalid selectors, selectors without actual help, and\nunknown descendants fail with usage exit 2 at the nearest known command.\n`--help=json` is unsupported. Option values and tokens after `--` do not activate\nhelp or JSON mode. Syntax containing `<placeholders>` is documentation, not a\nready-to-run recovery command.\n\nText and `gjc.command-help` version 1 JSON responses are each at most 8192 UTF-8\nbytes including the newline. Text escapes controls and labels display literals;\nnever paste escaped display text as shell argv. Complete entries have stable\nIDs. Oversized values use non-executable base64 fragments: concatenate contiguous\n`offsetBytes` ranges, verify `totalBytes` and `sha256`, then decode the complete\nUTF-8 JSON value. `sectionComplete` ends a section; only `documentComplete: true`\nwith `next: null` ends traversal. Help paging never reruns an operation.\n\n## Broker authority\n\n`list`, `inspect`, `send`, `status`, and `tail` resolve sessions through the\nSDK broker and Router. The Router validates indexed endpoint authority and keeps\nthe connection credential in SDK core; the CLI receives only credential-free\nresults. The broker is started on demand (`ensureBroker`) when discovery is\nabsent, and an unavailable broker fails closed with a typed operational error\n(exit 1).\n\n`--agent-dir` selects the broker state directory. It may appear at the session\nfamily level before the verb (`gjc sdk session --agent-dir <dir> list`) or on a\nleaf command. `--repo` selects the workspace directory for scoped listing or\nsaved-session resolution (default: the current directory). For compatibility,\n`inspect`, `send`, `status`, and `raw query` also accept `--repo`, but ignore it:\nthe exact session ID selects the broker target. Successful calls print a\npath-free warning to stderr. Failed `--json` calls keep stderr empty and return\ntheir structured error; command-local help identifies `--repo` as compatibility-only.\n\n## Semantic verbs\n\n### list\n\n`gjc sdk session list` queries the broker `session.list` global and projects\nevery indexed session into the versioned row DTO (`SESSION_ROWS_VERSION`). Each\nrow is credential-free and carries:\n\nThe list is fully paginated before scope filtering. By default its effective\nscope is `repo`. Select a scope with:\n\n```sh\ngjc sdk session list --scope repo|cwd|worktree|all [--repo <path>]\n```\n\n`--repo` is the selected workspace path and defaults to the process cwd. The\nresult reports the effective `scope` and a bounded credential-free `selection`\ndescriptor containing the canonical selected path and, for Git selections,\nthe canonical worktree root and Git common directory.\n\n- `repo` matches the canonical Git common directory, so the main checkout and\n  linked worktrees are included while another repository is excluded.\n- `worktree` matches only the selected path's canonical containing worktree.\n- `cwd` matches only the exact canonical selected workspace; nested directories\n  do not match.\n- `all` preserves the complete unfiltered Broker listing.\n\nFor a path outside Git, `repo` and `worktree` fail with the typed\n`not_a_repository` operational error and an actionable suggestion to use\n`cwd` or `all`; they never broaden the result. `cwd` remains available for an\nexact canonical path match. Unreadable or removed row workspaces are excluded\nfrom Git scopes deterministically and reported in `warnings`.\n\nThe raw global `session.list` route remains unfiltered, and `inspect`, `send`,\n`status`, `tail`, `close`, `retire`, and raw control/query behavior is unchanged.\n\nFor a process-isolated caller that needs bounded discovery, request exactly one\nBroker page instead of the semantic all-pages list:\n\n```sh\ngjc sdk session raw global --op session.list --page --limit 20 \\\n  --agent-dir <agent-dir>\ngjc sdk session raw global --op session.list --page --cursor <opaque-cursor> \\\n  --limit 20 --agent-dir <agent-dir>\n```\n\n`--page` preserves the Broker page envelope, including `indexSeq`, `warnings`,\nthe bounded `sessions` array, and the opaque `continuationCursor`. The cursor\nis a snapshot continuation: pass it back unchanged, with the same `--limit`,\nand never restart from the first page or locally slice an all-pages result. A\ncontinuation cursor cannot be combined with `cwd` or `resolveSessionId`; exact\nsaved-session resolution is a separate, single-page lookup.\nSemantic `gjc sdk session list` remains the fully paginated, scope-filtered\noperation.\n\n- `sessionId` and the `locator` (`cwd`, `worktreeRoot`, `stateRoot`), where `cwd`\n  is the canonical workspace directory and `worktreeRoot` is the canonical Git\n  worktree root or `null` outside a worktree;\n- `endpointGeneration`, `pid`, `live`, `deleted` (tombstone), `indexSeq`;\n- `hostIncarnation` and `identityProvenance` (`composite` | `legacy`);\n- `activity` (`{state: active|idle, at}`) and `lastHeartbeatAt`;\n- `terminalUncertain`, `lifecycleRequestId`, `endpointMtimeMs`;\n- `ambiguous` when the same `sessionId` has more than one unresolved\n  authority-fencing `stateRoot` (cross-repo duplicate). A proven non-endpoint\n  bookkeeping registration (the direct-session GC fence row, endpoint\n  generation 0) stays indexed without fencing endpoint attachment; every other\n  unresolved root, including an unproven generation-0 `lifecycle_terminal`\n  claim, still fences.\n\n### inspect\n\n`gjc sdk session inspect <sessionId>` renders one indexed row from the broker.\nIt never reads endpoint discovery records directly: a missing or unavailable\nbroker fails closed rather than exposing endpoint authority outside SDK core.\n\n### send\n\n`gjc sdk session send <sessionId> --text <prompt>` submits an ordered\n`turn.prompt` carrying a caller-chosen operation reference (a ULID by default,\nor `--op-ref`). The result envelope reports `accepted` with the receipt and the\noperation reference used for later reconciliation.\n\n- `--wait` polls `turn.result` with `kind: \"prompt\"` until the prompt reaches a\n  terminal state or the wait window (`--timeout-ms`, default 30s) elapses.\n  `send --wait` never cancels a running turn; a window that elapses before a\n  terminal state is reported as `wait_timeout` with the last observed status.\n\n- `--text` and the JSON input sources (`--json-input`,\n  `--json-input-file` — which must be a `0600` regular file —\n  `--json-input-stdin`) are mutually exclusive for the prompt body.\n- File input is read through one descriptor, rejects symlink/replacement races,\n  and is capped at 4 MiB before JSON parsing.\n\n### status\n\n`gjc sdk session status <sessionId> <opRef>` performs a lossless `turn.result`\nlookup with `kind: \"prompt\"` for a previously submitted operation reference and\nreturns the full reconciliation record plus a `summary.completed` flag.\nSee [lossless prompt results](#lossless-prompt-results).\n\n\n### tail\n\n`gjc sdk session tail <sessionId>` replays the retained transcript from the\ndurable checkpoint and then follows the live event-ring frames, emitting the\ndefault tail kinds (session lifecycle and turn lifecycle events) plus retained\ntranscript entries.\n\n- `--strict` fails closed with `retention_gap` (exit 1) when retained history\n  or the event ring dropped entries before the checkpoint.\n- `--until-idle` exits once the current turn reaches a terminal state; a session\n  close exits any tail as `terminal: true`, while a bare live tail otherwise\n  remains attached until `--timeout-ms`. Each item carries `revision` (the durable checkpoint revision); the triple `(revision,generation,seq)` is unique for the session, while `generation:seq` alone is revision-local and restarts each accepted prompt — key idempotency on the triple. Lifecycle\n  events that carry a `(generation, seq)` position are reconciled and emitted in\n  that canonical order rather than arrival order, so a retained terminal event\n  from an earlier turn does not complete a newer turn that is still running, and\n  a terminal event observed live is not undone by replayed history that arrives\n  after it. Positioned event items are emitted canonically ahead of an\n  arrival-ordered segment of events that carry no position; such an event stays\n  visible but cannot supersede a positioned turn state. Different lifecycle\n  kinds claiming the same `(generation, seq)` fail closed with `protocol_error`\n  (exit 1) because no order between them can be proven, and that conflict\n  outranks an otherwise successful idle or close completion. A canonical\n  position is a pair of non-negative safe integers. A replayed event-ring row that\n  states either coordinate property must state both validly; a row claiming only\n  one coordinate, or a null, negative, fractional, non-finite, or\n  unsafe-integer coordinate, fails closed with `protocol_error` rather than\n  being treated as unpositioned. Only a row that states neither coordinate is\n  unpositioned. Retained transcript entries are deduplicated independently of\n  event-ring rows and are not event-ring authority, so a transcript row that\n  projects the same kind and position as a real event never suppresses it. For a\n  specific prompt operation, `status <sessionId> <opRef>` remains the lossless\n  authority.\n- `--all-events` widens the emitted set to every event-ring kind.\n- `--cursor` resumes from a saved signed checkpoint claim. `session.checkpoint`\n  verifies the unexpired claim and exchanges it for a fresh connection-owned\n  cursor pinned to the exact prior revision; direct cross-connection cursor\n  consumption remains rejected, so reconnect never echoes or rewinds a cursor.\n- `--after-transcript-id` selects the caller's last observed transcript row;\n  live resumes require it alongside `--cursor`, while offline tails may use the\n  boundary directly. The boundary is recoverable: an unknown row leaves the\n  retained snapshot intact, while a boundary older than the retained window\n  fails closed with a retention gap.\n- `--timeout-ms` bounds live follow; a session whose lifecycle already ended\n  (terminal or `terminalUncertain`) replays retained history and exits instead\n  of hanging.\n\nA deleted session has no tail (`session_deleted`). A stopped session replays\nits retained transcript without an endpoint (offline source), bounded to the\nmost recent retained entries.\n\n### close\n\n`gjc sdk session close <sessionId>` is the official semantic wrapper for the\n`session.close` broker global. It ends one live session: the broker validates\nindexed authority, asks the host to shut down gracefully, escalates to SIGTERM\nagainst the durably identified session process when graceful teardown exceeds\nthe bounded deadline, and appends terminal `session_closed` evidence. A session\nwhose ownership is `terminalUncertain` is refused rather than signalled — that\nis what `retire` is for.\n\n```sh\ngjc sdk session close <sessionId> [--agent-dir <agent-dir>] [--idempotency-key <key>]\n```\n\nClosing never attaches to the session. A Router attachment registers the\ncalling process as a live client and renews the host's abandonment window,\nwhich is the opposite of the intent, so the lifecycle mutation is answered by\nthe broker over its own client.\n\n`--idempotency-key` is optional here, unlike the raw `session.close` global. The\ndefault request key is derived from the session id and the current endpoint\ngeneration/incarnation. A retry against the same live host replays the same\nlifecycle request; a host resumed under the same session id receives a fresh\nrequest identity and is closed by a new lifecycle operation. Pass\n`--idempotency-key` explicitly to supply a caller-chosen attempt key.\n\n### retire\n\n`gjc sdk session retire <sessionId>` is the official semantic wrapper for the\n`session.reconcile_uncertain` broker global. It retires an indexed\n`terminalUncertain` create effect only when exactly one matching uncertain\ncreate identity exists, the recorded host is proven exited, the endpoint is\nabsent, and any lifecycle marker/readiness leftovers are regular files bound to\nthat same PID and incarnation. The broker removes only those verified\nleftovers, appends terminal `session_closed` evidence, and converts the\nmatching lifecycle receipt to a terminal error. Ambiguous identity, live or\nunverifiable hosts, endpoint presence, malformed leftovers, and mismatches\nrefuse without signalling a process. Supply `--idempotency-key`; the JSON\ninput is read from a `0600` file or stdin when it contains proof material.\n\n## Raw hatch\n\n`gjc sdk session raw <control|query|global>` dispatches exactly one SDK\noperation and returns the broker/host response:\n\n- `raw control <sessionId> --op <operation>` — one control operation with\n  `--json-input*`; `--confirm` confirms destructive control operations.\n- `raw query <sessionId> --query <operation>` — one query; `--cursor` passes a\n  continuation cursor.\n- `raw global --op <operation>` — one broker global. Lifecycle globals\n  (`session.create`, `session.fork`, `session.resume`, `session.close`,\n  `session.delete`, `session.reconcile_uncertain`, `session.lookup`) require\n  `--idempotency-key`.\n\n`session.lookup` is a read-only reconciliation of a previously submitted\n`session.create`. Reuse the caller request key and the same create target that\nwere retained before dispatch; GJC derives the Broker identity and fingerprint\ninside the lifecycle boundary. It never calls `session.create` and never\nreplays session work:\n\n```sh\ngjc sdk session raw global --op session.lookup \\\n  --idempotency-key <create-request-key> \\\n  --json-input '{\"cwd\":\"/absolute/path/to/repo\"}' \\\n  --agent-dir <agent-dir>\n```\n\nThe credential-free result identifies the original operation and request key.\n`status: \"found\"` carries the canonical session result; `pending`,\n`not_found`, `conflict`, `uncertain`, and `terminal` are distinct structured\noutcomes and retain `certainty` and the recovery identity. A missing record is\nnot proof that the create did not execute, so callers must not resubmit solely\nbecause lookup reports `not_found`. Reconciliation failures exit nonzero while\npreserving the structured outcome in JSON.\n\nA separately connected local controller can stop the active turn and its exact\nowned work with an explicitly confirmed operator abort:\n\n```sh\ngjc sdk session raw control <sessionId> \\\n  --op turn.abort \\\n  --json-input '{\"mode\":\"terminal\",\"scope\":\"owned\",\"operator\":true}' \\\n  --idempotency-key '<unique-key>' \\\n  --confirm\n```\n\nThe JSON input accepts only operation fields (`mode`, `scope`, `operator`).\n`--confirm` and `--idempotency-key` are CLI authority inputs, not JSON fields.\nThe exact `operator:true` shape is routed through the local Broker, which\nrevalidates the current endpoint identity and injects a process-bound private\ncapability before dispatch. MCP, ACP, notifications, and ordinary SDK endpoint\nrequests cannot mint operator authority: copying `operator:true` and\n`confirm:true` into a public control frame is rejected. Omitting confirmation,\nomitting the key, or supplying `operator:false` fails closed without invoking\nthe terminal-abort surface. Non-operator terminal abort retains its existing\nconnection-ownership semantics.\n\n`session.get_endpoint` is refused unconditionally: endpoint credentials remain\nan SDK-core implementation detail. The raw hatch validates operation names and\nadapter dispositions up front and never renders endpoint-disclosure results.\n\n## Lossless prompt results\n\n`turn.result` with `kind: \"prompt\"` reports `accepted`, `in_flight`,\n`terminal_ok`, or `failed`; only retained-record capacity eviction yields\n`unknown`. `turn.prompt_status` remains a legacy prompt-only alias. A prompt\nthat is active at process restart is finalized from its durable pending outcome\n(or `prompt_failed` when it has none), so it never reports as `unknown` while a\nrecord exists.\n\n`unknown` means uncertainty, never proof of non-execution: do not reuse an\noperation reference as a retry mechanism (`client_ref_conflict` while the\nrecord is retained; after eviction a reused ref may be admitted again with the\nprior outcome unknown). Use one fresh operation reference per logical prompt\nand reconcile with `status`.\n\n## Checkpoint gaps\n\n`tail` reports a `retention_gap` when retained history or the event ring\ndropped entries before the durable checkpoint: the gap carries the missing\nsequence range (`missing.from`/`missing.to`) and a `resync` checkpoint.\n`--strict` turns any gap into `retention_gap` with exit 1; without `--strict`,\ntail continues from the resync position and reports the gap in the envelope.\n\n\n## Migration from the removed daemon session route\n\n`gjc daemon session` is removed and no alias is provided. Migrate:\n\n| Removed route | Replacement |\n| --- | --- |\n| `gjc daemon session list` | `gjc sdk session list` |\n| `gjc daemon session inspect <sessionId>` | `gjc sdk session inspect <sessionId>` |\n| `gjc daemon session send <sessionId> --text <prompt>` | `gjc sdk session send <sessionId> --text <prompt>` |\n| `gjc daemon session tail <sessionId>` | `gjc sdk session tail <sessionId>` |\n| raw control/query dispatch | `gjc sdk session raw control|query|global` |\n\nThe broker-bound surface replaces the daemon-owned routing: sessions are\nresolved through the SDK broker with validated endpoint identity instead of\ndirect discovery-file reads, and output is versioned and credential-free.\n\n## Exit codes and error envelope\n\nSession verbs exit `0` and keep their existing successful JSON stdout contract,\nincluding when `--json` is absent. **Machine callers must explicitly add\n`--json` for machine-readable failures.** Ordinary failures otherwise write\nbounded text to stderr only. With `--json`, failure writes exactly one\n`gjc.command-error` version 1 envelope and newline to stdout, with empty stderr.\nBoth modes are limited to 8192 UTF-8 bytes including formatting and newline.\nUsage errors exit `2`; operation failures (including unavailable broker/session,\nretention gaps and `send --wait` timeouts) exit `1`. A live `session tail` wait\nwindow is a bounded observation rather than an operational failure: it exits `0`\nwith `terminal: false` and all items observed before the deadline.\n\nThe envelope preserves `command`, `error.code`, `category`, `retryability`,\n`outcomeCertainty`, allowlisted `references` and evidence-based `nextSteps`, plus\n`omittedOptional`, `complete`, `evidence` and `continuation`. Safe fields are\nexplicitly projected; arbitrary exception messages, request bodies, credentials\nand stacks are not public error evidence. Do not infer non-execution from a\nnonzero exit or timeout: `wait_timeout` after acceptance means applied work,\nwhereas `uncertain_after_send` means the outcome is unknown. Preserve session,\noperation, idempotency, claim, command and turn references when supplied.\n\nError guidance performs no additional probes, status calls, retries, restarts or\nkills. Execute an appropriate explicit observation only when the task warrants\nit; reconcile before considering replay. `retire` is a proof-bound mutation,\nnot a generic status check, and requires confirmed intent and actual applicable\nproof. Daemon `stop`/`restart` interrupt work; `--force` permits SIGKILL escalation.\nDaemon kinds are `telegram`, `discord`, `slack` (default `telegram`); `daemon`\ndefaults to `status`, and `reload` aliases `restart`. There is no\n`gjc daemon restart sdk` recovery command. Never repeat successful mutations\nwhen a multi-target daemon result contains failures.\n\n### Retained error evidence\n\nWhen essential sanitized reconciliation references do not fit inline, the CLI\nmay retain them locally, but advertises `evidence.status: \"retained\"` and a\ncontinuation only after successful publication and read-back verification.\nRetrieval is an explicit family-root operation, not an operation retry:\n\n```text\ngjc sdk --error-ref <32-lowercase-hex-id> --error-sha256 <64-lowercase-hex> [--error-page <N>] [--error-agent-dir <dir>] [--json]\ngjc daemon --error-ref <32-lowercase-hex-id> --error-sha256 <64-lowercase-hex> [--error-page <N>] [--error-agent-dir <dir>] [--json]\n```\n\nUse the actual returned argv rather than constructing a locator. Ref and digest\nare required together; page defaults to 1 and is a positive decimal safe integer.\nSelectors support separate/equals forms; duplicates are invalid. Retrieval is\nexclusive with help, operation positionals and operation flags. Scope/page\nselectors require retrieval. `--error-agent-dir` is distinct from SDK operation\n`--agent-dir`; daemon worker `--agent-dir` is private. Retrieval uses only the\nexplicit/default root and checks the stored family, never scans other roots.\n\nThe store is `<effective-agent-dir>/cli-error-evidence-v1`. Records expire exactly\n24 hours after creation, without sliding reads. Expiry refuses retrieval; lazy\ncleanup is not a promise of immediate secure erasure. Limits are 64 committed\nrecords, 1 MiB per record and 16 MiB committed aggregate, plus at most one 1 MiB\npending file and one 4096-byte lock: at most 66 files and 17 MiB + 4096 bytes of\nlogical payload (filesystem allocation overhead is separate). Unexpired records\nare not evicted to make space. POSIX owner-only permissions are verified; an\nunsupported secure permission mechanism fails closed. No success/help output\ninitializes the store and there is no background cleanup service.\n\nSuccessful retrieval is `gjc.command-error-evidence` version 1 on stdout, exit 0,\nwith each text/JSON page bounded to 8192 bytes. It means retrieval succeeded, not\nthat the original operation did. Follow the pinned digest/scope/mode continuation;\nreassemble contiguous base64 bytes and verify total length and SHA256 before\nUTF-8/JSON decoding or using references. Pages contain immutable retained evidence,\nnot resampled runtime state.\n\nDisk, permissions, quota, lock contention or verification failure may prevent\nretention. The original failure remains nonzero with its original outcome\ncertainty and retryability: `complete: false`, `evidence.status: \"unavailable\"`,\nand `continuation: null`, with the explicit warning that necessary evidence\ncould not be retained and **do not blindly retry the original operation**.\nMissing essential evidence is not described as optional, and no invented path,\nID, digest or fallback store is advertised. Lossless retrieval is guaranteed only\nfor successfully published records within their retention lifetime; expiry,\ndeletion or corruption can make later retrieval unavailable.\n\nThese bounds do not paginate successful session/search/spawn/guides results.\nSearch outside Git retains its successful exit-0 result; observing an unhealthy\ndaemon is still a successful status operation. Serve preflight errors use the\nordinary failure contract; after relay ownership, protocol framing and termination\nremain unchanged, without CLI error envelopes injected into the stream.\n\n## Scoped search (`gjc sdk search`)\n\n`gjc sdk search [--scope repo|pwd|global] [--limit N] [--cursor <token>] [--json]`\nlists broker-visible sessions inside one exact scope. The default scope is\n`repo`: the identical canonical Git worktree of the invoking directory, never a\npath prefix or subtree. `pwd` matches the exact canonical working directory and\n`global` covers every broker-visible row.\n\nEvery result — table and JSON, populated and empty — carries a scope/status\nenvelope: the requested scope, the canonical resolved scope, a status\n(`populated`, `empty`, `not-in-git-worktree`, `unavailable`), and the\nobservation time. Running `--scope repo` outside a Git worktree is a successful\nempty result (`not-in-git-worktree`, exit 0) and never falls back to `pwd` or\n`global`. Broker unavailability keeps the locally resolved scope, exits\nnon-zero, and stays credential-free. Continuation cursors are frozen: a\ncontinuation that supplies a different scope or anchor fails with\n`scope_cursor_mismatch` instead of re-scoping.\n\nRows are probed only after scope filtering, through broker/router-owned\ncredential-free attachments, yielding `reachable`, `unreachable`, or `stale`.\n\n## Local-only spawn (`gjc sdk spawn`)\n\n`gjc sdk spawn --cwd <dir> --prompt <task> [--model <selector>] [--profile <name>] [--json]`\ncreates one task-seeded background child session through the broker. It is\nlegal only inside a live interactive `gjc --master` session: the command needs\nthe master's transient capability (threaded through the master session\nenvironment) and the broker verifies it against the live effective master host\nbefore any effect. Spawn is prohibited on MCP, ACP, daemon CLI/raw session CLI,\nTelegram, Discord, and Slack surfaces.\n\nEach invocation uses a fresh idempotency identity. One identity produces at\nmost one child substrate and one seed prompt; repeated requests replay the\nstored outcome. A semantically new task requires a new invocation, never a\nretry of an old identity. `spawn_in_progress` and `terminal_uncertain` are\nhonest durable states: inspect with `gjc sdk search` or session status instead\nof retrying blindly.\n\nThe task text and master capability never persist anywhere in broker state —\nno plaintext, hash, or derived verifier appears in the lifecycle ledger, spawn\nauthority journal, receipts, logs, or output. Spawn output renders only safe\nfields: result code, claim id, child session id, substrate kind, and opaque\nseed facts.\n\nClose spawned children through the standard `session.close` path; the broker\ncloses only an exactly re-proven substrate and retains uncertainty on identity\nmismatch. Children orphaned by confirmed master loss are reaped after\n`sdk.masterOrphanGraceMs` (default 120000 ms, bounded 60000..3600000), with the\norphan clock preserved across broker restarts.\n",
+	"sdk.md": "# Gajae-Code SDK\n\nFor embedding GJC in-process, see [the embedding SDK guide](./sdk-embedding.md).\nFor a beginner-friendly application development guide (recipes, customization, and surface selection), see [Building applications on the SDK](./sdk-app-guide.md).\n\n<p align=\"center\">\n  <img src=\"../assets/telegram-mobile-hero.png\" alt=\"Gajae Code mobile answers for coding agents hero illustration\" width=\"100%\" />\n</p>\n\nThe SDK exposes a generic action/reply protocol without requiring integrations to scrape the terminal. SDK core owns all managed attachment discovery and credential-bearing clients through `SessionRouter`; Telegram, Discord, Slack, ACP, MCP, and CLI adapters receive only capability-scoped operations and never endpoint credentials.\n\n> Status: the Rust core (`crates/gjc-sdk`) provides the session-local wire protocol and endpoint record. TypeScript SDK core provides Broker lifecycle authority and `SessionRouter` attachment authority. Endpoint records and tokens are internal implementation details, not an external attachment surface.\n\n## External attachment policy\n\nExternal and managed integrations attach through SDK-core surfaces only:\n\n- lifecycle mutations use `SessionLifecycleService` and the Broker lifecycle ledger;\n- read-only uncertain-create reconciliation uses the public `session.lookup` lifecycle operation with the original request key and target;\n- live session controls use opaque `SessionAttachment` capabilities issued by `SessionRouter`;\n- endpoint URL/token discovery, raw WebSocket relays, and `gjc sdk serve` are not public attachment mechanisms;\n- lifecycle-equivalent per-session controls are prohibited on Telegram, Discord, Slack, ACP, MCP, and daemon CLI adapters.\n\nFor terminal-side session operation, use the broker-bound [SDK session CLI](./sdk-session-cli.md):\n`gjc sdk session list|inspect|send|status|tail|close|retire` plus the explicit `raw`\n`control|query|global` hatch. The CLI resolves the exact attachment through SDK\ncore and emits credential-free JSON on success. Add `--json` explicitly for\nmachine failures; default ordinary failures are text on stderr, not JSON stdout.\n\n### Public CLI discovery and recovery\n\nUse `gjc sdk --help` or deepest local help such as\n`gjc sdk session raw query --help --json` and `gjc daemon reload --help`.\nHelp covers only public paths and immediate children, never worker-only actions\nor flags. `--help-section overview|usage|children|arguments|options|examples|recovery`\nand `--help-page <N>` select bounded static pages; follow `next.argv` with its\n`--help-revision <sha256>` and mode intact. `-h` is accepted, `--help=json` is not.\nSelectors require actual help, valid positive decimal pages and no duplicates.\nHelp is inert and never initializes runtime services or storage.\n\nOrdinary errors use `gjc.command-error` version 1: with `--json`, one stdout\nJSON envelope and empty stderr; otherwise stderr text. Help, errors and explicit\nerror-evidence pages are bounded to 8192 UTF-8 bytes including newline. Existing\nsuccessful result shapes and serve frames after relay ownership are unchanged.\nDo not treat a timeout as proof that work was not applied; preserve returned\nreferences and reconcile rather than blindly replaying a mutation.\n\nOversized essential sanitized error evidence may be retained for exactly 24\nhours in `<effective-agent-dir>/cli-error-evidence-v1`: 64 committed records,\n1 MiB each, 16 MiB committed aggregate, with one additional pending file up to\n1 MiB and a lock up to 4096 bytes. Follow a verified continuation using\n`gjc sdk` or `gjc daemon` with `--error-ref <id> --error-sha256 <digest>`, optional\n`--error-page <N> --error-agent-dir <dir>`, and `--json` for machine output.\nRetrieval is root-only, exclusive with help/operations, and never searches other\nroots or replays the original operation. Reconstruct contiguous base64 fragments\nand verify length/digest before decoding; fragments are not executable commands.\nPublication failure reports incomplete/unavailable evidence and no continuation,\nnot fabricated recovery. Availability is conditional on successful publication\nand the retention lifetime, not a promise to overcome disk failure or deletion.\n\nRecovery hints perform no extra probes or automatic recovery. Daemon targets are\n`telegram`, `discord`, `slack`, not the SDK broker: never suggest\n`gjc daemon restart sdk`. `reload` aliases `restart`; stop/restart interrupt work\nand `--force` permits hard-kill escalation. Session retirement requires actual\nproof and confirmed intent, not merely an uncertain result. See the\n[full help, error and evidence contract](./sdk-session-cli.md#command-local-help).\n\n## Migration from removed external transports\n\nThe retired `--mode rpc`, `rpc-ui` and `bridge` transports have no replacement\nwire client. The existing `gjc sdk serve` relay remains discoverable CLI tooling,\nnot an external SDK attachment API. Process-isolated controllers use Coordinator\nMCP, `gjc sdk session`, or a configured managed adapter. In-process applications\nuse the [embedding SDK](./sdk-embedding.md).\n\n## External-agent SDK skills\n\nThe generated `sdk-skills/` bundle provides host-neutral guidance for scripts\nthat invoke the broker-bound session CLI. It is intentionally separate from\nGJC's four internal workflow skills, the coordinator MCP plugin, and the SDK MCP\nadapter. Its TypeScript and Python templates do not discover endpoints or create\ntransport clients.\n\nThe bundle owns exactly six files:\n\n- `manifest.json`\n- `gjc-sdk-discover/SKILL.md`\n- `gjc-sdk-operate/SKILL.md`\n- `gjc-sdk-author/SKILL.md`\n- `gjc-sdk-author/templates/direct-sdk.ts`\n- `gjc-sdk-author/templates/direct-sdk.py`\n\nRegenerate with `bun run generate-sdk-skills`; CI checks byte-for-byte content\nand rejects unexpected files with `bun run check:sdk-skills`.\n\n### Bundle format version\n\n`manifest.json` is the versioned root of the on-disk bundle contract. It\nidentifies `formatVersion` (currently `1`) and the exact relative file closure\nthat regeneration owns. Consumers must treat a bundle whose manifest is missing,\nmalformed, or declares an unsupported version as unreadable and fail closed. The\nskill prompts are authored as static Markdown sources under\n`scripts/gjc-sdk-skills/prompts/`; the generator copies them verbatim and\n`check:sdk-skills` proves the committed bundle matches the generated artifacts.\n\n### Trust boundary\n\nThe templates invoke only the broker-bound CLI. `SessionRouter` keeps endpoint\nresolution, credentials, SDK clients, replay, reconnect, and rotation inside SDK\ncore. The templates' fixed allowlists and nonce-bound approval are trusted-local\nprocedural safeguards, not capability isolation; lifecycle and attachment\nauthority remain enforced by Broker and Router.\n\nNo renderer-grade cross-process event stream is exposed to external scripts.\nUse managed adapters or Coordinator MCP for event-driven orchestration; see the\n[RPC-to-SDK v3 parity audit](./sdk-rpc-parity-audit.md) for remaining gaps.\n\n## Architecture\n\n```\nBroker lifecycle → Session runtime endpoint → SessionRouter → opaque adapter capability\n```\n\nThe Broker is the sole lifecycle executor and durable terminal authority. `SessionRouter` is the sole credential-bearing external attachment manager. Provider supervisors own only provider transport and presentation state.\n\n- **One endpoint per top-level session.** Each top-level session runs its own loopback WebSocket server. Subagents do not host endpoints. The Broker index is the authoritative live-session catalog, and `SessionRouter` multiplexes managed provider attachments across indexed sessions.\n- **Hosted by default.** SDK hosting is independent of notification configuration. Set `GJC_SDK_DISABLE=1` to opt out of hosting for a top-level session.\n- **Notification delivery is optional.** Configure and enable a managed notification adapter only when remote delivery is needed; the SDK endpoint remains available without one.\n- **Managed integrations use opaque attachments.** Telegram, Discord, Slack, ACP, MCP, and CLI adapters compose SDK-core services; they do not discover endpoint files or receive URL/token credentials.\n- **Zero wire-protocol change.** New transports do not require changes to `crates/gjc-sdk` or the JSON protocol.\n- **tmux-agnostic.** The endpoint behaves identically with or without tmux.\n\n## Internal endpoint publication\n\nA running session publishes an implementation-private credential record for Broker resolution. `SessionRouter` is the sole consumer of the resolved URL/token pair and the sole owner of per-session SDK clients, replay, reconnect, rotation, prepared activation, and opaque attachment capabilities.\n\nThe record path, schema, credential transport, and handshake are not public client contracts. ACP, MCP, Coordinator, CLI, provider daemons, extensions, and integrations must use Router-issued attachments or Broker lifecycle services; they must not scan state roots, parse discovery files, retain endpoint credentials, or open raw per-session WebSockets. Broker and Router validate process identity, endpoint generation, incarnation, and file integrity before attachment, and fail closed on stale or uncertain state.\n\n### Internal broker launch isolation\n\nWhen the SDK starts its default internal broker or session host from the published TypeScript source, GJC uses a fixed Bun launch policy: `--no-env-file`, a product-owned empty `bunfig.toml`, absolute product entrypoint paths, and no inherited `BUN_OPTIONS` or mutable compiled-mode markers. The broker bootstraps from the product SDK directory rather than the caller project; a session host still runs with the lifecycle-authorized workspace as its process cwd.\n\nThis boundary prevents a child from newly loading caller-cwd or user-global Bun preload/dotenv policy. It cannot determine how a value already present in the parent environment was originally loaded, so ordinary provider/GJC environment values remain inherited. Default internal children, including compiled self-spawns, remove inherited `BUN_OPTIONS` so parent eval/test/inspect/debug/runtime options cannot be replayed into a detached child. Compiled binaries otherwise retain their existing self-spawn command contract, corroborated by a dedicated embedded marker and exact anchored Bun virtual-filesystem identity. The explicit `GJC_SDK_SESSION_COMMAND` session-host override remains a trusted legacy operator boundary and is not parsed as a shell-safe general command API. There is no broker-command override.\n\nBroker and per-session discovery tokens remain in their authoritative private discovery files for SDK-core resolution. Launch errors, logs, and diagnostics redact those tokens and never include the child environment or isolation configuration contents.\n\n## Internal protocol\n\nThe following frame shapes are SDK-core implementation details for maintainers.\nExternal integrations must not construct these frames, attach to session\ntransports, or receive endpoint credentials; use a Router-issued attachment, the\nbroker-bound CLI, or Coordinator MCP instead.\n\n### Server → client\n\n`action_needed` — something needs attention:\n\n```json\n{ \"type\": \"action_needed\", \"id\": \"act_9e31\", \"kind\": \"ask\",\n  \"sessionId\": \"sess-1\", \"workflowGateId\": \"wg_run_stage_1\",\n  \"question\": \"Proceed?\", \"options\": [\"Yes\", \"No\"], \"recommendedIndex\": 1 }\n```\n\n```json\n{ \"type\": \"action_needed\", \"id\": \"act_a42f\", \"kind\": \"ask\",\n  \"sessionId\": \"sess-1\", \"question\": \"Choose a target\", \"options\": [\"A\", \"B\"] }\n```\n\n```json\n{ \"type\": \"action_needed\", \"id\": \"idle-sess-1-7\", \"kind\": \"idle\",\n  \"sessionId\": \"sess-1\", \"summary\": \"finished refactor; awaiting next step\" }\n```\n\n- `id` is an opaque, transient presentation/action ID. It is the **only** authority accepted by generic `reply.id` through the current Router-issued attachment. It is not a durable workflow ID.\n- `workflowGateId?: string` is optional, additive SDK v3 correlation metadata, present only for the active presentation of a durable workflow gate. When present, it equals that gate's Q12 `gate_id`. Its public correlation key is `(sessionId, workflowGateId)` on the current Router-issued attachment; it never authorizes generic `reply`.\n- `kind: \"ask\"` is answerable in interactive/TUI and SDK workflow-gate sessions. `kind: \"idle\"` is notify-only and ephemeral (not replayed to attachments that start later). Ordinary asks and idle frames omit `workflowGateId`.\n- `recommendedIndex?: number` is optional, zero-based display metadata for `options`. Clients must validate that it is an in-range integer and ignore malformed values. Raw option labels and reply indices remain authoritative; never decorate submitted answers or infer a recommendation from position. The additive field is wire-compatible, but Rust consumers constructing the public `ActionNeeded` struct by literal must provide `recommended_index: None` when no recommendation exists.\n- This corrects the pre-v3 documentation invariant that `action_needed.id == gate_id`: they are deliberately different values. Clients must not preserve that invariant, infer a relationship from question/options/order, or retain private route, claim, receipt, epoch, token, or endpoint-generation maps.\n\n`action_resolved` — a pending action is now terminal and **non-repliable**:\n\n```json\n{ \"type\": \"action_resolved\", \"id\": \"act_9e31\", \"resolvedBy\": \"local\" }\n```\n\n`resolvedBy` is `local` (a local/direct control retired the presentation), `client` (a remote generic reply won), or `timeout`.\n\n`reply_rejected` — sent only to the client whose reply failed:\n\n```json\n{ \"type\": \"reply_rejected\", \"id\": \"act_9e31\", \"reason\": \"already_answered\" }\n```\n\nReasons: `already_answered`, `unknown_action`, `invalid_answer`,\n`resolver_unavailable`, `idempotency_conflict`, `unauthorized`.\n\n`bash_folded` — a foreground bash wait left the foreground and became a background job. Emitted once per fold into the replayable session event ring (so late-connecting clients receive it on `event_replay`), with `generic_safe` adapter disposition:\n\n```json\n{ \"type\": \"bash_folded\", \"sessionId\": \"sess-1\", \"jobId\": \"bg_3\", \"generation\": \"bg_3:1\", \"reason\": \"steer\" }\n```\n\n- `reason` is `steer` (a user steer arrived while the command had run past the 2 s grace window), `chord` (the `app.tool.backgroundFold` keybinding), `timer` (`bash.autoBackground`), or `sdk_control` (the `bash.background` control).\n- A replayed frame may describe a job that has since finished. `runtime.jobs.list` is the source of truth: each running/recent job carries `metadata.backgrounded` and, whenever it is `true` because of a fold, `metadata.foldReason` with the same values. The `bash.background` control (C52) returns `{ backgrounded: true, jobId }` on a fresh fold, `already_backgrounded` when no wait is foldable but a running job of this session was already folded (by steer, chord, timer, or a prior control call), `no_active_bash` when nothing is running or foldable, and `not_foldable` when a live wait refused the fold.\n- A `turn.steer` that folds a running bash behaves exactly like a TUI steer: the steer is consumed by the same turn at the tool boundary immediately after the fold result; `turn.steer_status` is unchanged.\n\nThe frames above are the internal transport contract implemented by SDK-core attachments. Managed adapters may receive optional server → client frames they can render or ignore: `identity_header` (one-time per-session repo/branch/machine header; Telegram topic-capable sessions additionally carry `telegramTopicsEnabled`), `context_update` (last message, task, goal, token usage, model, diff), `turn_stream` (live/finalized turn output), `image_attachment` (agent-produced images), `activity` (busy/idle, drives the typing indicator), `inbound_ack` (delivery state of an injected user message), `session_closed` (endpoint teardown; threaded adapters may delete/archive the remote conversation), `config_update` (current verbosity/redact), `hello` (server capability/version), and `pong`.\n\n### Internal inbound frames\n\nSDK core creates inbound frames only after Router attachment checks. External\nintegrations must not construct or persist them. Managed adapters use their\nopaque `SessionAttachment`, and process-isolated scripts use `gjc sdk session`;\nneither path receives transport credentials.\n\n## Model catalog query (Q10)\n\nThe SDK exposes the model catalog through the paged Q10 registry query. `Q10`,\n`models.list/current`, `models.list`, and `models.current` are exact aliases:\neach returns the same paged registry array, not a current-model singleton or a\nfiltered list. Continue using the returned cursor until `page.complete` is\ntrue.\n\nEach row preserves the five legacy fields (`provider`, `id`, `name`,\n`contextWindow`, and `maxTokens`) and additively includes `reasoning`,\n`thinking`, and `current`. `currentThinkingLevel` appears only on the current\nrow when the live session has a thinking level. The exported DTO types are\n`Q10Model`, `Q10ThinkingCapabilities`, `Q10ThinkingEffort`,\n`Q10SettableThinkingLevel`, `Q10CurrentThinkingLevel`, and\n`Q10ThinkingMode`, all from `@gajae-code/coding-agent/sdk`; there is no public\n`/sdk/models` subpath.\n\n```json\n{\n  \"provider\": \"runtime-provider\",\n  \"id\": \"reasoning-model\",\n  \"name\": \"Reasoning Model\",\n  \"contextWindow\": 128000,\n  \"maxTokens\": 8192,\n  \"reasoning\": true,\n  \"thinking\": {\n    \"validLevels\": [\"off\", \"minimal\", \"low\", \"medium\", \"high\"],\n    \"minLevel\": \"minimal\",\n    \"maxLevel\": \"high\",\n    \"mode\": \"effort\",\n    \"defaultLevel\": \"low\"\n  },\n  \"current\": true,\n  \"currentThinkingLevel\": \"high\"\n}\n```\n\n`thinking.validLevels` is always present and starts with `\"off\"`; it is the\ncanonical menu for `model.set` and never contains `\"inherit\"`. For a\nnon-reasoning model it is exactly `[\"off\"]`. Successful reasoning rows always\ninclude `minLevel`, `maxLevel`, and `mode`; only `defaultLevel` and raw `levels`\nare optional. Raw `levels` deliberately keeps its descriptor order and\nduplicates, while `validLevels` is the canonical, deduplicated menu clients\nshould render. `\"inherit\"` is a current-state readback value only and is rejected\nas a `model.set` input.\n\nMalformed reasoning descriptors are not client-recoverable catalog data. The\nquery returns the SDK's safe `internal` error rather than exposing a partially\nformed row or descriptor details.\n### Model profiles as synthetic models (`gajae-code/<profile>`)\n\nThe Q10 catalog also exposes model profiles as logical synthetic models under\nthe reserved provider namespace `gajae-code`, e.g. `gajae-code/codex-eco`.\nThese rows let clients (such as ACP model pickers) offer presets like ordinary\nmodels without provider-specific metadata:\n\n```json\n{\n  \"provider\": \"gajae-code\",\n  \"id\": \"codex-eco\",\n  \"name\": \"Codex Eco\",\n  \"contextWindow\": 222222,\n  \"maxTokens\": 8888,\n  \"reasoning\": false,\n  \"thinking\": { \"validLevels\": [\"off\"] },\n  \"current\": false\n}\n```\n\n- `gajae-code/<profile>` is a **logical namespace, not a callable provider**. No\n  API transport, credentials, or streaming route is registered for it; send the\n  value back through the generic `model.set` control (or the ACP `Model`\n  select) to activate the profile.\n- Synthetic rows are **availability-filtered**: only profiles whose required and\n  alternative providers have usable stored credentials are listed. The profile\n  id suffix is parsed losslessly after the first namespace slash, so profile ids\n  containing additional slashes or punctuation round-trip exactly.\n- `contextWindow`/`maxTokens` mirror the profile's resolvable default model when\n  available and otherwise fall back to the shared unknown-model constants\n  (222222 / 8888); the profile's real default model remains authoritative.\n- Synthetic rows are non-reasoning with `validLevels: [\"off\"]`: a `model.set`\n  on a synthetic id with any thinking level other than `off` is rejected with\n  `invalid_input`, and only an absent or `off` level is forwarded as a session\n  override.\n- **Current-state semantics:** while a profile is active for the session, exactly\n  the synthetic row carries `current: true` with `currentThinkingLevel:\n  \"inherit\"`, and the underlying concrete row is not marked current. A persisted\n  `modelProfile.default` alone (without an in-session active marker) never\n  creates a synthetic current row. Selecting a concrete `provider/model` clears\n  the active marker and restores concrete current semantics.\n- **Selecting a synthetic profile is session-scoped.** `model.set` with\n  `gajae-code/<profile>` activates the full profile in the live session without\n  writing `modelProfile.default`, `modelRoles`, or\n  `task.agentModelOverrides`. Persisting a profile remains an explicit TUI\n  choice (`/model` → default), mirroring `gjc --mpreset <profile> --default`.\n  Unknown or ambiguous synthetic ids fail with `invalid_input`; missing profile\n  credentials fail with the existing authentication-required error.\n- `gajae-code` is **reserved**: a user-defined `models.yml` provider of the same\n  name disables the synthetic facade (rows are omitted and synthetic selection\n  is rejected) rather than being silently shadowed. Q27 (`models.profiles.list`)\n  remains the full profile catalog with explicit `available` status; Q10 is the\n  availability-aware facade for client selection.\n`config.patch` mutations are serialized through the same session admission\nboundary as profile activation and default-model selection, so a patch racing\na synthetic `gajae-code/*` selection (or another patch) is applied in a\ndeterministic order and is never lost or clobbered by an activation rollback.\nThe cost is the same as `model.set`: an external `config.patch` queues behind\nany in-flight prompt admission rather than applying mid-turn.\n\n## Prompt acceptance, termination, and reconciliation (Q26)\n\n`runtime.capabilities.promptTerminalOutcomeVersion` is `1` when this contract is available. Its normalized TypeScript terminal outcome is:\n\n```ts\ntype SdkPromptTerminalOutcome =\n\t| {\n\t\t\tkind: \"stopped\";\n\t\t\treason: \"end_turn\" | \"max_tokens\" | \"max_turn_requests\" | \"refusal\" | \"cancelled\";\n\t\t\tprovenance: \"agent\" | \"client_cancel\";\n\t  }\n\t| {\n\t\t\tkind: \"failed\";\n\t\t\tcode: \"prompt_failed\" | \"prompt_deadline_exceeded\";\n\t\t\tmessage: string;\n\t\t\tprovenance: \"agent_failed\" | \"deadline\";\n\t  };\n```\n\n`turn.prompt` returns `{ accepted: true, commandId, turnId, clientRef? }` only after\nits asynchronous preflight accepts the prompt. That receipt is a durable,\n**non-terminal pending claim**, not a process-durable terminal result. The SDK\nlater finalizes that claim with exactly one `SdkPromptTerminalOutcome`; cleanup\nmay follow only after the claim is durable.\n\nThe authoritative public reconciliation query is `Q26` / `turn.result`, scoped\nto the same live session runtime. Callers supply `kind: \"prompt\"`; its `outcome`\nfield is exposed only after finalization. A pending claim is never represented\nor exposed as a terminal outcome. `turn.prompt_status` remains a legacy\nprompt-only alias that injects the same `kind`.\n\nEvery prompt and skill status response includes `receiptState`: active records are `absent`; terminal records are `present`, `missing`, or `unknown`; unknown lookup is `unknown`. Ordinary success requires `status: \"terminal_ok\"`, `receiptState: \"present\"`, and readable non-empty text or an artifact path. A failed execution may retain a partial `present` receipt. Legacy version-1 reconciliation records without this additive field remain readable and project `unknown` rather than optimistic success.\n\nCallers that must recover from a lost acknowledgement should assign one fresh\n`clientRef` (a trimmed, non-empty string of at most 128 characters) to each\nlogical prompt, then reconcile through the broker-bound CLI:\n\n```sh\ngjc sdk session raw query <sessionId> --query turn.result \\\n  --json-input '{\"kind\":\"prompt\",\"clientRef\":\"request-018f\"}'\n```\n\nThe alternate selector uses the same `kind` with\n`{\"kind\":\"prompt\",\"commandId\":\"command-id\",\"turnId\":\"turn-id\"}` as its JSON input.\n\nThe result status is `accepted`, `in_flight`, `terminal_ok`, `failed`, or\n`unknown`. Known records include `acceptedAt`; in-flight and terminal records add\n`startedAt` and/or `terminalAt`; finalized records include `outcome`; failed records\nalso include a bounded sanitized `error.code` and `error.message`. Cursors, partial\ngenerated-ID pairs, mixed selectors, and extra selector fields are rejected.\n\nCorrelated `agent_end` and `agent_failed` frames carry the same finalized\n`outcome`. Clients must correlate those frames and Q26 by the prompt identifiers,\nnot infer terminality from stream activity or an earlier pending claim.\n\nReconciliation state survives client disconnect/reconnect. With the session-private durable store (`.sdk-reconciliation/`), accepted and terminal prompt records also survive **GJC session-process restart** for the same session identity within capacity, subject to crash-consistent fsync. A non-terminal prompt record at restart finalizes its pending outcome and receipt state. A stopped prompt without receipt evidence becomes `terminal_ok + missing`; failed prompt or skill settlement without body evidence becomes `unknown`. Eviction or absence still returns honest `unknown`; that means the prior outcome is unknowable, not that execution did not occur. Active records are capped at 128 per kind and are never aged into terminal. Terminal records are capped at 256 per kind and evicted oldest-terminal first, with no age-based eviction. Reconciliation stores no prompt, transcript, credential, or provider-response body.\n\n`turn.prompt` remains ordered and non-idempotent. Its envelope `idempotencyKey`\ndoes not replay a response or produce `idempotency_conflict`. A retained duplicate\n`clientRef` fails before execution with `client_ref_conflict`, but callers must not\nreuse a `clientRef` as a retry mechanism: after eviction the same value can identify\na new prompt while the old outcome remains unknown.\n\n`turn.abort` returns a typed disposition. A caller that does not own the target\nreceives `resource_gone`; it must not treat that result as cancellation of another\nprompt.\n\n`sdk.promptDeadlineMs` defaults to `3_600_000`. It accepts only safe integers in\n`[60_000, 86_400_000]`; there is no disable value. The SDK snapshots the setting\nwhen the prompt is durably accepted as the initial inactivity lease. Fresh\n**attributable** progress for the exact accepted `commandId`/`turnId` — `tool_execution_start` /\n`tool_execution_update` / `tool_execution_end` observed at the prompt/agent runtime boundary — renews the deadline to\n`lastProgressAt + sdk.promptDeadlineMs`, bounded by the hard maximum `sdk.promptMaxRuntimeMs`\n(default `21_600_000`, same `60_000–86_400_000` range). Only tool-execution events for the\naccepted turn count — including a running tool's partial-result `tool_execution_update`, so a\nlong-running tool that streams output (e.g. a multi-minute compile) keeps renewing the lease mid-run;\nheartbeats, streaming text/thinking deltas, retries, other turns/sessions, and\nunrelated session noise do not renew the lease, and out-of-order delivery never shortens it. The\nhard maximum is never unbounded: every renewal is capped at `acceptedAt + sdk.promptMaxRuntimeMs` so a\nwedged or continuously noisy prompt still reaches a deterministic terminal outcome. Terminalization then has a fixed `10_000` ms\ngrace period, which is not configurable. A controlled terminal failure reaches ACP\nas JSON-RPC `-32603` with `data.code` of `prompt_failed` or\n`prompt_deadline_exceeded`.\n\n## Skill invoke reconciliation\n\n`skill.invoke` accepts optional `clientRef` and returns an early accepted receipt\n`{ accepted: true, commandId, turnId, clientRef?, name, path, lineCount?, args? }` after\ndurable/preflight accept (SDK control path), not after skill completion. Query prior\nstatus with `Q26` / `turn.result` and `kind: \"skill\"`. `skill.invoke_status`\nremains a legacy skill-only alias that injects the same `kind`. Kind-scoped indexes\nmean prompt and skill `clientRef` values never collide. Skill records use the same\ncapacity/retention limits, but an active skill record at restart settles with\n`error.code = process_restart`.\n\n## Correlated steer acknowledgement (Q30)\n\n`turn.steer` accepts an optional `clientRef` (trimmed, non-empty, at most 128 characters). When present, GJC hashes the exact validated steer text with SHA-256 and durably reserves `dispatching` before queueing. The result contains `sessionId`, `clientRef`, `status: accepted | rejected | uncertain`, known `acceptedAt` or `terminalAt`, and bounded error metadata; it never echoes text.\n\nReplay the same `clientRef` with the same text to recover the retained result without dispatching again. Reuse with different text returns `client_ref_conflict`. A live `dispatching` record and a restart during dispatch both project `uncertain`; GJC never automatically redispatches an ordered control whose first effect is unknowable. Query the same session with:\n\n```json\n{ \"type\": \"query_request\", \"query\": \"turn.steer_status\", \"input\": { \"clientRef\": \"steer-018f\" } }\n```\n\nQ31 returns `accepted`, `rejected`, `uncertain`, or `unknown` and never dispatches work. Settled steer records share the 256-record oldest-terminal-first capacity bound with no age-based eviction; live dispatching records are not terminal-evicted. Existing uncorrelated `turn.steer` calls retain their legacy non-idempotent behavior. Version-1 reconciliation remains additive, and only digest plus bounded metadata is stored—never steer text.\n\n## Model profile discovery and validation (Q27)\n\n`Q27` / `models.profiles.list` pages the effective model-profile catalog owned by\nthe attached session. Rows are sorted by exact ID and contain only:\n\n```json\n{ \"id\": \"codex-medium\", \"displayName\": \"codex-medium\", \"source\": \"builtin\" }\n```\n\n`source` is `builtin` or `configured`. Profiles from `<agentDir>/models.yml`\noverride built-ins with the same exact ID, including their display label. Profile\nIDs are not trimmed, case-folded, sanitized, or restricted to safe-token names;\ndiscover the exact ID and send it unchanged. The retired `codex-standard` alias is\nfallback-only and never shadows a configured profile with that exact ID.\n\nQ27 uses retained-revision, connection-bound pagination. Continue an issued cursor\nto finish its stable snapshot; a fresh cursorless query observes the current\nregistry. The query accepts no root, path, or selector input. An invalid or\nunreadable `models.yml` fails closed with `model_profile_registry_error` rather\nthan returning a plausible built-ins-only catalog.\n\nBroker `session.create`, `session.fork`, and `session.resume` validate `modelPreset`\nbefore spawning against the same `<broker.settings.agentDir>/models.yml` authority\nthat the child receives through `GJC_AGENT_DIR` / `GJC_CODING_AGENT_DIR`. Unknown\nIDs return `unknown_model_profile`. Both typed errors include bounded `details`\nwith `requestedProfile` where applicable, whole exact `availableProfiles` entries\nthat fit the detail budget, and `discoveryQuery: \"models.profiles.list\"`. The\ndiscovery pointer is authoritative when the bounded error cannot include every ID.\n\nThe same lifecycle operations accept an optional `modelId`: an explicit\n`provider/model` pin with `gjc --model` grammar (#4707). Coordinators resolve it\nagainst the full model registry (the CLI `--model` surface, not the\nauthenticated-only subset) before sending the create request, so unknown ids are\nrejected before any session exists. The broker guards only its shape; the child\napplies it exactly like a CLI `--model` selection, which also means an explicit\n`modelId` wins over `modelPreset` when both are supplied — the same precedence as\n`gjc --mpreset <profile> --model <model>`. The full effective order is:\n\n```\nmodelId pin  >  modelPreset  >  configured modelProfile.default  >  role/resume/default\n```\n\nThe pin is a guarantee, not a preference. The coordinator validates against its\nown registry and the child owns the registry that actually serves requests, so\nthe two can drift (a model removed, a provider disabled, an extension that\nfailed to register). On drift the child fails session construction before\nreadiness and before any profile application, disposes the partial session, and\nreports an error naming the pinned selector — it never publishes success on a\nsubstituted model. Coordinator validation refreshes the registry per request\n(offline, from the on-disk discovery cache) so ids added or removed after an\nearlier pin are judged against current contents.\n\n### Active provider query (Q29)\n\n`Q29` / `providers.list/active` pages the providers currently eligible for model\nselection through the same authenticated, retained-snapshot envelope as Q10. Each\nrow is the non-secret DTO `{ provider, connectionKind }`, where `connectionKind`\nis `credential` or `credentialless`.\n\nProvider IDs are returned exactly as they appear in Q10 `model.provider`: existing\nmixed-case, spaced, punctuated, and long custom IDs are preserved without aliases\nor normalization. Rows are deduplicated and ordered by UTF-8 provider bytes.\nJoin Q29 to Q10 by exact provider ID; Q10 remains the full configured catalog.\n\nA credentialed discovery-only provider appears only after fresh discovery proves\nthe exact model is usable. Static configured models can appear without a network\nprobe. The query never invokes a model, refreshes credentials, probes a remote\naccount, or exposes credentials, account metadata, paths, or provider responses.\n\nResolver failures are atomic and return\n`{ \"code\": \"internal\", \"message\": \"Unable to resolve active providers.\" }`.\nThey omit a page and restart metadata. An expired continuation follows the shared\ncursor contract and returns `error.code: \"cursor_expired\"` with\n`error.restartQuery: true`. Malformed cursor strings return `invalid_cursor`;\ncross-query or selector mismatches return `invalid_input`.\n\n## Answer semantics\n\nA remote reply answers a pending ask in every session state:\n\n- **Interactive / TUI mode:** the ask tool races the local selector against the\n  remote reply (first valid answer wins). A client submits generic `reply` using\n  the active presentation `id`; a local answer emits `action_resolved`\n  (`resolvedBy: \"local\"`) and that presentation becomes non-repliable.\n- **SDK workflow gate:** generic `reply` still uses the active presentation\n  `id`, never `workflowGateId`. The resolved gate drives the session the same\n  way a local answer would.\n\nA session has at most one active answerable presentation. Interactive asks and durable workflow gates are serialized; further Q12 gates wait in a durable queue. A same-server reconnect replays the active `action_needed` with the same presentation ID. After a process restart, previously pending or accepted-but-unadvanced records are quarantined diagnostics and a reconstructed workflow remints fresh durable gate and presentation IDs. Terminal, stale, and reissued action IDs never regain authority.\n\nGeneric and direct controls may race. Once the native generic claim is acquired, it wins; a direct control that atomically retires the exact unclaimed active presentation first wins instead. Losing direct controls fail without advancing the gate, and losing generic replies are stale/non-repliable. Clients must not retry by matching text, durable IDs, or presentation history; they must fail closed rather than guess when session or action identity is unsafe or ambiguous.\n\n### Durable workflow controls and Q12\n\n`workflow.gate_answer` and `workflow.plan_approve` operate on the durable Q12\n`gate_id`, not `action_needed.id`. Managed adapters bind `expectedSessionId`\nfrom their current Router-issued attachment. Process-isolated operators use the\nraw-control flow documented in the [SDK session CLI guide](./sdk-session-cli.md); they do not construct protocol frames.\n\n`expectedSessionId` omission remains accepted and audited for the entire SDK v3 line so deployed v3 control clients continue to work; new clients must send it now. It cannot become mandatory, or be removed from the controls, before SDK v4 and at least one full published deprecation release/window with deployed-client notice. A supplied session mismatch is rejected before the gate resolver runs. Neither control accepts a presentation ID, remaps an old ID to a reminted gate, or uses heuristic matching.\n\nQ12 (`workflow.gates.list`) exposes durable query records and additive SDK v3 diagnostics. A pending record preserves its workflow fields including `gate_id` and adds `id: \"pending:<gate_id>\"`, `tag: \"pending\"`, and `answer_recorded: false`. An accepted-answer diagnostic uses `id: \"diagnostic:<gate_id>\"`, `tag: \"accepted\"`, `answer_recorded: true`, and `resolved_at`, plus one `post_accept_disposition` value (`accepted`, `terminalized`, `advanced`, `continuation_lost`, or `unknown`) so an operator can distinguish a gate still waiting for continuation from one whose answer was durably advanced. A restart quarantine diagnostic uses `id: \"diagnostic:<gate_id>\"`, `tag: \"quarantined\"`, `answer_recorded`, and optional `lifecycle` containing `state: \"quarantined\"`, its restart reason, `quarantinedAt`, and an optional `supersededByGateId` after a remint. When available, every record also carries the originating `runtime_turn_id`; raw answers and derived answer values are never exposed. Diagnostics are query-only: they cannot be routed, answered, or promoted. Treat Q12 as the durable status surface, not as generic-reply authority.\n\n### Coordinator MCP question pull loop\n\nThe Coordinator MCP bridge is a separate, public-safe pull surface for external coordinators. `gjc_coordinator_list_questions` requires `session_id` and reconciles pending `workflow.gates.list` rows on every call, returning bounded public `questions`, `diagnostics`, and `reconciliation`. It accepts `status: \"pending\"`; `status: \"open\"` remains a compatibility alias. Multiple pending rows can be returned. A pending row carries its safe question shape, public option ids, and `answer_binding`, never raw/private gate payloads or values.\n\n`gjc_coordinator_submit_question_answer` requires `session_id`, `turn_id`, `question_id`, `answer_binding`, `answer`, `idempotency_key`, and `allow_mutation: true`. It re-lists/revalidates after restart and resolves through `workflow.gate_answer`, not generic `ask.answer`. An incomplete reconciliation returns `terminal_uncertain`; stale, terminal, missing, or ownership-mismatched rows cannot be answered. Re-list after restart rather than retaining old identifiers. An identical retry with the same idempotency key replays the accepted result; conflicting reuse returns `idempotency_conflict`.\n\nThis contract does not change #2549/#2551 or unattended plain-CLI behavior.\n\n### Rust and N-API compatibility\n\nThe Rust `ActionNeeded`, `ServerMessage`, and `register_ask` APIs remain\nlegacy-compatible and uncorrelated. Correlation is available through additive\nRust workflow-frame decoding/current-reader APIs and the workflow registration\npath; consumers that need correlation must opt in explicitly. N-API likewise\nretains `registerAsk`, and adds `registerWorkflowGateAsk` for a correlated wire\nframe plus `registerArbitratedAsk` and `retireIfUnclaimed` for in-process\npresentation arbitration. The arbitration lease and all claim/receipt/epoch\nstate remain private: these APIs do not create a public authority value.\n\n### Runtime and native addon release pairing\n\nThe `@gajae-code/coding-agent` runtime and `@gajae-code/natives` native addon ship from the same source release at exact matching package versions. The native loader requires the matching version sentinel; mixed native/runtime versions are unsupported and must not claim SDK compatibility.\n\n## Minimal provider adapter example\n\nProvider integrations compose SDK core's `SessionRouter`; they never read endpoint files or retain URL/token credentials:\n\n```js\nimport { router } from \"@gajae-code/coding-agent/sdk\";\n\nconst sessionRouter = new router.SessionRouter({\n  agentDir,\n  deps: {\n    onAttachment: (attachment) => provider.bind(attachment.sessionId, attachment),\n    onFrame: (attachment, frame) => provider.render(attachment.sessionId, frame.body),\n    onSessionRemoved: (attachment) => provider.unbind(attachment.sessionId),\n  },\n});\n\nawait sessionRouter.start();\nconst attachment = sessionRouter.attachment(sessionId);\nif (!attachment) throw new Error(\"session attachment unavailable\");\nawait attachment.send({ type: \"reply\", id: actionId, answer });\n```\n\n`SessionRouter` performs exact endpoint resolution, credential custody, replay, reconnect, rotation, and dispatch-time stale-lease rejection.\n\n### Exact fenced session close\n\nCapture the endpoint authority from the original Router binding and pass that\nsame pair to the lifecycle service. The generation and incarnation are one\nauthority: a partial target is rejected before it reaches the Broker.\n\n```ts\nconst authority = await sessionRouter.bindingAuthority(sessionId);\nif (!authority) throw new Error(\"session endpoint authority unavailable\");\n\nconst outcome = await lifecycleService.close({\n  actor,\n  capability: \"session.close\",\n  requestKey: \"close-captured-session\",\n  target: authority,\n});\n```\n\n`bindingAuthority()` returns `undefined` when the Router cannot prove the\ncurrent endpoint and its incarnation. Do not reconstruct the authority from\nendpoint credentials, process metadata, or a later session lookup; a\nreplacement may become current between capture and close.\n\n### Exact generation reconciliation\n\nManaged consumers that close or delete a session can reconcile one previously\npersisted attachment generation without retaining endpoint credentials:\n\n```ts\nconst proof = await sessionRouter.generationStatus(sessionId, endpointGeneration);\n\nswitch (proof.status) {\n  case \"current\":\n    // This exact generation is the current live indexed authority.\n    break;\n  case \"retired\":\n    // A retained host-unregister, close, or delete event positively retired it.\n    break;\n  case \"replaced\":\n    // A different live generation is current; use proof.currentGeneration.\n    break;\n  case \"unknown\":\n    // Do not infer retirement or retry a possibly-applied lifecycle mutation.\n    break;\n}\n```\n\n`generationStatus(sessionId, endpointGeneration)` is credential-free and may be\ncalled after `SessionLifecycleService` returns from `session.close` or\n`session.delete`, and after `SessionRouter.stop()`. Its evidence contains only\n`source: \"session_index\"`, a coherent `observedIndexSeq`, the successful\nstate's `evidenceIndexSeq`, and, for positive retirement, the safe terminal\nevent kind. It never exposes endpoint URL/token data, process IDs, locators,\nprivate Broker responses, or lifecycle cleanup payloads.\n\nThe result is an observation of one locked index reconciliation cut:\n\n- `current` requires the queried generation to be the current live, unambiguous\n  indexed authority.\n- `retired` requires a retained exact-generation `host_unregistered`,\n  `session_closed`, or `session_deleted` event. Missing attachment, missing\n  endpoint publication, Router shutdown, or a dead/unreachable host never imply\n  retirement.\n- `replaced` requires both prior observation of the queried generation and a\n  strictly greater current live generation. Same-generation reconnect remains\n  current; reuse, regression, or safe-integer wrap is classified as unknown\n  rather than manufacturing a successor relationship.\n- `unknown` is fail-closed. Reasons distinguish invalid input, unavailable or\n  incomplete index reconciliation, an unobserved session/generation, ambiguous\n  authority, and detected generation reuse. Consumers must preserve uncertain\n  lifecycle state rather than treating `unknown` as retired. Expired positive\n  evidence is reported specifically as `proof_expired`.\n\nProof survives Broker, Router, and consumer process restart because it is read\nfrom the durable session index, not Router attachment memory. Positive terminal\nproof has the session-index `maxAgeMs` lifetime (30 days by default), even when a\ndelete tombstone is retained longer for audit. Row-bound compaction may evict a\nwhole session sooner. After proof expiry, compaction eviction, or loss of a\ncomplete index, `generationStatus` returns `unknown`, never a synthetic\nretirement proof. This bounds the public proof surface independently of durable\nBroker audit retention.\n\n## Fallback chains\n\nModel-role selectors may be ordered fallback chains; see [Fallback chains](./models.md#fallback-chains) for configuration and retry-budget details. Resolution-time skips do not consume attempts. When a request-time retry advances to another eligible entry, the selected default fallback remains sticky for later prompts in that session until an explicit model selection or a chain reset changes it.\n\n`model_fallback_switched { eventId, from, to, reason, role, scope, activeIndex, chainLength, attemptsUsed }` is the canonical session lifecycle event for every real fallback-model switch. It replaces the legacy `retry_fallback_applied` / `retry_fallback_succeeded` event names. Embedding clients can subscribe to this in-process session event; managed adapters receive only the status projections their SDK-core integration supports.\n\n\n## Managed session-directory adapter guidance\n\nSDK adapters that need to inspect saved sessions must import only the supported public surface from `@gajae-code/coding-agent/sdk`:\n\n```ts\nimport {\n  SESSION_DIRECTORY_API_VERSION,\n  listManagedSessionCandidates,\n  resolveManagedSessionScope,\n} from \"@gajae-code/coding-agent/sdk\";\n\nif (SESSION_DIRECTORY_API_VERSION !== 1) throw new Error(\"Unsupported session-directory API\");\nconst resolved = await resolveManagedSessionScope({ cwd: process.cwd() });\nif (resolved.kind === \"resolved\") {\n  const listing = await listManagedSessionCandidates({ scope: resolved.scope });\n  // Consume only listing.kind === \"complete\" and its owned candidates.\n}\n```\n\nThis is a readonly resolver/listing contract. Do not import `@gajae-code/coding-agent/session/internal/*`, derive `v2-…` names, write bindings, or implement migration/cleanup in an adapter; private internal subpaths are intentionally unavailable from the packaged module. Treat `network_unsupported`, binding/security errors, incomplete listings, invalid candidates, and foreign candidates as non-authoritative results rather than retrying with a guessed path.\n\nThe resolver uses canonical native identity: supported POSIX and Windows local aliases can designate one scope, while UNC/network workspaces are unsupported. Scope digests are collision-resistant identifiers, not injective aliases, credentials, or authentication. The owner-only checks protect managed local storage paths but do not authenticate an adapter or make hostile concurrent filesystem races safe. Adapters that need mutations must use the higher-level lifecycle/session APIs rather than the readonly directory API.\n## Managed notification adapters\n\nGJC ships managed SDK adapters for Telegram, Discord, and Slack. `SessionRouter` resolves one session-owned endpoint per attachment and keeps every endpoint credential inside SDK core. Provider daemons receive only opaque attachment capabilities; they neither change the wire protocol nor expose a remote shell.\n\nThe recommended interactive path is `/settings` → **Notifications**. It owns\nsetup, health, test, recovery, reconnect, local enablement, and Telegram\nremoval without exposing stored credentials.\n`gjc notify setup` remains the authoritative CLI fallback for headless and\nautomated environments.\n\nNotification credentials and `notifications.*` settings are global-only.\nProject notification keys are\nignored and runtime notification overrides are rejected. Telegram pairing\nrevalidates the complete bot-token/chat identity immediately before polling and\nagain before activation. A foreign or unknown owner is never killed, reloaded, or taken over;\nsetup fails closed without saving or exposing the raw token.\n\nConfiguration completeness, provider-local quarantine, durable desired intent, effective enablement, runtime readiness, and delivery outcomes are separate contracts. The global `notifications.enabled` master never erases provider credentials or desired flags. `/settings` edits secrets through explicit `keep`, `replace`, or `remove` actions, commits only the selected provider in one CAS batch, and reports post-commit observer or activation failures without pretending the durable save rolled back. Malformed provider-local values are quarantined for explicit repair while safe sibling providers remain usable; malformed global notification structure remains fail-closed.\n\n`GJC_NOTIFICATIONS=0` suppresses only automatic generic current-session admission. Explicit `/notify on` can opt the current session back in without mutating durable provider state, and direct provider APIs remain governed by provider effectiveness and their own runtime readiness. Telegram, Discord, and Slack attachments are reconstructed through `SessionRouter`; no provider receives the shared endpoint token.\n\n- [Telegram notification onboarding](./telegram-onboarding.md) documents\n  `gjc notify setup` and private-chat pairing.\n- [Discord notification onboarding](./discord-onboarding.md) documents\n  `gjc notify setup discord`, required configuration, thread lifecycle, and\n  least-privilege permissions.\n- [Slack notification onboarding](./slack-onboarding.md) documents\n  `gjc notify setup slack`, Socket Mode configuration, immediate envelope ack,\n  and thread lifecycle.\n\n`gjc notify status` reports provider completeness, repair/quarantine state, desired intent, effective enablement, and masked tokens. Destination identifiers remain visible and may be sensitive. The Discord and Slack setup commands are non-interactive and require their documented identifier and token flags; supply secrets through an approved local mechanism, not examples, committed files, shell history, logs, or chat. `gjc notify health --provider <provider> --probe` performs a provider-owned REST diagnostic even when complete credentials are intentionally inactive, while `gjc notify test --provider <provider>` additionally requires effective enablement and runtime readiness.\n\nSession lifecycle and attachment routing are SDK-core services shared by every\nchat provider. `SessionLifecycleService` authorizes typed create, fork, resume,\nclose, delete, and list requests, derives the Broker idempotency identity, and\nprojects credential-free outcomes. The Broker remains the only lifecycle\nexecutor and durable terminal authority.\n\n`SessionRouter` consumes the Broker `SessionIndex`, resolves exact endpoint\nauthority, retains endpoint credentials and SDK clients, and owns replay,\nreconnect, rotation, and stale-attachment revocation. Telegram, Discord, and\nSlack receive only opaque current-generation attachments. Provider daemons own\ntransport leases, cursors, rate limits, threads/topics/messages, presentation\njournals, and delivery receipts; they cannot read endpoint files or tokens,\nallocate SessionIds, or perform session process lifecycle effects.\n\n\n## Managed Telegram daemon (bundled reference client)\n\nThe managed Telegram client is a provider supervisor and presentation adapter.\nIt owns the single `getUpdates` poller and Telegram topic state, while\n`SessionRouter` reconstructs SDK attachments from Broker state. A provider\nrestart never creates, resumes, closes, or mutates a GJC session by itself.\n\nFor Telegram forum topics, the daemon deletes the presentation topic through\n`deleteForumTopic` (falling back to `closeForumTopic` when deletion is unavailable)\nwhen `SessionRouter` retires the current attachment or when the daemon confirms\nthat no eligible local session still owns the topic. A resumed session creates or\nrebinds a fresh current-generation topic before sending again. Topic cleanup is\nbest-effort and cannot change the Broker lifecycle result.\n\n### Singleton poller and trust model\n\nTelegram `getUpdates` allows only one active long-poll owner per bot token. The\nmanaged daemon enforces **one bot token = one getUpdates poller** with a local\nlock/state file under the agent directory. New sessions attach to the existing\nfresh daemon owner instead of starting another poller, preventing Telegram 409\nconflicts.\n\nThe trust model is intentionally strict:\n\n- setup pairs exactly one private Telegram chat;\n- runtime accepts updates only from that paired chat id;\n- groups, supergroups, channels, and unpaired users never receive session names,\n  action ids, pending status, or configuration hints;\n- daemon state stores a token fingerprint, not the raw bot token.\n\n### Routing in private-chat topics\n\nThe paired private chat prefers Telegram topics for coordinator/lifecycle sessions\n(Threaded Mode). The daemon tags messages by session, stores compact callback\naliases for inline buttons, and routes replies back to the exact session/action.\nOrdinary sessions use flat delivery and do not create topics. A forum-enabled\nsupergroup is no longer required: when the bot owner enables Threaded Mode in\n@BotFather, the daemon creates topics only for admitted orchestration sessions.\nGJC cannot enable Threaded Mode through the Bot API; setup only verifies the\ncapability and guides the manual BotFather toggle.\n\nIf BotFather's per-bot **Bot Settings** menu does not show **Threads Settings**\nor **Threaded Mode**, the supported fallback is the normal private-chat pairing.\nSetup can be saved as `threaded=unverified`/`threaded=unknown`, and the daemon\nstill tries topics when Telegram allows them. When `createForumTopic` is refused,\nthe daemon does not drop the send: it routes the notification to the normal\n(flat) paired private chat and posts a one-time nudge: `Flat Telegram private chat\nsupports outbound notifications and inline ask buttons only. Enable Threaded Mode\nin @BotFather > Bot Settings > Threads Settings for free-text replies and session\ncommands.` Pairing is private-only, so flat delivery stays within the user's own\nprivate DM.\n\nSupported reply paths:\n\n- tap an inline button on an ask notification;\n- reply inside the session's thread/topic (replies are thread-native; the\n  topic identifies the session, so no session tag is needed).\n\nIn threaded mode the user can also adjust per-session behaviour with in-thread\nconfig commands: `/verbose` (per-tool-turn assistant text), `/lean` (settled\nassistant answer at idle plus immediate ask lead-ins; the default),\n`/verbosity <lean|verbose>`, and `/redact <on|off>`. The legacy\n`/answer <session-tag> <answer>` command is removed — replies are routed by the\ntopic they arrive in.\n\nFlat fallback keeps outbound notifications and inline-button answers working, but\nplain free-text never guesses from the global pending-ask set. Free-text replies\nand `/verbose`/`/lean`/`/verbosity`/`/redact` commands are thread-native and\nrequire Threaded Mode/topic routing. Enable Threaded Mode in @BotFather > Bot\nSettings > Threads Settings when you need free-text replies or session commands.\nDo not pair a group, supergroup, or channel to work around a missing BotFather\nmenu; the bundled setup flow is\nprivate-chat only, and non-private chat ids remain fail-closed to avoid session\ndata leaks.\nBecause the flat private chat has no per-session topic, flat idle markers carry\na short session tag (`🟢 Agent idle · <tag>`, last six characters of the session\nid) so concurrent sessions stay distinguishable. The tag never appears on asks\nor in threaded/topic delivery, where the topic itself identifies the session.\n\nUnknown, expired, or restart-unvalidated callback aliases fail closed: the daemon\nsends guidance and does not guess a target session or action.\n\n### Discord and Slack setup\n\nDiscord and Slack use the same internal notification events and reply protocol as\nTelegram. Store only runtime credentials in local GJC settings or environment;\nnever paste bot tokens, webhook URLs, transcripts, prompts, host paths, or raw logs\ninto docs, tests, issues, or PR comments.\n\nConfiguration keys:\n\n```yaml\nnotifications:\n  enabled: true\n  discord:\n    botToken: \"<local Discord bot token>\"\n    applicationId: \"<Discord application id>\"\n    guildId: \"<Discord guild id>\"\n    parentChannelId: \"<Discord parent channel id>\"\n  slack:\n    botToken: \"<local Slack bot token>\"\n    appToken: \"<local Slack app-level token>\"\n    workspaceId: \"<Slack workspace id>\"\n    channelId: \"<Slack channel id>\"\n    authorizedUserId: \"<Slack user id authorized for inbound replies and commands>\"\n  redact: true\n```\n\nThe bundled adapters intentionally render public-safe message bodies and return\nroute metadata only for pending internal actions. They do not own polling,\nsession scans, daemon locks, rate limits, or SDK lifecycle. Production transport\nsenders should consume the adapter payloads and keep all credential-bearing HTTP\nor gateway details outside logged payloads.\n### Redaction\n\n`notifications.redact` strips sensitive content before remote delivery, but\n**asks are exempt**: an ask is an interactive prompt the human must read and\nanswer remotely, so its `question` and `options` are always sent unredacted\n(otherwise it would be unanswerable). When redaction is enabled, `idle`\nsummaries are removed and streamed content frames (`turn_stream`,\n`context_update`, `image_attachment`) are suppressed at their emit sites. When\nredaction is disabled, all content is delivered unchanged.\n\n### Local `/notify`\n\nInside a GJC session, `/notify` controls the current session only:\n\n- `/notify status` reports enabled/disabled state, daemon observation when known,\n  and redaction state without printing secrets;\n- `/notify off` disables the current session's notification endpoint and removes\n  its discovery record without mutating global Settings;\n- `/notify on` re-enables the current session when global setup is complete and\n  `GJC_NOTIFICATIONS=0` is not forcing opt-out.\n\n## Session lifecycle and attachment surfaces\n\nSDK core exposes two related provider-neutral capabilities:\n\n1. **`SessionLifecycleService`** accepts an authenticated actor, an explicit\n   operation capability, a stable caller request key, and a typed target. It\n   derives one Broker idempotency key and invokes the canonical Broker lifecycle\n   operation. Results never expose endpoint URLs, tokens, process identities,\n   cleanup paths, or raw Broker receipts. Successful create, fork, and resume\n   results may include the credential-free `endpointGeneration` plus opaque\n   `endpointIncarnation`; pass both back for an exact close authority rather\n   than deriving a replacement identity from the numeric generation. A supplied\n   saved-session `sessionIdentity` is enforced as the transcript snapshot\n   precondition for resume and fork.\n   For `session.list` targets that include `cwd` and `resolveSessionId`, the\n   Broker attaches `savedSession` only after managed-scope and transcript\n   identity validation. It retries one complete scan after a concurrent source\n   change; a continued omission includes `savedSessionOmission` with the\n   requested session ID and a path-free reason, never transcript contents or\n   credentials.\n2. **`SessionRouter`** owns live attachment discovery and transport. It validates\n   the exact indexed endpoint generation, keeps credentials and `SdkClient`\n   instances private, replays from the attachment cursor, reconnects after\n   rotation, and revokes stale capabilities. Provider-facing attachments expose\n   only `sessionId`, `generation`, `isCurrent()`, and `send()`.\n\n### Dispatch-boundary observers (managed router path)\n\n`SessionRouter.request(sessionId, frame, expectedGeneration?, expectedAttachment?, options)`\naccepts two optional synchronous observers in `options` — the supported\ndispatch-boundary surface for transport-close-aware consumers (#4640):\n\n- **`beforeDispatch(context)`** — fires immediately before the wire write.\n  Throwing (or any synchronous failure) aborts the dispatch with nothing on the\n  wire, no sent record, and a retryable rejection carrying the caller's own\n  error. Returning a thenable (e.g. an `async` function) is a contract\n  violation: the dispatch aborts pre-send and the eventual rejection is sunk.\n- **`onDispatch(context)`** — fires synchronously immediately after the frame is\n  handed to the socket, never before. `context.frame.id` is the exact correlated\n  identity a response must carry; from this point a transport close before the\n  response settles the request as `uncertain_after_send`. Observer throws and\n  returned-thenable rejections are sunk; they can neither displace settlement\n  nor reach the process unhandled-rejection channel.\n\nThe observer `context.frame` is a **deep-frozen, credential-redacted copy**: the\ninjected session endpoint `token` (and any other credential field) exists only\non the internal wire frame and is never handed to observer code, and mutation\nattempts throw in strict mode. The raw credential-bearing `SdkClient` remains\nunexported (`./sdk/client` is blocked in the package export map); the router is\nthe only supported path to this boundary.\n\nThere is no daemon-owned lifecycle control endpoint, provider lifecycle ledger,\nnotification-root scanner, or provider-created SessionId. Telegram `/session_*`\ncommands call the SDK lifecycle service directly. A Telegram update or topic\nreservation supplies the stable provider request identity; the Broker allocates\nthe SessionId, and Telegram CAS-binds the returned opaque ID to its presentation\nmapping.\n\n### Lifecycle trust and recovery\n\n- paired provider identity and operation capability are checked before the\n  Broker call;\n- retries reuse the same provider request key, so one request produces one\n  Broker ledger identity and at most one lifecycle effect;\n- `terminal_uncertain` remains uncertain and is reconciled from Broker ledger,\n  effect marker, process incarnation, endpoint/index, readiness, and exact\n  cleanup evidence only;\n- provider transport restart reloads cursor and presentation state, while the\n  Router reconstructs attachments from Broker state;\n- stale endpoint generations and attachments fail closed;\n- provider topic/thread/message cleanup cannot rewrite a confirmed lifecycle\n  outcome.\n\n### Phone test guide (create / close / resume from Telegram)\n\nEnd-to-end manual check once `gjc notify setup` has paired your private chat:\n\n1. Run `gjc notify setup` and start or reload the Telegram provider supervisor.\n   The supervisor owns only the Telegram poller and presentation state.\n2. Send `/session_create path <repo-dir>`, `/session_create worktree <repo>\n   <branch>`, or `/session_create dir <newdir>`. The SDK lifecycle service submits\n   one canonical Broker create request; the bot reports the credential-free\n   outcome.\n3. `/session_recent` lists verified recent managed sessions, marks whether each\n   session is connected or only saved, and includes a resume command for saved\n   sessions.\n4. `/session_close <sessionId>` asks Broker lifecycle to close the exact managed\n   session and preserves history. Inside that session's Telegram topic, omit the\n   ID and use `/session_close`.\n5. `/session_resume <sessionId|prefix>` resolves verified managed history,\n   reattaches a live session or performs canonical Broker resume, and refuses\n   ambiguous prefixes. Inside an existing session topic, including an inactive\n   topic left by a stopped session, omit the ID and use `/session_resume`.\n\nCommands are accepted only from the paired chat. Duplicate Telegram updates and\nreplayed topic reservations reuse their original request identity; they never\nallocate or spawn a second session.\n\n## Master mode surfaces\n\n`gjc --master [--scope repo|pwd|global]` launches an interactive-TUI-only\nmaster session (default scope `repo`). The master receives one bundled\noperating-guidance block appended after custom system-prompt transformation and\nexactly one scoped, no-probe broker peer snapshot immediately before its first\naccepted provider request; idle masters collect nothing.\n\nMaster orchestration is broker-routed and best effort: scoped discovery via\n`gjc sdk search` (result-level scope envelopes, exact worktree/cwd identity,\nno scope fallback) and task-seeded children via the local-only `gjc sdk spawn`\n(see docs/sdk-session-cli.md). The broker is the sole authority for\nmaster-created lifecycle: an opaque idempotency identity serializes each spawn\nbehind a durable create-or-join claim, seed delivery is Q26-correlated (never\nblindly re-sent), close mutates only an exactly re-proven substrate, and\norphaned children converge through ordinary close after\n`sdk.masterOrphanGraceMs`. Task text and master capability are transient\ndispatch inputs and never persist in any durable store, log, or output.\n",
 	"secrets.md": "# Secret Obfuscation\n\nPrevents sensitive values (API keys, tokens, passwords) from being sent to LLM providers. When enabled, secrets are replaced with authenticated placeholders before leaving the process, and restored in tool call arguments returned by the model.\n\n## Enabling\n\nDisabled by default. Toggle via `/settings` UI or directly in `config.yml`:\n\n```yaml\nsecrets:\n  enabled: true\n```\n\n## How it works\n\n1. On session startup, secrets are collected from two sources:\n   - **Environment variables** whose names match common secret patterns (`KEY`, `SECRET`, `TOKEN`, `PASSWORD`, `PASS`, `AUTH`, `CREDENTIAL`, `PRIVATE`, `OAUTH`) with values >= 8 characters\n   - **`secrets.yml` files** (see below)\n\n2. Outbound text messages to the LLM have secret values replaced with authenticated, versioned placeholders like `#GJC1_…#`.\n\n3. Session context/tool arguments returned from the model are deep-walked and obfuscation placeholders are restored to original values before display or execution.\n\nTwo modes control what happens to each secret:\n\n| Mode                  | Behavior                                        | Reversible                                      |\n| --------------------- | ----------------------------------------------- | ----------------------------------------------- |\n| `obfuscate` (default) | Replaced with authenticated `#GJC1_…#` token    | Yes (deobfuscated in tool args/session context) |\n| `replace`             | Replaced with deterministic same-length string | No (one-way)                                    |\n\nAuthenticated placeholders use a process-local key. Plain-secret tokens remain stable across sessions, reloads, and forks within the running process; after a process restart, earlier tokens intentionally remain opaque.\n\nRegex-discovered tokens are reversible only by the originating obfuscator instance. A fresh obfuscator in the same process or after restart keeps them opaque because regex matches are not reconstructed from persisted placeholders.\n\n## secrets.yml\n\nDefine custom secret entries in YAML. Two locations are checked:\n\n| Level   | Path                       | Purpose                     |\n| ------- | -------------------------- | --------------------------- |\n| Global  | `~/.gjc/agent/secrets.yml` | Plain and regex secrets across all projects |\n| Project | `<cwd>/.gjc/secrets.yml`   | Project-specific plain secrets              |\n\nProject plain entries override global plain entries with matching `content`; a global regex with the same `content` remains active. Project-scope regex entries are ignored because workspace-contained files are not trusted to supply executable regex patterns. This project scope includes `<cwd>/.gjc/secrets.yml` and any caller-supplied agent directory whose lexical or canonical path is contained within the workspace.\n\n### Schema\n\nEach entry in the array has these fields:\n\n| Field         | Type                         | Required | Description                                       |\n| ------------- | ---------------------------- | -------- | ------------------------------------------------- |\n| `type`        | `\"plain\"` or `\"regex\"`       | Yes      | Match strategy                                    |\n| `content`     | string                       | Yes      | The secret value (plain) or regex pattern (regex) |\n| `mode`        | `\"obfuscate\"` or `\"replace\"` | No       | Default: `\"obfuscate\"`                            |\n| `replacement` | string                       | No       | Custom replacement (replace mode only)            |\n| `flags`       | string                       | No       | Regex flags (regex type only)                     |\n\n### Examples\n\n#### Plain secrets\n\n```yaml\n# Obfuscate a specific API key (default mode)\n- type: plain\n  content: sk-proj-abc123def456\n\n# Replace a database password with a fixed string\n- type: plain\n  content: hunter2\n  mode: replace\n  replacement: \"********\"\n```\n\n#### Regex secrets\n\nRegex entries are supported only by agent configuration outside the current workspace (normally `~/.gjc/agent/secrets.yml`). Use `type: plain` for workspace-contained configuration.\n\n```yaml\n# Obfuscate any AWS-style key\n- type: regex\n  content: \"AKIA[0-9A-Z]{16}\"\n\n# Case-insensitive match with explicit flags\n- type: regex\n  content: \"api[_-]?key\\\\s*=\\\\s*\\\\w+\"\n  flags: \"i\"\n\n# Regex literal syntax (pattern and flags in one string)\n- type: regex\n  content: \"/bearer\\\\s+[a-zA-Z0-9._~+\\\\/=-]+/i\"\n```\n\nRegex entries always scan globally (the `g` flag is enforced automatically). The regex literal syntax `/pattern/flags` is supported as an alternative to separate `content` + `flags` fields. Escaped slashes within the pattern (`\\\\/`) are handled correctly. The sticky `y` flag is rejected because it would prevent global scanning.\n\n#### Replace mode with regex\n\n```yaml\n# One-way replace connection strings (not reversible)\n- type: regex\n  content: \"postgres://[^\\\\s]+\"\n  mode: replace\n  replacement: \"postgres://***\"\n```\n\n## Interaction with env var detection\n\nEnvironment variables are collected first, then file-defined entries are appended. File entries can cover secrets that don't live in env vars (config files, hardcoded values, etc.). If the same plain value appears in both env and file entries, the env entry's obfuscate-mode mapping is used first.\n\n## Key files\n\n- `packages/coding-agent/src/secrets/index.ts` -- loading, merging, env var collection\n- `packages/coding-agent/src/secrets/obfuscator.ts` -- `SecretObfuscator` class, placeholder generation, message obfuscation\n- `packages/coding-agent/src/secrets/regex.ts` -- regex literal parsing and compilation\n- `packages/coding-agent/src/config/settings-schema.ts` -- `secrets.enabled` setting definition\n\n## See also\n\n- [`auth-broker-gateway.md`](./auth-broker-gateway.md) -- remote credential vault and forward-proxy that keep provider OAuth refresh tokens and access tokens off developer hosts entirely (complementary to in-process obfuscation).\n",
 	"session-import.md": "# Session Import (Codex and Claude)\n\nGJC can import an external **Codex** or **Claude** session transcript into a new\nGJC session so you can continue the conversation with reconstructed context\ninstead of copying a long session by hand.\n\n## CLI surface\n\n```\n/import-session <transcript-file> [--provider codex|claude]\n```\n\n- Available on Linux in the interactive TUI and trusted local startup command path. It is\n  deliberately excluded from ACP and remote-control transports because it reads\n  an operator-selected local file.\n- `<transcript-file>` is an explicit, user-selected export/transcript file\n  (absolute or cwd-relative; quote paths containing spaces).\n- `--provider` narrows detection to one provider and fails closed on a\n  mismatch. Without it, the format is detected deterministically from the file\n  content.\n- On success, GJC creates a **new** resumable session containing the reconstructed\n  context and reports its id. The active session is not switched automatically;\n  use `/resume` to select the import.\n\nThere is intentionally no flag-less provider-directory mode: import never\nenumerates `~/.codex` / `~/.claude` or reads live provider process state. You\nalways name the exact file to import.\n\n## Supported source formats\n\nDetection is content-based and provider-neutral; unknown shapes fail with an\nactionable diagnostic instead of a speculative parse.\n\n| Format | Provider | File shape |\n| --- | --- | --- |\n| `codex-rollout-jsonl` | Codex | Codex CLI rollout transcript (`rollout-*.jsonl`): `session_meta`, `response_item` (`message`, `function_call`, `function_call_output`, `custom_tool_call*`, `local_shell_call`, `web_search_call`, `reasoning`), `event_msg`, `turn_context` records, one JSON object per line. |\n| `claude-code-jsonl` | Claude | Claude Code session transcript (`~/.claude/projects/<slug>/<uuid>.jsonl` copied out explicitly): `user` / `assistant` / `summary` / `system` records with `uuid`/`sessionId` envelopes. |\n| `claude-export-json` | Claude | claude.ai data export: one conversation object (or an array of conversations) with `uuid`, `name`, and `chat_messages[]` (`sender: \"human\" \\| \"assistant\"`, `content[]` text blocks). |\n\nNormalization rules:\n\n- User/assistant text is preserved; consecutive assistant text is merged.\n- Tool calls and results become bounded, single-line **tool/file evidence**\n  entries (`$ <tool> <summary>` / `→ <output>`) attached to the preceding\n  assistant message. Tool payloads are never executable in the new session.\n- Model-internal content (Codex `reasoning`, Claude `thinking`) and provider\n  bookkeeping (`turn_context`, `system`, `isMeta` rows, file-history snapshots)\n  are recognized and skipped by design.\n- Records that fail to parse, lack required fields, or use unknown record types\n  are **quarantined** — counted and digested (record number, byte length,\n  SHA-256) in provenance and the import summary, never silently dropped.\n- A native GJC session file is rejected with `unsupported_format` (use\n  resume/fork for those).\n\n## Provenance and identity\n\nEvery imported session persists a `custom` entry with\n`customType: \"session-import\"` recording: provider, format, source file\nbasename, source session id and title (when the format carries them), SHA-256\nand byte size of the exact imported source bytes, converter/sanitizer versions,\nmapped/quarantined/redacted/omitted counts, truncation flag, target session id,\nand import timestamp. The reconstructed context lives in a separate\n`custom_message` entry (same `customType`, `display: true`) so imported context\nis visually and structurally distinct from native GJC history, while still\nparticipating in LLM context like a handoff document.\n\nRe-importing the same file is allowed and creates another distinct session;\nthe provenance record (source hash + import timestamp) is what distinguishes\nthem. The source file is only ever read — verify with the recorded digest.\n\n## Redaction\n\nBefore any imported text enters the new session it passes a fail-closed\nsanitizer (`sanitizerVersion` in provenance): Anthropic/OpenAI/GitHub/Slack/\nGoogle/AWS keys, JWTs, bearer tokens, PEM private keys, long hex secrets,\nURL-embedded credentials, and `NAME=value` / `key: value` assignments whose\nname contains a sensitive word (key/secret/token/password/credential/…).\nMatches are replaced with `[REDACTED]`; the redaction count and rule kinds are\nreported in the summary and provenance. False positives are preferred over\nfalse negatives: a benign look-alike loses one span, a missed credential would\nleak into a durable transcript.\n\n## Bounds and diagnostics\n\n| Bound | Value | Over-limit behavior |\n| --- | --- | --- |\n| Source file size | 64 MiB | `content_too_large` with limit/observed bytes |\n| Normalized messages | 5,000 | `content_too_large` with observed count |\n| Rendered continuation context | 120,000 chars | deterministic head+tail bounding with an explicit elision marker (`omitted` count in provenance) |\n| Single message text | 16,000 chars | truncated with an ellipsis marker |\n| Tool evidence per message | 100 lines / 8 KiB | marked truncated |\n| Quarantine records | 512 retained | count kept, `quarantine.truncated` flag set |\n\nError codes are deterministic and actionable: `invalid_request`,\n`source_not_found`, `source_unreadable`, `source_changed` (retryable),\n`unsupported_format`, `format_mismatch`, `malformed_input`, `content_too_large`,\n`destination_conflict`, `io_failed`. If persistence or post-write verification\nfails, the partially created session file is removed best-effort and the\ncurrent session is never modified.\n\n## Non-goals\n\n- **No model-internal state cloning.** Reasoning traces, token telemetry,\n  provider session caches, and tool-execution state are not imported; this is\n  context reconstruction, not process migration.\n- **No live provider scraping.** Import reads only the file you name.\n- **No silent drops.** Every source record is mapped, recognized-and-skipped,\n  or quarantined with a digest; totals are reported.\n- **No mid-stream import.** `/import-session` refuses to run while a response\n  is streaming.\n",
 	"session-operations-export-share-fork-resume.md": "# Session Operations: export, dump, share, fork, resume/continue\n\nThis document describes operator-visible behavior for session export/share/fork/resume operations as currently implemented.\n\n## Implementation files\n\n- [`../src/modes/controllers/command-controller.ts`](../packages/coding-agent/src/modes/controllers/command-controller.ts)\n- [`../src/session/agent-session.ts`](../packages/coding-agent/src/session/agent-session.ts)\n- [`../src/session/session-manager.ts`](../packages/coding-agent/src/session/session-manager.ts)\n- [`../src/session-import/`](../packages/coding-agent/src/session-import/)\n- [`../src/export/html/index.ts`](../packages/coding-agent/src/export/html/index.ts)\n- [`../src/export/custom-share.ts`](../packages/coding-agent/src/export/custom-share.ts)\n- [`../src/main.ts`](../packages/coding-agent/src/main.ts)\n\n## Operation matrix\n\n| Operation                               | Entry path                | Session mutation                      | Session file creation/switch                                                       | Output artifact                                                                  |\n| --------------------------------------- | ------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ---- |\n| `/dump`                                 | Interactive slash command | No                                    | No                                                                                 | Clipboard text                                                                   |\n| `/export [path]`                        | Interactive slash command | No                                    | No                                                                                 | HTML file                                                                        |\n| `--export <session.jsonl> [outputPath]` | CLI startup fast-path     | No runtime session mutation           | No active session; reads target file                                               | HTML file                                                                        |\n| `/share`                                | Interactive slash command | No                                    | No                                                                                 | Temp HTML + share URL/gist                                                       |\n| `/star`                                | Interactive/headless slash command | Yes (append-only header metadata)      | No; marks only the active session                                               | None                                                                             |\n| `/unstar`                              | Interactive/headless slash command | Yes (append-only header metadata)      | No; clears the active session's star                                            | None                                                                             |\n| `/fork`                                 | Interactive slash command | Original unchanged; active session switches | Opens the user-prompt selector; selection creates and switches to a persistent session containing history before that prompt | Selected prompt text is restored to the editor |\n| `--fork <id                             | path>`                    | CLI startup                           | Yes after session creation                                                         | Creates a new session fork from the selected source into current cwd/session dir | None |\n| `/import-session <transcript-file> [--provider codex\\|claude]` | Interactive or trusted local startup command | No active-session mutation | Creates one independently resumable native session file | Bounded quarantine digest proof and provenance |\n| `/resume`                               | Interactive slash command | Yes (active in-memory state replaced) | Switches to selected existing session file                                         | None                                                                             |\n| `--resume`                              | CLI startup (picker)      | Yes after session creation            | Opens selected existing session file                                               | None                                                                             |\n| `--resume <id                           | path>`                    | CLI startup                           | Yes after session creation                                                         | Opens existing session; cross-project case can fork into current project         | None |\n| `--continue`                            | CLI startup               | Yes after session creation            | Opens terminal breadcrumb or most-recent session; creates new one if none exists   | None                                                                             |\n\nStars are per-transcript discovery metadata and require a persistent session; `/star` and `/unstar` reject `--no-session` runtimes. New sessions and forks start unstarred even when their parent is starred. Stars affect resume-picker and read-only dashboard ordering only; `--continue`, retention pruning, and explicit deletion keep their existing behavior.\n\n## Import external sessions\n\n`/import-session <transcript-file> [--provider codex|claude]` imports one explicit Codex CLI rollout transcript, Claude Code transcript, or claude.ai conversation export. Format detection is content-based; `--provider` narrows detection and fails closed on a mismatch. The command never scans private live process state or provider history directories.\n\nThe importer reconstructs user/assistant context and bounded tool evidence in a fresh native session. Unsupported or malformed records are never silently dropped: aggregate counts and at most 512 full-record SHA-256 quarantine proofs are retained in provenance. The source basename, provider/format, source/session identifier when available, exact source digest and byte count, converter/sanitizer versions, mapping/redaction counts, and bounded-context state are persisted. Raw provider archives are never copied into the session store.\n\nThe source is opened once with no-follow semantics and read through that retained descriptor; device, inode, link count, size, mtime, and ctime must remain exact through the complete read. Regular hard-linked exports are accepted without weakening managed-session storage, whose files remain single-linked. Secret-bearing values, Authorization/Cookie headers, terminal escapes, C0/C1 controls, bidi/zero-width controls, tool labels, IDs, titles, cwd metadata, and source diagnostics are sanitized before display or persistence.\n\nEach invocation creates one new session, verifies that it reopens with the same captured destination authority and reconstructs continuable history, then releases that authority. Imports are refused while the current session is streaming. Imported sessions do not replace the active session automatically; select the new session with `/resume`.\n\nThe command is available only on Linux in the interactive TUI and trusted local startup command path. It is neither advertised nor dispatched over ACP or remote-control transports.\n## Export and dump\n\n### `/export [outputPath]` (interactive)\n\nFlow:\n\n1. `InputController` routes `/export...` to `CommandController.handleExportCommand`.\n2. The command splits on whitespace and uses only the first argument after `/export` as `outputPath`.\n3. `AgentSession.exportToHtml()` calls `exportSessionToHtml(sessionManager, state, { outputPath, themeName })`.\n4. On success, UI shows path and opens the file in browser.\n\nBehavior details:\n\n- `--copy`, `clipboard`, and `copy` arguments are explicitly rejected with a warning to use `/dump`.\n- Export embeds session header/entries/leaf plus current `systemPrompt` and tool descriptions from agent state.\n- No session entries are appended during export.\n\nCaveat:\n\n- Argument parsing is whitespace-based (`text.split(/\\s+/)`), so quoted paths with spaces are not preserved as a single path by this command path.\n\n### `--export <inputSessionFile> [outputPath]` (CLI)\n\nFlow in `main.ts`:\n\n1. Handled early (before interactive/session startup).\n2. Calls `exportFromFile(inputPath, outputPath?)`.\n3. `SessionManager.open(inputPath)` loads entries, then HTML is generated and written.\n4. Process prints `Exported to: ...` and exits.\n\nBehavior details:\n\n- Missing input file surfaces as `File not found: <path>`.\n- This path does not create an `AgentSession` and does not mutate any running session.\n\n### `/dump` (interactive clipboard export)\n\nFlow:\n\n1. `CommandController.handleDumpCommand()` calls `session.formatSessionAsText()`.\n2. If empty string, reports `No messages to dump yet.`\n3. Otherwise copies to clipboard via native `copyToClipboard`.\n\nDump content includes:\n\n- System prompt\n- Active model/thinking level\n- Tool definitions + parameters\n- User/assistant messages\n- Thinking blocks and tool calls\n- Tool results and execution blocks (except `excludeFromContext` bash/python entries)\n- Custom/hook/file mention/branch summary/compaction summary entries\n\nNo session persistence changes are made by dumping.\n\n## Share\n\n`/share` is interactive-only and always starts by exporting current session to a temp HTML file.\n\n### Phase 1: temp export\n\n- Temp file path: `${os.tmpdir()}/${Snowflake.next()}.html`\n- Uses `session.exportToHtml(tmpFile)`\n- If export fails (notably in-memory sessions), share ends with error.\n\n### Phase 2: custom share handler (if present)\n\n`loadCustomShare()` checks `~/.gjc/agent` for first existing candidate:\n\n- `share.ts`\n- `share.js`\n- `share.mjs`\n\nRequirements:\n\n- Module must default-export a function `(htmlPath) => Promise<CustomShareResult | string | undefined>`.\n\nIf present and valid:\n\n- UI enters `Sharing...` loader state.\n- Handler result interpretation:\n  - string => treated as URL, shown and opened\n  - object => `url` and/or `message` shown; `url` opened\n  - `undefined`/falsy => generic `Session shared`\n- Temp file is removed after completion.\n\nCritical fallback behavior:\n\n- If custom handler exists but loading fails, command errors and returns.\n- If custom handler executes and throws, command errors and returns.\n- In both failure cases, it **does not** fall back to GitHub gist.\n- Gist fallback happens only when no custom share script exists.\n\n### Phase 3: default gist fallback\n\nOnly when no custom share handler is found:\n\n1. Validates `gh auth status`.\n2. Shows `Creating gist...` loader.\n3. Runs `gh gist create --public=false <tmpFile>`.\n4. Parses gist URL, derives gist id, builds preview URL `https://gistpreview.github.io/?<id>`.\n5. Shows both preview and gist URLs; opens preview.\n\nCancellation/abort semantics in share:\n\n- Loader has `onAbort` hook that restores editor UI and reports `Share cancelled`.\n- The underlying `gh gist create` command is not passed an abort signal in this code path; cancellation is UI-level and checked after command returns.\n\n## Fork\n\nInteractive `/fork` starts an independent continuation from a selected user prompt. It reuses the existing user-message selector and session-branch lifecycle rather than duplicating the whole active transcript.\n\n### Preconditions and immediate guards\n\n- All prompt-fork entry points (`/fork`, `app.session.fork`, and branch-configured double Escape) refuse active responses, compaction, foreground Bash/Python execution, or pending prompt submission.\n- They require a persistent active session. A `--no-session` runtime is refused because the result must be independently resumable.\n\n### Interactive flow\n\n1. `/fork` opens the same user-prompt selector used by the ordinary user-message branch flow. Once admitted, opening the picker closes any active `/btw` side chat.\n2. Cancelling the selector leaves the active session and transcript unchanged; the closed side chat is not reopened.\n3. Selecting a user prompt runs `AgentSession.branch()` at that prompt boundary. Its `session_before_branch` hook may cancel the operation; a successful switch emits `session_branch`.\n4. A new persistent session is created with the history before the selected prompt, and the TUI switches to it.\n5. The selected prompt text is restored to the editor for editing. It is not submitted automatically. Session-specific TODOs, title/status, and other identity-bound UI state are synchronized to the child.\n\nIf branching fails before the successor is committed, the original session remains active. If a later restoration step fails after commit, the UI is reconciled to the already-active child and reports that the fork was created but restoration failed; it does not pretend the original session is still active.\n\nThe original session file and transcript remain unchanged. The new session keeps the same cwd and works against the same files, and the command itself does not modify those files; `/fork` does not create or switch a Git branch or worktree. `/tree` remains same-session navigation.\n\n### Low-level full-session `AgentSession.fork()`\n\nThe low-level `AgentSession.fork()` API remains a whole-session duplicate operation and is not the interactive `/fork` prompt-selection flow:\n\n1. Emits `session_before_switch` with `reason: \"fork\"` (cancellable).\n2. Flushes pending writes.\n3. Calls `SessionManager.fork()`.\n4. Copies the artifacts directory from the old session namespace to the new namespace (best-effort; non-ENOENT copy failures are logged, not fatal).\n5. Updates `agent.sessionId`.\n6. Emits `session_switch` with `reason: \"fork\"`.\n\n`SessionManager.fork()` requires persistent mode and an existing session file. It creates a new session id and JSONL path, rewrites the header with a new id and timestamp plus the unchanged cwd and previous session id as `parentSession`, and retains all non-header entries.\n\nIn-memory `SessionManager.fork()` returns `undefined`, so low-level `AgentSession.fork()` returns `false`.\n\n### CLI `--fork <id|path>`\n\nStartup `--fork` is resolved before normal session creation:\n\n1. `--fork` is rejected with `--no-session`.\n2. Path-like values (`/`, `\\`, or `.jsonl`) call `SessionManager.forkFrom(path, cwd, sessionDir)`.\n3. Other values resolve like resumable session ids via current scope and then global search when allowed.\n4. The forked file is created in the current cwd/session-dir scope and becomes the active session manager for startup.\n\n### Managed directory migration during session operations\n\nDefault persistent creates and forks write only to the managed v2 workspace scope. A resume/list operation may surface a validated legacy candidate for the same canonical workspace identity; with `session.directoryMigration: \"copy-retain\"`, the migration path copies it into v2 and retains the source. It never replaces an existing destination, and a migration tombstone prevents completed/retired legacy work from being retried as fresh work. `disabled` leaves legacy data in place.\n\nThe migration path does not delete legacy sessions or artifacts automatically. It fails closed on conflicting bindings, changed source identity, unsafe artifact trees, or unavailable owner-only path security; it does not claim authentication or protection against hostile concurrent filesystem races. Explicit `--session-dir` remains an operator-selected override.\n\n## Resume and continue\n\n## Interactive `/resume`\n\nFlow:\n\n1. Opens session selector populated via `SessionManager.list(currentCwd, currentSessionDir)`.\n2. On selection, `SelectorController.handleResumeSession(sessionPath)` calls `session.switchSession(sessionPath)`.\n3. UI clears/rebuilds chat and todos, then reports `Resumed session`.\n\nNotes:\n\n- This picker only lists sessions in the current session directory scope.\n- It does not use global cross-project search.\n\n## CLI `--resume`\n\n### `--resume` (no value)\n\n- `main.ts` lists sessions for current cwd/sessionDir and opens picker.\n- Selected path is opened with `SessionManager.open(selectedPath)` before session creation.\n\n### `--resume <value>`\n\n`createSessionManager()` resolution order:\n\n1. If value looks like path (`/`, `\\`, or `.jsonl`), open directly.\n2. Else treat as id prefix:\n   - search current scope (`SessionManager.list(cwd, sessionDir)`)\n   - if not found and no explicit `sessionDir`, search global (`SessionManager.listAll()`)\n\nCross-project id match behavior:\n\n- If matched session cwd differs from current cwd, CLI asks:\n  - `Session found in different project ... Fork into current directory? [y/N]`\n- On yes: `SessionManager.forkFrom(match.path, cwd, sessionDir)` creates a new local forked file.\n- On no/non-TTY default: command errors.\n\n## CLI `--continue`\n\n`SessionManager.continueRecent(cwd, sessionDir)`:\n\n1. Resolves session dir for current cwd.\n2. Reads terminal-scoped breadcrumb first.\n3. Falls back to most recently modified session file.\n4. Opens found session; if none exists, creates new session.\n\nThis is startup-only behavior; there is no interactive `/continue` slash command.\n\n## How session switching actually mutates runtime state\n\n`AgentSession.switchSession(sessionPath)` does the runtime transition used by resume-like operations:\n\n1. Emit `session_before_switch` with `reason: \"resume\"` and `targetSessionFile` (cancellable).\n2. Disconnect agent event subscription and abort in-flight work.\n3. Clear queued steering/follow-up/next-turn messages.\n4. Flush current session manager writes.\n5. `sessionManager.setSessionFile(sessionPath)` and update `agent.sessionId`.\n6. Build session context from loaded entries.\n7. Emit `session_switch` with `reason: \"resume\"`.\n8. Replace agent messages from context.\n9. Restore model (if available in current registry).\n10. Restore or initialize thinking level.\n11. Reconnect agent event subscription.\n\nNo new session file is created by `switchSession()` itself.\n\n## Event emissions and cancellation points\n\n### Switch/fork lifecycle hooks\n\nFor `newSession`, `fork`, and `switchSession`:\n\n- Before event: `session_before_switch`\n  - reasons: `new`, `fork`, `resume`\n  - cancellable by returning `{ cancel: true }`\n- After event: `session_switch`\n  - same reason set\n  - includes `previousSessionFile`\n\n`ExtensionRunner.emit()` returns early on the first cancelling before-event result.\n\n### Custom tool `onSession` behavior\n\nSDK bridges extension session events to custom tool `onSession` callbacks:\n\n- `session_switch` -> `onSession({ reason: \"switch\", previousSessionFile })`\n- `session_branch` -> `reason: \"branch\"`\n- `session_start` -> `reason: \"start\"`\n- `session_tree` -> `reason: \"tree\"`\n- `session_shutdown` -> `reason: \"shutdown\"`\n\nThese callbacks are observational; they do not cancel switch/fork.\n\n### Other cancellation surfaces relevant to this doc\n\n- `/fork` is blocked while a response, compaction, foreground Bash/Python execution, or prompt submission is active.\n- `/resume` selector can be cancelled by user closing selector.\n- Cross-project `--resume <id>` can be cancelled by declining fork prompt.\n- `/share` has UI abort path (`Share cancelled`) for gist flow; it does not wire process-kill semantics for `gh gist create` in this code path.\n\n## Non-persistent (in-memory) session behavior\n\nWhen session manager is created with `SessionManager.inMemory()` (`--no-session`):\n\n- Session file path is absent.\n- `/export` and `/share` fail with `Cannot export in-memory session to HTML` (propagated to command error UI).\n- `/fork` fails because `SessionManager.fork()` requires persistence.\n- `/dump` still works because it serializes in-memory agent state.\n- CLI resume/continue semantics are bypassed if `--no-session` is set, because manager creation returns in-memory immediately.\n\n## Known implementation caveats (as of current code)\n\n- `SelectorController.handleResumeSession()` does not check the boolean result from `session.switchSession(...)`; a hook-cancelled switch can still proceed through UI \"Resumed session\" repaint/status path.\n- `/share` custom-share failures do not degrade to default gist fallback; they terminate the command with error.\n- `/export` argument tokenization is simplistic and does not preserve quoted paths with spaces.\n",
@@ -114,19 +115,19 @@ export const EMBEDDED_DOCS: Readonly<Record<string, string>> = {
 	"telemetry.md": "# Privacy-preserving telemetry\n\nGJC includes a minimal update and adoption telemetry path. It is **disabled by default** and sends nothing unless enabled in the user configuration.\n\n## What can be sent\n\nEvents use schema version `1` and a fixed allowlist. The current event names are:\n\n- `update_check_started`\n- `update_check_completed`\n- `update_install_started`\n- `update_install_completed`\n- `update_install_failed`\n\nAn event may contain only:\n\n- the schema version;\n- the fixed event name;\n- a locally generated random UUIDv4 install ID;\n- an ISO timestamp;\n- the stable/nightly update channel;\n- a fixed result (`available`, `up_to_date`, `installed`, `failed`, or `skipped`); and\n- a fixed update method (`bun`, `npm`, `binary`, or `migrate`).\n\nUnknown fields are discarded. Values outside the allowlist are rejected before transport.\n\n## What is never collected\n\nTelemetry never serializes prompts, command-line arguments, paths, environment variables, secrets, account identity, model or provider identity, repository identity, arbitrary error text, hostname, username, machine ID, or IP-derived identity. The install ID is generated randomly and is not derived from device, network, account, or repository data.\n\nThe install ID is stored locally in the user agent directory as `telemetry-install-id` with private file permissions. A malformed existing ID fails closed rather than being replaced.\n\n## Controls and kill switch\n\nEnable or disable the feature with the normal settings surface:\n\n```sh\ngjc config set telemetry.enabled true\ngjc config set telemetry.enabled false\ngjc config get telemetry.enabled\n```\n\nThe setting defaults to `false`. The emergency process-level kill switch always wins over the setting:\n\n```sh\nGJC_DISABLE_TELEMETRY=1 gjc update\n```\n\nThe kill switch accepts `1`, `true`, `yes`, or `on`. It is evaluated before an event is scheduled.\n\n## Transport behavior\n\nEvents are sent as HTTPS `POST` requests to `https://telemetry.gajae.dev/v1/events`. Transport is best effort: calls are scheduled without blocking the update command, at most two requests are in flight, and each request is bounded by a 1500 ms timeout. Disabled telemetry, queue saturation, offline failures, timeouts, non-success responses, and serializer failures do not affect GJC behavior and are not printed as arbitrary error text.\n\nNo local event queue or transcript is retained. Server-side retention and aggregate reporting are outside the client contract and must be documented by the service before production collection is enabled.\n",
 	"terminal-app-integrations.md": "# Terminal app integrations (Paseo · Orca · T3 Code)\n\nGJC is a terminal-first coding agent, but it does not have to be the outermost window. Three external\n\"agent shells\" — desktop/mobile orchestrators that run agents for you — can drive GJC today, at three\ndifferent levels of support.\n\n| Host | Support | How GJC is driven | Setup |\n| --- | --- | --- | --- |\n| [Paseo](https://paseo.sh) | ★★★★★ | ACP provider (`gjc acp`), managed by GJC's own installer | [`gjc setup paseo`](#paseo) |\n| [Orca](https://onorca.dev) | ★★★★☆ | Custom CLI agent — Orca launches `gjc` in a worktree terminal | [manual, one field](#orca) |\n| [T3 Code](https://t3.codes) | ★★★☆☆ (experimental) | No built-in GJC harness upstream yet; drive GJC beside it | [read this first](#t3-code) |\n\nRatings describe how much of GJC's surface the host actually reaches — model/mode pickers, permission\nprompts, cancel semantics, session listing — not how good the host is.\n\n---\n\n## Paseo\n\n[Paseo](https://github.com/getpaseo/paseo) is an ACP client, and GJC's ACP surface is\nconformance-tested against the pinned external `acpx@0.13.0` `acp-core-v1` corpus, so this is the\ndeepest integration GJC has with any external app.\n\n### Install\n\n```sh\ngjc setup paseo             # register GJC in $PASEO_HOME/config.json (default ~/.paseo/config.json)\npaseo daemon restart        # Paseo caches config in a long-lived daemon\npaseo provider ls           # gjc must read `available`, not `error`\n```\n\nGJC is also proposed for Paseo's in-app ACP provider catalog ([getpaseo/paseo#3471](https://github.com/getpaseo/paseo/pull/3471)), which\nwould make even this command unnecessary for new users.\n\n`gjc setup paseo` writes exactly one provider entry — an absolute `gjc acp` command,\n`GJC_ACP_PERMISSION_MODE=prompt`, and the `acp` base — under `agents.providers.gjc`, and it bridges\nPaseo's orchestration skills into GJC skill discovery. Paseo owns those files, so every write is\nconservative:\n\n- a round-trip fidelity self-check refuses to touch a config GJC cannot reproduce byte-for-byte;\n- publication is guarded by a compare-and-swap, with a mode-0600 backup beside the original\n  (`$PASEO_HOME/config.json`, default `~/.paseo/config.json`, holds a credential that never reaches\n  stdout, stderr, `--json`, or a diff);\n- a durable, credential-free intent record makes an interrupted run recoverable;\n- the Paseo daemon is never restarted for you.\n\n### Verify and roll back\n\n```sh\ngjc setup paseo --check          # diagnose: pass / stale / drift / skipped\ngjc setup paseo --check --json   # machine-readable, exit code carries the verdict\ngjc setup paseo --remove         # roll back only what GJC itself created\n```\n\n`--remove` deletes a key only when GJC's own provenance ledger recorded creating it *and* the value\nstill matches what GJC wrote, so a hand-edited entry always survives. `~/.agents/skills` is treated as\nread-only.\n\n### Extra providers for model profiles\n\n```sh\ngjc setup paseo --mpreset codex-eco    # registers an additional `gjc-codex-eco` provider\n```\n\nModel profiles are also selectable without a second provider: GJC advertises each usable profile to\nACP clients as a synthetic model under the reserved `gajae-code/<profile>` namespace (e.g.\n`gajae-code/codex-eco`), so Paseo's ordinary **Model** picker can switch profiles for the live session.\n\n### Announcing interactive sessions\n\nAn interactive `gjc` session can be driven from the terminal and Paseo at the same time. Paseo prompts\nreach the running session, and assistant text, thinking, and tool calls stream back to the client that\nsubmitted them. Paseo 0.7.2 does not render GJC's running/idle metadata, so its displayed status may\nremain `idle` during terminal work. Automatic announcement is **opt-in and off by default**:\n\n```sh\ngjc config set paseo.autoImport true    # or Settings → Interaction → \"Announce Sessions to Paseo\"\n```\n\nWhen a registered GJC provider and a reachable Paseo daemon are available, startup runs the equivalent\nof:\n\n```sh\npaseo import --provider <provider-key> --cwd /path/to/repo <session-id>\n```\n\nThe base `gjc` provider is preferred, then the first enabled `gjc-<preset>`. GJC verifies broker\nliveness before importing, retries an unavailable daemon every 30 seconds for about ten minutes, and\ncancels pending or active work when the setting is disabled in the running Settings UI. Duplicate\nimports and password-required daemons are quiet skips; export `PASEO_PASSWORD` for a protected daemon.\nOther import failures appear as a nonblocking status and in the debug log.\n\nWhen the live session has an active model preset, the base provider inherits that session's preset\nin the ACP **Preset** picker; a separate `gjc-<preset>` provider is not required. A configured default\nalone does not turn a session using a directly selected model into a preset session.\n\nPrimary control follows the host's startup surface, not the latest attachment. A CLI-started session\nkeeps terminal permission prompts and UI; attaching Paseo does not grant it authority to close or\ndelete the underlying session. A Paseo/SDK-started host keeps ACP provider and lifecycle authority\nwhen Paseo reloads or reconnects. Secondary clients can still submit prompts and change the model\npreset; per-turn prompt and cancellation ownership is unchanged.\nACP attachments require the host's `runtime.capabilities` response to include this startup-surface\nprovenance; restart an older host before attaching so ownership is never inferred from an incomplete\ncapability response.\n\nThat boundary is observable. Closing a CLI-primary session from the editor ends your attachment —\nproviders, subscriptions and any in-flight turn are released — while the terminal session itself keeps\nrunning; a prompt sent afterwards fails instead of reaching the host. Deleting one is refused rather\nthan silently ignored, because the deletion would never happen. Close and delete the session from its\nown terminal, or from the client that started it.\n\n### Lifecycle: GJC creates, you delete\n\nGJC adds one Paseo entry per new session and never deletes or rewrites it. `gjc -c` preserves the\nsession id and reuses its imported entry. Ended sessions remain listed until you prune them:\n\n```sh\npaseo ls                  # find the stale ids\npaseo delete <agent-id>\n```\n\nLeave `paseo.autoImport` off to manage imports manually. `paseo run --provider gjc` and manual imports\nwork regardless of the setting.\n\n### Run it\n\n```sh\npaseo run --provider gjc --cwd /path/to/repo --wait-timeout 3m \"your prompt\"\npaseo logs <agent-id>     # rendered transcript\npaseo ls                  # running / idle / error\npaseo stop <agent-id>     # ACP session/cancel\npaseo delete <agent-id>\n```\n\nPaseo lists **Gajae Code** with GJC's model catalog (filtered to providers with usable stored\ncredentials), Default/Plan modes, and thinking levels, because GJC emits the spec-defined `category`\non the `mode`, `model`, and `thought_level` select options.\n\n### Cancel semantics\n\n`paseo stop` sends an ACP `session/cancel`, which by default stops **only the current turn** — owned\nbackground work (subagents, background jobs) keeps running. To make a stop terminate exactly the work\nGJC owns, add to the provider's `env` entry and restart the Paseo daemon:\n\n```json\n\"env\": { \"GJC_ACP_PERMISSION_MODE\": \"prompt\", \"GJC_ACP_ABORT_SCOPE\": \"owned\" }\n```\n\n### Troubleshooting\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| `gjc` reads `error` in `paseo provider ls` | daemon still holds the pre-install config | `paseo daemon restart` |\n| `gjc setup paseo --check` reports `stale` | config is correct, daemon has not reloaded | `paseo daemon restart` |\n| `gjc setup paseo --check` reports `drift` | the entry was edited by hand or by another tool | reconcile manually, or `--remove` then re-install |\n| `failed to create agent` in `$PASEO_HOME/daemon.log` (default `~/.paseo/daemon.log`) | `gjc` not resolvable from the daemon's PATH | re-run `gjc setup paseo` so the absolute path is rewritten |\n| Permission-gated tools never prompt | `GJC_ACP_PERMISSION_MODE` overridden | set it back to `prompt` in the provider `env` |\n| Nothing appears in Paseo after `gjc` | `paseo.autoImport` is off (the default) | `gjc config set paseo.autoImport true` |\n| Announcement reports `daemon-auth-required` | the daemon requires a password | export `PASEO_PASSWORD`, or import manually |\n\nAnnouncement details are recorded at debug level:\n\n```sh\ngrep 'Paseo session announcement' ~/.gjc/logs/gjc.$(date +%F).log | tail -1\n```\n\nGJC reads no Paseo credential file; `paseo import` inherits the session environment.\n\nDeeper reading: [ACP local development loop](./acp-local-development.md) ·\n[External-control readiness](./external-control-readiness.md#paseo-custom-agent) ·\n[Environment variables](./environment-variables.md#11-acp-permission-handling).\n\n---\n\n## Orca\n\n[Orca](https://github.com/stablyai/orca) is a worktree ADE: it runs a fleet of agents side by side,\neach in its own git worktree, with diff review, a mobile companion, and SSH/remote worktrees. Its agent\npicker \"just launches a process in a terminal\", so **any** CLI agent works — including `gjc`.\n\nGJC is not (yet) in Orca's preconfigured agent list, so you add it once as a custom agent. The\nupstream registry entry is proposed in [stablyai/orca#15025](https://github.com/stablyai/orca/pull/15025); until it lands, use the custom\nagent below.\n\n### Setup\n\n1. Install and authenticate GJC on the machine Orca runs agents on:\n\n   ```sh\n   curl -fsSL https://raw.githubusercontent.com/Yeachan-Heo/gajae-code/v0.15.3/scripts/install.sh -o gjc-install.sh\n   sh gjc-install.sh\n   gjc auth\n   ```\n\n   To pick a newer installer, change `v0.15.3` to the release tag you want (see [docs/install.md](install.md)).\n\n2. In Orca, open **Settings → Agents** and add a custom agent:\n\n   | Field | Value |\n   | --- | --- |\n   | Name | `Gajae Code` |\n   | Command | `gjc` |\n   | Arguments | *(empty — bare `gjc` starts the TUI in the worktree cwd)* |\n\n3. Create a worktree, pick **Gajae Code** in the agent combobox, and start prompting.\n\nOrca pre-fills a permission-bypass flag for agents that expose one. **GJC has none by design** — leave\nthe argument list empty. GJC's own approval gates (`bash`, `eval`, destructive file operations, workflow\napprovals) stay in force inside the worktree, which is the point: the worktree is disposable, the\napproval record is not.\n\n### What you get, and what you do not\n\n- **You get:** true parallelism across worktrees, Orca's diff viewer and AI-diff annotation, terminal\n  splits, the mobile companion, and SSH worktrees — all with GJC running as the agent.\n- **You do not get (yet):** Orca's deep-integration features that require per-agent adapters — usage /\n  rate-limit tracking, account hot-swap, agent hooks, and native status. Those need Gajae Code in Orca's\n  built-in registry ([PR](https://github.com/stablyai/orca/pull/15025)).\n\n### Driving several GJC worktrees at once\n\nOrca's own CLI (`orca worktree create`, `snapshot`, …) composes with GJC's `--worktree` launcher and the\n`gjc sdk session` CLI. If you want a controller — not a human — fanning work across GJC sessions, prefer\nthe [Coordinator MCP bridge](./hermes-mcp-bridge.md) over terminal scraping.\n\n---\n\n## T3 Code\n\n[T3 Code](https://github.com/pingdotgg/t3code) is an agent-harness control surface with an excellent\nmobile app: a local server on your machine plus iOS/Android/web/desktop clients that drive agent CLIs.\n\n**Status: experimental.** Upstream T3 Code ships harnesses for Codex, Claude Code, Cursor CLI, Grok Build\nand OpenCode only. There is no GJC harness in T3 Code today and no released bridge package, so nothing\nhere is a one-command install yet. Treat this section as the honest state of the art, not a supported path.\n\n### What works today\n\nRun T3 Code's server for the agents it does support, and drive GJC in parallel through its own machine\nsurfaces on the same box:\n\n```sh\nnpx t3@latest              # T3 Code server + local web app\ngjc sdk session list       # GJC's own session control surface, unrelated to T3\n```\n\nFor phone access to GJC itself — questions, approvals, and prompts from a mobile device — GJC already\nships first-class remote surfaces that do not depend on T3 Code:\n\n- [Telegram onboarding](./telegram-onboarding.md) — answer the agent from your phone\n- [Discord onboarding](./discord-onboarding.md)\n- [Bot / external controller integration](./bot-integration.md)\n- [SDK & wire protocol](./sdk.md) · [SDK session CLI](./sdk-session-cli.md)\n\n### What native support will look like\n\nGJC exposes a conformance-tested ACP agent (`gjc acp`) with streaming session updates, spec-shaped\npermission requests, and cancel semantics — the same surface Paseo consumes. A T3 Code provider only has\nto map T3's thread/turn/permission model onto that surface. That work is proposed upstream in\n[pingdotgg/t3code#7290](https://github.com/pingdotgg/t3code/discussions/7290) — a bespoke driver is a large change in T3 Code's Effect-TS provider\nlayer, so the discussion asks whether they want a `gjc` driver or a generic ACP driver first. Until\nsomething lands there, `gjc` in T3 Code is not supported.\n\nIf you are building your own bridge, start from\n[External-control readiness](./external-control-readiness.md) and\n[ACP local development](./acp-local-development.md), and use `GJC_ACP_PERMISSION_MODE` to map permission\nmodes rather than inventing CLI flags — GJC has no permission-bypass flag.\n\n---\n\n## Choosing between them\n\n- Want the deepest, best-supported integration with model/mode/thinking pickers and real permission\n  prompts → **Paseo**.\n- Want many GJC sessions racing in isolated worktrees with first-class diff review → **Orca**.\n- Want GJC on your phone right now → skip the host apps and use GJC's own\n  [Telegram](./telegram-onboarding.md) or [bot](./bot-integration.md) surfaces.\n",
 	"theme.md": "# Theming Reference\n\nThis document describes how theming works in the coding-agent today: schema, loading, runtime behavior, and failure modes.\n\n## What the theme system controls\n\nThe theme system drives:\n\n- foreground/background color tokens used across the TUI\n- markdown styling adapters (`getMarkdownTheme()`)\n- selector/editor/settings list adapters (`getSelectListTheme()`, `getEditorTheme()`, `getSettingsListTheme()`)\n- symbol preset + symbol overrides (`unicode`, `nerd`, `ascii`)\n- syntax highlighting colors used by native highlighter (`@gajae-code/natives`)\n- status line segment colors\n\nPrimary implementation: `src/modes/theme/theme.ts`.\n\n## Theme JSON shape\n\nTheme files are JSON objects validated against the runtime schema in `theme.ts` (`ThemeJsonSchema`) and mirrored by `src/modes/theme/theme-schema.json`.\n\nTop-level fields:\n\n- `name` (required)\n- `colors` (required; all color tokens required)\n- `vars` (optional; reusable color variables)\n- `export` (optional; HTML export colors)\n- `symbols` (optional)\n  - `preset` (optional: `unicode | nerd | ascii`)\n  - `overrides` (optional: key/value overrides for `SymbolKey`)\n\nColor values accept:\n\n- hex string (`\"#RRGGBB\"`)\n- 256-color index (`0..255`)\n- variable reference string (resolved through `vars`)\n- empty string (`\"\"`) meaning terminal default (`\\x1b[39m` fg, `\\x1b[49m` bg)\n\n## Required color tokens (current)\n\nAll tokens below are required in `colors`.\n\n### Core text and borders (11)\n\n`accent`, `border`, `borderAccent`, `borderMuted`, `success`, `error`, `warning`, `muted`, `dim`, `text`, `thinkingText`\n\n### Background blocks (7)\n\n`selectedBg`, `userMessageBg`, `customMessageBg`, `toolPendingBg`, `toolSuccessBg`, `toolErrorBg`, `statusLineBg`\n\n### Message/tool text (5)\n\n`userMessageText`, `customMessageText`, `customMessageLabel`, `toolTitle`, `toolOutput`\n\n### Markdown (10)\n\n`mdHeading`, `mdLink`, `mdLinkUrl`, `mdCode`, `mdCodeBlock`, `mdCodeBlockBorder`, `mdQuote`, `mdQuoteBorder`, `mdHr`, `mdListBullet`\n\n### Tool diff + syntax highlighting (12)\n\n`toolDiffAdded`, `toolDiffRemoved`, `toolDiffContext`,\n`syntaxComment`, `syntaxKeyword`, `syntaxFunction`, `syntaxVariable`, `syntaxString`, `syntaxNumber`, `syntaxType`, `syntaxOperator`, `syntaxPunctuation`\n\n### Mode/thinking borders (8)\n\n`thinkingOff`, `thinkingMinimal`, `thinkingLow`, `thinkingMedium`, `thinkingHigh`, `thinkingXhigh`, `bashMode`, `pythonMode`\n\n### Status line segment colors (14)\n\n`statusLineSep`, `statusLineModel`, `statusLinePath`, `statusLineGitClean`, `statusLineGitDirty`, `statusLineContext`, `statusLineSpend`, `statusLineStaged`, `statusLineDirty`, `statusLineUntracked`, `statusLineOutput`, `statusLineCost`, `statusLineSubagents`\n\n## User-produced status content\n\nThe `command` segment is the supported way to put user-produced content in the\nstatus line. It is configured alongside a custom segment layout:\n\n```yaml\nstatusLine:\n  preset: custom\n  leftSegments: [model, command]\n  segmentOptions:\n    command:\n      command: \"git branch --show-current\"\n      refreshMs: 5000\n      timeoutMs: 500\n      maxLength: 80\n```\n\nThe command and its active-segment opt-in are read from the user/global settings\nlayer only; project-scoped settings cannot cause a command to execute. The\ncommand runs in the configured shell from the project directory. GJC starts it\nin the background and renders the last successful value while the next refresh\nis pending, so a slow command cannot block TUI rendering. Each run has a bounded\ntimeout (50–10,000 ms), stdout is capped before decoding, and the displayed\nvalue is ANSI/control-character sanitized and width-bounded (1–256 columns). A\ntimeout, non-zero exit, or launch failure leaves the last value in place; when\nno value exists, the segment shows a placeholder and records a bounded logger\ndiagnostic. The normal status-line `maxRows` layout still owns final row fitting\nand overflow behavior.\n\nThis is an explicit arbitrary-command execution boundary: review the command in\nuser/global configuration before enabling the segment. The command is not\nexecuted unless `command` is present in the user/global active `leftSegments` or\n`rightSegments` list.\n\n## Optional tokens\n\n### `export` section (optional)\n\nUsed for HTML export theming helpers:\n\n- `export.pageBg`\n- `export.cardBg`\n- `export.infoBg`\n\nIf omitted, export code derives defaults from resolved theme colors.\n\n### `symbols` section (optional)\n\n- `symbols.preset` sets a theme-level default symbol set.\n- `symbols.overrides` can override individual `SymbolKey` values.\n\nRuntime precedence:\n\n1. settings `symbolPreset` override (if set)\n2. theme JSON `symbols.preset`\n3. fallback `\"unicode\"`\n\nInvalid override keys are ignored and logged (`logger.debug`).\n\n## Built-in vs custom theme sources\n\nTheme lookup order (`loadThemeJson`):\n\n1. built-in embedded themes (`red-claw.json`, `blue-crab.json`, `claude-code.json`, `codex.json`, and `opencode.json` compiled into `defaultThemes`)\n2. custom theme file: `<customThemesDir>/<name>.json`\n\nCustom themes directory comes from `getCustomThemesDir()`:\n\n- default: `~/.gjc/agent/themes`\n- overridden by `GJC_CODING_AGENT_DIR` (`$GJC_CODING_AGENT_DIR/themes`)\n\n`getAvailableThemes()` returns merged built-in + custom names, sorted, with built-ins taking precedence on name collision.\n\n## Loading, validation, and resolution\n\nFor custom theme files:\n\n1. read JSON\n2. parse JSON\n3. validate against `ThemeJsonSchema`\n4. resolve `vars` references recursively\n5. convert resolved values to ANSI by terminal capability mode\n\nValidation behavior:\n\n- missing required color tokens: explicit grouped error message\n- bad token types/values: validation errors with JSON path\n- unknown theme file: `Theme not found: <name>`\n\nVar reference behavior:\n\n- supports nested references\n- throws on missing variable reference\n- throws on circular references\n\n## Terminal color mode behavior\n\nColor mode detection (`detectColorMode`):\n\n- `COLORTERM=truecolor|24bit` => truecolor\n- `WT_SESSION` => truecolor\n- `TERM` in `dumb`, `linux`, or empty => 256color\n- otherwise => truecolor\n\nConversion behavior:\n\n- hex -> `Bun.color(..., \"ansi-16m\" | \"ansi-256\")`\n- numeric -> `38;5` / `48;5` ANSI\n- `\"\"` -> default fg/bg reset\n\n## Runtime switching behavior\n\n### Initial theme (`initTheme`)\n\n`main.ts` initializes theme with settings:\n\n- `symbolPreset`\n- `colorBlindMode`\n- `theme.dark`\n- `theme.light`\n\nAuto theme slot selection uses terminal appearance in this order:\n\n1. terminal-reported OSC 11 background luminance, unless the macOS/Zellij fallback path is active\n2. `COLORFGBG` background index (`< 8` => dark, `>= 8` => light)\n3. macOS appearance fallback only for the known-broken macOS/Zellij OSC 11 path\n4. dark slot fallback\n\nBuilt-in theme note: `red-claw` is the default dark GJC theme, and `blue-crab` is the default light-slot theme. Both are crustacean brand themes with separate semantic error/warning/diff-removal tokens and crab-oriented symbol overrides. Three additional bundled migration themes — `claude-code`, `codex`, and `opencode` — mirror the look of those tools for easy eye-migration. All three are dark-classified and recommended for `theme.dark`, but are selectable in either slot; they keep GJC's default symbol identity (no crab-symbol overrides).\n\nCurrent defaults from settings schema:\n\n- `theme.dark = \"red-claw\"`\n- `theme.light = \"blue-crab\"`\n- `symbolPreset = \"unicode\"`\n- `colorBlindMode = false`\n\n### Interactive switching (`/theme`)\n\n- `/theme` with no arguments opens the interactive theme selector with live preview.\n- `/theme <name>` switches immediately: the name is validated against built-in and custom themes, persisted to the detected slot (`theme.dark` or `theme.light`), and applied to the running session (status line, editor border, and chat re-render at once). An unknown name is rejected with the list of available themes and changes nothing.\n\n### Explicit switching (`setTheme`)\n\n- loads selected theme\n- updates global `theme` singleton\n- optionally starts watcher\n- triggers `onThemeChange` callback\n\nOn failure:\n\n- falls back to built-in `dark`\n- returns `{ success: false, error }`\n\n### Preview switching (`previewTheme`)\n\n- applies temporary preview theme to global `theme`\n- does **not** change persisted settings by itself\n- returns success/error without fallback replacement\n\nThe settings theme picker is confirm-only; arrow-key browsing does not call `previewTheme`, so the rendered theme and displayed/persisted theme name stay aligned until Enter confirms a new selection.\n\n## Watchers and live reload\n\nWhen watcher is enabled (`setTheme(..., true)` / interactive init):\n\n- watches `<customThemesDir>/<currentTheme>.json` only when that file exists\n- built-ins are effectively not watched; built-in theme lookup also takes precedence over same-name custom files\n- matching file changes schedule a debounced reload; reload errors or temporary file absence keep the last successfully loaded theme\n- the watcher does not perform a delete/rename fallback; it waits for a future successful reload or explicit theme switch\n\nAuto mode also reevaluates dark/light slot mapping from terminal appearance changes, `SIGWINCH`, and the macOS fallback observer when active.\n\n## Color-blind mode behavior\n\n`colorBlindMode` changes only one token at runtime:\n\n- `toolDiffAdded` is HSV-adjusted (green shifted toward blue)\n- adjustment is applied only when resolved value is a hex string\n\nOther tokens are unchanged.\n\n## Where theme settings are persisted\n\nTheme-related settings are persisted by `Settings` to global config YAML:\n\n- path: `<agentDir>/config.yml`\n- default agent dir: `~/.gjc/agent`\n- effective default file: `~/.gjc/agent/config.yml`\n\nPersisted keys:\n\n- `theme.dark`\n- `theme.light`\n- `symbolPreset`\n- `colorBlindMode`\n\nLegacy migration exists: old flat `theme: \"name\"` is migrated to nested `theme.dark` or `theme.light` based on luminance detection; legacy built-in names `dark`/`light` map to `red-claw`/`blue-crab` unless matching custom theme files exist.\n\n## Creating a custom theme (practical)\n\n1. Create file in custom themes dir, e.g. `~/.gjc/agent/themes/my-theme.json`.\n2. Include `name`, optional `vars`, and **all required** `colors` tokens.\n3. Optionally include `symbols` and `export`.\n4. Select the theme in Settings (`Display -> Dark theme` or `Display -> Light theme`) depending on which auto slot you want. All bundled themes are selectable: the crustacean defaults `red-claw` and `blue-crab`, plus the migration themes `claude-code`, `codex`, and `opencode` (dark-classified, recommended for the dark slot but selectable in either).\n\nMinimal skeleton:\n\n```json\n{\n  \"name\": \"my-theme\",\n  \"vars\": {\n    \"accent\": \"#7aa2f7\",\n    \"muted\": 244\n  },\n  \"colors\": {\n    \"accent\": \"accent\",\n    \"border\": \"#4c566a\",\n    \"borderAccent\": \"accent\",\n    \"borderMuted\": \"muted\",\n    \"success\": \"#9ece6a\",\n    \"error\": \"#f7768e\",\n    \"warning\": \"#e0af68\",\n    \"muted\": \"muted\",\n    \"dim\": 240,\n    \"text\": \"\",\n    \"thinkingText\": \"muted\",\n\n    \"selectedBg\": \"#2a2f45\",\n    \"userMessageBg\": \"#1f2335\",\n    \"userMessageText\": \"\",\n    \"customMessageBg\": \"#24283b\",\n    \"customMessageText\": \"\",\n    \"customMessageLabel\": \"accent\",\n    \"toolPendingBg\": \"#1f2335\",\n    \"toolSuccessBg\": \"#1f2d2a\",\n    \"toolErrorBg\": \"#2d1f2a\",\n    \"toolTitle\": \"\",\n    \"toolOutput\": \"muted\",\n\n    \"mdHeading\": \"accent\",\n    \"mdLink\": \"accent\",\n    \"mdLinkUrl\": \"muted\",\n    \"mdCode\": \"#c0caf5\",\n    \"mdCodeBlock\": \"#c0caf5\",\n    \"mdCodeBlockBorder\": \"muted\",\n    \"mdQuote\": \"muted\",\n    \"mdQuoteBorder\": \"muted\",\n    \"mdHr\": \"muted\",\n    \"mdListBullet\": \"accent\",\n\n    \"toolDiffAdded\": \"#9ece6a\",\n    \"toolDiffRemoved\": \"#f7768e\",\n    \"toolDiffContext\": \"muted\",\n\n    \"syntaxComment\": \"#565f89\",\n    \"syntaxKeyword\": \"#bb9af7\",\n    \"syntaxFunction\": \"#7aa2f7\",\n    \"syntaxVariable\": \"#c0caf5\",\n    \"syntaxString\": \"#9ece6a\",\n    \"syntaxNumber\": \"#ff9e64\",\n    \"syntaxType\": \"#2ac3de\",\n    \"syntaxOperator\": \"#89ddff\",\n    \"syntaxPunctuation\": \"#9aa5ce\",\n\n    \"thinkingOff\": 240,\n    \"thinkingMinimal\": 244,\n    \"thinkingLow\": \"#7aa2f7\",\n    \"thinkingMedium\": \"#2ac3de\",\n    \"thinkingHigh\": \"#bb9af7\",\n    \"thinkingXhigh\": \"#f7768e\",\n\n    \"bashMode\": \"#2ac3de\",\n    \"pythonMode\": \"#bb9af7\",\n\n    \"statusLineBg\": \"#16161e\",\n    \"statusLineSep\": 240,\n    \"statusLineModel\": \"#bb9af7\",\n    \"statusLinePath\": \"#7aa2f7\",\n    \"statusLineGitClean\": \"#9ece6a\",\n    \"statusLineGitDirty\": \"#e0af68\",\n    \"statusLineContext\": \"#2ac3de\",\n    \"statusLineSpend\": \"#7dcfff\",\n    \"statusLineStaged\": \"#9ece6a\",\n    \"statusLineDirty\": \"#e0af68\",\n    \"statusLineUntracked\": \"#f7768e\",\n    \"statusLineOutput\": \"#c0caf5\",\n    \"statusLineCost\": \"#ff9e64\",\n    \"statusLineSubagents\": \"#bb9af7\"\n  }\n}\n```\n\n## Testing custom themes\n\nUse this workflow:\n\n1. Start interactive mode (watcher enabled from startup).\n2. Open settings and confirm the custom theme in the dark/light theme picker; arrow-key browsing is intentionally non-mutating.\n3. For custom theme files, edit the JSON while running and confirm auto-reload on save.\n4. Exercise critical surfaces:\n   - markdown rendering\n   - tool blocks (pending/success/error)\n   - diff rendering (added/removed/context)\n   - status line readability\n   - thinking level border changes\n   - bash/python mode border colors\n5. Validate both symbol presets if your theme depends on glyph width/appearance.\n\n## Real constraints and caveats\n\n- All `colors` tokens are required for custom themes.\n- `export` and `symbols` are optional.\n- `$schema` in theme JSON is informational; runtime validation is enforced by a Zod schema in code.\n- `setTheme` failure falls back to `dark`; `previewTheme` failure does not replace current theme.\n- File watcher reload errors or temporary missing files keep the current loaded theme until a successful reload or explicit theme switch.\n",
-	"tools/ask.md": "# ask\n\n> Prompts the interactive user for one or more choices or free-form answers.\n\n## Source\n- Entry: `packages/coding-agent/src/tools/ask.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/ask.md`\n- Key collaborators:\n  - `packages/coding-agent/src/config/settings-schema.ts` — `ask.timeout` / `ask.notify` defaults\n  - `packages/coding-agent/src/modes/theme/theme.ts` — checkbox and tree glyphs for TUI rendering\n  - `packages/coding-agent/src/tui.ts` — status-line rendering\n\n## Inputs\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `questions` | `Question[]` | Yes | One or more questions. Empty arrays are rejected by schema and also guarded at runtime. |\n\n### `Question`\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `id` | `string` | Yes | Stable identifier used in multi-question results. |\n| `question` | `string` | Yes | Prompt text shown to the user. |\n| `options` | `{ label: string }[]` | Yes | Explicit options. The UI always appends `Other (type your own)`; callers must not include it. |\n| `multi` | `boolean` | No | Enables multi-select mode. Default: `false`. |\n| `recommended` | `number` | No | Zero-based recommended option index. In single-select mode the label gets ` (Recommended)` appended in the UI. |\n\n## Outputs\n- Single-shot result.\n- `content[0].text` is plain text:\n  - single question: `User selected: ...` and/or `User provided custom input: ...`\n  - multiple questions: `User answers:` followed by one line per `id`\n- `details`:\n  - single question: `{ question, options, multi, selectedOptions, customInput? }`\n  - multiple questions: `{ results: QuestionResult[] }`, where each item includes `id`, `question`, `options`, `multi`, `selectedOptions`, and optional `customInput`\n- Cancellation and headless cases throw instead of returning a structured success result.\n\n## Flow\n1. `AskTool.createIf()` registers the tool when the session has a UI, is workflow-gate eligible, or exposes a workflow-gate emitter; a plain headless session without any answer surface never gets it.\n2. `execute()` prefers a local interactive UI (`context.ui`) when one exists. Otherwise it uses a registered ask answer source (e.g. an SDK/ACP client) or, without one, the durable workflow gate (`packages/coding-agent/src/tools/ask.ts`).\n3. It reads `ask.timeout` from settings, converts seconds to milliseconds, and disables timeout entirely while plan mode is enabled (`packages/coding-agent/src/tools/ask.ts`).\n4. If `ask.notify` is not `off`, it sends a terminal notification: `Waiting for input`.\n5. For each question, `askSingleQuestion()` drives either:\n   - single-select list + optional editor for `Other`\n   - multi-select checkbox loop + `Done selecting` sentinel + optional editor for `Other`\n6. In multi-question mode, left/right arrow handlers enable back/forward navigation between questions and preserve prior selections.\n7. If a timeout fires before any selection/custom input, the tool auto-selects the recommended option, or the first option when no valid `recommended` index exists.\n8. If the user cancels without timeout, `execute()` aborts the tool context and throws `ToolAbortError(\"Ask tool was cancelled by the user\")`.\n9. On success it formats human-readable text plus structured `details`; the TUI renderer uses `details` for rich display.\n\n## Modes / Variants\n- Single question: returns flattened `details` fields for one question.\n- Multiple questions: returns `details.results[]` and allows back/forward navigation across questions.\n- Single-select: one option or custom input.\n- Multi-select: toggled checkbox list, `Done selecting` sentinel only when forward navigation is not active.\n\n## Side Effects\n- User-visible prompts / interactive UI\n  - Opens a selection dialog via `context.ui.select(...)`.\n  - Opens a text editor dialog via `context.ui.editor(...)` for `Other`.\n  - Sends a terminal notification unless `ask.notify=off`.\n- Session state\n  - Reads plan-mode state to disable timeouts.\n  - Calls `context.abort()` on headless use or user cancellation.\n- Background work / cancellation\n  - Wraps UI waits in `untilAborted(...)` so abort signals interrupt pending dialogs.\n\n## Limits & Caps\n- `questions` must contain at least 1 item (`askSchema` in `packages/coding-agent/src/tools/ask.ts`).\n- `ask.timeout` default is `0` (disabled); a positive value auto-selects the recommended option after that many seconds (`packages/coding-agent/src/config/settings-schema.ts`).\n- `GJC_ASK_ANSWER_DEADLINE_MS` bounds how long a **headless** ask waits for an answer, in milliseconds. Unset, empty, `0`, negative, non-integer, or greater than `MAX_ASK_ANSWER_DEADLINE_MS` (`2_147_483_647`, the largest delay the runtime timer can represent) disables the bound, which is the default. On expiry the ask logs `ask_answer_deadline_exceeded`, aborts the enclosing turn, and throws `ToolAbortError(\"Ask was aborted: no answer was received within Ns of the headless ask answer deadline\")`. This is an answer deadline, not an acknowledgement bound: no answer source reports that it has taken the question, so a late answer is settled as `resolve_without_commit`/`aborted` rather than attributed to an unresponsive source. It is deliberately separate from `ask.timeout`, which auto-selects an answer for the interactive picker and may legitimately let a remote responder answer later.\n- Prompt guidance says provide 2-5 options, but code does not enforce that (`packages/coding-agent/src/prompts/tools/ask.md`).\n- Timeout only applies to the option picker; once the user chooses `Other`, the editor has no timeout (`packages/coding-agent/src/prompts/tools/ask.md`).\n\n## Errors\n- Missing interactive UI: throws `ToolAbortError(\"Ask tool requires interactive mode\")`.\n- User cancels picker/editor without timeout: throws `ToolAbortError(\"Ask tool was cancelled by the user\")`.\n- Abort signal during input: converted to `ToolAbortError(\"Ask input was cancelled\")`.\n- Remote answer source closes the ask: throws `ToolAbortError(\"Ask was cancelled by the remote client\")`.\n- `GJC_ASK_ANSWER_DEADLINE_MS` expires with no answer: throws `ToolAbortError(\"Ask was aborted: no answer was received within Ns of the headless ask answer deadline\")`.\n- Empty `questions` at runtime returns a text error payload instead of throwing: `Error: questions must not be empty`.\n\n## Notes\n- `recommended` is only a UI hint; invalid indexes are ignored.\n- In single-select mode the returned `selectedOptions` value strips the appended ` (Recommended)` suffix.\n- Multi-select results preserve selection order by `Set` insertion order, not original option order after arbitrary toggles.\n- Option labels and prompt text are returned verbatim in `details`; the tool does not interpret them beyond UI affordances like `Other` and ` (Recommended)`.\n",
-	"tools/ast-edit.md": "# ast_edit\n\n> Preview and apply structural rewrites over source files via native ast-grep.\n\n## Source\n- Entry: `packages/coding-agent/src/tools/ast-edit.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/ast-edit.md`\n- Key collaborators:\n  - `crates/pi-natives/src/ast.rs` — native rewrite planning and file mutation\n  - `crates/pi-natives/src/language/mod.rs` — language aliases and extension inference\n  - `packages/coding-agent/src/tools/path-utils.ts` — path/glob parsing and multi-path resolution\n  - `packages/coding-agent/src/tools/resolve.ts` — preview/apply queueing\n  - `packages/coding-agent/src/tools/render-utils.ts` — parse-error dedupe and display caps\n  - `packages/coding-agent/src/utils/file-display-mode.ts` — hashline vs line-number diff references\n  - `packages/coding-agent/src/hashline/hash.ts` — stable hashline diff anchors\n  - `packages/natives/native/index.d.ts` — JS-visible native binding contract\n\n## Inputs\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `ops` | `{ pat: string; out: string }[]` | Yes | One or more rewrite rules. `pat` must be non-empty. Duplicate `pat` values fail before native execution. Empty `out` deletes the matched node. |\n| `paths` | `string[]` | Yes | One or more files, directories, globs, or internal URLs with backing files. Empty entries are rejected. Globs are forbidden for internal URLs. |\n\nShared AST pattern grammar and language catalog: see [`ast_grep`](./ast-grep.md#inputs).\n\n- `ast_edit` uses the same `$NAME`, `$_`, `$$$NAME`, and `$$$` metavariable semantics.\n- The tool prompt adds rewrite-specific constraints:\n  - metavariable names must be uppercase and must stand for whole AST nodes,\n  - captures from `pat` are substituted into `out`,\n  - each rewrite is a 1:1 structural substitution; one capture cannot expand into multiple sibling nodes unless the grammar itself permits that expansion at that position.\n\n## Outputs\n- Single-shot preview result from `ast_edit` itself.\n- Model-facing `content` is one text block showing proposed edits, grouped by file for directory/multi-file runs.\n  - Each change renders as two lines: `-REF|before` and `+REF|after` in hashline mode, or `-LINE:COLUMN before` / `+LINE:COLUMN after` when hashlines are off.\n  - Only the first line of each `before`/`after` snippet is shown, truncated to 120 characters in the wrapper.\n  - `Limit reached; narrow paths.` and formatted parse issues are appended when applicable.\n- If no rewrites match, text is `No replacements made` plus formatted parse issues when present.\n- `details` includes aggregate preview metadata:\n  - `totalReplacements`, `filesTouched`, `filesSearched`, `applied`, `limitReached`\n  - optional `parseErrors`, `scopePath`, `files`, `fileReplacements`, `displayContent`, `meta`\n- The tool always previews first (`applied: false` in the direct result). Actual file writes happen only later through `resolve(action: \"apply\", ...)`.\n- When preview produced replacements, `ast_edit` also queues a pending `resolve` action. Successful apply returns a separate `resolve` result, not another `ast_edit` result.\n\n## Flow\n1. `AstEditTool.execute()` validates each op in `packages/coding-agent/src/tools/ast-edit.ts`:\n   - empty `pat` fails,\n   - at least one op is required,\n   - duplicate `pat` values fail,\n   - ops are converted to a `Record<pattern, replacement>`.\n2. The wrapper reads `GJC_MAX_AST_FILES` via `$envpos(..., 1000)` and uses that as the native `maxFiles` cap for both preview and apply.\n3. Path normalization, internal URL handling, missing-path partitioning, and multi-path resolution follow the same `path-utils.ts` flow as `ast_grep`.\n4. The wrapper stats the resolved base path to decide whether to render grouped directory output.\n5. `runAstEditOnce(...)` always runs native `astEdit(...)` with `dryRun: true` and `failOnParseError: false` on the first pass.\n6. Native `ast_edit` in `crates/pi-natives/src/ast.rs`:\n   - normalizes the rewrite map and sorts rules by pattern string,\n   - resolves strictness (`smart` by default),\n   - collects candidate files from a file or gitignore-aware directory scan,\n   - infers a single language for the whole call unless `lang` was supplied,\n   - compiles every rewrite pattern for that language,\n   - parses each file, skips files with syntax-error trees, collects `replace_by(...)` edits for every match, enforces replacement and file caps, and returns textual before/after slices plus source ranges.\n7. The TS wrapper deduplicates parse errors, groups changes by file, and renders preview diff lines.\n8. If preview found replacements and `applied` is false, `queueResolveHandler(...)` registers a forced `resolve` action and injects a `resolve-reminder` steering message.\n9. On `resolve(action: \"apply\")`, the queued callback reruns the same rewrite set with `dryRun: false`, recomputes counts, and rejects the apply as an error if the live result no longer matches the preview (`stalePreview`).\n10. On a non-stale apply, the callback returns `Applied N replacements in M files.`; on discard, `resolve` returns a discard message without mutating files.\n\n## Modes / Variants\n- Single file: preview or apply against one file.\n- Directory + optional glob: native scan walks the directory, then filters by compiled glob.\n- Multiple explicit paths/globs: wrapper unions them into one synthetic scope or runs per-target native calls when paths only meet at root.\n- Internal URL inputs: only supported when the router resolves them to a backing file path.\n- Preview mode: always the direct `ast_edit` tool result.\n- Apply mode: only reachable through the queued `resolve` callback after a preview.\n- Hashline output mode vs plain line/column mode: controlled by `resolveFileDisplayMode()`.\n\n## Side Effects\n- Filesystem\n  - Preview reads files and scans directories.\n  - Apply rewrites files in place with `std::fs::write(...)`, but only when the computed output differs from the original source.\n- Session state (transcript, memory, jobs, checkpoints, registries)\n  - Queues a one-shot forced `resolve` tool choice through `queueResolveHandler(...)`.\n  - Adds a `resolve-reminder` steering message.\n- User-visible prompts / interactive UI\n  - Direct `ast_edit` results are previews.\n  - Follow-up apply/discard is exposed through the hidden `resolve` tool.\n- Background work / cancellation\n  - Native preview/apply work runs on a blocking worker via `task::blocking(...)`.\n  - Cancellation and optional native timeout are cooperative through `CancelToken::heartbeat()`.\n\n## Limits & Caps\n- File cap exposed by the wrapper: `GJC_MAX_AST_FILES`, default `1000`, in `packages/coding-agent/src/tools/ast-edit.ts`.\n- Native `maxFiles` and `maxReplacements` are both clamped to at least `1` when provided in `crates/pi-natives/src/ast.rs`.\n- The wrapper never sets `maxReplacements`; native behavior therefore defaults to effectively unbounded replacements for a run.\n- Parse issues are rendered with at most `PARSE_ERRORS_LIMIT = 20` lines in `packages/coding-agent/src/tools/render-utils.ts`; `details.parseErrors` is deduplicated but not capped.\n- Directory scans use `include_hidden: true`, `use_gitignore: true`, and skip `node_modules` unless the glob text explicitly mentions `node_modules` in `crates/pi-natives/src/ast.rs`.\n- No separate glob-expansion count cap exists. Candidate count is whatever the resolved path/glob expands to after gitignore filtering, then native `maxFiles` stops mutations after the configured number of touched files.\n- Preview text truncates each rendered `before` and `after` first line to 120 characters in `packages/coding-agent/src/tools/ast-edit.ts`.\n\n## Errors\n- TS wrapper throws `ToolError` for empty patterns, duplicate rewrite patterns, empty path entries, unsupported internal-URL globs, internal URLs without `sourcePath`, and missing paths.\n- Native code returns hard errors for:\n  - inability to infer one language across all candidates when `lang` is absent,\n  - unsupported explicit `lang`,\n  - bad glob compilation or unreadable search roots,\n  - overlapping computed edits (`Overlapping replacements detected; refine pattern to avoid ambiguous edits`),\n  - out-of-bounds edit ranges or non-UTF-8 replacement text,\n  - write failures during apply,\n  - cancellation or timeout.\n- With `failOnParseError: false` (the wrapper always uses this), pattern compile failures and file parse failures become `parseErrors` instead of aborting the whole run.\n- If every rewrite pattern fails to compile, native `ast_edit` returns a successful zero-replacement result with `parseErrors` populated.\n- Files containing tree-sitter error nodes are skipped for rewriting; they do not get partial edits.\n- Apply can fail after a successful preview if the preview becomes stale. The resolve callback compares replacement totals and per-file counts and returns an error result rather than applying a mismatched preview silently.\n\n## Notes\n- `ast_edit` does not expose the native `lang`, `strictness`, `selector`, `maxReplacements`, `failOnParseError`, or `timeoutMs` fields to the model. The runtime fixes the call shape to a preview-first, smart-strictness, best-effort parse mode.\n- Because the wrapper does not expose `lang`, mixed-language rewrites only succeed when every candidate infers to the same canonical language. This is stricter than `ast_grep`.\n- Idempotency is not enforced syntactically. A rewrite like `foo($A) -> foo($A)` previews zero changes because output equals input; a rewrite that keeps matching its own output may still produce replacements on repeated calls.\n- Rewrites are accumulated per file, then applied from the end of the file backward after an overlap check. Independent matches can coexist; overlapping matches abort the run.\n- Native rewrite rule order is by pattern-string sort, not by the original `ops` array order, because `normalize_rewrite_map(...)` sorts the `(pattern, rewrite)` pairs.\n- Preview/apply parity is validated only by totals and per-file counts, not by a byte-for-byte diff of every replacement payload.",
-	"tools/ast-grep.md": "# ast_grep\n\n> Structural code search over supported source files via native ast-grep.\n\n## Source\n- Entry: `packages/coding-agent/src/tools/ast-grep.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/ast-grep.md`\n- Key collaborators:\n  - `crates/pi-natives/src/ast.rs` — native scan, parse, match engine\n  - `crates/pi-natives/src/language/mod.rs` — language aliases and extension inference\n  - `packages/coding-agent/src/tools/path-utils.ts` — path/glob parsing and multi-path resolution\n  - `packages/coding-agent/src/tools/render-utils.ts` — parse-error dedupe and display caps\n  - `packages/coding-agent/src/tools/match-line-format.ts` — anchor-prefixed match rendering\n  - `packages/coding-agent/src/utils/file-display-mode.ts` — hashline vs line-number output mode\n  - `packages/natives/native/index.d.ts` — JS-visible native binding contract\n\n## Inputs\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `pat` | `string` | Yes | Single AST pattern. The wrapper trims it and rejects empty strings. |\n| `paths` | `string[]` | Yes | One or more files, directories, globs, or internal URLs with backing files. Empty entries are rejected. Globs are forbidden for internal URLs. |\n| `skip` | `number` | No | Match offset. Defaults to `0`, then `Math.floor(...)`; negatives and non-finite values fail. |\n\nPattern grammar and language support exposed to the model:\n- `$NAME` — capture one AST node.\n- `$_` — match one AST node without binding.\n- `$$$NAME` — capture zero or more AST nodes; ast-grep stops lazily at the next satisfiable node.\n- `$$$` — match zero or more AST nodes without binding.\n- Metavariable names must be uppercase and must stand for whole AST nodes, not partial tokens or string fragments.\n- Reusing the same metavariable requires identical code at each occurrence.\n- Patterns must parse as one valid AST node for the inferred target language.\n- Supported canonical languages come from `SupportLang::all_langs()` in `crates/pi-natives/src/language/mod.rs`: `astro`, `bash`, `c`, `cmake`, `cpp`, `csharp`, `dart`, `clojure`, `css`, `diff`, `dockerfile`, `elixir`, `erlang`, `go`, `graphql`, `haskell`, `hcl`, `html`, `ini`, `java`, `javascript`, `json`, `just`, `julia`, `kotlin`, `lua`, `make`, `markdown`, `nix`, `objc`, `ocaml`, `odin`, `perl`, `php`, `powershell`, `protobuf`, `python`, `r`, `regex`, `ruby`, `rust`, `scala`, `solidity`, `sql`, `starlark`, `svelte`, `swift`, `toml`, `tlaplus`, `tsx`, `typescript`, `verilog`, `vue`, `xml`, `yaml`, `zig`.\n\n## Outputs\n- Single-shot tool result.\n- Model-facing `content` is one text block:\n  - grouped by file for directory/multi-file searches,\n  - match lines rendered as `*LINE+HASH|text` in hashline mode or `*LINE|text` otherwise,\n  - continuation lines for multi-line matches rendered with a leading space,\n  - optional `meta: NAME=value` lines when ast-grep captured metavariables.\n- If no matches are found, text is `No matches found` or `No matches found. Parse issues mean the query may be mis-scoped; narrow paths before concluding absence.` plus formatted parse issues.\n- If the wrapper truncates visible results, the text ends with `Result limit reached; narrow paths or increase limit.`\n- `details` includes counts and metadata, not full match payloads:\n  - `matchCount`, `fileCount`, `filesSearched`, `limitReached`\n  - optional `parseErrors`, `scopePath`, `files`, `fileMatches`, `displayContent`, `meta`\n- Native ranges (`byteStart`, `byteEnd`, `startLine`, `startColumn`, `endLine`, `endColumn`) exist only inside the native result; the wrapper does not emit them directly to the model.\n\n## Flow\n1. `AstGrepTool.execute()` validates `pat`, normalizes `skip`, and normalizes each `paths` entry in `packages/coding-agent/src/tools/ast-grep.ts`.\n2. Internal URLs are resolved through `session.internalRouter`; entries without `sourcePath` fail, and internal-URL globs fail early.\n3. For multiple path inputs, `partitionExistingPaths()` drops missing bases only when at least one surviving base remains; if all bases are missing the call fails.\n4. `parseSearchPath()` splits a single path into `basePath` plus optional `glob`. `resolveExplicitSearchPaths()` collapses multiple inputs into a common base plus a brace-union glob, or separate `targets` when the only common base is a filesystem root.\n5. The wrapper stats the resolved base path to decide whether output should be grouped as a directory result.\n6. Execution dispatches to either:\n   - one native `astGrep(...)` call for a single resolved base, or\n   - `runMultiTargetAstGrep(...)`, which calls the native binding once per target, rebases paths back to the common root, sorts globally, then applies `skip` and the wrapper limit.\n7. Native `ast_grep` in `crates/pi-natives/src/ast.rs`:\n   - normalizes and deduplicates patterns,\n   - resolves a `MatchStrictness` (`smart` by default),\n   - collects candidate files from a file or gitignore-aware directory scan,\n   - infers language per candidate from extension unless `lang` was provided,\n   - compiles the pattern separately for each language present,\n   - reads each file, reports syntax-error trees as parse issues, runs `find_all`, and optionally captures metavariable bindings.\n8. Native results are sorted by path and source position, then paged by `offset`/`limit`.\n9. The TS wrapper normalizes parse-error strings, deduplicates them, groups matches by formatted path, renders anchor lines, appends limit/parse notices, and returns `toolResult(...).text(...).done()`.\n\n## Modes / Variants\n- Single file: native path is the file; output is a flat list of rendered match lines.\n- Directory + optional glob: native scan walks the directory, then filters by compiled glob.\n- Multiple explicit paths/globs: wrapper unions them into one synthetic scope or runs per-target native calls when paths only meet at root.\n- Internal URL inputs: only supported when the router can resolve them to a backing file path.\n- Hashline output mode vs plain line-number mode: controlled by `resolveFileDisplayMode()`; hashline mode requires the edit tool and non-raw, mutable sources.\n\n## Side Effects\n- Filesystem\n  - Stats input paths in the TS wrapper.\n  - Native code reads matched files and scans directories through `fs_cache`.\n- Session state (transcript, memory, jobs, checkpoints, registries)\n  - None beyond normal tool transcript/result metadata.\n- Background work / cancellation\n  - Native work runs on a blocking worker via `task::blocking(...)`.\n  - Cancellation and optional native timeout are cooperative through `CancelToken::heartbeat()`.\n\n## Limits & Caps\n- Wrapper-visible result cap: `DEFAULT_AST_LIMIT = 50` in `packages/coding-agent/src/tools/ast-grep.ts`.\n  - Single-target calls rely on the native default limit of 50 in `crates/pi-natives/src/ast.rs`.\n  - Multi-target calls fetch `skip + 50 + 1` matches per target, then re-page after global sort.\n- Native `limit` is clamped to at least `1`; omitted `offset` defaults to `0` in `crates/pi-natives/src/ast.rs`.\n- Parse issues are rendered with at most `PARSE_ERRORS_LIMIT = 20` lines in `packages/coding-agent/src/tools/render-utils.ts`; `details.parseErrors` itself is only deduplicated, not capped.\n- Directory scans use `include_hidden: true`, `use_gitignore: true`, and skip `node_modules` unless the glob text explicitly mentions `node_modules` in `crates/pi-natives/src/ast.rs`.\n- No hard file-count cap is applied by the wrapper or native `ast_grep`; candidate count is whatever the resolved path/glob expands to after gitignore filtering.\n- Multi-path union deduplicates identical path inputs before resolution in `resolveExplicitSearchPaths()`.\n\n## Errors\n- TS wrapper throws `ToolError` for empty patterns, invalid `skip`, empty path entries, unsupported internal-URL globs, internal URLs without `sourcePath`, and missing paths.\n- Native code returns hard errors for:\n  - unsupported explicit `lang`,\n  - inability to infer language for a candidate when `lang` is not supplied,\n  - invalid AST pattern compilation for every relevant language,\n  - unreadable search roots or bad glob compilation,\n  - cancellation (`Aborted: Signal`) or timeout (`Aborted: Timeout`).\n- File-level parse failures and many per-language pattern compile failures are non-fatal: they are accumulated in `parseErrors` and surfaced alongside successful matches.\n- `no matches` is not an error, even when parse issues were recorded.\n\n## Notes\n- `pat` is always wrapped into a one-element `patterns` array by the TS tool; the model cannot send multiple patterns through `ast_grep` even though the native binding supports it.\n- `ast_grep` can search mixed-language trees because native compilation happens per discovered language, but the prompt still tells the model to keep calls single-language when possible to reduce parse noise.\n- Pattern compilation is per language present in the candidate set. One pattern can succeed for some languages and generate per-file parse errors for others in the same run.\n- A file with tree-sitter error nodes still gets searched; the syntax warning is additive, not a skip condition.\n- For glob semantics, `*.ts` matches only direct children while `**/*.ts` recurses; this is covered by native tests in `crates/pi-natives/src/ast.rs`.\n- Output anchors are intended for follow-up tools, but the exact anchor format depends on session edit mode (`hashline` vs line-number mode).",
+	"tools/ask.md": "# ask\n\n> Prompts the interactive user for one or more choices or free-form answers.\n\n## Source\n- Entry: `packages/coding-agent/src/tools/ask.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/ask.md`\n- Key collaborators:\n  - `packages/coding-agent/src/config/settings-schema.ts` — `ask.timeout` / `ask.notify` defaults\n  - `packages/coding-agent/src/modes/theme/theme.ts` — checkbox and tree glyphs for TUI rendering\n  - `packages/coding-agent/src/tui/status-line.ts` — status-line rendering (`renderStatusLine()`)\n\n## Inputs\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `questions` | `Question[]` | Yes | One or more questions. Empty arrays are rejected by schema and also guarded at runtime. |\n\n### `Question`\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `id` | `string` | Yes | Stable identifier used in multi-question results. |\n| `question` | `string` | Yes | Prompt text shown to the user. |\n| `options` | `{ label: string }[]` | Yes | Explicit options. The UI always appends `Other (type your own)`; callers must not include it. |\n| `multi` | `boolean` | No | Enables multi-select mode. Default: `false`. |\n| `recommended` | `number` | No | Zero-based recommended option index. In single-select mode the label gets ` (Recommended)` appended in the UI. |\n\n## Outputs\n- Single-shot result.\n- `content[0].text` is plain text:\n  - single question: `User selected: ...` and/or `User provided custom input: ...`\n  - multiple questions: `User answers:` followed by one line per `id`\n- `details`:\n  - single question: `{ question, options, multi, selectedOptions, customInput? }`\n  - multiple questions: `{ results: QuestionResult[] }`, where each item includes `id`, `question`, `options`, `multi`, `selectedOptions`, and optional `customInput`\n- Cancellation and headless cases throw instead of returning a structured success result.\n\n## Flow\n1. `AskTool.createIf()` registers the tool when the session has a UI, is workflow-gate eligible, or exposes a workflow-gate emitter; a plain headless session without any answer surface never gets it.\n2. `execute()` prefers a local interactive UI (`context.ui`) when one exists. Otherwise it uses a registered ask answer source (e.g. an SDK/ACP client) or, without one, the durable workflow gate (`packages/coding-agent/src/tools/ask.ts`).\n3. It reads `ask.timeout` from settings, converts seconds to milliseconds, and disables timeout entirely while plan mode is enabled (`packages/coding-agent/src/tools/ask.ts`).\n4. If `ask.notify` is not `off`, it sends a terminal notification: `Waiting for input`.\n5. For each question, `askSingleQuestion()` drives either:\n   - single-select list + optional editor for `Other`\n   - multi-select checkbox loop + `Done selecting` sentinel + optional editor for `Other`\n6. In multi-question mode, left/right arrow handlers enable back/forward navigation between questions and preserve prior selections.\n7. If a timeout fires before any selection/custom input, the tool auto-selects the recommended option, or the first option when no valid `recommended` index exists.\n8. If the user cancels without timeout, `execute()` aborts the tool context and throws `ToolAbortError(\"Ask tool was cancelled by the user\")`.\n9. On success it formats human-readable text plus structured `details`; the TUI renderer uses `details` for rich display.\n\n## Modes / Variants\n- Single question: returns flattened `details` fields for one question.\n- Multiple questions: returns `details.results[]` and allows back/forward navigation across questions.\n- Single-select: one option or custom input.\n- Multi-select: toggled checkbox list, `Done selecting` sentinel only when forward navigation is not active.\n\n## Side Effects\n- User-visible prompts / interactive UI\n  - Opens a selection dialog via `context.ui.select(...)`.\n  - Opens a text editor dialog via `context.ui.editor(...)` for `Other`.\n  - Sends a terminal notification unless `ask.notify=off`.\n- Session state\n  - Reads plan-mode state to disable timeouts.\n  - Calls `context.abort()` on headless use or user cancellation.\n- Background work / cancellation\n  - Wraps UI waits in `untilAborted(...)` so abort signals interrupt pending dialogs.\n\n## Limits & Caps\n- `questions` must contain at least 1 item (`askSchema` in `packages/coding-agent/src/tools/ask.ts`).\n- `ask.timeout` default is `0` (disabled); a positive value auto-selects the recommended option after that many seconds (`packages/coding-agent/src/config/settings-schema.ts`).\n- `GJC_ASK_ANSWER_DEADLINE_MS` bounds how long a **headless** ask waits for an answer, in milliseconds. Unset, empty, `0`, negative, non-integer, or greater than `MAX_ASK_ANSWER_DEADLINE_MS` (`2_147_483_647`, the largest delay the runtime timer can represent) disables the bound, which is the default. On expiry the ask logs `ask_answer_deadline_exceeded`, aborts the enclosing turn, and throws `ToolAbortError(\"Ask was aborted: no answer was received within Ns of the headless ask answer deadline\")`. This is an answer deadline, not an acknowledgement bound: no answer source reports that it has taken the question, so a late answer is settled as `resolve_without_commit`/`aborted` rather than attributed to an unresponsive source. It is deliberately separate from `ask.timeout`, which auto-selects an answer for the interactive picker and may legitimately let a remote responder answer later.\n- Prompt guidance says provide 2-5 options, but code does not enforce that (`packages/coding-agent/src/prompts/tools/ask.md`).\n- Timeout only applies to the option picker; once the user chooses `Other`, the editor has no timeout (`packages/coding-agent/src/prompts/tools/ask.md`).\n\n## Errors\n- Missing interactive UI: throws `ToolAbortError(\"Ask tool requires interactive mode\")`.\n- User cancels picker/editor without timeout: throws `ToolAbortError(\"Ask tool was cancelled by the user\")`.\n- Abort signal during input: converted to `ToolAbortError(\"Ask input was cancelled\")`.\n- Remote answer source closes the ask: throws `ToolAbortError(\"Ask was cancelled by the remote client\")`.\n- `GJC_ASK_ANSWER_DEADLINE_MS` expires with no answer: throws `ToolAbortError(\"Ask was aborted: no answer was received within Ns of the headless ask answer deadline\")`.\n- Empty `questions` at runtime returns a text error payload instead of throwing: `Error: questions must not be empty`.\n\n## Notes\n- `recommended` is only a UI hint; invalid indexes are ignored.\n- In single-select mode the returned `selectedOptions` value strips the appended ` (Recommended)` suffix.\n- Multi-select results preserve selection order by `Set` insertion order, not original option order after arbitrary toggles.\n- Option labels and prompt text are returned verbatim in `details`; the tool does not interpret them beyond UI affordances like `Other` and ` (Recommended)`.\n",
+	"tools/ast-edit.md": "# ast_edit\n\n> Preview and apply structural rewrites over source files via native ast-grep.\n\n## Source\n- Entry: `packages/coding-agent/src/tools/ast-edit.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/ast-edit.md`\n- Key collaborators:\n  - `crates/pi-natives/src/ast.rs` — native rewrite planning and file mutation\n  - `crates/pi-ast/src/language/mod.rs` — language aliases and extension inference\n  - `packages/coding-agent/src/tools/path-utils.ts` — path/glob parsing and multi-path resolution\n  - `packages/coding-agent/src/tools/resolve.ts` — preview/apply queueing\n  - `packages/coding-agent/src/tools/render-utils.ts` — parse-error dedupe and display caps\n  - `packages/coding-agent/src/utils/file-display-mode.ts` — hashline vs line-number diff references\n  - `packages/coding-agent/src/hashline/hash.ts` — stable hashline diff anchors\n  - `packages/natives/native/index.d.ts` — JS-visible native binding contract\n\n## Inputs\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `ops` | `{ pat: string; out: string }[]` | Yes | One or more rewrite rules. `pat` must be non-empty. Duplicate `pat` values fail before native execution. Empty `out` deletes the matched node. |\n| `paths` | `string[]` | Yes | One or more files, directories, globs, or internal URLs with backing files. Empty entries are rejected. Globs are forbidden for internal URLs. |\n\nShared AST pattern grammar and language catalog: see [`ast_grep`](./ast-grep.md#inputs).\n\n- `ast_edit` uses the same `$NAME`, `$_`, `$$$NAME`, and `$$$` metavariable semantics.\n- The tool prompt adds rewrite-specific constraints:\n  - metavariable names must be uppercase and must stand for whole AST nodes,\n  - captures from `pat` are substituted into `out`,\n  - each rewrite is a 1:1 structural substitution; one capture cannot expand into multiple sibling nodes unless the grammar itself permits that expansion at that position.\n\n## Outputs\n- Single-shot preview result from `ast_edit` itself.\n- Model-facing `content` is one text block showing proposed edits, grouped by file for directory/multi-file runs.\n  - Each change renders as two lines: `-REF|before` and `+REF|after` in hashline mode, or `-LINE:COLUMN before` / `+LINE:COLUMN after` when hashlines are off.\n  - Only the first line of each `before`/`after` snippet is shown, truncated to 120 characters in the wrapper.\n  - `Limit reached; narrow paths.` and formatted parse issues are appended when applicable.\n- If no rewrites match, text is `No replacements made` plus formatted parse issues when present.\n- `details` includes aggregate preview metadata:\n  - `totalReplacements`, `filesTouched`, `filesSearched`, `applied`, `limitReached`\n  - optional `parseErrors`, `scopePath`, `files`, `fileReplacements`, `displayContent`, `meta`\n- The tool always previews first (`applied: false` in the direct result). Actual file writes happen only later through `resolve(action: \"apply\", ...)`.\n- When preview produced replacements, `ast_edit` also queues a pending `resolve` action. Successful apply returns a separate `resolve` result, not another `ast_edit` result.\n\n## Flow\n1. `AstEditTool.execute()` validates each op in `packages/coding-agent/src/tools/ast-edit.ts`:\n   - empty `pat` fails,\n   - at least one op is required,\n   - duplicate `pat` values fail,\n   - ops are converted to a `Record<pattern, replacement>`.\n2. The wrapper reads `GJC_MAX_AST_FILES` via `$envpos(..., 1000)` and uses that as the native `maxFiles` cap for both preview and apply.\n3. Path normalization, internal URL handling, missing-path partitioning, and multi-path resolution follow the same `path-utils.ts` flow as `ast_grep`.\n4. The wrapper stats the resolved base path to decide whether to render grouped directory output.\n5. `runAstEditOnce(...)` always runs native `astEdit(...)` with `dryRun: true` and `failOnParseError: false` on the first pass.\n6. Native `ast_edit` in `crates/pi-natives/src/ast.rs`:\n   - normalizes the rewrite map and sorts rules by pattern string,\n   - resolves strictness (`smart` by default),\n   - collects candidate files from a file or gitignore-aware directory scan,\n   - infers a single language for the whole call unless `lang` was supplied,\n   - compiles every rewrite pattern for that language,\n   - parses each file, skips files with syntax-error trees, collects `replace_by(...)` edits for every match, enforces replacement and file caps, and returns textual before/after slices plus source ranges.\n7. The TS wrapper deduplicates parse errors, groups changes by file, and renders preview diff lines.\n8. If preview found replacements and `applied` is false, `queueResolveHandler(...)` registers a forced `resolve` action and injects a `resolve-reminder` steering message.\n9. On `resolve(action: \"apply\")`, the queued callback reruns the same rewrite set with `dryRun: false`, recomputes counts, and rejects the apply as an error if the live result no longer matches the preview (`stalePreview`).\n10. On a non-stale apply, the callback returns `Applied N replacements in M files.`; on discard, `resolve` returns a discard message without mutating files.\n\n## Modes / Variants\n- Single file: preview or apply against one file.\n- Directory + optional glob: native scan walks the directory, then filters by compiled glob.\n- Multiple explicit paths/globs: wrapper unions them into one synthetic scope or runs per-target native calls when paths only meet at root.\n- Internal URL inputs: only supported when the router resolves them to a backing file path.\n- Preview mode: always the direct `ast_edit` tool result.\n- Apply mode: only reachable through the queued `resolve` callback after a preview.\n- Hashline output mode vs plain line/column mode: controlled by `resolveFileDisplayMode()`.\n\n## Side Effects\n- Filesystem\n  - Preview reads files and scans directories.\n  - Apply rewrites files in place with `std::fs::write(...)`, but only when the computed output differs from the original source.\n- Session state (transcript, memory, jobs, checkpoints, registries)\n  - Queues a one-shot forced `resolve` tool choice through `queueResolveHandler(...)`.\n  - Adds a `resolve-reminder` steering message.\n- User-visible prompts / interactive UI\n  - Direct `ast_edit` results are previews.\n  - Follow-up apply/discard is exposed through the hidden `resolve` tool.\n- Background work / cancellation\n  - Native preview/apply work runs on a blocking worker via `task::blocking(...)`.\n  - Cancellation and optional native timeout are cooperative through `CancelToken::heartbeat()`.\n\n## Limits & Caps\n- File cap exposed by the wrapper: `GJC_MAX_AST_FILES`, default `1000`, in `packages/coding-agent/src/tools/ast-edit.ts`.\n- Native `maxFiles` and `maxReplacements` are both clamped to at least `1` when provided in `crates/pi-natives/src/ast.rs`.\n- The wrapper never sets `maxReplacements`; native behavior therefore defaults to effectively unbounded replacements for a run.\n- Parse issues are rendered with at most `PARSE_ERRORS_LIMIT = 20` lines in `packages/coding-agent/src/tools/render-utils.ts`; `details.parseErrors` is deduplicated but not capped.\n- Directory scans use `include_hidden: true`, `use_gitignore: true`, and skip `node_modules` unless the glob text explicitly mentions `node_modules` in `crates/pi-natives/src/ast.rs`.\n- No separate glob-expansion count cap exists. Candidate count is whatever the resolved path/glob expands to after gitignore filtering, then native `maxFiles` stops mutations after the configured number of touched files.\n- Preview text truncates each rendered `before` and `after` first line to 120 characters in `packages/coding-agent/src/tools/ast-edit.ts`.\n\n## Errors\n- TS wrapper throws `ToolError` for empty patterns, duplicate rewrite patterns, empty path entries, unsupported internal-URL globs, internal URLs without `sourcePath`, and missing paths.\n- Native code returns hard errors for:\n  - inability to infer one language across all candidates when `lang` is absent,\n  - unsupported explicit `lang`,\n  - bad glob compilation or unreadable search roots,\n  - overlapping computed edits (`Overlapping replacements detected; refine pattern to avoid ambiguous edits`),\n  - out-of-bounds edit ranges or non-UTF-8 replacement text,\n  - write failures during apply,\n  - cancellation or timeout.\n- With `failOnParseError: false` (the wrapper always uses this), pattern compile failures and file parse failures become `parseErrors` instead of aborting the whole run.\n- If every rewrite pattern fails to compile, native `ast_edit` returns a successful zero-replacement result with `parseErrors` populated.\n- Files containing tree-sitter error nodes are skipped for rewriting; they do not get partial edits.\n- Apply can fail after a successful preview if the preview becomes stale. The resolve callback compares replacement totals and per-file counts and returns an error result rather than applying a mismatched preview silently.\n\n## Notes\n- `ast_edit` does not expose the native `lang`, `strictness`, `selector`, `maxReplacements`, `failOnParseError`, or `timeoutMs` fields to the model. The runtime fixes the call shape to a preview-first, smart-strictness, best-effort parse mode.\n- Because the wrapper does not expose `lang`, mixed-language rewrites only succeed when every candidate infers to the same canonical language. This is stricter than `ast_grep`.\n- Idempotency is not enforced syntactically. A rewrite like `foo($A) -> foo($A)` previews zero changes because output equals input; a rewrite that keeps matching its own output may still produce replacements on repeated calls.\n- Rewrites are accumulated per file, then applied from the end of the file backward after an overlap check. Independent matches can coexist; overlapping matches abort the run.\n- Native rewrite rule order is by pattern-string sort, not by the original `ops` array order, because `normalize_rewrite_map(...)` sorts the `(pattern, rewrite)` pairs.\n- Preview/apply parity is validated only by totals and per-file counts, not by a byte-for-byte diff of every replacement payload.",
+	"tools/ast-grep.md": "# ast_grep\n\n> Structural code search over supported source files via native ast-grep.\n\n## Source\n- Entry: `packages/coding-agent/src/tools/ast-grep.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/ast-grep.md`\n- Key collaborators:\n  - `crates/pi-natives/src/ast.rs` — native scan, parse, match engine\n  - `crates/pi-ast/src/language/mod.rs` — language aliases and extension inference\n  - `packages/coding-agent/src/tools/path-utils.ts` — path/glob parsing and multi-path resolution\n  - `packages/coding-agent/src/tools/render-utils.ts` — parse-error dedupe and display caps\n  - `packages/coding-agent/src/tools/match-line-format.ts` — anchor-prefixed match rendering\n  - `packages/coding-agent/src/utils/file-display-mode.ts` — hashline vs line-number output mode\n  - `packages/natives/native/index.d.ts` — JS-visible native binding contract\n\n## Inputs\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `pat` | `string` | Yes | Single AST pattern. The wrapper trims it and rejects empty strings. |\n| `paths` | `string[]` | Yes | One or more files, directories, globs, or internal URLs with backing files. Empty entries are rejected. Globs are forbidden for internal URLs. |\n| `skip` | `number` | No | Match offset. Defaults to `0`, then `Math.floor(...)`; negatives and non-finite values fail. |\n\nPattern grammar and language support exposed to the model:\n- `$NAME` — capture one AST node.\n- `$_` — match one AST node without binding.\n- `$$$NAME` — capture zero or more AST nodes; ast-grep stops lazily at the next satisfiable node.\n- `$$$` — match zero or more AST nodes without binding.\n- Metavariable names must be uppercase and must stand for whole AST nodes, not partial tokens or string fragments.\n- Reusing the same metavariable requires identical code at each occurrence.\n- Patterns must parse as one valid AST node for the inferred target language.\n- Supported canonical languages come from `SupportLang::all_langs()` in `crates/pi-ast/src/language/mod.rs`: `astro`, `bash`, `c`, `cmake`, `cpp`, `csharp`, `dart`, `clojure`, `css`, `diff`, `dockerfile`, `elixir`, `erlang`, `go`, `graphql`, `haskell`, `hcl`, `html`, `ini`, `java`, `javascript`, `json`, `just`, `julia`, `kotlin`, `lua`, `make`, `markdown`, `nix`, `objc`, `ocaml`, `odin`, `perl`, `php`, `powershell`, `protobuf`, `python`, `r`, `regex`, `ruby`, `rust`, `scala`, `solidity`, `sql`, `starlark`, `svelte`, `swift`, `toml`, `tlaplus`, `tsx`, `typescript`, `verilog`, `vue`, `xml`, `yaml`, `zig`.\n\n## Outputs\n- Single-shot tool result.\n- Model-facing `content` is one text block:\n  - grouped by file for directory/multi-file searches,\n  - match lines rendered as `*LINE+HASH|text` in hashline mode or `*LINE|text` otherwise,\n  - continuation lines for multi-line matches rendered with a leading space,\n  - optional `meta: NAME=value` lines when ast-grep captured metavariables.\n- If no matches are found, text is `No matches found` or `No matches found. Parse issues mean the query may be mis-scoped; narrow paths before concluding absence.` plus formatted parse issues.\n- If the wrapper truncates visible results, the text ends with `Result limit reached; narrow paths or increase limit.`\n- `details` includes counts and metadata, not full match payloads:\n  - `matchCount`, `fileCount`, `filesSearched`, `limitReached`\n  - optional `parseErrors`, `scopePath`, `files`, `fileMatches`, `displayContent`, `meta`\n- Native ranges (`byteStart`, `byteEnd`, `startLine`, `startColumn`, `endLine`, `endColumn`) exist only inside the native result; the wrapper does not emit them directly to the model.\n\n## Flow\n1. `AstGrepTool.execute()` validates `pat`, normalizes `skip`, and normalizes each `paths` entry in `packages/coding-agent/src/tools/ast-grep.ts`.\n2. Internal URLs are resolved through `session.internalRouter`; entries without `sourcePath` fail, and internal-URL globs fail early.\n3. For multiple path inputs, `partitionExistingPaths()` drops missing bases only when at least one surviving base remains; if all bases are missing the call fails.\n4. `parseSearchPath()` splits a single path into `basePath` plus optional `glob`. `resolveExplicitSearchPaths()` collapses multiple inputs into a common base plus a brace-union glob, or separate `targets` when the only common base is a filesystem root.\n5. The wrapper stats the resolved base path to decide whether output should be grouped as a directory result.\n6. Execution dispatches to either:\n   - one native `astGrep(...)` call for a single resolved base, or\n   - `runMultiTargetAstGrep(...)`, which calls the native binding once per target, rebases paths back to the common root, sorts globally, then applies `skip` and the wrapper limit.\n7. Native `ast_grep` in `crates/pi-natives/src/ast.rs`:\n   - normalizes and deduplicates patterns,\n   - resolves a `MatchStrictness` (`smart` by default),\n   - collects candidate files from a file or gitignore-aware directory scan,\n   - infers language per candidate from extension unless `lang` was provided,\n   - compiles the pattern separately for each language present,\n   - reads each file, reports syntax-error trees as parse issues, runs `find_all`, and optionally captures metavariable bindings.\n8. Native results are sorted by path and source position, then paged by `offset`/`limit`.\n9. The TS wrapper normalizes parse-error strings, deduplicates them, groups matches by formatted path, renders anchor lines, appends limit/parse notices, and returns `toolResult(...).text(...).done()`.\n\n## Modes / Variants\n- Single file: native path is the file; output is a flat list of rendered match lines.\n- Directory + optional glob: native scan walks the directory, then filters by compiled glob.\n- Multiple explicit paths/globs: wrapper unions them into one synthetic scope or runs per-target native calls when paths only meet at root.\n- Internal URL inputs: only supported when the router can resolve them to a backing file path.\n- Hashline output mode vs plain line-number mode: controlled by `resolveFileDisplayMode()`; hashline mode requires the edit tool and non-raw, mutable sources.\n\n## Side Effects\n- Filesystem\n  - Stats input paths in the TS wrapper.\n  - Native code reads matched files and scans directories through `fs_cache`.\n- Session state (transcript, memory, jobs, checkpoints, registries)\n  - None beyond normal tool transcript/result metadata.\n- Background work / cancellation\n  - Native work runs on a blocking worker via `task::blocking(...)`.\n  - Cancellation and optional native timeout are cooperative through `CancelToken::heartbeat()`.\n\n## Limits & Caps\n- Wrapper-visible result cap: `DEFAULT_AST_LIMIT = 50` in `packages/coding-agent/src/tools/ast-grep.ts`.\n  - Single-target calls rely on the native default limit of 50 in `crates/pi-natives/src/ast.rs`.\n  - Multi-target calls fetch `skip + 50 + 1` matches per target, then re-page after global sort.\n- Native `limit` is clamped to at least `1`; omitted `offset` defaults to `0` in `crates/pi-natives/src/ast.rs`.\n- Parse issues are rendered with at most `PARSE_ERRORS_LIMIT = 20` lines in `packages/coding-agent/src/tools/render-utils.ts`; `details.parseErrors` itself is only deduplicated, not capped.\n- Directory scans use `include_hidden: true`, `use_gitignore: true`, and skip `node_modules` unless the glob text explicitly mentions `node_modules` in `crates/pi-natives/src/ast.rs`.\n- No hard file-count cap is applied by the wrapper or native `ast_grep`; candidate count is whatever the resolved path/glob expands to after gitignore filtering.\n- Multi-path union deduplicates identical path inputs before resolution in `resolveExplicitSearchPaths()`.\n\n## Errors\n- TS wrapper throws `ToolError` for empty patterns, invalid `skip`, empty path entries, unsupported internal-URL globs, internal URLs without `sourcePath`, and missing paths.\n- Native code returns hard errors for:\n  - unsupported explicit `lang`,\n  - inability to infer language for a candidate when `lang` is not supplied,\n  - invalid AST pattern compilation for every relevant language,\n  - unreadable search roots or bad glob compilation,\n  - cancellation (`Aborted: Signal`) or timeout (`Aborted: Timeout`).\n- File-level parse failures and many per-language pattern compile failures are non-fatal: they are accumulated in `parseErrors` and surfaced alongside successful matches.\n- `no matches` is not an error, even when parse issues were recorded.\n\n## Notes\n- `pat` is always wrapped into a one-element `patterns` array by the TS tool; the model cannot send multiple patterns through `ast_grep` even though the native binding supports it.\n- `ast_grep` can search mixed-language trees because native compilation happens per discovered language, but the prompt still tells the model to keep calls single-language when possible to reduce parse noise.\n- Pattern compilation is per language present in the candidate set. One pattern can succeed for some languages and generate per-file parse errors for others in the same run.\n- A file with tree-sitter error nodes still gets searched; the syntax warning is additive, not a skip condition.\n- For glob semantics, `*.ts` matches only direct children while `**/*.ts` recurses; this is covered by native tests in `crates/pi-natives/src/ast.rs`.\n- Output anchors are intended for follow-up tools, but the exact anchor format depends on session edit mode (`hashline` vs line-number mode).",
 	"tools/bash.md": "# bash\n\n> Execute a shell command in the session workspace, with optional PTY or background-job handling.\n\n## Source\n- Entry: `packages/coding-agent/src/tools/bash.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/bash.md`\n- Key collaborators:\n  - `packages/coding-agent/src/tools/bash-interactive.ts` — PTY/TUI execution path.\n  - `packages/coding-agent/src/tools/bash-interceptor.ts` — blocks tool-better shell patterns.\n  - `packages/coding-agent/src/tools/bash-skill-urls.ts` — expands internal URLs to paths.\n  - `packages/coding-agent/src/exec/bash-executor.ts` — non-PTY shell execution.\n  - `packages/coding-agent/src/session/streaming-output.ts` — tail buffer, truncation, artifact spill.\n  - `packages/coding-agent/src/tools/tool-timeouts.ts` — timeout clamp bounds.\n  - `packages/coding-agent/src/config/settings-schema.ts` — default interceptor rules.\n  - `docs/bash-tool-runtime.md` — deeper executor/runtime notes; use as the companion doc for shell-session internals.\n\n## Inputs\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `command` | `string` | Yes | Shell command text to execute. A leading `cd <path> && ...` is rewritten into `cwd` only when `cwd` was omitted. |\n| `env` | `Record<string, string>` | No | Extra environment variables. Keys must match `^[A-Za-z_][A-Za-z0-9_]*$` or the tool throws. Values also go through internal-URL expansion. |\n| `timeout` | `number` | No | Timeout in seconds. Default `300`; clamped to `1..3600` by `clampTimeout(\"bash\", ...)`. |\n| `cwd` | `string` | No | Working directory, resolved against `session.cwd` via `resolveToCwd`. Must exist and be a directory. |\n| `pty` | `boolean` | No | Request PTY mode. Default `false`. PTY is used only when `pty: true`, `GJC_NO_PTY !== \"1\"`, and the tool context has a UI. |\n| `async` | `boolean` | No | Background execution request. Present only when `async.enabled` is true for the session. Returns immediately with a job id instead of waiting. |\n\n## Outputs\nThe tool returns a single `text` content block plus optional `details`.\n\n- Success, foreground:\n  - `content[0].text`: command output, or `(no output)` when the command produced nothing.\n  - `details.timeoutSeconds`: effective timeout after clamping.\n  - `details.requestedTimeoutSeconds`: only present when the requested timeout was clamped.\n  - `details.meta.truncation`: present when output was truncated in memory; includes `artifactId` when full output spilled to an artifact.\n- Success, background start (`async: true` or auto-background):\n  - `content[0].text`: optional preview tail, timeout notice if any, then `Background job <id> started: <label>` with follow-up instructions.\n  - `details.async`: `{ state: \"running\", jobId, type: \"bash\" }`.\n- Background progress / completion:\n  - delivered through `onUpdate` / async job manager, not the initial return.\n  - running updates contain tail text and `details.async.state: \"running\"` only after the job is considered backgrounded.\n  - completion/failure updates carry final text and `details.async.state: \"completed\" | \"failed\"`.\n- Failure:\n  - the tool throws `ToolError` / `ToolAbortError`; non-zero exits are surfaced as errors, not success results.\n\nStdout and stderr are merged before the model sees them. Non-zero exit codes are appended to the thrown error text as `Command exited with code <n>`.\n\n## Flow\n1. `BashTool.execute()` in `packages/coding-agent/src/tools/bash.ts` reads `command`, normalizes `env`, and defaults `timeout` to `300`.\n2. If `cwd` is absent, it rewrites a leading `cd <path> && ...` into the structured `cwd` field and strips that prefix from `command`.\n3. If `async: true` is requested while `async.enabled` is off, it throws `ToolError` before any execution.\n4. If `bashInterceptor.enabled` is on, `checkBashInterception()` runs against both the original command and the `cd`-stripped command. A matching enabled rule throws before URL expansion or execution.\n5. `expandInternalUrls()` rewrites supported internal URLs inside `command`, each `env` value, and protocol-looking `cwd` values. Command/env replacements are shell-escaped unless `noEscape` is requested by the caller path.\n6. `resolveToCwd()` resolves `cwd` against `session.cwd`; `fs.stat()` verifies that the target exists and is a directory.\n7. `clampTimeout(\"bash\", requestedTimeoutSec)` enforces `TOOL_TIMEOUTS.bash` (`default: 300`, `min: 1`, `max: 3600`). When clamped, `#buildCompletedResult()` / `#buildBackgroundStartResult()` append a notice line.\n8. Execution path splits:\n   1. `async: true` -> `#startManagedBashJob()` registers a session async job and returns immediately.\n   2. Non-PTY with `bash.autoBackground.enabled` and an async job manager -> starts a managed job, waits up to `min(thresholdMs, timeoutMs - 1000)`, and either returns the completed result or converts the run into a background job.\n   3. Foreground non-PTY, ACP client-terminal, and PTY waits are manager-backed when async support is available, so the fold chord can transfer ownership without restarting the command; otherwise they remain ordinary foreground waits.\n9. Foreground non-PTY calls `executeBash()` from `packages/coding-agent/src/exec/bash-executor.ts`.\n10. Foreground PTY calls `runInteractiveBashPty()` from `packages/coding-agent/src/tools/bash-interactive.ts`.\n11. Both paths allocate an output artifact first when `session.allocateOutputArtifact` is available. The artifact path/id are passed into the sink so large output can spill to disk.\n12. `executeBash()` loads shell settings, optional shell snapshot, and shell minimizer settings, then runs via a persistent native `Shell` session or one-shot `executeShell()`. `docs/bash-tool-runtime.md` covers that path in detail.\n13. `runInteractiveBashPty()` creates a `PtySession`, overlays an xterm-backed console UI, forwards user key input into the PTY, captures output through `OutputSink`, and keeps the PTY owned by the manager when its observer folds. Escape explicitly kills; disposal alone never kills folded work.\n14. On completion, `#buildCompletedResult()` formats `(no output)` when needed, attaches truncation metadata from the `OutputSink` summary, and re-checks exit status / timeout / cancellation before returning.\n15. On non-zero exit, timeout, missing exit status, or cancellation, `#buildResultText()` throws with the captured output included in the error message.\n\n## Modes / Variants\n1. Foreground non-PTY\n   - Default path.\n   - Uses `executeBash()`.\n   - Streams tail-only updates through `streamTailUpdates()` and `TailBuffer(DEFAULT_MAX_BYTES)`.\n2. Foreground PTY\n   - Requires `pty: true`, UI context, and `GJC_NO_PTY !== \"1\"`.\n   - Uses `runInteractiveBashPty()` and a `PtySession` overlay; observer disposal is non-owning, while Escape or `job cancel` kills the session.\n   - Supports interactive input; `Esc` kills the session from the overlay.\n3. Explicit background job\n   - Requires `async: true` and `async.enabled`.\n   - Registers a job with `session.asyncJobManager` and returns `{ state: \"running\", jobId }` immediately.\n4. Auto-backgrounded non-PTY job\n   - Requires `bash.autoBackground.enabled`, no PTY, and an async job manager.\n   - Starts like a foreground managed job, then backgrounds it when it outlives the wait window.\n5. Intercepted command\n   - No subprocess created.\n\n6. Foreground fold\n   - The remappable `app.tool.backgroundFold` chord (Alt+Shift+B by default; Cmd+B on macOS) can fold a running managed non-PTY Bash wait, ACP client-terminal wait, or PTY wait into a manager-owned job.\n   - A user steer admitted into the live run folds the same three surfaces automatically once the command has run for `STEER_FOLD_GRACE_MS` (2000 ms, exported from `bash.ts`, not configurable). Steers inside the grace window let the command finish normally. The steer fold fires only while `busyPromptMode` is `steer`; `toolInterruptPolicy` is not a gate, since a fold never kills the command; the `bash.autoBackground` setting is not consulted.\n   - Every fold records `metadata.foldReason` on the job (`steer` | `chord` | `timer` | `sdk_control`) through `AsyncJobManager.markBackgrounded(jobId, generation, reason)`. `async: true` jobs are backgrounded without a fold reason (`markStartedInBackground`).\n   - The background-start result carries `details.foldReason`; a steer fold appends `Folded into background job <id> because a user steer arrived; the command keeps running with its original timeout and its result will wake a later turn.`\n   - Chord, timer, and SDK-control folds stop the foreground turn cleanly after the result boundary; completion wakes a later turn with a receipt containing output, original intent, and a `job` retrieval handle. A steer fold does NOT end the turn: the same run consumes the steer at the tool boundary right after the fold result (subagent-await parity), remaining parallel tools in that batch are skipped, and the job's completion wakes a later turn.\n   - Folded jobs retain their original deadline and live `job tail` output. PTY observer disposal is non-owning; `job cancel` kills the live PTY through the manager lifecycle. Esc still aborts and kills the foreground command; a steer never kills it.\n\n## Side Effects\n- Filesystem\n  - Validates `cwd` with `fs.stat()`.\n  - May allocate and write artifact files for full output (`bash`) and minimizer-preserved raw output (`bash-original`).\n  - `expandInternalUrls(..., { ensureLocalParentDirs: true })` creates parent directories for `local://` paths before execution.\n- Subprocesses / native bindings\n  - Non-PTY uses native shell execution via `@gajae-code/natives` (`Shell.run()` or `executeShell()`).\n  - PTY uses native `PtySession.start()`.\n- Session state\n  - Reads session settings for async, auto-background, interceptor, tool availability, and shell configuration.\n  - Registers jobs with `session.asyncJobManager` for explicit/auto background runs.\n  - Uses `session.getSessionId()` to isolate shell reuse and async session keys.\n  - Uses `session.allocateOutputArtifact()` for spill files.\n- User-visible prompts / interactive UI\n  - PTY mode opens a TUI overlay titled `Console` and forwards input to the PTY.\n  - Background start messages direct the agent to the `job` tool (use `list: true` for a snapshot, or pass `poll: [id]` to wait).\n- Background work / cancellation\n  - Async and auto-background jobs continue after the initial tool return.\n  - Cancellation aborts the native run; Escape and `job cancel` kill a PTY, while overlay disposal alone is non-owning for folded work.\n\n## Limits & Caps\n- Default timeout: `300s` (`TOOL_TIMEOUTS.bash.default` in `packages/coding-agent/src/tools/tool-timeouts.ts`).\n- Timeout clamp: `1..3600s` (`TOOL_TIMEOUTS.bash.min/max`).\n- Auto-background default threshold: `60_000ms` (`DEFAULT_AUTO_BACKGROUND_THRESHOLD_MS` in `packages/coding-agent/src/tools/bash.ts`), further capped to `timeoutMs - 1000` by `#resolveAutoBackgroundWaitMs()`.\n- Hard kill grace beyond requested timeout in non-PTY executor: `5_000ms` (`HARD_TIMEOUT_GRACE_MS` in `packages/coding-agent/src/exec/bash-executor.ts`).\n- In-memory output tail cap: `50 * 1024` bytes (`DEFAULT_MAX_BYTES` in `packages/coding-agent/src/session/streaming-output.ts`). Once exceeded, the sink keeps only the tail window in memory.\n- Streaming callback throttle in `executeBash()`: `50ms` between `onChunk` calls when streaming is enabled.\n- TUI collapsed preview: `10` visual lines (`BASH_DEFAULT_PREVIEW_LINES`) when rendered inline in the agent UI; this is a renderer cap, not a tool output cap.\n\n## Errors\n- Input validation:\n  - invalid env key -> `ToolError(\"Invalid bash env name: <key>\")`.\n  - async requested while disabled -> `ToolError(\"Async bash execution is disabled...\")`.\n  - missing async job manager -> `ToolError(\"Async job manager unavailable for this session.\")`.\n  - missing/bad `cwd` -> `ToolError(\"Working directory does not exist: ...\")` or `ToolError(\"Working directory is not a directory: ...\")`.\n- Interceptor:\n  - matched command -> `ToolError` with `Blocked: <rule.message>` and the original command.\n  - invalid interceptor regexes are silently skipped by `compileRules()`.\n- Internal URL expansion:\n  - unsupported scheme, unknown skill, path traversal, missing router support, or router resolution failures all throw `ToolError` from `packages/coding-agent/src/tools/bash-skill-urls.ts`.\n- Execution:\n  - non-zero exit -> thrown `ToolError` containing captured output plus `Command exited with code <n>`.\n  - missing exit code -> thrown `ToolError` with `Command failed: missing exit status`.\n  - timeout -> thrown `ToolError`; PTY uses `Command timed out after <n> seconds`, non-PTY executor returns cancelled output that `BashTool` converts to an error.\n  - user abort -> `ToolAbortError` when the caller signal is aborted.\n- Artifact allocation / artifact save failures are swallowed in `saveBashOriginalArtifact()` and `OutputSink.#createFileSink()`; execution continues without that artifact.\n\n## Notes\n- `strict = true` and `concurrency = \"exclusive\"` are set on `BashTool`; the tool does not run concurrently with another bash tool call in the same session.\n- `command` and `env` URL expansions shell-escape replacements; `cwd` expansion uses `noEscape: true` because it becomes a filesystem path argument, not shell text.\n- `checkBashInterception()` blocks only when the matching rule's `tool` name is present in `ctx.toolNames`; missing tools disable their corresponding rule.\n- Default interceptor rules come from `DEFAULT_BASH_INTERCEPTOR_RULES` in `packages/coding-agent/src/config/settings-schema.ts`:\n  - `cat|head|tail|less|more` -> `read`\n  - `grep|rg|ripgrep|ag|ack` -> `search`\n  - `find|fd|locate` with name/type/glob flags -> `find`\n  - `sed -i`, `perl -i`, `awk -i inplace` -> `edit`\n  - `echo|printf|cat <<` with an output redirection of its own -> `write`. The redirection is only attributed to that leading command, so a redirection after `;`, `&&`, `||`, or `|` does not match, and fd redirections such as `2>/dev/null` are not treated as file writes.\n- PTY mode is ignored in non-UI contexts and when `GJC_NO_PTY=1`; the tool silently falls back to non-PTY execution.\n- Non-PTY runs merge `NON_INTERACTIVE_ENV` with `env`; PTY runs also prepend `NON_INTERACTIVE_ENV` before custom env values.\n- When the shell minimizer rewrites output inside `executeBash()`, the visible output is replaced with minimized text and a `[raw output: artifact://<id>]` footer may be appended if `onMinimizedSave` persisted the original text.\n- The TUI renderer parses partial JSON to recover `env` assignments early in streaming previews; that behavior is display-only.\n- For executor internals that are not tool-specific — shell session reuse keys, snapshots, prefix handling, and native timeout behavior — see `docs/bash-tool-runtime.md`.\n",
 	"tools/bisect.md": "# `bisect` tool\n\n`bisect` finds the exact commit that introduced (or fixed) a behavior by driving\n`git bisect` with a shell predicate, then restores the working tree and reports\nthe culprit. It is a discoverable built-in tool (activated on demand through\n`search_tool_bm25`, like `debug`, `recipe`, and `checkpoint`).\n\n## Why a tool instead of raw `git bisect`\n\nRunning `git bisect` by hand is error-prone for an agent: it is easy to forget\n`git bisect reset`, misread which commit is culpable, or strand the repository\nin a detached bisect state. The tool:\n\n- validates preconditions before touching repo state,\n- always runs `git bisect reset` in a `finally` block and then discards any\n  tracked-file edits the predicate made with `git reset --hard`, so the working\n  tree's tracked files are restored to their pre-bisect state even on error or\n  abort (untracked files the predicate created are left in place — the tool\n  never deletes files it did not create),\n- returns a structured, durable result (culprit + per-step verdicts) instead of\n  scrollback that must be re-parsed.\n\n## Parameters\n\n| Name | Default | Meaning |\n| --- | --- | --- |\n| `good` | — (required) | The **older** endpoint; must be an ancestor of `bad`. |\n| `bad` | `HEAD` | The **newer** endpoint. |\n| `run` | — (required) | Shell command evaluated at each revision. |\n| `invert` | `false` | Find the commit that *fixed* the behavior instead. |\n| `maxSteps` | `40` | Maximum bisection steps before giving up. |\n| `stepTimeoutMs` | `600000` | Per-step timeout; a timed-out step counts as a skip. |\n\n### Predicate exit-code contract\n\n`run` is executed as `sh -c <run>` from the repository root (the top level of the\nworking tree) at each candidate commit — even when the tool is invoked from a\nsubdirectory. Its exit code is mapped to a verdict:\n\n| Exit code | Verdict |\n| --- | --- |\n| `0` | good |\n| `125` | skip (revision cannot be tested) |\n| any other non-zero | bad |\n\n### Search direction\n\n`git bisect` requires `good` to be an ancestor of `bad`, so `good` is always the\nolder endpoint and `bad` the newer one, in both modes.\n\n- **Default (find the regression):** the predicate passes at `good` and fails at\n  `bad`. The tool reports the first commit that turned it bad.\n- **`invert: true` (find the fix):** the predicate fails at `good` and passes at\n  `bad`. Internally the good/bad verdict of each intermediate commit is flipped,\n  so the search reports the first commit that turned it good. A skip is never\n  reinterpreted.\n\n## Preconditions\n\n- The current directory must be inside a git worktree.\n- The worktree must be clean (no uncommitted tracked changes). Commit or stash\n  first — bisect checks out historical commits and would clobber uncommitted\n  work.\n- `good` must resolve, `bad` must resolve, they must differ, and `good` must be\n  an ancestor of `bad`.\n\n## Result\n\nOn success the tool reports the first bad (or first fixing) commit with its\nauthor, date, subject, and changed files, plus every revision it tested and\ntheir verdicts. When the search cannot converge (only skipped commits remain, a\n`git bisect` step fails, or `maxSteps` is reached) it reports the reason and the\nrevisions tested. In all cases every tracked file is restored to its pre-bisect\nstate; if the predicate created untracked files, the result says so and leaves\nthem in place.\n\n## Examples\n\nFind the commit that broke a specific test (older `v1.4.0` passes, `HEAD` fails):\n\n```json\n{ \"good\": \"v1.4.0\", \"bad\": \"HEAD\", \"run\": \"bun test test/login.test.ts\" }\n```\n\nFind the commit that fixed a bug (older `v1.0.0` fails, `HEAD` passes):\n\n```json\n{ \"good\": \"v1.0.0\", \"bad\": \"HEAD\", \"run\": \"bun test test/login.test.ts\", \"invert\": true }\n```\n\n## Implementation\n\n- Tool + pure loop controller + parsers: `packages/coding-agent/src/tools/bisect.ts`\n- `git bisect` wrappers: the `bisect` namespace in `packages/coding-agent/src/utils/git.ts`\n- Description: `packages/coding-agent/src/prompts/tools/bisect.md`\n\nThe bisect loop is a pure function (`runBisectController`) with all git and\npredicate effects injected, so it is unit-tested without a real repository;\n`parseFirstBadCommit` and `classifyExit` are tested independently, and an\nintegration test drives the whole tool against a real temporary git repository.\n",
 	"tools/browser.md": "# browser\n\n> Open, reuse, close, and script Puppeteer tabs against headless Chromium or CDP-attached apps.\n\n## Source\n- Entry: `packages/coding-agent/src/tools/browser.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/browser.md`\n- Key collaborators:\n  - `packages/coding-agent/src/tools/browser/tab-supervisor.ts` — global tab registry; worker lifecycle; run/close coordination.\n  - `packages/coding-agent/src/tools/browser/tab-worker.ts` — executes `run` code; implements the `tab` helper API.\n  - `packages/coding-agent/src/tools/browser/tab-worker-entry.ts` — worker-thread transport bootstrap.\n  - `packages/coding-agent/src/tools/browser/registry.ts` — browser-handle registry keyed by browser kind.\n  - `packages/coding-agent/src/tools/browser/launch.ts` — Puppeteer loading, Chromium resolution/download, headless launch, stealth injection.\n  - `packages/coding-agent/src/tools/browser/attach.ts` — CDP attach/reuse, target picking, spawned-app process handling.\n  - `packages/coding-agent/src/tools/browser/tab-protocol.ts` — worker init/run/result message schema.\n  - `packages/coding-agent/src/tools/browser/readable.ts` — `tab.extract()` readability extraction.\n  - `packages/coding-agent/src/tools/browser/render.ts` — TUI rendering for `open`/`close` status lines and `run` JS cells.\n  - `packages/coding-agent/src/tools/puppeteer/00_stealth_tampering.txt` — mask patched functions/descriptors as native.\n  - `packages/coding-agent/src/tools/puppeteer/01_stealth_activity.txt` — synthesize visibility/focus/scroll activity.\n  - `packages/coding-agent/src/tools/puppeteer/02_stealth_hairline.txt` — fix Modernizr hairline detection.\n  - `packages/coding-agent/src/tools/puppeteer/03_stealth_botd.txt` — spoof `navigator.webdriver`, `window.chrome`, and Chrome fingerprint surfaces.\n  - `packages/coding-agent/src/tools/puppeteer/04_stealth_iframe.txt` — patch iframe `contentWindow`/`srcdoc` behavior.\n  - `packages/coding-agent/src/tools/puppeteer/05_stealth_webgl.txt` — spoof WebGL vendor/renderer/precision.\n  - `packages/coding-agent/src/tools/puppeteer/06_stealth_screen.txt` — normalize screen/viewport/device-pixel-ratio values.\n  - `packages/coding-agent/src/tools/puppeteer/07_stealth_fonts.txt` — spoof local fonts and perturb canvas text rendering.\n  - `packages/coding-agent/src/tools/puppeteer/08_stealth_audio.txt` — spoof audio latency/sample-rate and perturb offline rendering.\n  - `packages/coding-agent/src/tools/puppeteer/09_stealth_locale.txt` — force locale/languages/timezone/date strings.\n  - `packages/coding-agent/src/tools/puppeteer/10_stealth_plugins.txt` — synthesize `navigator.plugins`/`navigator.mimeTypes`.\n  - `packages/coding-agent/src/tools/puppeteer/11_stealth_hardware.txt` — spoof `navigator.hardwareConcurrency`.\n  - `packages/coding-agent/src/tools/puppeteer/12_stealth_codecs.txt` — spoof media codec support.\n  - `packages/coding-agent/src/tools/puppeteer/13_stealth_worker.txt` — carry UA/platform spoofing into `Worker`/`SharedWorker`.\n\n## Inputs\n\n### Shared fields\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `action` | `\"open\" \\| \"close\" \\| \"act\" \\| \"run\"` | Yes | Dispatches to the open/close/act/run path. |\n| `name` | `string` | No | Tab id. Defaults to `\"main\"`. Tabs live in a process-global map, so the same name is reused across later calls and in-process subagents until closed. |\n| `timeout` | `number` | No | Tool wall-clock timeout in seconds. Defaults to `30`; clamped to the browser tool range before execution. |\n\n### `action: \"open\"`\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | No | Navigate after the tab is ready. Existing reusable tabs also navigate when `url` is supplied. |\n| `viewport` | `{ width: number; height: number; scale?: number }` | No | Requested viewport. For headless launch this becomes the initial viewport; for a page it is applied with `page.setViewport()`. `scale` maps to Puppeteer `deviceScaleFactor`. |\n| `wait_until` | `\"load\" \\| \"domcontentloaded\" \\| \"networkidle0\" \\| \"networkidle2\"` | No | Navigation wait condition. Defaults to `\"networkidle2\"` where omitted. |\n| `dialogs` | `\"accept\" \\| \"dismiss\"` | No | Installs a page `dialog` handler that auto-accepts or auto-dismisses dialogs. Omitted means no handler. |\n| `app` | `{ path?: string; cdp_url?: string; browser?: \"chrome\"; user_data_dir?: string; profile_directory?: string; background?: boolean; no_focus?: boolean; cdp_port?: number; args?: string[]; target?: string }` | No | Selects browser kind. No `app` uses the session `browser.headless` setting. `app.path` alone is resolved against the session cwd and used as the executable path for spawn/attach reuse. `app.cdp_url` connects to an existing CDP endpoint. `app.browser: \"chrome\"` selects guarded saved-profile mode: `path` defaults to installed Chrome/Chromium and `profile_directory` defaults to `\"Default\"`, while `user_data_dir` is required and must be a non-default Chrome data directory because Chrome 136+ disables remote debugging for its default data directory. Non-Chrome executables and default Chrome data roots are rejected. `args` are appended only when spawning `app.path` or a Chrome profile. `target` is used for attached/spawned/profile page selection. |\n\n### `action: \"close\"`\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `all` | `boolean` | No | Close every known tab. Omitted closes only `name`. |\n| `kill` | `boolean` | No | When a tab release drops a spawned-app browser handle to refcount 0, also terminate its process tree. For Chrome profile mode this kills only a profile browser process launched by GJC; externally-owned profile CDP and `app.cdp_url` are disconnect-only. Has no effect on headless shutdown. |\n\n### `action: \"run\"`\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `code` | `string` | Yes | Async-function body executed in a VM context with `page`, `browser`, `tab`, `display`, `assert`, `wait`, `console`, timers, `URL`, `TextEncoder`, `TextDecoder`, and `Buffer` in scope. |\n\n### `action: \"act\"`\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `actions` | non-empty `Array<ActionStep>` | Yes | Structured, ordered interaction steps. Prefer this to `run` for routine navigation and interaction. Verbs: `navigate`, `click`, `type`, `fill`, `select`, `press`, `scroll`, `back`, `wait`, `observe`, `extract`, `screenshot`. `click`/`type` accept an observed numeric `id` or selector; `fill`/`select` require selectors. |\n\n## Outputs\nThe tool returns one result per call; no streaming partial output is emitted from the browser implementation itself.\n\n- `open`: text content with `Opened` or `Reused`, browser description, URL, and optional title. `details` includes `action`, `name`, `browser`, `url`, `viewport`, and the same text in `details.result`.\n- `close`: text content with either `Closed ...` or `No tab named ...`. `details` includes `action`, `name`, and `details.result`.\n- `run`: ordered `content` array built as:\n  1. every `display(value)` call in execution order,\n  2. a runtime-diagnostics JSON block when the tab observed page exceptions or `console.error` events,\n  3. final return value, JSON-stringified unless already a string,\n  4. or `Ran code on tab \"...\"` if nothing else was produced.\n- `act`: the same ordered `content` shape, with per-step results as the final JSON return value, or `Ran <n> action(s) on tab \"...\"` if no step produced content.\n- `display(value)` coercion in `packages/coding-agent/src/tools/browser/tab-worker.ts`:\n  - `{ type: \"image\", data: string, mimeType: string }` becomes image content,\n  - `string` becomes text content,\n  - other values become pretty JSON text when serializable, else `String(value)`.\n- `tab.screenshot()` also appends text plus an image content item unless `silent: true`; `details.screenshots` records persisted screenshot metadata `{ dest, mimeType, bytes, width, height }`.\n- `run` and `act` `details` include `action`, `name`, current `browser`/`url` when the tab exists, optional `screenshots`, and `details.result` containing only concatenated text outputs.\n- Runtime diagnostics are opt-in: `open(..., { diagnostics: true })` subscribes the tab to CDP `Runtime.exceptionThrown` and `console.error` events (an extra CDP session plus `Runtime.enable` per tab — the added per-event traffic is the reason it is not on by default). Each tab keeps the newest 20 events in memory. The next successful `run` or `act` drains them as `{ runtimeDiagnostics, runtimeDiagnosticsDropped }`; failed actions leave the mailbox for the next successful response. Each entry contains only kind, timestamp, origin-only URL, line/column, and an error class from a fixed allowlist of built-in error classes when available; path segments, query strings, messages, console arguments, values, and stacks are never retained. Serialization is bounded: the `url` field is capped with a visible `…` marker and the whole block is capped at 4 KiB, shedding the oldest entries first and marking the block with `runtimeDiagnosticsTruncated: true` when that cap is hit — truncation is never silent.\n\n## Flow\n1. `BrowserTool.execute()` (`packages/coding-agent/src/tools/browser.ts`) abort-checks, clamps `timeout` via `clampTimeout(\"browser\", ...)`, defaults `name` to `\"main\"`, and dispatches `open`, `close`, `act`, or `run`.\n2. `open` resolves browser kind with `resolveBrowserKind()`:\n   - `app.cdp_url` → `{ kind: \"connected\" }` after trimming trailing slashes.\n   - `app.browser: \"chrome\"` → `{ kind: \"chrome-profile\" }`. `path` defaults to installed Chrome/Chromium (`resolveSystemChromeForProfile()`, admitting only Chrome/Chromium brands) and `profile_directory` defaults to `\"Default\"`. `user_data_dir` is required, resolved against the session cwd, and rejected when it resolves (including through a symlink) to a platform default Stable/Beta/Dev/Canary/Chromium root; trusted Linux environment overrides plus Flatpak and Snap defaults are included. Chrome 136+ does not honor remote-debugging switches for default Chrome data directories. Explicit Edge, Brave, Vivaldi, Opera, and unknown browser executables are rejected before profile fields are resolved. `background`, `no_focus`, and optional `cdp_port` are copied through.\n   - `app.path` → `{ kind: \"spawned\" }` after resolving against session cwd.\n   - otherwise → `{ kind: \"headless\", headless: session.settings.get(\"browser.headless\") }`.\n3. `open` rejects reusing the same tab name across different browser kinds (`sameBrowserKind()`); callers must close first.\n4. `open` acquires a browser handle through `acquireBrowser()` (`packages/coding-agent/src/tools/browser/registry.ts`):\n   - existing connected handle is reused by browser-kind key;\n   - stale disconnected handles are disposed and recreated;\n   - headless launches via `launchHeadlessBrowser()`;\n   - `connected` waits for `${cdpUrl}/json/version`, then `puppeteer.connect()`;\n   - `spawned` first tries `findReusableCdp()`, else kills same-path processes, allocates a free loopback port, spawns the executable with `--remote-debugging-port=<port>`, waits for CDP, then connects.\n   - `chrome-profile` checks same-executable processes for matching `--user-data-dir` and `--profile-directory`; if the matching process already exposes a responding `127.0.0.1` CDP port it reuses and later only disconnects, if it is running without attachable CDP it refuses without killing or relaunching, and if it is not running GJC launches Chrome with `--remote-debugging-address=127.0.0.1`, an ephemeral or configured `--remote-debugging-port`, `--user-data-dir`, `--profile-directory`, and `--no-startup-window` when `background` or `no_focus` is set. Only this GJC-launched process is eligible for `kill` cleanup.\n5. `open` acquires a tab through `acquireTab()` (`packages/coding-agent/src/tools/browser/tab-supervisor.ts`):\n   - same-name + same-browser + alive tab is reused unless `dialogs` changed;\n   - same-name but different browser handle, dead state, or changed dialog policy forces release and recreation;\n   - reusing with a new `url` navigates by issuing `await tab.goto(...)` through the worker.\n6. New tabs build a `WorkerInitPayload` in `buildInitPayload()`:\n   - headless mode sends `url`, `waitUntil`, `viewport`, `dialogs`, and timeout;\n   - attach mode resolves a page with `pickElectronTarget()`, gets its target id, and sends `targetId` plus `dialogs`.\n7. `acquireTab()` spawns a dedicated Bun `Worker` from `tab-worker-entry.ts`; if that fails it falls back to inline execution in the main thread (`spawnInlineWorker()`), preserving behavior but losing protection against synchronous infinite loops.\n8. `WorkerCore.#init()` (`packages/coding-agent/src/tools/browser/tab-worker.ts`) connects back to the browser websocket endpoint. Headless mode opens a new page, applies stealth patches, applies viewport, installs dialog handling if requested, and optionally navigates. Attach mode resolves the requested target page and optionally installs dialog handling.\n9. On success the worker sends `ready` with `{ url, title, viewport, targetId }`; the supervisor stores a `TabSession`, increments browser-handle refcount with `holdBrowser()`, and keeps the tab in a process-global `Map<string, TabSession>`.\n\n### Existing non-default Chrome profile mode\n\nUse this mode for a dedicated, persistent Chrome data root that already contains the automation profile and login state. Chrome 136+ rejects remote debugging against the browser's default data root, so do not point this mode at the daily Chrome root. Create and sign in to a separate root first, close that Chrome instance, then let GJC reopen it with the guarded CDP lifecycle:\n\n```json\n{\n  \"action\": \"open\",\n  \"name\": \"work-browser\",\n  \"app\": {\n    \"browser\": \"chrome\",\n    \"user_data_dir\": \"~/Library/Application Support/GJC/Chrome Automation\",\n    \"profile_directory\": \"Default\",\n    \"background\": true,\n    \"no_focus\": true,\n    \"target\": \"example.com\"\n  }\n}\n```\n\nSecurity and lifecycle rules:\n\n- CDP is bound to `127.0.0.1`; do not expose logged-in profile CDP ports on a public interface. A CDP client has full browser-account access.\n- `user_data_dir` must be a separate non-default data root. Platform Stable/Beta/Dev/Canary/Chromium defaults, Linux environment/Flatpak/Snap defaults, and aliases to them are rejected before launch. Use `app.cdp_url` only for an already-authorized endpoint that you intentionally started and control.\n- Saved-profile and attached-CDP automation can read and act with that profile's cookies and authenticated accounts. Use it only when that credentialed access is intentional.\n- Never use generic `app.path` spawning for a daily Chrome profile: it may kill stale same-path processes. Use explicit `app.browser: \"chrome\"` profile mode, which applies the ownership guards below.\n- A matching already-running profile is reused only when its localhost CDP endpoint responds. A matching profile running normally without CDP is refused with remediation text; GJC does not kill or relaunch it.\n- `background` and `no_focus` add Chromium's `--no-startup-window` launch guard. Focus avoidance is best-effort and platform-dependent; already-visible Chrome windows can still be selected by `target` but are not OS-keyboard/mouse driven.\n- Cleanup disconnects externally-owned CDP endpoints. `kill: true` terminates only the Chrome profile process that GJC launched for this mode.\n10. `run` requires non-empty `code`; `act` requires non-empty `actions`, validates and compiles them into injection-safe JSON-parsed code, then both delegate to `runInTab()`.\n11. `runInTabWithSnapshot()` rejects dead tabs and concurrent runs (`Tab ... is busy`), captures session cwd plus optional `browser.screenshotDir`, registers an abort hook, sends a `run` message to the worker, and races the result against `timeoutMs + 750` ms. Timeouts force-kill the tab worker and, for headless tabs, close the orphaned page target.\n12. `WorkerCore.#run()` creates a VM context, exposes the raw Puppeteer `page`/`browser` plus a synthetic `tab` API, and executes `(async () => { ...code... })()` via `vm.runInContext()`.\n13. The `tab` helper API implemented in `#createTabApi()` is:\n   - `tab.name: string`\n   - `tab.page: Page`\n   - `tab.signal?: AbortSignal`\n   - `tab.url(): string`\n   - `tab.title(): Promise<string>`\n   - `tab.goto(url, { waitUntil? })`\n   - `tab.observe({ includeAll?, viewportOnly? })`\n   - `tab.screenshot({ selector?, fullPage?, save?, silent? })`\n   - `tab.extract(format = \"markdown\")`\n   - `tab.click(selector)`\n   - `tab.type(selector, text)`\n   - `tab.fill(selector, value)`\n   - `tab.press(key, { selector? })`\n   - `tab.scroll(deltaX, deltaY)`\n   - `tab.drag(from, to)`\n   - `tab.waitFor(selector)`\n   - `tab.evaluate(fn, ...args)`\n   - `tab.scrollIntoView(selector)`\n   - `tab.select(selector, ...values)`\n   - `tab.uploadFile(selector, ...filePaths)`\n   - `tab.waitForUrl(pattern, { timeout? })`\n   - `tab.waitForResponse(pattern, { timeout? })`\n   - `tab.id(n)`\n14. Selector handling in `normalizeSelector()` requires a non-empty string, accepts plain CSS and Puppeteer query handlers, and rewrites legacy Playwright-style prefixes `p-text/`, `p-xpath/`, `p-pierce/`, `p-aria/`; other `p-*` prefixes throw a `ToolError`. Non-string and whitespace-only selectors fail before browser actions. Numeric observation ids must use `(await tab.id(58)).click()`, not `tab.click(58)`. Omit optional selectors (or pass `undefined`) for unfocused `tab.press()` or page-level `tab.screenshot()`; null, false, zero, and blank selectors are not omission.\n15. `tab.observe()` clears the element cache, takes a Puppeteer accessibility snapshot, filters to interactive nodes unless `includeAll`, optionally filters to viewport-visible nodes, assigns numeric ids, caches `ElementHandle`s, and returns URL/title/viewport/scroll metadata plus `elements`.\n16. `tab.id(n)` resolves the cached `ElementHandle`, verifies `el.isConnected`, and throws a stale-id error after cache invalidation if the DOM changed or the cache was cleared.\n17. `tab.goto()` clears the cached element ids before navigating. Any new `tab.observe()` also clears and rebuilds the cache.\n18. `tab.click()` uses a custom retry loop for `text/...` selectors to find an actionable visible match; other selectors use `page.locator(...).click()` with the run timeout.\n19. `tab.screenshot()` captures either the whole page or a selector PNG, downsizes a copy for model output, chooses a persistence path, writes the image to disk, records metadata, and optionally emits text + image display entries.\n20. `display()` calls accumulate in an array. After code finishes, the worker posts `{ displays, returnValue, screenshots }`; `BrowserTool.#run()` appends the return value as trailing text content when not `undefined`.\n21. `close` releases one tab or all tabs via `releaseTab()` / `releaseAllTabs()`. Each tab aborts pending runs, asks the worker to close, waits up to `750` ms for a `closed` ack, terminates the worker, decrements browser refcount, and disposes the browser handle when refcount reaches zero.\n\n## Modes / Variants\n- **Action dispatch**\n  - `open` — acquire/reuse browser + tab.\n  - `close` — release one tab or all tabs.\n  - `act` — validate and run structured interaction steps; preferred for routine navigation and interaction.\n  - `run` — execute JS inside the tab worker.\n- **Browser kind**\n  - **Headless**: launches local Chromium with Puppeteer, applies stealth patches, and creates a fresh page per tab.\n  - **Spawned app (`app.path`)**: reuses an existing CDP-enabled process for that executable when possible; otherwise kills same-path processes, spawns the executable with remote debugging enabled, then attaches. No stealth patches are injected.\n  - **Connected browser (`app.cdp_url`)**: attaches to an already-running CDP endpoint. No process ownership; close only disconnects.\n- **Target selection for attached/spawned browsers**\n  - With `app.target`, `pickElectronTarget()` returns the first page whose URL or title contains the case-insensitive substring.\n  - Without `app.target`, it skips titles/URLs matching `request handler|devtools|background page|background host|service worker` and otherwise falls back to the first page.\n- **Worker mode**\n  - **Dedicated worker**: normal path; user code runs off the main thread and can be aborted even when it blocks synchronously.\n  - **Inline fallback**: activated when Bun worker spawn fails; behavior matches, but synchronous infinite loops on user code cannot be interrupted.\n- **Dialog policy**\n  - No `dialogs` field: no auto-handler.\n  - `accept`/`dismiss`: page `dialog` events are handled automatically.\n  - Changing dialog policy on an existing live tab forces tab recreation instead of mutating the worker in place.\n- **Screenshot persistence**\n  - `save` provided: persist full-resolution PNG at the resolved cwd-relative or absolute path.\n  - `browser.screenshotDir` session setting set: persist full-resolution PNG under that directory with a timestamped filename.\n  - Neither set: persist the resized image to a temp-file path under the OS temp dir.\n\n## Side Effects\n- Filesystem\n  - `loadPuppeteer()` writes `{}` to `<puppeteer-safe-dir>/package.json` before importing `puppeteer-core`.\n  - First headless launch may download Chromium into the Puppeteer cache directory returned by `getPuppeteerDir()`.\n  - `tab.screenshot()` creates parent directories and writes image files.\n  - `tab.uploadFile()` resolves supplied paths against the session cwd.\n- Network\n  - CDP attach paths poll `http://127.0.0.1:<port>/json/version` or the supplied `cdp_url` `/json/version`.\n  - Headless/browser-attach sessions create CDP websocket connections.\n  - Headless first-use Chromium download uses `@puppeteer/browsers`.\n  - User `page` / `tab` operations perform normal browser network traffic.\n- Subprocesses / native bindings\n  - Headless mode launches Chromium through Puppeteer.\n  - `app.path` mode may spawn the target executable via `Bun.spawn()`.\n  - `killExistingByPath()` / `gracefulKillTreeOnce()` use `@gajae-code/natives` process inspection/termination.\n  - Worker mode uses Bun `Worker`; fallback mode does not.\n- Session state (transcript, memory, jobs, checkpoints, registries)\n  - Browser handles are cached in a process-global `Map` keyed by browser kind in `packages/coding-agent/src/tools/browser/registry.ts`.\n  - Tabs are cached in a process-global `Map` keyed by `name` in `packages/coding-agent/src/tools/browser/tab-supervisor.ts`.\n  - `run` captures session cwd and optional `browser.screenshotDir` for screenshot/save path resolution.\n  - `restartForModeChange()` drops only headless tabs.\n- User-visible prompts / interactive UI\n  - None beyond normal tool output. Dialog auto-handling is invisible unless it fails and emits debug logs.\n- Background work / cancellation\n  - `open`, `run`, CDP waits, and browser actions thread through abort signals.\n  - A timed-out `run` aborts the worker execution path and can tear down the tab.\n\n## Limits & Caps\n- Tool timeout clamp: default `30` s, min `1` s, max `30` s (`TOOL_TIMEOUTS.browser` in `packages/coding-agent/src/tools/tool-timeouts.ts`).\n- Supervisor grace period around init/run/close: `750` ms (`GRACE_MS` in `packages/coding-agent/src/tools/browser/tab-supervisor.ts`).\n- Puppeteer protocol timeout for launch/connect operations: `60_000` ms (`BROWSER_PROTOCOL_TIMEOUT_MS` in `packages/coding-agent/src/tools/browser/launch.ts`).\n- Connected-browser CDP readiness wait: `5_000` ms before `puppeteer.connect()` (`packages/coding-agent/src/tools/browser/registry.ts`).\n- Spawned-app CDP readiness wait after spawn: `30_000` ms (`packages/coding-agent/src/tools/browser/registry.ts`).\n- CDP polling cadence: 150 ms in `waitForCdp()` (`packages/coding-agent/src/tools/browser/attach.ts`).\n- Headless default viewport: `1365x768` at `deviceScaleFactor: 1.25` (`DEFAULT_VIEWPORT` in `packages/coding-agent/src/tools/browser/launch.ts`).\n- Screenshot model-attachment resize cap: `maxWidth 1024`, `maxHeight 1024`, `maxBytes 150 * 1024`, `jpegQuality 70` (`packages/coding-agent/src/tools/browser/tab-worker.ts`).\n- `tab.waitForUrl()` polling interval: `200` ms (`packages/coding-agent/src/tools/browser/tab-worker.ts`).\n- Drag simulation uses `12` mouse-move steps (`packages/coding-agent/src/tools/browser/tab-worker.ts`).\n\n## Errors\n- `BrowserTool.execute()` converts DOM-style `AbortError` into `ToolAbortError`; other errors propagate.\n- `run` hard-fails on missing code: `Missing required parameter 'code' for action 'run'.`\n- `open` fails when reusing a name across browser kinds: `Tab \"...\" is bound to a different browser (...). Close it first.`\n- `runInTabWithSnapshot()` fails when the tab is absent/dead (`Tab \"...\" is not alive. Reopen it.`) or already running (`Tab \"...\" is busy`).\n- Worker init failures and run failures are serialized through `RunErrorPayload`; `ToolError` and abort state are reconstructed on the host side by `errorFromPayload()`.\n- Attached-target mismatches surface as:\n  - `No page targets available on the attached browser`\n  - `No page target matched \"...\". Available pages:\\n...`\n  - `Target ... is no longer available on the attached browser`\n- Spawned-app path validation requires an absolute executable path, not an app bundle path.\n- Spawn/attach failures are wrapped into `ToolError`s such as `Timed out waiting for CDP endpoint ...`, `Failed to attach to ...`, or `Connected to ... but puppeteer.connect failed: ...`.\n- `tab` helper errors are user-visible `ToolError`s, including unsupported selector prefix, stale/unknown element id, invalid drag target, missing upload files, non-`<select>` for `tab.select()`, non-file-input for `tab.uploadFile()`, and screenshot selector misses.\n- On run timeout, the worker reports `Browser code execution timed out after <ms>ms`; the supervisor may escalate to `Browser code execution hung past grace; tab killed` if the worker does not respond after the grace window.\n\n## Notes\n- `loadPuppeteer()` and `loadPuppeteerInWorker()` temporarily redirect `cwd` to a safe Puppeteer directory before importing `puppeteer-core`, because Puppeteer probes the current working directory during module load.\n- Headless launch prefers a detected system Chrome/Chromium, then `PUPPETEER_EXECUTABLE_PATH`, and only then downloads Chromium.\n- Headless launch always passes `--no-sandbox`, `--disable-setuid-sandbox`, `--disable-blink-features=AutomationControlled`, and a `--window-size=...` matching the initial viewport. It also ignores Puppeteer default args `--disable-extensions`, `--disable-default-apps`, and `--disable-component-extensions-with-background-pages`.\n- Proxy-related env vars only affect headless launch: `PUPPETEER_PROXY`, `PUPPETEER_PROXY_BYPASS_LOOPBACK`, and `PUPPETEER_PROXY_IGNORE_CERT_ERRORS`.\n- Stealth patches are applied only in headless mode. Spawned or externally connected browsers are intentionally left untouched.\n- `applyStealthPatches()` also strips Puppeteer's `//# sourceURL=__puppeteer_evaluation_script__` suffix from CDP `Runtime.evaluate` / `Runtime.callFunctionOn` payloads.\n- `tab.extract()` reads `page.content()`, runs Readability first, then falls back to `main article`/`article`/`main`/`[role='main']`/`body`, and returns `null` if neither extraction path yields content.\n- `close(all: true, kill: false)` disconnects from spawned/connected browsers when the last tab closes but leaves spawned app processes running.\n- Headless orphan cleanup is best-effort: if a worker dies before closing its page, the supervisor searches browser targets by `targetId` and closes that page.\n- Console methods inside `run` do not appear in tool output; they are forwarded as debug/warn/error logs through the worker transport.\n- Runtime diagnostics are not written to a separate browser state or log. Once surfaced, their bounded metadata follows the ordinary tool-result transcript lifecycle. Opening a tab without `diagnostics: true` creates no CDP `Runtime` subscription and no per-event work.",
-	"tools/calc.md": "# calc\n\n> Evaluates one or more arithmetic expressions and returns formatted numeric results.\n\n## Source\n- Entry: `packages/coding-agent/src/tools/calculator.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/calculator.md`\n- Key collaborators:\n  - `packages/coding-agent/src/tui.ts` — status lines and tree-list rendering\n  - `packages/coding-agent/src/tools/render-utils.ts` — preview limits and formatting helpers\n\n## Inputs\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `calculations` | `Calculation[]` | Yes | Batch of expressions to evaluate in order. |\n\n### `Calculation`\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `expression` | `string` | Yes | Arithmetic expression string. |\n| `prefix` | `string` | Yes | Prepended verbatim to the rendered numeric result. |\n| `suffix` | `string` | Yes | Appended verbatim to the rendered numeric result. |\n\n## Outputs\n- Single-shot result.\n- `content[0].text` is the newline-joined `prefix + value + suffix` string for each calculation.\n- `details.results` is an array of `{ expression, value, output }`.\n- On renderer fallback, if `details` is missing but `content[0].text` exists, the TUI tries to pair each output line with the original expressions from call args.\n\n## Flow\n1. `execute()` wraps evaluation in `untilAborted(...)`.\n2. For each entry, `evaluateExpression(...)` tokenizes the expression, parses it with a recursive-descent parser, rejects non-finite outputs, and normalizes `-0` to `0`.\n3. `tokenizeExpression(...)` accepts whitespace, parentheses, operators, and number literals; any other character throws immediately.\n4. `ExpressionParser` applies precedence in this order: `+ -`, `* / %`, unary `+ -`, exponentiation `**`, parentheses/literals.\n5. Exponentiation is right-associative (`2 ** 3 ** 2` parses as `2 ** (3 ** 2)`).\n6. Each numeric result is formatted with `String(value)` and wrapped with the provided `prefix` and `suffix`.\n7. The tool returns text output plus structured `details`.\n\n## Side Effects\n- Background work / cancellation\n  - Supports abort via `untilAborted(...)`.\n- Session state\n  - None.\n- Filesystem / Network / Subprocesses\n  - None.\n\n## Limits & Caps\n- Supported operators: `+`, `-`, `*`, `/`, `%`, `**` (`packages/coding-agent/src/tools/calculator.ts`).\n- Supported numeric literals:\n  - decimal integers/floats, including leading-dot forms like `.5`\n  - scientific notation like `1e10`, `2.5E-3`\n  - hexadecimal `0x...`\n  - binary `0b...`\n  - octal `0o...`\n- Results must be finite; `Infinity` and `NaN` are rejected.\n- The renderer collapses long result lists using `PREVIEW_LIMITS.COLLAPSED_ITEMS` from `packages/coding-agent/src/tools/render-utils.ts`.\n\n## Errors\n- Invalid characters: e.g. `Invalid character \"x\" in expression`.\n- Malformed numbers: invalid prefixed literal, invalid exponent, invalid number.\n- Syntax errors: `Unexpected token in expression`, `Unexpected end of expression`, `Missing closing parenthesis`, `Expression is empty`.\n- Non-finite arithmetic: `Expression result is not a finite number`.\n- Any evaluation error aborts the whole batch; the tool does not return partial successes.\n\n## Notes\n- Despite the schema example showing `sqrt(16)`, the parser does not support functions, identifiers, units, or constants; only numeric literals, operators, and parentheses are accepted.\n- Precision is plain JavaScript `number` semantics throughout, including floating-point rounding behavior.\n- `/` and `%` use JavaScript numeric operators directly; there is no integer-only mode or unit handling.\n- Unary operators bind tighter than `*`/`/`/`%` but looser than exponentiation because unary parsing delegates to `#parsePower()`.\n",
+	"tools/calc.md": "# calc\n\n> Evaluates one or more arithmetic expressions and returns formatted numeric results.\n\n## Source\n- Entry: `packages/coding-agent/src/tools/calculator.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/calculator.md`\n- Key collaborators:\n  - `packages/coding-agent/src/tui/status-line.ts`, `packages/coding-agent/src/tui/tree-list.ts` — status lines and tree-list rendering\n  - `packages/coding-agent/src/tools/render-utils.ts` — preview limits and formatting helpers\n\n## Inputs\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `calculations` | `Calculation[]` | Yes | Batch of expressions to evaluate in order. |\n\n### `Calculation`\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `expression` | `string` | Yes | Arithmetic expression string. |\n| `prefix` | `string` | Yes | Prepended verbatim to the rendered numeric result. |\n| `suffix` | `string` | Yes | Appended verbatim to the rendered numeric result. |\n\n## Outputs\n- Single-shot result.\n- `content[0].text` is the newline-joined `prefix + value + suffix` string for each calculation.\n- `details.results` is an array of `{ expression, value, output }`.\n- On renderer fallback, if `details` is missing but `content[0].text` exists, the TUI tries to pair each output line with the original expressions from call args.\n\n## Flow\n1. `execute()` wraps evaluation in `untilAborted(...)`.\n2. For each entry, `evaluateExpression(...)` tokenizes the expression, parses it with a recursive-descent parser, rejects non-finite outputs, and normalizes `-0` to `0`.\n3. `tokenizeExpression(...)` accepts whitespace, parentheses, operators, and number literals; any other character throws immediately.\n4. `ExpressionParser` applies precedence in this order: `+ -`, `* / %`, unary `+ -`, exponentiation `**`, parentheses/literals.\n5. Exponentiation is right-associative (`2 ** 3 ** 2` parses as `2 ** (3 ** 2)`).\n6. Each numeric result is formatted with `String(value)` and wrapped with the provided `prefix` and `suffix`.\n7. The tool returns text output plus structured `details`.\n\n## Side Effects\n- Background work / cancellation\n  - Supports abort via `untilAborted(...)`.\n- Session state\n  - None.\n- Filesystem / Network / Subprocesses\n  - None.\n\n## Limits & Caps\n- Supported operators: `+`, `-`, `*`, `/`, `%`, `**` (`packages/coding-agent/src/tools/calculator.ts`).\n- Supported numeric literals:\n  - decimal integers/floats, including leading-dot forms like `.5`\n  - scientific notation like `1e10`, `2.5E-3`\n  - hexadecimal `0x...`\n  - binary `0b...`\n  - octal `0o...`\n- Results must be finite; `Infinity` and `NaN` are rejected.\n- The renderer collapses long result lists using `PREVIEW_LIMITS.COLLAPSED_ITEMS` from `packages/coding-agent/src/tools/render-utils.ts`.\n\n## Errors\n- Invalid characters: e.g. `Invalid character \"x\" in expression`.\n- Malformed numbers: invalid prefixed literal, invalid exponent, invalid number.\n- Syntax errors: `Unexpected token in expression`, `Unexpected end of expression`, `Missing closing parenthesis`, `Expression is empty`.\n- Non-finite arithmetic: `Expression result is not a finite number`.\n- Any evaluation error aborts the whole batch; the tool does not return partial successes.\n\n## Notes\n- Despite the schema example showing `sqrt(16)`, the parser does not support functions, identifiers, units, or constants; only numeric literals, operators, and parentheses are accepted.\n- Precision is plain JavaScript `number` semantics throughout, including floating-point rounding behavior.\n- `/` and `%` use JavaScript numeric operators directly; there is no integer-only mode or unit handling.\n- Unary operators bind tighter than `*`/`/`/`%` but looser than exponentiation because unary parsing delegates to `#parsePower()`.\n",
 	"tools/checkpoint.md": "# checkpoint\n\n> Mark the current top-level conversation state so later `rewind` can collapse exploratory context into a report.\n\n## Source\n- Entry: `packages/coding-agent/src/tools/checkpoint.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/checkpoint.md`\n- Key collaborators:\n  - `packages/coding-agent/src/session/agent-session.ts` — captures the active checkpoint after tool success.\n  - `packages/coding-agent/src/session/session-manager.ts` — persists the normal session entry stream; not the active checkpoint marker.\n  - `packages/coding-agent/src/tools/index.ts` — registers the tool and gates it behind `checkpoint.enabled`.\n  - `packages/coding-agent/src/config/settings-schema.ts` — defines the disabled-by-default feature flag.\n\n## Inputs\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `goal` | `string` | Yes | Investigation goal. Required by the schema and echoed in the tool result. |\n\n## Outputs\nThe tool returns a single text result plus structured details:\n\n- text body:\n  - `Checkpoint created.`\n  - `Goal: <goal>`\n  - `Run your investigation, then call rewind with a concise report.`\n- `details`:\n  - `goal: string`\n  - `startedAt: string` — ISO timestamp created inside `CheckpointTool.execute()`\n\nNo checkpoint ID, artifact URI, job handle, file path, or restore token is returned.\n\n## Flow\n1. `CheckpointTool.createIf()` in `packages/coding-agent/src/tools/checkpoint.ts` returns `null` for subagents by checking `session.taskDepth`; only top-level sessions can see the tool.\n2. `CheckpointTool.execute()` rejects subagent calls again with `ToolError(\"Checkpoint not available in subagents.\")`.\n3. It rejects nested checkpoints with `ToolError(\"Checkpoint already active.\")` when `session.getCheckpointState?.()` is already set.\n4. It creates `startedAt = new Date().toISOString()` and returns a normal `toolResult()` payload. The tool itself does not persist anything.\n5. On the later `tool_execution_end` event, `AgentSession` in `packages/coding-agent/src/session/agent-session.ts` detects successful `checkpoint` execution and captures three in-memory fields:\n   - `checkpointMessageCount` — current `agent.state.messages.length`, after the checkpoint tool result has already been appended\n   - `checkpointEntryId` — `sessionManager.getEntries().at(-1)?.id ?? null`, i.e. the last persisted session entry ID at checkpoint time\n   - `startedAt` — copied from tool details or regenerated\n6. `AgentSession` stores that object in its private `#checkpointState` field and clears `#pendingRewindReport`.\n\n## Side Effects\n- Session state (transcript, memory, jobs, checkpoints, registries)\n  - Sets `AgentSession.#checkpointState` in memory.\n  - Records the checkpoint boundary as a message count plus a session entry ID.\n  - Enables the later yield guard: if a checkpoint is active and no rewind report is pending, `#enforceRewindBeforeYield()` injects a developer-role warning and schedules another turn.\n- User-visible prompts / interactive UI\n  - The tool result tells the model to call `rewind` after the investigation.\n  - If the agent tries to `yield` first, `AgentSession` injects:\n\n```text\n<system-warning>\nYou are in an active checkpoint. You MUST call rewind with your investigation findings before yielding. Do NOT yield without completing the checkpoint.\n</system-warning>\n```\n\n## Limits & Caps\n- Availability is gated by `checkpoint.enabled`, default `false`, in `packages/coding-agent/src/config/settings-schema.ts`.\n- The tool is registered as discoverable in `packages/coding-agent/src/tools/index.ts`.\n- Only one active checkpoint is allowed per top-level session.\n- Checkpoint state is not persisted as a dedicated session entry. If the process exits, a resumed session can reload the conversation history, but not the live `#checkpointState` guard.\n- Session persistence still applies to the ordinary checkpoint tool call message. Global session persistence truncation is `MAX_PERSIST_CHARS = 500_000` in `packages/coding-agent/src/session/session-manager.ts`.\n\n## Errors\n- `ToolError(\"Checkpoint not available in subagents.\")` — thrown for subagent sessions.\n- `ToolError(\"Checkpoint already active.\")` — thrown when a prior checkpoint has not been rewound or cleared.\n- The tool body has no local `try/catch`; unexpected exceptions propagate.\n\n## Notes\n- Despite the summary string `Create a git-based checkpoint to save and restore session state`, the implementation does not call git and does not snapshot filesystem state.\n- Captured state is conversation/session metadata only:\n  - in-memory message count\n  - session entry ID in the session tree\n  - timestamp\n- Not captured:\n  - working tree contents\n  - staged changes\n  - artifacts\n  - blob-store contents\n  - SQLite history rows from `packages/coding-agent/src/session/history-storage.ts`\n  - auth or agent records from `packages/coding-agent/src/session/agent-storage.ts`\n- If the turn ends with `stopReason === \"aborted\"` while a checkpoint is active, `AgentSession` clears `#checkpointState` and `#pendingRewindReport` instead of preserving a half-finished checkpoint.\n",
 	"tools/computer.md": "# computer\n\n> Supervisor-gated macOS desktop screenshot and input control through the native computer controller.\n\n## Source\n\n- Entry: `packages/coding-agent/src/tools/computer.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/computer.md`\n- Renderer: `packages/coding-agent/src/tools/computer/render.ts`\n- Native controller: `@gajae-code/natives` `ComputerController`\n\n## Availability\n\n`computer` is callable by default on supported Apple Silicon macOS (`process.platform === \"darwin\"` and `process.arch === \"arm64\"`).\n\nAn explicit `computer.enabled=false` disables it. When `computer.enabled` is unset, `computer.alwaysOn=false` also disables it; `computer.enabled=true` explicitly enables it on a supported host.\n\nWhen disabled, every action including `screenshot` returns `COMPUTER_DISABLED`. Disabled catalog/listing paths do not construct `ComputerController`, start hotkeys, probe Screen Recording, probe Accessibility, capture screenshots, or expose the callable schema to `search_tool_bm25`.\n\n## Inputs\n\nThe model action object uses an exact snake_case discriminated schema. CamelCase fields are rejected.\n\n### Shared fields\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `action` | see actions below | Yes | Dispatch action. |\n| `timeout` | `number` | No | Maximum action time in seconds. |\n| `include_screenshot` | `boolean` | No | Request a bounded post-action screenshot when supported. |\n\n### Actions\n\n| Action | Required fields | Optional fields |\n| --- | --- | --- |\n| `screenshot` | none | shared |\n| `click` | `x`, `y` | `button`, shared |\n| `double_click` | `x`, `y` | `button`, shared |\n| `move` | `x`, `y` | `button`, shared |\n| `drag` | `x`, `y`, `to_x`, `to_y` | `button`, shared |\n| `scroll` | `x`, `y`, `scroll_x`, `scroll_y` | shared |\n| `type` | `text` | shared |\n| `keypress` | `keys` | shared |\n| `wait` | `ms` | shared |\n\n`button` is one of `left`, `right`, or `middle`.\n\n## Coordinate contract\n\n`x`, `y`, `to_x`, and `to_y` are screenshot pixels in the latest screenshot coordinate frame. They are not CSS pixels and not normalized fractions. The screenshot result records dimensions, scale, origin, display epoch, and capture id when supplied by native code. Coordinate actions must not clamp invalid coordinates; native code returns `COMPUTER_COORD_INVALID` or `COMPUTER_DISPLAY_STALE` before input when the coordinate/display contract cannot be satisfied.\n\n## Scope and limitations\n\n- Capture and coordinates cover only the primary display. The tool has no PID or window target.\n- Click, move, drag, scroll, type, and keypress are global, unscoped input; the current focus and macOS determine where they go.\n- A side-effecting action captures the global cursor once and restores it after held input is released. A batch containing input owns one native capture-to-restore transaction across all ordered input, wait, and screenshot steps.\n- Do not use the desktop manually while a side-effecting action or batch runs; concurrent use is unsafe, and restoration can overwrite cursor movement made during the transaction.\n- `screenshot` is read-only, and `wait` posts no input. Screenshot/wait-only batches do not move or restore the cursor.\n- The kill switch gates future input, but it does not isolate the desktop or restore application focus. Cursor restoration does not target or reactivate any PID or window.\n- Key sequences recheck suspension, hotkey liveness, and heartbeat freshness between complete keys. A key already pressed gets its release attempt before stopping. Keyboard-event creation failures stop the sequence and retain the pressed key for cleanup before cursor restoration; the original failure remains visible even if cleanup succeeds. Persistent backend failure can prevent release: cleanup is best-effort within the transaction, not an acknowledgement of delivery by macOS.\n\n## Errors\n\nStable computer error codes include:\n\n- `COMPUTER_DISABLED`\n- `COMPUTER_SUSPENDED`\n- `COMPUTER_SUPERVISOR_NOT_LIVE`\n- `COMPUTER_PERMISSION_REQUIRED` (Accessibility or Screen & System Audio Recording)\n- `COMPUTER_SCREENSHOT_FAILED` (capture failed after the current-process preflight passed)\n- `COMPUTER_DISPLAY_STALE`\n- `COMPUTER_COORD_INVALID`\n- `COMPUTER_CANCELLED`\n- `COMPUTER_KEY_EVENT_FAILED` (native virtual-key event creation failed)\n- `COMPUTER_CURSOR_CAPTURE_FAILED`\n- `COMPUTER_CURSOR_RESTORE_FAILED`\n- `COMPUTER_TRANSACTION_FAILED`\n\nTS handles settings/platform exposure, UX mapping, screenshot persistence, and audit output. Native execution remains the side-effect authority for supervisor state, permissions, display freshness, coordinate validation, cancellation, release-all behavior, and the serialized cursor capture/restore transaction. Whole batches cross the native boundary once; TypeScript does not perform cursor cleanup.\n\nmacOS TCC checks apply to the executable that is currently running the tool.\nFor source-linked GJC this is normally Bun; for a compiled launch it is the\ncompiled `gjc` binary. Grant the permission to that launcher and fully quit\nand relaunch GJC after changing the grant. GJC's macOS development and\nsingle-host release builds use a stable ad-hoc designated requirement so a\nrebuild does not silently become a new TCC identity.\n\n## Rendering\n\nThe TUI renderer is bounded: it shows action, coordinates, scroll/key/wait summary, screenshot dimensions/byte count/capture id, supervisor status, and error code. It never renders raw screenshot base64.\n",
 	"tools/cron.md": "# cron\n\n> A single inline tool that schedules recurring or one-shot prompts within the current session. Select the operation with the `op` field (`create` | `list` | `delete`).\n>\n> **Note on upstream parity:** upstream Claude Code exposes three sibling tools (`CronCreate`, `CronList`, `CronDelete`). GJC intentionally consolidates them into one `cron` tool with an `op` discriminator (matching the `op`/`action` pattern used by `job`, `subagent`, `goal`, and `irc`). The frozen upstream schema fixtures are retained as a historical record; see \"Parity oracle\" below.\n\n## Source\n\n- Entry: `packages/coding-agent/src/tools/cron.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/cron.md`\n- Key collaborators:\n  - `packages/coding-agent/src/async/job-manager.ts` — provides the `registerOwnerCleanup` / `runOwnerCleanups` primitives that clear schedules on session/agent teardown.\n  - `packages/coding-agent/src/session/agent-session.ts` — invokes `runOwnerCleanups({ ownerId })` from `#cancelOwnAsyncJobs()` before cancelling owned jobs, so cron timers cannot race teardown.\n\n## Operations\n\n| `op` | Purpose |\n| --- | --- |\n| `create` | Schedule a prompt on a 5-field cron expression. Returns an 8-character job id. |\n| `list` | List every scheduled task in this session (per calling agent). |\n| `delete` | Cancel a scheduled task by id. |\n\nEach session can hold up to **50** scheduled tasks per owner. Recurring tasks\nauto-expire **7 days** after creation. One-shot tasks delete themselves after\nfiring.\n\nEvery firing starts a normal agent turn, so its assistant response may be visible\neven though the injected cron message itself is hidden. Use `monitor` with a\nstateful script for ongoing PR/CI polling, log watching, or other jobs that\nshould emit only when state changes, and set `persistent: true` so it survives\nthe first emitted event. A cron prompt that merely asks the agent not to report\nroutine polls cannot guarantee silent execution.\n\n## Inputs\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `op` | `\"create\" \\| \"list\" \\| \"delete\"` | Yes | Selects the operation. |\n| `cron_expression` | `string` | `op=create` | Standard 5-field cron expression in local time: `minute hour day-of-month month day-of-week`. |\n| `prompt` | `string` | `op=create` | Prompt to inject between turns when the cron fires. Each firing starts a normal, potentially visible agent turn. |\n| `recurring` | `boolean` | `op=create` (defaults `true`) | `true` to fire on every match (recurring, auto-expires after 7 days); `false` to fire once and self-delete. |\n| `id` | `string` | `op=delete` | The 8-character job ID returned by `op=create`. |\n\nSupported field syntax: `*`, single values (`5`), steps (`*/15`), ranges\n(`1-5`), comma lists (`1,15,30`). Day-of-week uses `0`/`7` for Sunday through\n`6` for Saturday. Extended syntax such as `L`, `W`, `?`, or weekday/month\nname aliases is **not** supported and the tool will reject expressions that use\nthem.\n\n## Outputs\n\n- `op=create` content: `Scheduled <id> (<human-schedule>)`. `details`: `{ op: \"create\", id, cron_expression, recurring, nextFireAt }`.\n- `op=list` content: lines of `<id> (<human-schedule>): <prompt preview>`, or `No scheduled jobs` when empty. `details`: `{ op: \"list\", jobs }` where `jobs` is an array of `{ id, cron, recurring, prompt, humanSchedule }`.\n- `op=delete` content: `Cancelled <id>` on success, `No scheduled task '<id>' found; nothing to cancel.` otherwise. `details`: `{ op: \"delete\", id, deleted }`.\n\n## Behavior / Lifecycle\n\n1. The cron tool gates on `isBackgroundJobSupportEnabled(session.settings)`. When async is disabled, the cron tool is not registered in `BUILTIN_TOOLS`.\n2. Schedules are stored in-memory per `ownerId` (resolved via `session.getAgentId()`). Subagents have their own isolated schedule lists.\n3. The first `op=create` call for a new owner registers an owner cleanup with `AsyncJobManager.registerOwnerCleanup(ownerId, fn)`. The cleanup clears every schedule for that owner and is run by:\n   - `AgentSession.#cancelOwnAsyncJobs()` on dispose / new-session / session-switch / handoff / branch\n   - `AsyncJobManager.dispose()` as a run-and-clear safety net\n4. Cron expression validation rejects malformed input synchronously with a `ToolError` whose message names the offending field.\n5. Each task is backed by a `setTimeout` for the next jitter-adjusted match. One-shot tasks self-delete after firing; recurring tasks reschedule until the 7-day expiry timer deletes them.\n6. The per-owner 50-task cap is enforced on `op=create`; the caller receives a `ToolError` rather than a silent drop.\n\n## Errors\n\n- `ToolError`: `Async execution is disabled; cron is unavailable in this session.`\n- `ToolError`: `cron op=create requires both 'cron_expression' and 'prompt'.`\n- `ToolError`: `cron op=delete requires 'id'.`\n- `ToolError`: `Invalid cron expression: ...` (field count, range, step value, ordering)\n- `ToolError`: `Cron task limit reached (50). Cancel an existing task with cron op=delete first.`\n- `ToolError`: `Cron is disabled by CLAUDE_CODE_DISABLE_CRON=1.`\n- zod validation errors for missing or wrong-typed inputs.\n\n## Examples\n\nSchedule a 5-minute deployment poll:\n\n```jsonc\n{\n  \"op\": \"create\",\n  \"cron_expression\": \"*/5 * * * *\",\n  \"prompt\": \"Check whether the staging deployment finished and tell me what happened\",\n  \"recurring\": true\n}\n```\n\nOne-shot reminder at 9am local:\n\n```jsonc\n{\n  \"op\": \"create\",\n  \"cron_expression\": \"0 9 * * *\",\n  \"prompt\": \"Remind me to push the release branch\",\n  \"recurring\": false\n}\n```\n\nList scheduled tasks, then cancel one:\n\n```jsonc\n{ \"op\": \"list\" }\n```\n\n```jsonc\n{ \"op\": \"delete\", \"id\": \"ab12cd34\" }\n```\n\n## Parity oracle\n\nThe upstream Claude Code per-tool schemas remain frozen as a historical record under\n`packages/coding-agent/test/fixtures/claude-code-tools/`:\n\n- `cron-create.schema.json`\n- `cron-list.schema.json`\n- `cron-delete.schema.json`\n\nThese fixtures were captured from the upstream Claude Code CLI (`claude --version 2.1.152`)\nand document the upstream three-tool surface. GJC's consolidated `cron` tool intentionally\ndiverges from that surface; the fixtures and `claude-code-tools-fixtures.test.ts` validate\nthe frozen upstream records, not GJC's live tool shape.\n",
 	"tools/debug.md": "# debug\n\n> Drive one DAP debug session; adjacent debug UI code reuses the same subsystem for logs, raw SSE capture, reports, profiling, and system diagnostics.\n\n## Source\n- Entry: `packages/coding-agent/src/tools/debug.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/debug.md`\n- Key collaborators:\n  - `packages/coding-agent/src/dap/session.ts` — session lifecycle, breakpoint/state cache\n  - `packages/coding-agent/src/dap/client.ts` — adapter process/socket transport, DAP message loop\n  - `packages/coding-agent/src/dap/config.ts` — adapter resolution and auto-selection\n  - `packages/coding-agent/src/dap/defaults.json` — built-in adapter definitions\n  - `packages/coding-agent/src/dap/types.ts` — request/response/capability shapes\n  - `packages/coding-agent/src/tools/tool-timeouts.ts` — per-tool timeout clamp\n  - `packages/coding-agent/src/debug/index.ts` — interactive debug selector menu\n  - `packages/coding-agent/src/debug/log-viewer.ts` — recent-log TUI viewer\n  - `packages/coding-agent/src/debug/raw-sse.ts` — raw SSE TUI viewer\n  - `packages/coding-agent/src/debug/raw-sse-buffer.ts` — bounded SSE capture buffer\n  - `packages/coding-agent/src/debug/profiler.ts` — CPU/heap profiling helpers\n  - `packages/coding-agent/src/debug/report-bundle.ts` — `.tar.gz` report bundling, log source, cache cleanup\n  - `packages/coding-agent/src/debug/system-info.ts` — system snapshot collection and env redaction\n\n## Inputs\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `action` | `\"launch\" \\| \"attach\" \\| \"set_breakpoint\" \\| \"remove_breakpoint\" \\| \"set_instruction_breakpoint\" \\| \"remove_instruction_breakpoint\" \\| \"data_breakpoint_info\" \\| \"set_data_breakpoint\" \\| \"remove_data_breakpoint\" \\| \"continue\" \\| \"step_over\" \\| \"step_in\" \\| \"step_out\" \\| \"pause\" \\| \"evaluate\" \\| \"stack_trace\" \\| \"threads\" \\| \"scopes\" \\| \"variables\" \\| \"disassemble\" \\| \"read_memory\" \\| \"write_memory\" \\| \"modules\" \\| \"loaded_sources\" \\| \"custom_request\" \\| \"output\" \\| \"terminate\" \\| \"sessions\"` | Yes | Dispatch key for the tool switch in `packages/coding-agent/src/tools/debug.ts`. |\n| `program` | `string` | No | Launch target path. Required for `launch`. Resolved relative to `cwd` if provided, otherwise session cwd. |\n| `args` | `string[]` | No | Program argv for `launch`. |\n| `adapter` | `string` | No | Explicit adapter name. Otherwise `selectLaunchAdapter()` / `selectAttachAdapter()` auto-pick from `packages/coding-agent/src/dap/config.ts`. |\n| `cwd` | `string` | No | Launch/attach working directory. Defaults to session cwd. |\n| `file` | `string` | No | Source file path for source breakpoints. |\n| `line` | `number` | No | Source line for source breakpoints. |\n| `function` | `string` | No | Function breakpoint name. Mutually exclusive with `file`+`line` in breakpoint actions. |\n| `name` | `string` | No | Data breakpoint info target name. Required for `data_breakpoint_info`. |\n| `condition` | `string` | No | Conditional expression for source/function/instruction/data breakpoints. |\n| `hit_condition` | `string` | No | Hit-count condition for instruction/data breakpoints. |\n| `expression` | `string` | No | Expression or raw debugger command. Required for `evaluate`. |\n| `context` | `string` | No | Evaluate context. Defaults to `\"repl\"`. Passed through as DAP evaluate context. |\n| `frame_id` | `number` | No | Frame selector for `evaluate`, `scopes`, `data_breakpoint_info`. `scopes` and `evaluate` default to the current stopped frame when omitted. |\n| `scope_id` | `number` | No | Variables reference from a scope. Accepted by `variables`; also used as a fallback variables reference for `data_breakpoint_info`. |\n| `variable_ref` | `number` | No | Variables reference for `variables`; preferred over `scope_id` when both are present. |\n| `pid` | `number` | No | Local process id for `attach`. `attach` requires `pid` or `port`. |\n| `port` | `number` | No | Remote attach port. If no adapter is forced, attach prefers `debugpy` when `port` is present. |\n| `host` | `string` | No | Remote attach host for `attach`. |\n| `levels` | `number` | No | Max stack frames for `stack_trace`. |\n| `memory_reference` | `string` | No | Memory reference/address for `disassemble`, `read_memory`, `write_memory`. `disassemble` also accepts it via `instruction_reference` fallback logic in `resolveDisassemblyReference()`. |\n| `instruction_reference` | `string` | No | Instruction breakpoint reference; required for instruction breakpoint actions. |\n| `instruction_count` | `number` | No | Required for `disassemble`. |\n| `instruction_offset` | `number` | No | Instruction offset for `disassemble`. |\n| `count` | `number` | No | Byte count for `read_memory`. Required there. |\n| `data` | `string` | No | Base64 payload for `write_memory`. Required there. |\n| `data_id` | `string` | No | Data breakpoint id. Required for `set_data_breakpoint` / `remove_data_breakpoint`. |\n| `access_type` | `\"read\" \\| \"write\" \\| \"readWrite\"` | No | Access filter for `set_data_breakpoint`. |\n| `command` | `string` | No | Custom DAP request command. Required for `custom_request`. |\n| `arguments` | `Record<string, unknown>` | No | Custom DAP request body for `custom_request`. |\n| `offset` | `number` | No | Offset for instruction breakpoints, disassembly, memory read, memory write. |\n| `resolve_symbols` | `boolean` | No | `disassemble` symbol-resolution flag. |\n| `allow_partial` | `boolean` | No | `write_memory` partial-write allowance. |\n| `start_module` | `number` | No | Modules pagination start index for `modules`. |\n| `module_count` | `number` | No | Modules pagination count for `modules`. |\n| `timeout` | `number` | No | Per-request timeout in seconds. Default `30`, clamped to `5..300`. |\n\n### Action-specific requirements\n- `launch`: `program`\n- `attach`: `pid` or `port`\n- `set_breakpoint` / `remove_breakpoint`: `function`, or `file` + `line`\n- `set_instruction_breakpoint` / `remove_instruction_breakpoint`: `instruction_reference`\n- `data_breakpoint_info`: `name`\n- `set_data_breakpoint` / `remove_data_breakpoint`: `data_id`\n- `evaluate`: `expression`\n- `variables`: `variable_ref` or `scope_id`\n- `disassemble`: capability `supportsDisassembleRequest`, plus `instruction_count`\n- `read_memory`: capability `supportsReadMemoryRequest`, plus `memory_reference` and `count`\n- `write_memory`: capability `supportsWriteMemoryRequest`, plus `memory_reference` and `data`\n- `modules`: capability `supportsModulesRequest`\n- `loaded_sources`: capability `supportsLoadedSourcesRequest`\n- `custom_request`: `command`\n\n### Interactive selector values\n`packages/coding-agent/src/debug/index.ts` also exposes a fixed UI-only selector with values `open-artifacts`, `performance`, `work`, `dump`, `memory`, `logs`, `system`, `raw-sse`, `transcript`, `clear-cache`. These are not model-callable through `debugSchema`; they are local TUI menu routes.\n\n## Outputs\nThe agent tool returns a standard `toolResult()` payload from `packages/coding-agent/src/tools/debug.ts`:\n- `content`: one text block. Every action renders human-readable text; there is no structured JSON block in `content`.\n- `details.action`: echoed action.\n- `details.success`: always initialized `true`; failures surface by throwing before a result is returned.\n- `details.snapshot`: present for actions that operate on or create a session, using `DapSessionSummary` from `packages/coding-agent/src/dap/types.ts`.\n- Action-specific `details` fields:\n  - `launch` / `attach`: `adapter`\n  - breakpoint actions: `breakpoints`, `functionBreakpoints`, `instructionBreakpoints`, `dataBreakpoints`\n  - `data_breakpoint_info`: `dataBreakpointInfo`\n  - `continue` / `step_*`: `state`, `timedOut`\n  - `threads`: `threads`\n  - `stack_trace`: `stackFrames`\n  - `scopes`: `scopes`\n  - `variables`: `variables`\n  - `evaluate`: `evaluation`\n  - `disassemble`: `disassembly`\n  - `read_memory`: `memoryAddress`, `memoryData`, `unreadableBytes`\n  - `write_memory`: `bytesWritten`\n  - `modules`: `modules`\n  - `loaded_sources`: `sources`\n  - `custom_request`: `customBody`\n  - `output`: `output`\n  - `sessions`: `sessions`\n\nStreaming/UI behavior:\n- The tool renderer merges call and result (`mergeCallAndResult: true`) and renders inline.\n- `debug.ts` itself does not emit progress updates through `_onUpdate`; result delivery is single-shot.\n- The interactive selector is UI-driven instead of model-driven. It swaps TUI components, appends status lines to the chat pane, opens files in external viewers, or writes archives/temp files.\n\nSide-channel artifacts outside the model tool result:\n- `createReportBundle()` writes `gjc-report-<timestamp>.tar.gz` under the reports dir and returns the filesystem path to the UI handler.\n- `#handleWorkReport()` writes `/tmp/work-profile-<Date.now()>.svg` before opening it.\n- `RawSseViewerComponent` and `DebugLogViewerComponent` can copy captured text to the clipboard.\n\n## Flow\n1. Tool registration is conditional: `DebugTool.createIf()` in `packages/coding-agent/src/tools/debug.ts` returns `null` unless `session.settings.get(\"debug.enabled\")` is true. `packages/coding-agent/src/tools/index.ts` wires the factory and rechecks the same setting in tool filtering.\n2. `DebugTool.execute()` clamps `params.timeout` through `clampTimeout(\"debug\", params.timeout)` and composes the caller `AbortSignal` with `AbortSignal.timeout(...)`.\n3. `launch` and `attach` resolve cwd/program paths, select an adapter in `packages/coding-agent/src/dap/config.ts`, then delegate to `dapSessionManager.launch()` / `.attach()`.\n4. `DapSessionManager.launch()` / `.attach()` enforce the single-session rule with `#ensureLaunchSlot()`, spawn the adapter through `DapClient.spawn()`, register listeners, send `initialize`, cache capabilities, start listening for an initial stop event before sending `launch`/`attach`, then complete the `initialized` → `configurationDone` handshake in `#completeConfigurationHandshake()`.\n5. `DapClient.spawn()` starts the adapter detached with `NON_INTERACTIVE_ENV`. Most adapters use stdio; socket-mode adapters (`dlv`) use `#spawnSocketUnix()` on Linux or `#spawnSocketClientAddr()` on macOS/other.\n6. `#registerSession()` in `packages/coding-agent/src/dap/session.ts` installs reverse-request handlers:\n   - `runInTerminal`: spawns the requested debuggee command detached via `ptree.spawn()` and returns `{ processId }`\n   - `startDebugging`: logs the child-session request and returns `{}`; it does not create nested sessions\n   - events: `output`, `initialized`, `stopped`, `continued`, `exited`, `terminated` update cached session state\n7. Operational actions (`set_breakpoint`, `evaluate`, `threads`, `read_memory`, `custom_request`, and similar) call `dapSessionManager` methods. Most flow through `#sendRequestWithConfig()`, which first sends `configurationDone` when required, then sends the DAP request, then updates `lastUsedAt`.\n8. Breakpoint actions maintain local cached breakpoint sets in `DapSessionManager` and remap adapter responses back onto those cached records.\n9. `continue` and the three step actions clear cached stop state, subscribe for `stopped`/`terminated`/`exited` before sending the DAP request, then `#awaitStopOutcome()` either returns the new stopped location or reports that the program is still running after timeout.\n10. `pause` sends DAP `pause`, waits for a stopped event if needed, and reuses cached stop state if the program was already stopped.\n11. `stack_trace`, `scopes`, `variables`, and `evaluate` default to the current stopped thread/frame when the caller omits ids and cached state is available.\n12. `output` reads the in-memory output ring from `DapSessionManager.getOutput()`. `terminate` sends `terminate` when supported, always attempts `disconnect`, marks the session terminated, and disposes the client.\n13. `sessions` reads the manager’s current map and formats all summaries. Although the manager stores a map, only one active session can exist because new launch/attach calls are blocked until the active one is terminated or cleaned up.\n14. The interactive selector in `packages/coding-agent/src/debug/index.ts` builds a `SelectList` of fixed values and dispatches each to a handler:\n   - `performance`: `startCpuProfile()`, wait for Enter/Escape, stop profiling, read a 30-second work profile with `getWorkProfile(30)`, then bundle via `createReportBundle()`\n   - `work`: read `getWorkProfile(30)`, write a temp SVG, open it externally\n   - `dump`: create a report bundle immediately\n   - `memory`: force GC, call `Bun.generateHeapSnapshot(\"v8\")`, then bundle\n   - `logs`: build a `DebugLogSource` and mount `DebugLogViewerComponent`\n   - `raw-sse`: resolve a `RawSseDebugBuffer` from the session and mount `RawSseViewerComponent`\n   - `system`: call `collectSystemInfo()` and render `formatSystemInfo()` into the chat pane\n   - `open-artifacts`: open the current session artifact directory if it exists\n   - `transcript`: delegates to `ctx.handleDebugTranscriptCommand()`\n   - `clear-cache`: show confirmation, then remove artifact directories older than 30 days with `clearArtifactCache()`\n\n## Modes / Variants\n- **Availability gate**\n  - Tool hidden when `debug.enabled` is false.\n- **Adapter selection**\n  - `launch`: explicit `adapter` wins; otherwise `selectLaunchAdapter()` ranks available adapters by extension match, root-marker match, then native-debugger preference (`gdb`, `lldb-dap`) for extensionless binaries.\n  - `attach`: explicit `adapter` wins; otherwise remote `port` prefers `debugpy`, then native debuggers, then first available adapter.\n- **Transport**\n  - stdio adapters: direct `stdin`/`stdout` framing.\n  - socket adapters: Unix domain socket on Linux; TCP callback on macOS/other.\n- **DAP agent-tool actions**\n  - `launch` — spawn adapter, initialize session, maybe stop on entry; returns formatted session snapshot and `details.adapter`.\n  - `attach` — connect to a live process or remote port; same output shape as `launch`.\n  - `set_breakpoint` — source or function breakpoint add/update; returns the current breakpoint list for that target.\n  - `remove_breakpoint` — source or function breakpoint removal; returns the remaining breakpoint list.\n  - `set_instruction_breakpoint` / `remove_instruction_breakpoint` — require `supportsInstructionBreakpoints`; return current instruction breakpoint list.\n  - `data_breakpoint_info` — require `supportsDataBreakpoints`; asks the adapter for a `dataId`, access types, and description for `name`.\n  - `set_data_breakpoint` / `remove_data_breakpoint` — require `supportsDataBreakpoints`; return the cached data-breakpoint list.\n  - `continue` / `step_over` / `step_in` / `step_out` — return text describing whether execution stopped, terminated, or kept running, plus `details.state` and `details.timedOut`.\n  - `pause` — interrupts a running target and returns a stopped snapshot.\n  - `evaluate` — adapter expression evaluation; defaults context to `repl`.\n  - `stack_trace` — fetches frames for the resolved thread.\n  - `threads` — fetches current threads.\n  - `scopes` — frame scopes for an explicit `frame_id` or the current stopped frame.\n  - `variables` — variables for `variable_ref` or `scope_id`.\n  - `disassemble` — require `supportsDisassembleRequest`; disassembles around a memory reference.\n  - `read_memory` — require `supportsReadMemoryRequest`; returns address, base64 data, unreadable-byte count.\n  - `write_memory` — require `supportsWriteMemoryRequest`; writes base64 data and reports bytes written.\n  - `modules` — require `supportsModulesRequest`; optional pagination via `start_module` / `module_count`.\n  - `loaded_sources` — require `supportsLoadedSourcesRequest`; returns loaded source descriptors.\n  - `custom_request` — sends any DAP request name with arbitrary arguments.\n  - `output` — dumps captured stdout/stderr/console text from the session cache.\n  - `terminate` — disconnects and disposes the active session; returns `No debug session to terminate.` when none exists.\n  - `sessions` — lists all cached session summaries.\n- **Interactive selector routes (UI-only)**\n  - `logs` — loads today’s log tail and optional older daily log files into `DebugLogViewerComponent`; supports copy, range selection, pid filtering, load-older.\n  - `raw-sse` — live view over the session’s `RawSseDebugBuffer`; supports tail-follow, scrolling, copy-all.\n  - `performance` — CPU profile + 30-second work profile + report bundle.\n  - `memory` — heap snapshot + report bundle.\n  - `dump` — report bundle without profiler artifacts.\n  - `work` — standalone work-profile flamegraph export/open.\n  - `system` — formatted OS/arch/CPU/memory/version/cwd/shell/terminal dump.\n  - `open-artifacts` / `transcript` / `clear-cache` — artifact directory open, transcript export, artifact-cache pruning.\n\n## Side Effects\n- Filesystem\n  - Resolves program/file/cwd paths against the session cwd.\n  - Report creation writes `.tar.gz` bundles and may read the session JSONL, artifact files, subagent session JSONLs, and log files.\n  - Work-profile export writes `/tmp/work-profile-<timestamp>.svg`.\n  - Log source reads daily log files from the logs dir.\n  - Artifact-cache cleanup removes session artifact directories older than the cutoff.\n  - `resolveRawSseDebugBuffer()` may attach a non-enumerable `rawSseDebugBuffer` property to the owner object.\n- Network\n  - Socket-mode adapters bind/connect local sockets.\n  - Remote attach may connect through the adapter to a remote debug port.\n- Subprocesses / native bindings\n  - Spawns debugger adapters (`gdb`, `lldb-dap`, `python -m debugpy.adapter`, `dlv`, and others from `defaults.json`) detached.\n  - Reverse DAP `runInTerminal` requests spawn the debuggee detached via `ptree.spawn()`.\n  - `getWorkProfile(30)` comes from `@gajae-code/natives`.\n  - CPU profiling uses `node:inspector/promises`; heap snapshots use `Bun.generateHeapSnapshot(\"v8\")`; raw/log viewers sanitize text via `@gajae-code/natives`.\n  - `openPath()` launches the OS default file/browser handler for artifact dirs and SVGs.\n  - Log/raw-SSE viewers can call `copyToClipboard()`.\n- Session state (transcript, memory, jobs, checkpoints, registries)\n  - `DapSessionManager` keeps session summaries, breakpoints, threads, stack frames, stop location, output capture, capabilities, and last-used timestamps in memory.\n  - Active-session id is global to the singleton `dapSessionManager`.\n  - `RawSseDebugBuffer` stores recent SSE events per owner/session.\n  - The tool is `exclusive`; concurrent debug tool calls are blocked by the scheduler.\n- User-visible prompts / interactive UI\n  - Debug selector shows confirmation before cache deletion.\n  - Performance profiling temporarily hijacks editor Enter/Escape handlers until profiling stops.\n  - Log/raw-SSE viewers replace the editor pane with custom components.\n- Background work / cancellation\n  - Every DAP request accepts an `AbortSignal`; timeouts and caller cancellation abort the active request, not the whole session lifetime.\n  - `DapSessionManager` runs a background cleanup loop every 30 seconds.\n  - Raw SSE viewers subscribe to buffer updates until closed.\n\n## Limits & Caps\n- Tool timeout clamp: `default=30`, `min=5`, `max=300` in `packages/coding-agent/src/tools/tool-timeouts.ts`.\n- Per-request DAP default timeout: `DEFAULT_REQUEST_TIMEOUT_MS = 30_000` in `packages/coding-agent/src/dap/client.ts`.\n- Single active session: enforced by `#ensureLaunchSlot()` in `packages/coding-agent/src/dap/session.ts`.\n- Idle session cleanup: `IDLE_TIMEOUT_MS = 10 * 60 * 1000`, checked every `CLEANUP_INTERVAL_MS = 30 * 1000`.\n- Adapter liveness heartbeat: `HEARTBEAT_INTERVAL_MS = 5 * 1000`.\n- Output capture cap: `MAX_OUTPUT_BYTES = 128 * 1024`; older text is trimmed in ~1 KiB slices and `outputTruncated` is recorded.\n- Initial stop capture timeout after launch/attach: `STOP_CAPTURE_TIMEOUT_MS = 5_000`.\n- Socket-mode adapter readiness timeout: `10_000` ms in `waitForCondition()` and TCP connect timeout logic in `packages/coding-agent/src/dap/client.ts`.\n- Raw SSE buffer caps in `packages/coding-agent/src/debug/raw-sse-buffer.ts`:\n  - `MAX_RAW_SSE_EVENTS = 1_000`\n  - `MAX_RAW_SSE_CHARS = 512_000`\n  - `MAX_RAW_SSE_EVENT_CHARS = 64_000` per event, with `: gjc-debug-truncated ...` marker appended on trim\n- Log viewer window in `packages/coding-agent/src/debug/log-viewer.ts`:\n  - `INITIAL_LOG_CHUNK = 50`\n  - `LOAD_OLDER_CHUNK = 50`\n- Report/log ingestion caps in `packages/coding-agent/src/debug/report-bundle.ts`:\n  - `MAX_LOG_LINES = 5000` for interactive log reading\n  - `MAX_LOG_BYTES = 2 * 1024 * 1024` tail-read ceiling\n  - report bundles include only the last `1000` log lines\n  - subagent session inclusion is capped at the most recent `10` JSONL files\n- Interactive profiling windows in `packages/coding-agent/src/debug/index.ts`: both performance and work reports request `getWorkProfile(30)`.\n- Artifact cache pruning default: `30` days in `clearArtifactCache()` and the selector confirmation text.\n\n## Errors\n- Parameter validation in `packages/coding-agent/src/tools/debug.ts` throws `ToolError` with explicit messages such as:\n  - `program is required for launch`\n  - `attach requires pid or port`\n  - `set_breakpoint requires file+line or function`\n  - `variables requires variable_ref or scope_id`\n  - `memory_reference is required for read_memory`\n  - `count is required for read_memory`\n  - `data is required for write_memory`\n  - `command is required for custom_request`\n- Adapter selection failure throws `No debugger adapter available. Installed adapters: ...`.\n- Capability-gated actions throw from `requireCapability(...)`, e.g. `Active adapter does not support memory reads.`\n- No-session and state errors come from `DapSessionManager`, e.g. `No active debug session. Launch or attach first.`, `No active stack frame. Run stack_trace first or supply frame_id.`, `Debugger reported no threads.`\n- Launching a second live session throws `Debug session <id> is still active. Terminate it before launching another.`\n- DAP transport/request failures surface as thrown errors from `DapClient`:\n  - `DAP request <command> timed out after <ms>ms`\n  - `DAP event <event> timed out after <ms>ms`\n  - `DAP adapter <name> is not running`\n  - `DAP adapter exited (code N): <stderr>` or `DAP adapter exited unexpectedly (code N)`\n  - adapter response `message` when a DAP request fails\n- `continue` / `step_*` are intentionally non-fatal when the target stays running past the timeout: they return `details.timedOut = true` and `state: \"running\"` instead of throwing.\n- `terminate` suppresses adapter errors while sending `terminate`/`disconnect`; it still disposes the client and returns the last summary when possible.\n- Interactive selector handlers report UI errors instead of throwing:\n  - profiler start/stop, report bundling, log reading, system-info collection, cache clearing, and artifact opening use `ctx.showError(...)` / `ctx.showWarning(...)`\n  - empty logs and empty artifact caches are warnings/status messages, not failures\n  - copy failures in log/raw-SSE viewers become status/error text in the UI\n- Report-bundle helpers are intentionally best-effort for many file reads: missing session files, missing artifact dirs, unreadable artifact files, missing log dirs, inaccessible cache dirs, and missing subagent files are skipped silently.\n- `collectSystemInfo()` is best-effort for CPU probing; failure there falls back to `Unknown CPU`.\n\n## Notes\n- `packages/coding-agent/src/prompts/tools/debug.md` tells the model only one active session is supported; that is not advisory, it is enforced in code.\n- `configurationDone` is sent automatically both during launch/attach handshake and lazily before later requests if the adapter required it and the initial handshake did not complete.\n- `startDebugging` reverse requests are acknowledged but not implemented; child debug sessions are not spawned.\n- `output` exposes the merged `output` event stream only; the tool does not distinguish stdout, stderr, and console categories.\n- Session summaries expose `needsConfigurationDone`; this is derived from adapter capabilities and whether `configurationDone` has been sent.\n- Source breakpoint file paths are normalized with `path.resolve()` before caching and sending to the adapter.\n- `evaluate` defaults to `repl`, so the tool can forward raw debugger commands when the adapter supports them.\n- `disassemble` resolves its target from `memory_reference` first, then `instruction_reference`; it throws if neither is present.\n- `RawSseDebugBuffer.recordEvent()` increments `totalEvents` before bounded retention. A snapshot can therefore show fewer retained records than total observed events.\n- Raw SSE buffer listener failures are swallowed so viewer bugs do not break capture.\n- `createDebugLogSource()` walks daily log files newest-first, but `loadOlderLogs()` reverses each requested slice before concatenation so older chunks prepend in chronological order.\n- `clearArtifactCache()` deletes directories by directory mtime, not per-file age.\n- `addDirectoryToArchive()` reads artifact files as text with `Bun.file(...).text()`. Binary artifact contents are not preserved byte-for-byte in the report bundle.\n- The tool renderer truncates displayed output for the TUI preview, but the underlying text result still contains the full returned string.\n",
 	"tools/edit.md": "# edit\n\n> Applies source edits; the default `edit.mode: auto` routes the edit protocol by model family, with the hashline patch language (single `input` string) as the fallback mode documented here.\n\n## Source\n- Entry: `packages/coding-agent/src/edit/index.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/hashline.md`\n- Key collaborators:\n  - `packages/coding-agent/src/utils/edit-mode.ts` — selects active edit mode\n  - `packages/coding-agent/src/hashline/grammar.lark` — custom-tool grammar for hashline mode\n  - `packages/coding-agent/src/hashline/input.ts` — splits `§PATH` sections\n  - `packages/coding-agent/src/hashline/parser.ts` — parses op-prefixed edits and verbatim payload lines\n  - `packages/coding-agent/src/hashline/apply.ts` — validates anchors and applies edits\n  - `packages/coding-agent/src/hashline/anchors.ts` — stale-anchor mismatch formatting\n  - `packages/coding-agent/src/hashline/recovery.ts` — cache-based stale-anchor recovery\n  - `packages/coding-agent/src/hashline/hash.ts` — computes `LINEhh|` anchors shared with `read`/`search`\n  - `packages/coding-agent/src/edit/file-read-cache.ts` — per-session read snapshot cache\n  - `packages/coding-agent/src/tools/read.ts` — emits anchored lines and records read snapshots\n  - `packages/coding-agent/src/tools/search.ts` — records sparse snapshots from matches/context\n  - `packages/coding-agent/src/tools/fs-cache-invalidation.ts` — invalidates FS scan caches after writes\n  - `packages/coding-agent/src/edit/streaming.ts` — computes in-flight diff previews for the TUI\n\n## Inputs\n\n### Hashline mode\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `input` | `string` | Yes | One or more edit sections. First non-blank line must be `§PATH` unless the caller supplies the legacy fallback `path` outside the model schema and the body already looks like hashline ops (`packages/coding-agent/src/hashline/input.ts`). Optional `*** Begin Patch` / `*** End Patch` envelope is ignored if present. |\n\nPatch language inside `input`:\n\n- Section header: `§PATH`\n- Insert after: `»ANCHOR`\n- Insert before: `«ANCHOR`\n- Replace/delete range: `≔A..B`\n- Single-line replace/delete sugar: `≔A` means `≔A..A`\n- `≔A..B` with no payload deletes the range. To keep a blank line, include one explicit empty payload line.\n- Payload lines: verbatim file content after `»`, `«`, or `≔`\n- Special anchors: `BOF`, `EOF`\n- Anchor token: `<line><2-char-hash>`, for example `41th`\n\nAnchors come from `read`/`search` output. `read` formats lines as `LINEhh|TEXT` via `formatHashLine` / `formatHashLines` in `packages/coding-agent/src/hashline/hash.ts`; copy only the token left of `|` into op lines.\n\nOther edit modes exist (`replace`, `patch`, `vim`, `apply_patch`) and are selected outside the tool payload by `resolveEditMode()` in `packages/coding-agent/src/utils/edit-mode.ts`. With the default `edit.mode: auto`, the mode is routed by detected model family (GPT/Codex → `apply_patch`; Claude/DeepSeek/Qwen → `replace`; MiniMax/GLM/Kimi and unknown models → `hashline`). Precedence: `GJC_EDIT_VARIANT`/`PI_EDIT_VARIANT` env force, then a matching `edit.modelVariants` rule, then explicit non-`auto` `edit.mode`, then a model-catalog edit recommendation when the session exposes one, then the built-in family mapping, then the `hashline` fallback. Their schemas are different; this document covers hashline mode.\n\n## Outputs\n- Single-shot tool result; hashline mode does not use a `resolve` preview/apply handshake.\n- `content` contains one text block per call. For a successful single-file edit it is either:\n  - `<path>:` plus a compact diff preview from `packages/coding-agent/src/hashline/diff-preview.ts`, or\n  - `Updated <path>` / `Created <path>` when no compact preview text is emitted.\n- Parse or recovery warnings are appended as:\n\n```text\nWarnings:\n...\n```\n\n- `details` is `EditToolDetails` from `packages/coding-agent/src/edit/renderer.ts`:\n  - `diff`: unified diff string\n  - `firstChangedLine`: first changed post-edit line\n  - `diagnostics`: LSP/format result if available\n  - `op`: `\"create\"` or `\"update\"` for hashline mode\n  - `meta`: output metadata\n  - `perFileResults`: present for multi-section input\n- Multi-section input returns one aggregated result with combined text and per-file details.\n- While the model is still typing arguments, the TUI can compute a diff preview with `packages/coding-agent/src/edit/streaming.ts`; that preview is not a deferred action and does not block execution.\n\n## Flow\n1. `EditTool.execute()` in `packages/coding-agent/src/edit/index.ts` resolves the active mode. The default setting is `auto`, which routes by model family; `hashline` is the unknown-model fallback. `customFormat` exposes the grammar for the selected mode, with hashline's `packages/coding-agent/src/hashline/grammar.lark` placeholders `$HFMT$` / `$HOP_INSERT_BEFORE$` / `$HOP_INSERT_AFTER$` / `$HOP_REPLACE$` / `$HOP_CHARS$` / `$HFILE$` filled from `packages/coding-agent/src/hashline/hash.ts`.\n2. `executeHashlineSingle()` in `packages/coding-agent/src/hashline/execute.ts` splits the raw `input` into `§PATH` sections with `splitHashlineInputs()`.\n3. If multiple sections target the same path, `mergeSamePathSections()` concatenates them before execution so every op still refers to the original file snapshot.\n4. Multi-section calls run a preflight pass (`preflightHashlineSection()`): parse ops, enforce plan-mode write rules, load the current file, reject anchor-scoped edits against missing files, reject auto-generated files, apply edits in memory, and fail if the result is a no-op. This prevents partial batches.\n5. `parseHashlineWithWarnings()` in `packages/coding-agent/src/hashline/parser.ts` tokenizes the diff body:\n   - ignores blank lines and optional `*** Begin Patch`\n   - stops at `*** End Patch`\n   - stops at `*** Abort` and emits `ABORT_WARNING`\n   - turns `»` / `«` payload runs into one `insert` edit per payload line\n   - turns `≔A..B` with payload into inserts before `A`, then deletes for `A..B`\n   - turns `≔A..B` with no payload into one `delete` edit per line in the range; a blank-in-place edit requires one explicit empty payload line\n6. `applyHashlineEdits()` in `packages/coding-agent/src/hashline/apply.ts` validates every referenced anchor before mutating anything. Each anchor hash is recomputed from current file content with `computeLineHash()`.\n7. If any anchor hash differs, `applyHashlineEdits()` throws `HashlineMismatchError`. `execute.ts` catches only that class and calls `tryRecoverHashlineWithCache()`.\n8. Recovery replays the edits against the most recent cached read/search snapshot for that path (`packages/coding-agent/src/edit/file-read-cache.ts`), then 3-way merges the result onto current disk content using `Diff.applyPatch(..., { fuzzFactor: 3 })` in `packages/coding-agent/src/hashline/recovery.ts`. On success the edit proceeds with a warning; on failure the original mismatch error is re-thrown.\n9. Before splicing lines, `absorbReplacementBoundaryDuplicates()` normalizes some malformed-but-recoverable ranges:\n   - duplicate prefix/suffix lines adjacent to a replacement can be absorbed by widening the delete range\n   - pure inserts can auto-drop duplicated leading/trailing payload lines when `edit.hashlineAutoDropPureInsertDuplicates` is enabled\n   - all such fixes append warnings\n10. `after_anchor` inserts are normalized to `before_anchor` of the next line, or `EOF` if the anchor was the last line.\n11. Anchor-targeted edits are bucketed by target line and applied bottom-up so earlier splices do not invalidate later original line numbers. `BOF` and `EOF` inserts are applied after that.\n12. The edited text is restored to the original BOM and line ending style with helpers from `packages/coding-agent/src/edit/normalize.ts` and persisted via `serializeEditFileText()` in `packages/coding-agent/src/edit/read-file.ts`.\n13. The writethrough callback from `createLspWritethrough()` may format the file and fetch diagnostics. Late diagnostics are queued back into session state as a hidden deferred message by `EditTool.#injectLateDiagnostics()` in `packages/coding-agent/src/edit/index.ts`.\n14. `invalidateFsScanAfterWrite()` calls `invalidateFsScanCache(path)` so filesystem-backed tools do not serve stale scan results.\n15. The session file-read cache is refreshed with the post-edit file text via `recordContiguous()`, making the just-written content the new recovery base for subsequent stale-anchor merges.\n16. The final response is built from a unified diff (`generateDiffString()`), a compact preview, and any accumulated warnings.\n\n## Modes / Variants\n- `hashline` — unknown-model fallback mode; line-anchored patch language described here (`packages/coding-agent/src/utils/edit-mode.ts`).\n- `replace` — exact/fuzzy old/new text replacement (`packages/coding-agent/src/edit/modes/replace.ts`).\n- `patch` — structured JSON diff-hunk mode (`packages/coding-agent/src/edit/modes/patch.ts`).\n- `apply_patch` — freeform patch-envelope `*** Begin Patch` envelope, internally expanded into patch-mode entries (`packages/coding-agent/src/edit/modes/apply-patch.ts`).\n- `vim` — persistent modal editing buffer (`packages/coding-agent/src/tools/vim.ts`).\n\nHashline op examples:\n\n```text\n§src/a.ts\n»4fb\nconst added = true;\n```\n\n```text\n§src/a.ts\n«4fb\nconst addedBefore = true;\n```\n\n```text\n§src/a.ts\n≔4fb..6qx\n```\n\n```text\n§src/a.ts\n≔4fb..5dm\nconst clean = (name || DEF).trim();\nreturn clean.length === 0 ? DEF : clean.toUpperCase();\n```\n\nBOF/EOF examples:\n\n```text\n§src/a.ts\n»BOF\nconst HEADER = true;\n```\n\n```text\n§src/a.ts\n»EOF\nexport const done = true;\n```\n\nDelete / blank examples:\n\n```text\n§src/a.ts\n≔4fb\n```\n\n```text\n§src/a.ts\n≔4fb\n\n»EOF\nexport const done = true;\n```\n\n## Side Effects\n- Filesystem\n  - Reads target files with `readEditFileText()`.\n  - Writes full updated file contents with `serializeEditFileText()`.\n  - Preserves BOM and original line-ending style.\n- Subprocesses / native bindings\n  - `createLspWritethrough()` may trigger formatter / diagnostics work through the LSP subsystem.\n  - `invalidateFsScanAfterWrite()` calls native `invalidateFsScanCache()` from `@gajae-code/natives`.\n- Session state\n  - Reads and updates the per-session `FileReadCache` used for stale-anchor recovery.\n  - Stores pending deferred-diagnostics abort controllers per path inside `EditTool`.\n  - Queues late diagnostics back into the session transcript as a hidden custom message.\n- Background work / cancellation\n  - A new edit to the same path aborts the prior deferred diagnostics fetch for that path (`packages/coding-agent/src/edit/index.ts`).\n  - The tool itself is marked `nonAbortable = true` and `concurrency = \"exclusive\"` in `packages/coding-agent/src/edit/index.ts`.\n\n## Limits & Caps\n- Default `edit.mode` is `auto` (model-family routing); `hashline` (`DEFAULT_EDIT_MODE`) is the fallback for unknown models, in `packages/coding-agent/src/utils/edit-mode.ts`.\n- Anchor hashes are always 2 lowercase letters from a stable 647-entry bigram table (`HL_BIGRAMS_COUNT`) in `packages/coding-agent/src/hashline/hash.ts`.\n- The visible mismatch report shows 2 lines of context on each side (`MISMATCH_CONTEXT`) in `packages/coding-agent/src/hashline/constants.ts`.\n- Stale-anchor recovery uses `fuzzFactor: 3` (`HASHLINE_RECOVERY_FUZZ_FACTOR`) in `packages/coding-agent/src/hashline/recovery.ts`.\n- The per-session read cache keeps at most 30 paths (`MAX_PATHS_PER_SESSION`) in `packages/coding-agent/src/edit/file-read-cache.ts`.\n- Hashline streaming chunk defaults are 200 lines or 64 KiB per chunk (`packages/coding-agent/src/hashline/types.ts`, consumed by `packages/coding-agent/src/hashline/stream.ts`).\n- `HL_OP_INSERT_BEFORE` is `«`, `HL_OP_INSERT_AFTER` is `»`, `HL_OP_REPLACE` is `≔`, `HL_OP_CHARS` is `«»≔`, `HL_FILE_PREFIX` is `§`, and `HL_BODY_SEP` is `|` (`packages/coding-agent/src/hashline/hash.ts`).\n\n## Errors\n- Missing section header:\n  - `input must begin with \"§PATH\" on the first non-blank line; got: ... Example: \"§src/foo.ts\" then edit ops.`\n- Empty header:\n  - `Input header \"§\" is empty; provide a file path.`\n- Bad anchor token:\n  - `line N: expected a full anchor such as \"119sr\"; got \"...\".`\n- Bad range syntax:\n  - `line N: explicit ranges are required for replacement...`\n  - `line N: range must include exactly two full anchors separated by \"..\".`\n  - `line N: range A..B ends before it starts.`\n  - `line N: range A..B uses two different hashes for the same line.`\n- Missing payload for `»` / `«`:\n  - `line N: » and « operations require at least one verbatim payload line.`\n- Stray payload line:\n  - `line N: payload line has no preceding », «, or ≔ operation.`\n- Unknown op:\n  - `line N: unrecognized op. Use «ANCHOR..., »ANCHOR..., ≔A..B...`\n- Delete vs blank:\n  - `≔A..B` with no payload deletes. To blank in place, include one explicit empty payload line before the next op/header/EOF.\n- Missing file for anchor-scoped edits:\n  - `File not found: <path>`\n- Out-of-range anchor:\n  - `Line N does not exist (file has M lines)`\n- Stale anchors throw `HashlineMismatchError`. The error message contains re-read guidance and reprints nearby current file lines as `LINEhh|TEXT`; mismatched lines are marked `*`. `displayMessage` renders the same information in a code-frame style.\n- No-op edit:\n  - `Edits to <path> resulted in no changes being made.`\n- Recovery failure is silent internally: if cache-based merge cannot prove a valid result, the original mismatch error is surfaced unchanged.\n\n## Notes\n- `read` and `search` are the authoritative source of anchors. The edit parser does not want the trailing `|TEXT`; copy only the `LINEhh` token.\n- Multi-op patches are parsed against the original file snapshot. Do not renumber later anchors after earlier ops; `applyHashlineEdits()` buckets and applies them bottom-up.\n- `≔A..B` is not a primitive replace in the parser. With payload, it expands to inserts before `A` plus deletes for `A..B`; with no payload, it only deletes `A..B`. To blank in place, include one explicit empty payload line. Stale-anchor checking still happens on the original range lines.\n- Interior lines of a multi-line range use hash `**` (`RANGE_INTERIOR_HASH`) and are not individually verified; only the first and last anchor hashes are checked.\n- `computeLineHash()` trims trailing whitespace before hashing. Anchors survive line-ending changes and trailing-space-only changes, but not substantive line edits.\n- For punctuation-only lines, the hash mixes in the line number; identical `}` lines on different lines intentionally get different anchors.\n- `splitHashlineInputs()` normalizes absolute `§PATH` headers back to a cwd-relative path when the file is inside the current working tree. Headers with any run of leading `§` chars (e.g. `§foo.ts`, `§§foo.ts`, `§§§foo.ts`) are accepted; the canonical form is `§PATH`.\n- Optional `*** Begin Patch` / `*** End Patch` markers are accepted in hashline mode, but the file sections are still `§PATH`-based, not OpenAI code `*** Update File:` hunks.\n- `*** Abort` terminates parsing early and returns `ABORT_WARNING`; ops parsed before the marker still apply.\n- File-read cache invalidation is conflict-based, not write-through invalidation. If `read` later records content for a line that disagrees with the cached snapshot, the entire snapshot for that path is replaced with the newly observed lines (`packages/coding-agent/src/edit/file-read-cache.ts`).\n- There is no resolve-style apply/discard phase for hashline edits. The only preview path is the transient TUI diff preview in `packages/coding-agent/src/edit/streaming.ts`.\n",
-	"tools/eval.md": "# eval\n\n> Execute Python or JavaScript code in persistent cell-based runtimes.\n\n> **Notice:** Do not shell out to `python -c`/`python -e`, `bun -e`, or `node -e` via the `bash` tool for ad-hoc code execution. Use this tool instead — it gives you persistent state across cells, structured `display()` output, image/JSON capture, and proper cancellation/timeout handling that one-shot `-e`/`-c` invocations cannot provide.\n\n> **Not to be confused with [`python`](./python.md).** `eval` runs in a **session-scoped** kernel and is the general-purpose choice. The `python` tool is a session-owned persistent REPL with its own `python:<session-id>` owner and an append-only JSONL transcript; it requires no active `autoresearch` mission. Both drive the same underlying Python kernel implementation — see [Kernel ownership](../python-repl.md#kernel-ownership).\n\n## Source\n- Entry: `packages/coding-agent/src/tools/eval.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/eval.md`\n- Key collaborators:\n  - `packages/coding-agent/src/eval/backend.ts` — backend execution contract\n  - `packages/coding-agent/src/eval/js/index.ts` — JS backend adapter\n  - `packages/coding-agent/src/eval/js/executor.ts` — JS execution + output sink\n  - `packages/coding-agent/src/eval/js/context-manager.ts` — persistent VM contexts, prelude, tool bridge\n  - `packages/coding-agent/src/eval/js/prelude.txt` — JS global helpers\n  - `packages/coding-agent/src/eval/py/index.ts` — Python backend adapter\n  - `packages/coding-agent/src/eval/py/executor.ts` — kernel session retention, reset, cleanup\n  - `packages/coding-agent/src/eval/py/kernel.ts` — Jupyter gateway/kernel protocol, display capture\n  - `packages/coding-agent/src/eval/py/prelude.py` — Python helper functions and status events\n  - `packages/coding-agent/src/session/streaming-output.ts` — truncation, artifacts, streamed chunks\n  - `docs/python-repl.md` — Python kernel/gateway internals\n\n## Inputs\n\nTool parameters are a JSON object with a single `cells` field — an ordered array of cell objects. Each cell is a structured record; there is no `*** Cell` header parsing, no language sniffing, and no implicit single-cell fallback. Cells run in array order; state persists within each language across cells and across tool calls.\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `cells` | `EvalCellInput[]` | Yes | Cells executed in order. At least one cell is required (`.min(1)`). |\n\nEach `EvalCellInput` (from `evalCellSchema` in `packages/coding-agent/src/tools/eval.ts`):\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `language` | `\"py\" \\| \"js\"` | Yes | Backend selector. `\"py\"` maps to the IPython/Jupyter kernel (`python` backend); `\"js\"` maps to the persistent JavaScript VM. |\n| `code` | `string` | Yes | Cell body, verbatim. JSON-encoded — embed newlines, quotes, and indentation directly; no fences, no headers. |\n| `title` | `string` | No | Short label rendered in the transcript (e.g. `\"imports\"`, `\"load config\"`). |\n| `timeout` | `integer` | No | Per-cell timeout in seconds, clamped to `1..600`. Defaults to 30 when omitted. |\n| `reset` | `boolean` | No | Wipe this cell's language kernel before running. Reset is per-language: a `py` cell's reset does not touch the JS VM and vice versa. Defaults to `false`. |\n\nMinimal example matching the live schema:\n\n```json\n{\n  \"cells\": [\n    { \"language\": \"py\", \"title\": \"imports\", \"timeout\": 10, \"code\": \"import json\\nfrom pathlib import Path\" },\n    { \"language\": \"py\", \"title\": \"load config\", \"code\": \"data = json.loads(read('package.json'))\\ndisplay(data)\" },\n    { \"language\": \"js\", \"title\": \"summary\", \"reset\": true, \"code\": \"const data = JSON.parse(await read('package.json'));\\ndisplay(data);\\nreturn data.name;\" }\n  ]\n}\n```\n\n## Outputs\n\nFinal result from `EvalTool.execute()` is single-shot, but `onUpdate` streams partial text and `details` while cells run.\n\nReturned shape:\n\n- `content`: one text block containing combined cell output, or `(no text output)` / `(no output)` when only rich outputs exist.\n- `details` (`EvalToolDetails` from `packages/coding-agent/src/eval/types.ts`):\n  - `cells`: per-cell code, status (`pending`/`running`/`complete`/`error`), output, duration, exit code, status events, markdown flag\n  - `language`: first backend used\n  - `languages`: distinct backends used, in first-use order\n  - `jsonOutputs`: structured values emitted via `display(...)`\n  - `images`: image payloads emitted by Python rich display or JS `display({ type: \"image\", ... })`\n  - `statusEvents`: aggregated helper/tool status events\n  - `notice`: backend fallback notice (currently unused; reserved for future per-cell notices)\n  - `meta`: truncation metadata\n  - `isError`: set on cell failure or cancellation\n\nRenderer behavior in `packages/coding-agent/src/tools/eval.ts`:\n\n- call preview renders each cell's `code` with syntax highlighting based on its declared `language`\n- result view renders each cell separately, including status, duration, and output\n- markdown outputs are rendered with the Markdown component instead of plain text\n- `jsonOutputs` render as a tree, collapsed or expanded depending on UI state\n- timeout / truncation notices render as dim metadata lines\n- images are carried in `details.images`; generic tool UI image handling renders them outside the text block\n\nSide-channel artifacts:\n\n- `session.allocateOutputArtifact?.(\"eval\")` may allocate an `artifact://...` backing store for spilled output.\n- Truncated output metadata points at that artifact when available.\n\n## Flow\n\n1. `EvalTool.execute()` in `packages/coding-agent/src/tools/eval.ts` receives `params.cells` already validated by the Zod schema — no string parsing step.\n2. For each cell, `execute()` maps `cell.language` to an `EvalLanguage` (`\"py\"` → `\"python\"`, `\"js\"` → `\"js\"`) and calls `resolveBackend(session, language)`:\n   - `python` is gated on `eval.py !== false` and `pythonBackend.isAvailable(session)`.\n   - `js` is gated on `eval.js !== false`.\n   - A disabled or unavailable requested backend throws `ToolError`; there is no auto-fallback or sniffing.\n3. The tool allocates an `OutputSink`, a `TailBuffer`, per-cell result objects, and a `sessionAbortController`. `session.trackEvalExecution?.(...)` can wrap the whole run for external cancellation tracking.\n4. Cells execute sequentially. For each cell, `execute()`:\n   - clamps `(cell.timeout ?? 30) * 1000` ms through `clampTimeout(\"eval\", ...)`\n   - builds a combined abort signal from the tool signal, the timeout, and the session abort controller\n   - marks the cell `running` and emits an update\n   - calls the backend’s `execute()` with `cwd`, `sessionId`, `sessionFile`, `kernelOwnerId`, `deadlineMs`, `reset` (defaults to `false`), artifact info, and chunk callback\n5. JS cells dispatch through `packages/coding-agent/src/eval/js/index.ts` into `executeJs()`; Python cells dispatch through `packages/coding-agent/src/eval/py/index.ts` into `executePython()`.\n6. Backend text chunks stream into the shared `OutputSink`; rich outputs are accumulated separately as JSON, images, markdown markers, and status events.\n7. After each cell:\n   - text output is trimmed and stored on that cell result\n   - multi-cell runs prefix text with `[i/n]` and the optional title\n   - cancellations return early with `isError: true` and a cell-specific abort message\n   - non-zero exit codes return early with `isError: true` and a message naming the failed cell\n   - later cells are skipped after the first error, but earlier cell state persists in the underlying runtime\n8. On success, the tool joins all cell outputs, synthesizes `(no text output)` or `(no output)` when needed, and attaches truncation metadata from `summarizeFinal()`.\n9. The renderer uses `details.cells`, `details.jsonOutputs`, and `details.statusEvents` to build notebook-style output. `mergeCallAndResult = true` and `inline = true`, so call and result render together in the transcript.\n\n## Modes / Variants\n\n### Backend selection\n\nBackend choice is **explicit per cell** — there is no auto-detection.\n\n- `language: \"py\"` → Python (IPython/Jupyter) backend\n- `language: \"js\"` → JavaScript VM backend\n\nIf the requested backend is disabled or unavailable, the tool throws `ToolError` for that cell. The caller chooses; the tool does not silently substitute.\n\n### JavaScript runtime\n\nImplemented in `packages/coding-agent/src/eval/js/context-manager.ts` and `packages/coding-agent/src/eval/js/prelude.txt`.\n\n- Persistent `vm.Context` instances keyed by `js:${sessionId}` in `vmContexts`\n- `reset: true` calls `resetVmContext(sessionKey)` before the cell executes\n- Top-level `await` and bare `return` are supported by wrapping code in an async IIFE when `wrapCode()` sees `await` or `return`\n- Top-level static `import ... from ...` and dynamic `import(...)` calls are routed through `rewriteImports()`, which sends them via `__gjc_import__` so the specifier resolves against the session cwd\n- Module cache is busted for **local** imports between cells so edits to source files are picked up without restarting the runtime. `__gjc_import__` deletes `require.cache[absPath]` before re-importing whenever the original specifier is a filesystem path: relative (`./x`, `../x`, `.`, `..`), POSIX-absolute (`/...`), home-prefixed (`~/...`), or Windows drive-letter (`C:\\...` / `C:/...`). Bare specifiers (`react`, `lodash/x`) and URL/scheme specifiers (`node:fs`, `file://...`, `https://...`) are left in cache so package identity stays stable across cells. The cache-bust only fires when the resolved target is an absolute path — unresolved bare-package fallbacks (`resolveImportSpecifier()` returning the original specifier) skip it.\n- The prelude installs globals:\n  - `display`, `print`\n  - `read`, `write`, `append`, `sort`, `uniq`, `counter`, `diff`, `tree`, `env`, `output`\n  - `tool.<name>(args)` proxy for arbitrary session tool calls\n- JS helpers are async because they cross the VM/tool boundary\n- `display(value)` behavior:\n  - plain objects/arrays become JSON outputs\n  - `{ type: \"image\", data, mimeType }` becomes an image output\n  - scalars become text\n- The VM exposes a restricted `process` subset plus `Buffer`, `fetch`, `Blob`, `File`, `Headers`, `Request`, `Response`, `fs`, `require`, and browser-style globals\n- Per-session VM runs are serialized with `runQueued()`\n\n### Python runtime\n\nImplemented in `packages/coding-agent/src/eval/py/executor.ts`, `packages/coding-agent/src/eval/py/kernel.ts`, and `packages/coding-agent/src/eval/py/prelude.py`. See `docs/python-repl.md` for gateway and kernel details.\n\n- Default mode is retained `session` kernels keyed by `python:${sessionId}`\n- Optional `python.kernelMode = \"per-call\"` creates a fresh kernel for each cell and shuts it down afterward\n- `reset: true` disposes the retained kernel for that session before the cell runs; later Python cells in the same tool call reuse the fresh kernel\n- Startup path:\n  - availability check\n  - create/connect kernel\n  - initialize cwd / env / `sys.path`\n  - execute `PYTHON_PRELUDE`\n- Python cells run inside IPython/Jupyter, so top-level `await` works; the prompt warns not to use `asyncio.run(...)`\n- The Python prelude defines synchronous helpers with the same surface as JS (except `tool.<name>` exists only in JS)\n- `display(value)` wraps dict/list/tuple values in `IPython.display.JSON`; rich display MIME bundles are preserved\n- Kernel `display_data` / `execute_result` messages map to:\n  - `application/x-gjc-status` → status event\n  - `image/png` → image output\n  - `application/json` → JSON output\n  - `text/markdown` → markdown output\n  - `text/plain` → text output\n  - `text/html` → HTML converted to markdown with `htmlToBasicMarkdown()`\n- Interactive stdin is rejected: `input_request` sends an empty reply, marks `stdinRequested`, and the executor returns exit code `1`\n\n### Multi-language call behavior\n\nA single tool call can mix Python and JS cells. Persistence is per language runtime:\n\n- `reset: true` on a Python cell does not touch JS state\n- `reset: true` on a JS cell does not touch Python state\n- each backend keeps its own retained session keyed from the same session-derived ID\n\n## Side Effects\n\n- Filesystem\n  - JS/Python prelude helpers can read, write, append, diff, and traverse files under the session cwd or absolute paths.\n  - Output may spill to an artifact file via `OutputSink`.\n- Network\n  - Python backend speaks NDJSON to a local `python3` subprocess over stdin/stdout (no network).\n  - JS runtime exposes `fetch` and `tool.<name>()`; those tools may perform additional network I/O.\n- Subprocesses / native bindings\n  - Python availability check runs `<python> -c ...`.\n  - Python backend spawns one `python -u runner.py` subprocess per kernel; cancellation sends `SIGINT`. Details in `docs/python-repl.md`.\n- Session state\n  - `session.assertEvalExecutionAllowed?.()` can block execution.\n  - `session.trackEvalExecution?.(...)` can register cancellable eval work.\n  - `session.getSessionFile?.()` and `session.getEvalKernelOwnerId?.()` influence kernel reuse and artifact lookup.\n  - JS VM contexts persist in `vmContexts` across eval calls until reset/disposal.\n  - Python retained kernels persist in `kernelSessions` until reset, eviction, idle cleanup, or owner cleanup.\n- User-visible prompts / interactive UI\n  - none; stdin requests are rejected programmatically\n- Background work / cancellation\n  - Python retained kernels have heartbeat and idle cleanup timers.\n  - Cancellation interrupts a running Python kernel and aborts JS promise waits.\n\n## Limits & Caps\n\n- Per-cell timeout default: 30s (applied when `timeout` is omitted in `EvalTool.execute()`; clamped through `TOOL_TIMEOUTS.eval.default` in `packages/coding-agent/src/tools/tool-timeouts.ts`)\n- Schema-level `timeout` range: integer `1..600` seconds (enforced by Zod on the cell schema)\n- Timeout clamp at runtime: 1s minimum, 600s maximum (`TOOL_TIMEOUTS.eval` in `packages/coding-agent/src/tools/tool-timeouts.ts`)\n- Transcript code/output preview: 10 lines by default (`EVAL_DEFAULT_PREVIEW_LINES` in `packages/coding-agent/src/tools/eval.ts`)\n- Output truncation window: 50KB default (`DEFAULT_MAX_BYTES` in `packages/coding-agent/src/session/streaming-output.ts`)\n- Output line cap inside truncation helpers: 3000 lines (`DEFAULT_MAX_LINES` in `packages/coding-agent/src/session/streaming-output.ts`)\n- Streaming tail buffer for live updates: `DEFAULT_MAX_BYTES * 2` = 100KB (`packages/coding-agent/src/tools/eval.ts`)\n- Python retained kernel idle timeout: 5 minutes (`IDLE_TIMEOUT_MS` in `packages/coding-agent/src/eval/py/executor.ts`)\n- Python retained kernel cap: 4 sessions (`MAX_KERNEL_SESSIONS` in `packages/coding-agent/src/eval/py/executor.ts`)\n- Python retained kernel cleanup sweep: every 30s (`CLEANUP_INTERVAL_MS` in `packages/coding-agent/src/eval/py/executor.ts`)\n- Python owner-cleanup shutdown wait: 2000ms (`OWNER_CLEANUP_KERNEL_SHUTDOWN_TIMEOUT_MS` in `packages/coding-agent/src/eval/py/executor.ts`)\n- Python heartbeat interval: 5s (`ensureKernelHeartbeat()` in `packages/coding-agent/src/eval/py/executor.ts`)\n- Python external gateway availability check timeout: 5s (`AbortSignal.timeout(5000)` in `packages/coding-agent/src/eval/py/kernel.ts`)\n- Python auto-restart budget: one restart per retained session before hard failure (`restartCount > 1` in `packages/coding-agent/src/eval/py/executor.ts`)\n\n## Errors\n\n- Zod validation rejects malformed `cells` arrays before `execute()` runs (missing `language`/`code`, out-of-range `timeout`, empty `cells`).\n- Missing session without proxy executor throws `ToolError(\"Eval tool requires a session when not using proxy executor\")`.\n- Disabled/unavailable backends throw `ToolError` from `resolveBackend()`:\n  - `eval.py = false` and a `py` cell is requested\n  - `eval.js = false` and a `js` cell is requested\n  - Python kernel unavailable and a `py` cell is requested\n- JS runtime exceptions are converted into text output plus `exitCode: 1`; cancellations return `cancelled: true` and may append `Command timed out`.\n- Python execution errors from the kernel become text output and `exitCode: 1`; later cells are skipped.\n- Python stdin requests are treated as errors with the message `Kernel requested stdin; interactive input is not supported.`\n- Cancellation is returned, not thrown, once backend execution has started. The tool formats it as a cell failure and sets `details.isError = true`.\n- If output truncates, the tool still succeeds; truncation is surfaced through `details.meta` and artifact-backed full output when available.\n\n## Notes\n\n- Backend selection is now strictly explicit per cell: `language` must be `\"py\"` or `\"js\"`. The previous `*** Cell` header parser, the `eval.lark` constrained grammar, and the sniffer-based fallback have all been removed.\n- `EvalTool.customFormat` no longer exists. Tool calls flow through the standard JSON schema; there is no Lark-constrained sampling path.\n- `tool.<name>()` exists only in JS. Python prelude helpers do not call back into the full tool registry.\n- JS helper paths reject protocol URIs (`://`) in `resolvePath()`; the JS prelude is filesystem-only unless the code calls `tool.read(...)` or another tool explicitly.\n- Python helper `output(...)` depends on `GJC_SESSION_FILE`; it fails outside a session-backed run.\n- `display()` can produce text and structured outputs from the same value; the renderer prefers markdown over `text/plain` when both exist.\n- JS static imports are rewritten only at top level. Nested imports stay invalid and surface normal JS syntax/runtime errors.\n- `EvalTool` is `concurrency = \"exclusive\"`, so eval calls do not overlap within a session.\n- The tool description shown to the model is templated by backend availability (`getEvalToolDescription()`); if Python is unavailable, the prompt omits Python-specific instructions.\n",
+	"tools/eval.md": "# eval\n\n> Execute Python or JavaScript code in persistent cell-based runtimes.\n\n> **Notice:** Do not shell out to `python -c`/`python -e`, `bun -e`, or `node -e` via the `bash` tool for ad-hoc code execution. Use this tool instead — it gives you persistent state across cells, structured `display()` output, image/JSON capture, and proper cancellation/timeout handling that one-shot `-e`/`-c` invocations cannot provide.\n\n> **Not to be confused with [`python`](./python.md).** `eval` runs in a **session-scoped** kernel and is the general-purpose choice. The `python` tool is a session-owned persistent REPL with its own `python:<session-id>` owner and an append-only JSONL transcript; it requires no active `autoresearch` mission. Both drive the same underlying Python kernel implementation — see [Kernel ownership](../python-repl.md#kernel-ownership).\n\n## Source\n- Entry: `packages/coding-agent/src/tools/eval.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/eval.md`\n- Key collaborators:\n  - `packages/coding-agent/src/eval/backend.ts` — backend execution contract\n  - `packages/coding-agent/src/eval/js/index.ts` — JS backend adapter\n  - `packages/coding-agent/src/eval/js/executor.ts` — JS execution + output sink\n  - `packages/coding-agent/src/eval/js/context-manager.ts` — persistent VM contexts, prelude, tool bridge\n  - `packages/coding-agent/src/eval/js/shared/prelude.txt` — JS global helpers\n  - `packages/coding-agent/src/eval/py/index.ts` — Python backend adapter\n  - `packages/coding-agent/src/eval/py/executor.ts` — kernel session retention, reset, cleanup\n  - `packages/coding-agent/src/eval/py/kernel.ts` — runner subprocess lifecycle, NDJSON framing, interrupt/shutdown\n  - `packages/coding-agent/src/eval/py/runner.py` — NDJSON runner executed by the kernel subprocess\n  - `packages/coding-agent/src/eval/py/display.ts` — MIME bundle to text/structured output mapping\n  - `packages/coding-agent/src/eval/py/prelude.py` — Python helper functions and status events\n  - `packages/coding-agent/src/session/streaming-output.ts` — truncation, artifacts, streamed chunks\n  - `docs/python-repl.md` — Python runner and kernel internals\n\n## Inputs\n\nTool parameters are a JSON object with a single `cells` field — an ordered array of cell objects. Each cell is a structured record; there is no `*** Cell` header parsing, no language sniffing, and no implicit single-cell fallback. Cells run in array order; state persists within each language across cells and across tool calls.\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `cells` | `EvalCellInput[]` | Yes | Cells executed in order. At least one cell is required (`.min(1)`). |\n\nEach `EvalCellInput` (from `evalCellSchema` in `packages/coding-agent/src/tools/eval.ts`):\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `language` | `\"py\" \\| \"js\"` | Yes | Backend selector. `\"py\"` maps to the persistent Python subprocess runner (`python` backend); `\"js\"` maps to the persistent JavaScript VM. |\n| `code` | `string` | Yes | Cell body, verbatim. JSON-encoded — embed newlines, quotes, and indentation directly; no fences, no headers. |\n| `title` | `string` | No | Short label rendered in the transcript (e.g. `\"imports\"`, `\"load config\"`). |\n| `timeout` | `integer` | No | Per-cell timeout in seconds, clamped to `1..600`. Defaults to 30 when omitted. |\n| `reset` | `boolean` | No | Wipe this cell's language kernel before running. Reset is per-language: a `py` cell's reset does not touch the JS VM and vice versa. Defaults to `false`. |\n\nMinimal example matching the live schema:\n\n```json\n{\n  \"cells\": [\n    { \"language\": \"py\", \"title\": \"imports\", \"timeout\": 10, \"code\": \"import json\\nfrom pathlib import Path\" },\n    { \"language\": \"py\", \"title\": \"load config\", \"code\": \"data = json.loads(read('package.json'))\\ndisplay(data)\" },\n    { \"language\": \"js\", \"title\": \"summary\", \"reset\": true, \"code\": \"const data = JSON.parse(await read('package.json'));\\ndisplay(data);\\nreturn data.name;\" }\n  ]\n}\n```\n\n## Outputs\n\nFinal result from `EvalTool.execute()` is single-shot, but `onUpdate` streams partial text and `details` while cells run.\n\nReturned shape:\n\n- `content`: one text block containing combined cell output, or `(no text output)` / `(no output)` when only rich outputs exist.\n- `details` (`EvalToolDetails` from `packages/coding-agent/src/eval/types.ts`):\n  - `cells`: per-cell code, status (`pending`/`running`/`complete`/`error`), output, duration, exit code, status events, markdown flag\n  - `language`: first backend used\n  - `languages`: distinct backends used, in first-use order\n  - `jsonOutputs`: structured values emitted via `display(...)`\n  - `images`: image payloads emitted by Python rich display or JS `display({ type: \"image\", ... })`\n  - `statusEvents`: aggregated helper/tool status events\n  - `notice`: backend fallback notice (currently unused; reserved for future per-cell notices)\n  - `meta`: truncation metadata\n  - `isError`: set on cell failure or cancellation\n\nRenderer behavior in `packages/coding-agent/src/tools/eval.ts`:\n\n- call preview renders each cell's `code` with syntax highlighting based on its declared `language`\n- result view renders each cell separately, including status, duration, and output\n- markdown outputs are rendered with the Markdown component instead of plain text\n- `jsonOutputs` render as a tree, collapsed or expanded depending on UI state\n- timeout / truncation notices render as dim metadata lines\n- images are carried in `details.images`; generic tool UI image handling renders them outside the text block\n\nSide-channel artifacts:\n\n- `session.allocateOutputArtifact?.(\"eval\")` may allocate an `artifact://...` backing store for spilled output.\n- Truncated output metadata points at that artifact when available.\n\n## Flow\n\n1. `EvalTool.execute()` in `packages/coding-agent/src/tools/eval.ts` receives `params.cells` already validated by the Zod schema — no string parsing step.\n2. For each cell, `execute()` maps `cell.language` to an `EvalLanguage` (`\"py\"` → `\"python\"`, `\"js\"` → `\"js\"`) and calls `resolveBackend(session, language)`:\n   - `python` is gated on `eval.py !== false` and `pythonBackend.isAvailable(session)`.\n   - `js` is gated on `eval.js !== false`.\n   - A disabled or unavailable requested backend throws `ToolError`; there is no auto-fallback or sniffing.\n3. The tool allocates an `OutputSink`, a `TailBuffer`, per-cell result objects, and a `sessionAbortController`. `session.trackEvalExecution?.(...)` can wrap the whole run for external cancellation tracking.\n4. Cells execute sequentially. For each cell, `execute()`:\n   - clamps `(cell.timeout ?? 30) * 1000` ms through `clampTimeout(\"eval\", ...)`\n   - builds a combined abort signal from the tool signal, the timeout, and the session abort controller\n   - marks the cell `running` and emits an update\n   - calls the backend’s `execute()` with `cwd`, `sessionId`, `sessionFile`, `kernelOwnerId`, `deadlineMs`, `reset` (defaults to `false`), artifact info, and chunk callback\n5. JS cells dispatch through `packages/coding-agent/src/eval/js/index.ts` into `executeJs()`; Python cells dispatch through `packages/coding-agent/src/eval/py/index.ts` into `executePython()`.\n6. Backend text chunks stream into the shared `OutputSink`; rich outputs are accumulated separately as JSON, images, markdown markers, and status events.\n7. After each cell:\n   - text output is trimmed and stored on that cell result\n   - multi-cell runs prefix text with `[i/n]` and the optional title\n   - cancellations return early with `isError: true` and a cell-specific abort message\n   - non-zero exit codes return early with `isError: true` and a message naming the failed cell\n   - later cells are skipped after the first error, but earlier cell state persists in the underlying runtime\n8. On success, the tool joins all cell outputs, synthesizes `(no text output)` or `(no output)` when needed, and attaches truncation metadata from `summarizeFinal()`.\n9. The renderer uses `details.cells`, `details.jsonOutputs`, and `details.statusEvents` to build notebook-style output. `mergeCallAndResult = true` and `inline = true`, so call and result render together in the transcript.\n\n## Modes / Variants\n\n### Backend selection\n\nBackend choice is **explicit per cell** — there is no auto-detection.\n\n- `language: \"py\"` → Python (subprocess runner) backend\n- `language: \"js\"` → JavaScript VM backend\n\nIf the requested backend is disabled or unavailable, the tool throws `ToolError` for that cell. The caller chooses; the tool does not silently substitute.\n\n### JavaScript runtime\n\nImplemented in `packages/coding-agent/src/eval/js/context-manager.ts` and `packages/coding-agent/src/eval/js/shared/prelude.txt`.\n\n- Persistent `vm.Context` instances keyed by `js:${sessionId}` in the `sessions` map of `context-manager.ts`\n- `reset: true` calls `resetVmContext(sessionKey)` before the cell executes\n- Top-level `await` and bare `return` are supported by wrapping code in an async IIFE when `wrapCode()` sees `await` or `return`\n- Top-level static `import ... from ...` and dynamic `import(...)` calls are routed through `rewriteImports()`, which sends them via `__gjc_import__` so the specifier resolves against the session cwd\n- Module cache is busted for **local** imports between cells so edits to source files are picked up without restarting the runtime. `__gjc_import__` deletes `require.cache[absPath]` before re-importing whenever the original specifier is a filesystem path: relative (`./x`, `../x`, `.`, `..`), POSIX-absolute (`/...`), home-prefixed (`~/...`), or Windows drive-letter (`C:\\...` / `C:/...`). Bare specifiers (`react`, `lodash/x`) and URL/scheme specifiers (`node:fs`, `file://...`, `https://...`) are left in cache so package identity stays stable across cells. The cache-bust only fires when the resolved target is an absolute path — unresolved bare-package fallbacks (`resolveImportSpecifier()` returning the original specifier) skip it.\n- The prelude installs globals:\n  - `display`, `print`\n  - `read`, `write`, `append`, `sort`, `uniq`, `counter`, `diff`, `tree`, `env`, `output`\n  - `tool.<name>(args)` proxy for arbitrary session tool calls\n- JS helpers are async because they cross the VM/tool boundary\n- `display(value)` behavior:\n  - plain objects/arrays become JSON outputs\n  - `{ type: \"image\", data, mimeType }` becomes an image output\n  - scalars become text\n- The VM exposes a restricted `process` subset plus `Buffer`, `fetch`, `Blob`, `File`, `Headers`, `Request`, `Response`, `fs`, `require`, and browser-style globals\n- Per-session VM runs are serialized with `runQueued()`\n\n### Python runtime\n\nImplemented in `packages/coding-agent/src/eval/py/executor.ts`, `packages/coding-agent/src/eval/py/kernel.ts`, and `packages/coding-agent/src/eval/py/prelude.py`. See `docs/python-repl.md` for runner and kernel details.\n\n- Default mode is retained `session` kernels keyed by `python:${sessionId}`\n- Optional `python.kernelMode = \"per-call\"` creates a fresh kernel for each cell and shuts it down afterward\n- `reset: true` disposes the retained kernel for that session before the cell runs; later Python cells in the same tool call reuse the fresh kernel\n- Startup path:\n  - availability check\n  - spawn `python -u runner.py` as its own process group\n  - initialize cwd / env / `sys.path`\n  - execute `PYTHON_PRELUDE`\n- The runner compiles cells with `PyCF_ALLOW_TOP_LEVEL_AWAIT` on a persistent event loop, so top-level `await` works; the prompt warns not to use `asyncio.run(...)`\n- The Python prelude defines synchronous helpers with the same surface as JS. When the host tool bridge starts, `tool.<name>(args)` is also available in Python (via the `PI_TOOL_BRIDGE_*` environment variables)\n- `display(value)` turns plain dict/list/tuple values into an `application/json` + `text/plain` bundle; objects with `_repr_*_` methods keep their rich MIME bundles\n- Runner `display` / `result` frames map through `renderKernelDisplay()` (`packages/coding-agent/src/eval/py/display.ts`) to:\n  - `application/x-gjc-status` → status event (no text)\n  - `image/png` / `image/jpeg` → image output\n  - `application/json` → JSON output\n  - text, by precedence: `text/markdown` (markdown output) > `text/plain` > `text/html` converted to markdown with `htmlToBasicMarkdown()`\n- Interactive stdin is not supported: the runner does not forward `input()` prompts, so a cell that calls `input()` blocks until it is cancelled or times out\n\n### Multi-language call behavior\n\nA single tool call can mix Python and JS cells. Persistence is per language runtime:\n\n- `reset: true` on a Python cell does not touch JS state\n- `reset: true` on a JS cell does not touch Python state\n- each backend keeps its own retained session keyed from the same session-derived ID\n\n## Side Effects\n\n- Filesystem\n  - JS/Python prelude helpers can read, write, append, diff, and traverse files under the session cwd or absolute paths.\n  - Output may spill to an artifact file via `OutputSink`.\n- Network\n  - Python backend speaks NDJSON to a local `python3` subprocess over stdin/stdout (no network).\n  - JS runtime exposes `fetch` and `tool.<name>()`; those tools may perform additional network I/O.\n- Subprocesses / native bindings\n  - Python availability check runs `<python> -c ...`.\n  - Python backend spawns one `python -u runner.py` subprocess per kernel; cancellation sends `SIGINT`. Details in `docs/python-repl.md`.\n- Session state\n  - `session.assertEvalExecutionAllowed?.()` can block execution.\n  - `session.trackEvalExecution?.(...)` can register cancellable eval work.\n  - `session.getSessionFile?.()` and `session.getEvalKernelOwnerId?.()` influence kernel reuse and artifact lookup.\n  - JS VM contexts persist in the `sessions` map of `context-manager.ts` across eval calls until reset/disposal.\n  - Python retained kernels persist in the executor's `sessions` map until reset, owner cleanup (`disposeKernelSessionsByOwner()`), or process shutdown (`disposeAllKernelSessions()`). There is no idle eviction or session cap.\n- User-visible prompts / interactive UI\n  - none; stdin requests are rejected programmatically\n- Background work / cancellation\n  - Python kernels have no heartbeat or idle timers. A dead retained kernel is detected with `isAlive()` when the next cell runs and is replaced.\n  - Cancellation interrupts a running Python kernel and aborts JS promise waits.\n\n## Limits & Caps\n\n- Per-cell timeout default: 30s (applied when `timeout` is omitted in `EvalTool.execute()`; clamped through `TOOL_TIMEOUTS.eval.default` in `packages/coding-agent/src/tools/tool-timeouts.ts`)\n- Schema-level `timeout` range: integer `1..600` seconds (enforced by Zod on the cell schema)\n- Timeout clamp at runtime: 1s minimum, 600s maximum (`TOOL_TIMEOUTS.eval` in `packages/coding-agent/src/tools/tool-timeouts.ts`)\n- Transcript code/output preview: 10 lines by default (`EVAL_DEFAULT_PREVIEW_LINES` in `packages/coding-agent/src/tools/eval.ts`)\n- Output truncation window: 50KB default (`DEFAULT_MAX_BYTES` in `packages/coding-agent/src/session/streaming-output.ts`)\n- Output line cap inside truncation helpers: 3000 lines (`DEFAULT_MAX_LINES` in `packages/coding-agent/src/session/streaming-output.ts`)\n- Streaming tail buffer for live updates: `DEFAULT_MAX_BYTES * 2` = 100KB (`packages/coding-agent/src/tools/eval.ts`)\n- Python kernel startup budget: 10s shared by the init script and prelude (`STARTUP_TIMEOUT_MS` in `packages/coding-agent/src/eval/py/kernel.ts`)\n- Python interrupt escalation: if the runner has not finished 5s after `SIGINT`, the kernel is shut down and the cell is marked as kernel-killed (`INTERRUPT_ESCALATION_MS` in `packages/coding-agent/src/eval/py/kernel.ts`)\n- Python shutdown: `{\"type\":\"exit\"}`, then `SIGTERM`, then `SIGKILL`, waiting 1s per step by default (`SHUTDOWN_GRACE_MS` in `packages/coding-agent/src/eval/py/kernel.ts`)\n- Python dead-kernel recovery: a retained kernel found dead before a cell runs is replaced; a non-cancellation failure that leaves it dead is replaced and the cell is retried once (`executeOnSession()` in `packages/coding-agent/src/eval/py/executor.ts`)\n- Retained Python kernels have no idle timeout, session cap, or heartbeat\n\n## Errors\n\n- Zod validation rejects malformed `cells` arrays before `execute()` runs (missing `language`/`code`, out-of-range `timeout`, empty `cells`).\n- Missing session without proxy executor throws `ToolError(\"Eval tool requires a session when not using proxy executor\")`.\n- Disabled/unavailable backends throw `ToolError` from `resolveBackend()`:\n  - `eval.py = false` and a `py` cell is requested\n  - `eval.js = false` and a `js` cell is requested\n  - Python kernel unavailable and a `py` cell is requested\n- JS runtime exceptions are converted into text output plus `exitCode: 1`; cancellations return `cancelled: true` and may append `Command timed out`.\n- Python execution errors from the kernel become text output and `exitCode: 1`; later cells are skipped.\n- Python timeouts annotate the output: `eval cell timed out after <n>s; kernel interrupted but remains running. ...`, or, when the kernel ignored the interrupt and was killed, a notice that it will be recreated on the next call (`formatKernelTimeoutAnnotation()` in `packages/coding-agent/src/eval/py/executor.ts`).\n- Cancellation is returned, not thrown, once backend execution has started. The tool formats it as a cell failure and sets `details.isError = true`.\n- If output truncates, the tool still succeeds; truncation is surfaced through `details.meta` and artifact-backed full output when available.\n\n## Notes\n\n- Backend selection is now strictly explicit per cell: `language` must be `\"py\"` or `\"js\"`. The previous `*** Cell` header parser, the `eval.lark` constrained grammar, and the sniffer-based fallback have all been removed.\n- `EvalTool.customFormat` no longer exists. Tool calls flow through the standard JSON schema; there is no Lark-constrained sampling path.\n- `tool.<name>()` exists in JS, and in Python when the host tool bridge starts. The other Python prelude helpers work on the filesystem directly.\n- JS helper paths reject protocol URIs (`://`) in `resolvePath()`; the JS prelude is filesystem-only unless the code calls `tool.read(...)` or another tool explicitly.\n- Python helper `output(...)` reads `PI_ARTIFACTS_DIR`, falling back to `PI_SESSION_FILE`, and raises `No session - output artifacts unavailable` when neither is set. The `eval` Python backend (`packages/coding-agent/src/eval/py/index.ts`) currently passes neither.\n- `display()` can produce text and structured outputs from the same value; the renderer prefers markdown over `text/plain` when both exist.\n- JS static imports are rewritten only at top level. Nested imports stay invalid and surface normal JS syntax/runtime errors.\n- `EvalTool` is `concurrency = \"exclusive\"`, so eval calls do not overlap within a session.\n- The tool description shown to the model is templated by backend availability (`getEvalToolDescription()`); if Python is unavailable, the prompt omits Python-specific instructions.\n",
 	"tools/find.md": "# find\n\n> Find filesystem paths by glob; use `search` when you need content matches instead of path matches.\n\n## Source\n- Entry: `packages/coding-agent/src/tools/find.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/find.md`\n- Key collaborators:\n  - `packages/coding-agent/src/tools/path-utils.ts` — normalize inputs; split base path vs glob.\n  - `packages/coding-agent/src/tools/list-limit.ts` — apply result-count caps.\n  - `packages/coding-agent/src/session/streaming-output.ts` — truncate text output at byte cap.\n  - `packages/coding-agent/src/tools/tool-result.ts` — build `content` and `details.meta`.\n  - `packages/coding-agent/src/tools/output-meta.ts` — encode limit / truncation metadata.\n  - `packages/coding-agent/src/tools/tool-errors.ts` — map user-facing tool errors.\n  - `packages/coding-agent/src/tools/index.ts` — register the built-in local implementation.\n\n## Inputs\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `paths` | `string[]` | Yes | One or more globs, files, or directories. Empty strings are rejected. Multiple entries may be merged into one brace-union search when their base paths can be resolved together. |\n| `hidden` | `boolean` | No | Whether hidden files are included. Defaults to `true` (`hidden ?? true`). |\n| `limit` | `number` | No | Max returned paths. Defaults to `1000`. Must be a finite positive number; non-integers are floored. |\n\n## Outputs\nThe tool returns a single text block plus structured `details`.\n\n- Success text: newline-delimited paths, one per line, relative to the session cwd when possible; absolute when outside cwd. Exact file inputs return that file path as one line.\n- Empty result text: `No files found matching pattern`.\n- Multi-path partial miss: appends `Skipped missing paths: ...` after the result block, or after the empty-result line.\n- `details` may include:\n  - `scopePath`: display form of the searched root or merged roots.\n  - `fileCount`: number of paths returned after result limiting.\n  - `files`: returned paths as an array.\n  - `truncated`: whether result count or byte truncation occurred.\n  - `resultLimitReached`: reached result limit.\n  - `missingPaths`: skipped missing inputs in multi-path calls.\n  - `truncation` / `meta.limits`: structured truncation and limit metadata for renderers.\n- Streaming: when the runtime supplies `onUpdate`, the local implementation emits incremental newline-delimited text snapshots during globbing, throttled to 200 ms.\n\n## Flow\n1. `FindTool.execute()` normalizes each `paths` entry with `normalizePathLikeInput()` and `/\\\\/g -> \"/\"` (`packages/coding-agent/src/tools/find.ts`). Empty normalized entries fail with `` `paths` must contain non-empty globs or paths ``.\n2. For multi-path local calls, `partitionExistingPaths(..., parseFindPattern)` (`packages/coding-agent/src/tools/path-utils.ts`) stats each base path. Missing entries are skipped; if all are missing, the tool throws `Path not found: ...`. Single missing paths still hard-fail.\n3. The tool tries `resolveExplicitFindPatterns()` to merge multiple inputs into one search rooted at a common base path. If that does not apply, it parses one input with `parseFindPattern()`.\n4. `parseFindPattern()` determines `(basePath, globPattern, hasGlob)`:\n   - no glob chars (`*`, `?`, `[`, `{`) => search that path with implicit `**/*`.\n   - glob in the first segment => search from `.` and, unless the pattern already starts with `**/`, prefix it with `**/`.\n   - glob later in the path => split at the first glob-bearing segment.\n5. `resolveToCwd()` converts the base path to an absolute path under the session cwd. A resolved `/` is rejected with `Searching from root directory '/' is not allowed`.\n6. `limit` is defaulted to `DEFAULT_LIMIT` (`1000`) and validated as a positive finite integer. `hidden` defaults to `true`. The tool also creates a 5 s timeout via `AbortSignal.timeout(GLOB_TIMEOUT_MS)`.\n7. Execution then branches:\n   - **Custom operations branch**: if `FindToolOptions.operations.glob` exists, the tool checks existence with `operations.exists()`, short-circuits exact-file inputs via `operations.stat()` when available, then calls `operations.glob(globPattern, searchPath, { ignore: [\"**/node_modules/**\", \"**/.git/**\"], limit })`.\n   - **Built-in local branch**: the tool stats `searchPath`. Exact-file inputs return immediately. Directory inputs call `natives.glob()` with `fileType: File`, `hidden`, `maxResults: limit`, `sortByMtime: true`, `gitignore: true`, and the combined abort signal.\n8. In the local branch, optional `onMatch` callbacks convert each match to a cwd-relative display path and emit throttled progress updates.\n9. After native glob returns, JS sorts `result.matches` by `mtime` descending (`(b.mtime ?? 0) - (a.mtime ?? 0)`) before formatting paths.\n10. `buildResult()` applies `applyListLimit()` to cap the array again at `limit`, joins paths with `\\n`, then runs `truncateHead()` with `maxLines: Number.MAX_SAFE_INTEGER`. In practice this leaves the 50 KB byte cap in place while disabling the default 3000-line cap.\n11. `toolResult()` packages text plus `details`, and records result-limit / truncation metadata for renderers.\n\n## Modes / Variants\n- **Exact file path**: if the parsed input has no glob and the resolved path stats as a file, output is that one path.\n- **Directory path**: if the parsed input has no glob and stats as a directory, the tool searches it with implicit `**/*`.\n- **Single glob path**: one input parsed by `parseFindPattern()`.\n- **Merged multi-path search**: multiple inputs resolved by `resolveExplicitFindPatterns()` into one brace-union glob rooted at a common base path.\n- **Partial multi-path search with missing inputs**: local multi-path calls skip missing base paths and surface them as `missingPaths` / `Skipped missing paths: ...`.\n- **Custom delegated search**: uses injected `FindOperations` instead of local fs + native glob.\n\n## Side Effects\n- Filesystem\n  - Stats the resolved base path, and in local multi-path mode stats every candidate base path up front.\n  - Does not write files.\n- Subprocesses / native bindings\n  - Built-in local mode calls the native `@gajae-code/natives` glob implementation.\n- Session state (transcript, memory, jobs, checkpoints, registries)\n  - Emits structured progress updates when `onUpdate` is provided.\n  - Adds truncation / limit metadata to the tool result.\n- Background work / cancellation\n  - Local globbing is cancellable through the caller abort signal plus an internal 5 s timeout.\n\n## Limits & Caps\n- Default result limit: `1000` (`DEFAULT_LIMIT` in `packages/coding-agent/src/tools/find.ts`).\n- Local glob timeout: `5000` ms (`GLOB_TIMEOUT_MS` in `packages/coding-agent/src/tools/find.ts`).\n- Output byte cap: `50 * 1024` bytes (`DEFAULT_MAX_BYTES` in `packages/coding-agent/src/session/streaming-output.ts`).\n- Default generic line cap in `truncateHead()` is `3000`, but `find` overrides `maxLines` to `Number.MAX_SAFE_INTEGER`, so byte size — not line count — is the practical output truncation cap.\n- Streaming update throttle: `200` ms between `onUpdate` emissions.\n- Sort order: most recent `mtime` first in the built-in local branch and promised in the prompt. The tool re-sorts in JS even though native glob receives `sortByMtime: true` so native code can still stop early at `maxResults`.\n\n## Errors\n- User-facing `ToolError`s from `FindTool.execute()` include:\n  - `` `paths` must contain non-empty globs or paths ``\n  - `Path not found: ...`\n  - `Searching from root directory '/' is not allowed`\n  - `Limit must be a positive number`\n  - `Path is not a directory: ...`\n  - `find timed out after 5s`\n- If the caller aborts, the local branch converts `AbortError` into `ToolAbortError`.\n- Non-`ENOENT` stat failures and other unexpected errors are rethrown.\n- Empty matches are not errors; they return the no-files text result.\n\n## Notes\n- Reach for `find` for filename / path discovery. Reach for `search` when the selection criterion is file contents or regex matches; `search` takes a `pattern` and returns anchored content matches, while `find` only returns matching paths (`packages/coding-agent/src/prompts/tools/find.md`, `packages/coding-agent/src/prompts/tools/search.md`).\n- Bare top-level globs are made recursive. `*.ts` is parsed as base `.` plus glob `**/*.ts`; `src/*.ts` stays rooted at `src` with a non-recursive `*.ts` segment; `src/**/*.ts` preserves explicit recursion.\n- `.gitignore` is always enabled in the built-in local branch (`gitignore: true`). There is no model-facing flag to disable it.\n- `hidden` defaults to `true`; hidden-file exclusion is opt-out, not opt-in.\n- Multi-path missing-input tolerance only applies in the built-in local branch. The custom-operations branch hard-fails the first missing `searchPath` it checks.\n- The custom `FindOperations.glob()` hook receives `ignore` and `limit`, but not the `hidden` flag or an explicit `.gitignore` toggle. A remote delegate must account for that itself if it wants parity with the local branch.\n- Built-in local globbing asks the native layer for `fileType: File`, so recursive directory searches yield files, not directories. Directory outputs are only possible through exact-path passthrough or custom delegates that return them.\n",
 	"tools/github.md": "# github\n\n> Dispatch GitHub CLI operations for repositories, issues, pull requests, search, and Actions run watching.\n\n## Source\n- Entry: `packages/coding-agent/src/tools/gh.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/github.md`\n- Key collaborators:\n  - `packages/coding-agent/src/tools/gh-format.ts` — shorten commit SHAs for summaries.\n  - `packages/coding-agent/src/tools/gh-renderer.ts` — TUI rendering, especially `run_watch` live/result views.\n  - `packages/coding-agent/src/utils/git.ts` — `gh`/`git` process wrappers, repo locking, branch config writes.\n  - `packages/utils/src/dirs.ts` — base directory for dedicated PR worktrees.\n  - `packages/coding-agent/src/sdk/session.ts` — session artifact allocation hook.\n  - `packages/coding-agent/src/session/artifacts.ts` — artifact filename format `<id>.<toolType>.log`.\n\n## Inputs\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `op` | `\"repo_view\" \\| \"pr_create\" \\| \"pr_checkout\" \\| \"pr_push\" \\| \"search_issues\" \\| \"search_prs\" \\| \"search_code\" \\| \"search_commits\" \\| \"search_repos\" \\| \"run_watch\"` | Yes | Dispatch selector. `GithubTool.execute()` switches only on this field. |\n| `repo` | `string` | No | `owner/repo` override. Ignored when the identifier argument is already a full GitHub URL. For `search_issues`/`search_prs`/`search_code`/`search_commits`, defaults to the current checkout's `owner/repo` when omitted (skipped when the query already contains a `repo:`/`org:`/`user:`/`owner:` qualifier or when current-repo resolution fails). Required in practice when `gh` cannot infer repo context from the current checkout. |\n| `branch` | `string` | No | Used by `repo_view`, `pr_push`, and `run_watch`. `run_watch` falls back to current git branch when `run` is omitted; `pr_push` falls back to current branch. |\n| `pr` | `string \\| string[]` | No | Used by `pr_checkout`. Each item may be a PR number, branch name, or GitHub PR URL. Array form enables batching. Omitted means current branch PR. |\n| `force` | `boolean` | No | Used only by `pr_checkout`. Defaults to `false`; allows resetting an existing `pr-<number>` local branch to the PR head commit. |\n| `forceWithLease` | `boolean` | No | Used only by `pr_push`; passed through to git push. |\n| `title` | `string` | No | Used only by `pr_create`. Required unless `fill` is `true`. |\n| `body` | `string` | No | Used only by `pr_create`. Mutually exclusive with `fill`. Empty/omitted body becomes `--body \"\"` to suppress the interactive editor. Non-empty body is written to a temp file and passed as `--body-file`. |\n| `base` | `string` | No | Used only by `pr_create`; passed as `--base`. |\n| `head` | `string` | No | Used only by `pr_create`; passed as `--head`. |\n| `draft` | `boolean` | No | Used only by `pr_create`. Defaults to `false`. |\n| `fill` | `boolean` | No | Used only by `pr_create`. Defaults to `false`. Mutually exclusive with `title` and `body`. |\n| `reviewer` | `string[]` | No | Used only by `pr_create`; each entry becomes `--reviewer`. |\n| `assignee` | `string[]` | No | Used only by `pr_create`; each entry becomes `--assignee`. |\n| `label` | `string[]` | No | Used only by `pr_create`; each entry becomes `--label`. |\n| `query` | `string` | No | Used by all `search_*` ops. Required there. |\n| `limit` | `number` | No | Used by all `search_*` ops. Defaults to `10`, floored, clamped to `50`, and must be `> 0`. |\n| `run` | `string` | No | Used only by `run_watch`. Must be a numeric run ID or full GitHub Actions run URL. |\n| `tail` | `number` | No | Used only by `run_watch`. Defaults to `15`, floored, clamped to `200`, and must be `> 0`. |\n\n## Outputs\nThe tool returns a single text result built by `buildTextResult()` in `packages/coding-agent/src/tools/gh.ts`.\n\n- `content`: one text block. Multi-item ops join sections with blank lines and `---` separators.\n- `sourceUrl`: set for single repo/PR/run results when a canonical URL is known.\n- `details`: optional structured metadata used by the TUI renderer.\n  - Common fields: `artifactId`, `repo`, `branch`, `worktreePath`, `remote`, `remoteBranch`, `headSha`, `runId`, `runIds`, `status`, `conclusion`, `failedJobs`.\n  - `pr_checkout` adds `checkouts: GhPrCheckoutSummary[]`.\n  - `run_watch` adds `watch: GhRunWatchViewDetails`, which drives the custom live/result renderer in `packages/coding-agent/src/tools/gh-renderer.ts`.\n- Artifact trailer: when `artifactId` is present, the text body gets an appended line like `Full failed-job logs: artifact://<id>`.\n  - `run_watch` allocates artifacts with `session.allocateOutputArtifact(\"github\")`; persistent sessions therefore save failed-log bodies as `<artifact-dir>/<id>.github.log`.\n\n`run_watch` is the only streaming op. It emits `onUpdate` snapshots while polling, then returns one final text result.\n\n## Flow\n1. `GithubTool.createIf()` exposes the tool only when `git.github.available()` finds `gh` on `PATH`.\n2. `GithubTool.execute()` wraps dispatch in `untilAborted()` and switches on `params.op`.\n3. Each op normalizes optional strings, arrays, booleans, and numeric caps locally in `packages/coding-agent/src/tools/gh.ts`.\n4. CLI execution goes through `git.github.run/json/text()` in `packages/coding-agent/src/utils/git.ts`:\n   - spawns `gh ...` with `Bun.spawn()`;\n   - trims stdout/stderr unless `trimOutput: false`;\n   - maps common auth/repo-context failures into tool-facing `ToolError` messages;\n   - `json()` rejects empty or invalid JSON.\n5. Read-style ops (`repo_view`, `search_*`) fetch JSON and format Markdown-like text summaries. Single-issue and single-PR views were moved out of the tool and now resolve through the `issue://` / `pr://` internal URL schemes, which share the same SQLite cache.\n7. PR diffs moved out of the tool. `pr://<N>/diff` lists changed files, `pr://<N>/diff/<i>` slices a single file, and `pr://<N>/diff/all` returns the full unified diff — see `docs/tools/read.md`. All three variants share one `gh pr diff` invocation through the `pr-diff` cache row.\n8. `pr_checkout` resolves PR metadata first, then enters `git.withRepoLock()` before any git mutation so parallel checkout calls for the same primary repo do not race on shared `.git` state.\n9. `pr_push` reads PR head metadata back from git branch config, derives a refspec, then pushes with `git.push()`.\n10. `pr_create` shells out once, then best-effort re-reads the created PR for a richer summary.\n11. `run_watch` chooses either run mode (`run` supplied) or commit mode (`run` omitted), polls GitHub Actions APIs every 3 seconds, emits streaming updates, and may save a full failed-log artifact before returning.\n12. Final text goes through `toolResult().text(...)`; if `session.allocateOutputArtifact()` returns a slot, failed-log text is persisted with `Bun.write()`.\n\n## Modes / Variants\n\n### `repo_view`\n\n| Aspect | Value |\n| --- | --- |\n| Required fields | `op` |\n| Optional fields | `repo`, `branch` |\n| `gh` command | `gh repo view [<repo>] [--branch <branch>] --json <GH_REPO_FIELDS>` |\n| Batching | None |\n| Output | `# <owner/repo>` header, description, URL, default branch, requested branch, visibility, permission, primary language, stars, forks, archive/fork flags, updated timestamp, homepage, topics. `sourceUrl = data.url`. |\n\nIf `repo` is omitted, `gh` repository resolution is used.\n\nSingle-issue and single-PR reads live in the `issue://<N>` / `pr://<N>` URL schemes (see `docs/tools/read.md`). They share `~/.gjc/cache/github-cache.db` (override via `GJC_GITHUB_CACHE_DB`) and the `github.cache.softTtlSec` / `github.cache.hardTtlSec` / `github.cache.enabled` settings. The cache retains rendered Markdown plus the raw JSON payload returned by `gh`, including private bodies, comments, reviews, and review comments when comments are enabled; rows are scoped by the local GitHub credential fingerprint. Root and repo-scoped reads (`issue://`, `pr://owner/repo`) issue a live `gh issue list` / `gh pr list` for browsing; query params `state`, `limit`, `author`, `label` pass through to `gh` (`issue://` accepts `state=open|closed|all`; `pr://` also accepts `merged`). PR diffs ride the same cache under `pr://<N>/diff[/…]`: the listing, full diff, and per-file slices all share one `pr-diff` row keyed by repo and PR number.\n\n### `pr_create`\n\n| Aspect | Value |\n| --- | --- |\n| Required fields | `op` plus either `fill=true` or `title` |\n| Optional fields | `repo`, `title`, `body`, `base`, `head`, `draft`, `fill`, `reviewer[]`, `assignee[]`, `label[]` |\n| `gh` command | `gh pr create ...` with flags assembled from provided fields |\n| Batching | None |\n| Output | `# Created Pull Request ...` summary with URL, state, draft flag, base/head, author, created time, labels, optional body. `sourceUrl` is the created PR URL. |\n\nBranches:\n- `fill && (title || body !== undefined)` throws.\n- Non-empty `body` is written under a temp dir `gh-pr-body-*` in `os.tmpdir()`, passed as `--body-file`, then removed in `finally`.\n- After creation, the tool parses the returned URL and best-effort runs `gh pr view <number> --repo <repo> --json <GH_PR_FIELDS_NO_COMMENTS>`; failures there are swallowed.\n\n### `pr_checkout`\n\n| Aspect | Value |\n| --- | --- |\n| Required fields | `op` |\n| Optional fields | `repo`, `pr`, `force` |\n| `gh` command | For each requested PR: `gh pr view [<pr>] [--repo <repo>] --json <GH_PR_CHECKOUT_FIELDS>`; cross-repo PRs may also call `gh repo view <headRepository> --json <GH_REPO_CLONE_FIELDS>`. |\n| Batching | Yes. `pr` may be `string[]`; each PR is resolved in parallel, but git mutations are serialized per primary repo by `git.withRepoLock()`. |\n| Output | Single PR: checkout/worktree summary plus `details.repo`, `details.branch`, `details.worktreePath`, `details.remote`, `details.remoteBranch`, `details.checkouts`. Batched: `# <n> Pull Request Worktrees (...)` plus one section per PR and aggregated `details.checkouts`. |\n\nWorktree and metadata behavior:\n- Local branch name is always `pr-<number>`.\n- Worktree path is `path.join(getWorktreesDir(), encodeRepoPathForFilesystem(primaryRepoRoot), localBranch)`, where `getWorktreesDir()` is `~/.gjc/wt`; effective path is `~/.gjc/wt/<encoded-primary-repo-root>/pr-<number>`.\n- Existing worktree detection is by branch ref `refs/heads/pr-<number>` from `git.worktree.list()`.\n- New worktree creation calls `git.worktree.add(repoRoot, finalWorktreePath, localBranch, { signal })` after verifying the path is neither already registered nor already present on disk.\n- For same-repo PRs, remote is `origin`. For cross-repo PRs, the tool resolves a clone URL for the head repo, reuses an existing remote with the same URL when possible, or creates `fork-<owner>` / `fork-<owner>-<n>`.\n- The branch push metadata is persisted with `git config` under the repository's shared `.git/config` as:\n  - `branch.pr-<number>.remote`\n  - `branch.pr-<number>.merge`\n  - `branch.pr-<number>.pushRemote`\n  - `branch.pr-<number>.gjcPrHeadRef`\n  - `branch.pr-<number>.gjcPrUrl`\n  - `branch.pr-<number>.gjcPrIsCrossRepository`\n  - `branch.pr-<number>.gjcPrMaintainerCanModify`\n- If `refs/heads/pr-<number>` already exists at a different commit, checkout fails unless `force=true`, in which case `git branch --force` resets it to the fetched PR head.\n- If a matching worktree already exists, the tool reuses it and reports `reused: true`.\n\n### `pr_push`\n\n| Aspect | Value |\n| --- | --- |\n| Required fields | `op` |\n| Optional fields | `branch`, `forceWithLease` |\n| `gh` command | None. This path uses git, not `gh`. |\n| Batching | None |\n| Output | `# Pushed Pull Request Branch` summary with local branch, remote, remote branch, remote URL, PR URL, and force-with-lease flag. `sourceUrl = prUrl` when known. |\n\nPush target resolution reads the `branch.<name>.gjcPrHeadRef`, `pushRemote`/`remote`, `gjcPrUrl`, `gjcPrMaintainerCanModify`, and `gjcPrIsCrossRepository` git-config keys written by `pr_checkout`. If the current checked-out branch matches the target branch, the source ref is `HEAD`; otherwise it pushes `refs/heads/<branch>`. The refspec is `HEAD:refs/heads/<headRef>` or `refs/heads/<branch>:refs/heads/<headRef>`.\n\n### `search_issues`\n\n| Aspect | Value |\n| --- | --- |\n| Required fields | `op`, `query` |\n| Optional fields | `repo`, `limit` |\n| `gh` command | `gh api -X GET /search/issues -f q=\"<query> [repo:<repo>] is:issue\" -F per_page=<limit>` |\n| Batching | None |\n| Output | `# GitHub issues search`, echoed query, optional repo, result count, then one bullet per issue with repo/state/author/labels/timestamps/URL. |\n\n`repo` defaults to the current checkout's `owner/repo` via `resolveSearchRepoScope()` when omitted. The default is suppressed when the query already contains a leading `repo:`/`org:`/`user:`/`owner:` qualifier or when `gh repo view` fails to resolve the current checkout (e.g. outside a github remote).\n\n### `search_prs`\n\n| Aspect | Value |\n| --- | --- |\n| Required fields | `op`, `query` |\n| Optional fields | `repo`, `limit` |\n| `gh` command | `gh api -X GET /search/issues -f q=\"<query> [repo:<repo>] is:pr\" -F per_page=<limit>` |\n| Batching | None |\n| Output | Same shape as `search_issues`, labeled as pull requests. |\n\n`repo` defaults to the current checkout's `owner/repo` as in `search_issues`.\n\n### `search_code`\n\n| Aspect | Value |\n| --- | --- |\n| Required fields | `op`, `query` |\n| Optional fields | `repo`, `limit` |\n| `gh` command | `gh api -X GET /search/code -f q=\"<query> [repo:<repo>]\" -F per_page=<limit> -H \"Accept: application/vnd.github.text-match+json\"` |\n| Batching | None |\n| Output | `# GitHub code search`, result count, then one bullet per match with path, repo, short commit SHA, URL, and first normalized text-match fragment line when present. |\n\n`repo` defaults to the current checkout's `owner/repo` as in `search_issues`.\n\n### `search_commits`\n\n| Aspect | Value |\n| --- | --- |\n| Required fields | `op`, `query` |\n| Optional fields | `repo`, `limit` |\n| `gh` command | `gh api -X GET /search/commits -f q=\"<query> [repo:<repo>]\" -F per_page=<limit>` |\n| Batching | None |\n| Output | `# GitHub commits search`, result count, then one bullet per commit: short SHA + first commit-message line, repo, author, date, URL. |\n\n`repo` defaults to the current checkout's `owner/repo` as in `search_issues`.\n\n### `search_repos`\n\n| Aspect | Value |\n| --- | --- |\n| Required fields | `op`, `query` |\n| Optional fields | `limit` |\n| `gh` command | `gh api -X GET /search/repositories -f q=\"<query>\" -F per_page=<limit>` |\n| Batching | None |\n| Output | `# GitHub repositories search`, result count, then one bullet per repo with first description line, language, stars, forks, open issues, visibility, archive/fork flags, updated time, URL. |\n\n`repo` is intentionally not used for this op.\n\n### `run_watch`\n\n| Aspect | Value |\n| --- | --- |\n| Required fields | `op` |\n| Optional fields | `repo`, `branch`, `run`, `tail` |\n| `gh` command | Repo resolution: `gh repo view --json nameWithOwner -q .nameWithOwner` when `repo` and run URL repo are both absent. Single-run mode uses `gh api --method GET /repos/<repo>/actions/runs/<runId>` and `gh api --method GET /repos/<repo>/actions/runs/<runId>/jobs`. Commit mode uses `gh api --method GET /repos/<repo>/branches/<branch>`, `gh api --method GET /repos/<repo>/actions/runs`, `gh api --method GET /repos/<repo>/actions/runs/<runId>/jobs`, and `gh api /repos/<repo>/actions/jobs/<jobId>/logs` for failed jobs. |\n| Batching | Implicit batching only in commit mode: all workflow runs for one commit are tracked together. |\n| Output | Streaming watch snapshots via `onUpdate`, then a final text report. On failure, appends `Full failed-job logs: artifact://<id>` and sets `details.artifactId`. |\n\nWatch flow:\n- `run` parsing accepts either a decimal run ID or a full run URL. URL repo must match explicit `repo` when both are given.\n- Poll interval is fixed at 3 seconds (`RUN_WATCH_INTERVAL_DEFAULT`).\n- Failure grace period is fixed at 5 seconds (`RUN_WATCH_GRACE_DEFAULT`). When any failed job appears before completion, the tool emits a note, waits once, re-fetches state, then collects logs so concurrent failures are included.\n- Failed-job logs are fetched with `gh api /repos/<repo>/actions/jobs/<jobId>/logs` via `git.github.run()`, not `json()`. Non-zero exit leaves `available: false` instead of failing the whole watch.\n- Inline result includes only the last `tail` lines per failed job. The saved artifact contains full logs (`mode: \"full\"`).\n- In commit mode, success is intentionally double-checked: once all known runs are successful, the tool waits one more poll interval and succeeds only if the set of run IDs is unchanged. This avoids returning before late workflow runs appear for the same commit.\n- `details.watch` drives a specialized renderer in `packages/coding-agent/src/tools/gh-renderer.ts`; non-watch results fall back to generic text rendering.\n\n## Side Effects\n- Filesystem\n  - `pr_create` may create a temp dir under `os.tmpdir()` named `gh-pr-body-*`, write `body.md`, then remove the dir in `finally`.\n  - `pr_checkout` may create directories under `~/.gjc/wt/<encoded-primary-repo-root>/` and add git worktrees there.\n  - `run_watch` may write a session artifact with full failed-job logs.\n- Network\n  - Every op shells out to `gh`, which then talks to GitHub APIs except `pr_push`.\n  - `pr_push` uses git network transport to the configured remote.\n- Subprocesses / native bindings\n  - All `gh` calls use `Bun.spawn([\"gh\", ...args])`.\n  - `pr_checkout` and `pr_push` also invoke git helpers from `packages/coding-agent/src/utils/git.ts`.\n- Session state (transcript, memory, jobs, checkpoints, registries)\n  - `run_watch` consumes `session.allocateOutputArtifact()` when failed-job logs are persisted.\n  - Returned `details` objects carry run/checkouts metadata for the renderer/UI.\n- User-visible prompts / interactive UI\n  - `gh` interactive editor fallback is suppressed for `pr_create` by forcing either `--body-file` or `--body \"\"`.\n  - `gh-renderer` provides compact headers for all ops and a custom live watch view for `run_watch`.\n- Background work / cancellation\n  - `run_watch` loops until success/failure and uses `scheduler.wait()` between polls.\n  - `GithubTool.execute()` is wrapped in `untilAborted()`; `git.github.run()` forwards the abort signal into `Bun.spawn()`.\n\n## Limits & Caps\n- Search result default: `10` (`SEARCH_LIMIT_DEFAULT` in `packages/coding-agent/src/tools/gh.ts`).\n- Search result max: `50` (`SEARCH_LIMIT_MAX`).\n- PR file preview inside the `pr://` view: first `50` files only (`FILE_PREVIEW_LIMIT` in `gh.ts`).\n- Run-watch poll interval: `3s` (`RUN_WATCH_INTERVAL_DEFAULT`).\n- Run-watch failure grace period: `5s` (`RUN_WATCH_GRACE_DEFAULT`).\n- Run-watch failed-log tail default: `15` lines (`RUN_WATCH_TAIL_DEFAULT`).\n- Run-watch failed-log tail max: `200` lines (`RUN_WATCH_TAIL_MAX`).\n- PR review comments page size: `100` (`REVIEW_COMMENTS_PAGE_SIZE`).\n- Actions jobs page size: `100` (`RUN_JOBS_PAGE_SIZE`).\n- Search and tail numeric inputs are floored with `Math.floor()`, clamped to the max, and rejected when non-finite or `<= 0`.\n- `pr_checkout` batch fan-out is unbounded in tool code; all requested PRs are launched with `Promise.all()`.\n\n## Errors\n- Tool creation is skipped entirely when `gh` is not installed.\n- `git.github.run()` throws `ToolError(\"GitHub CLI (gh) is not installed...\")` if `gh` is missing at execution time.\n- `git.github.text/json()` map common failures to model-facing messages:\n  - not authenticated → `GitHub CLI is not authenticated. Run \\`gh auth login\\`.`\n  - missing repo context without explicit `repo` → `GitHub repository context is unavailable. Pass \\`repo\\` explicitly or run the tool inside a GitHub checkout.`\n  - otherwise stderr/stdout text, or fallback `GitHub CLI command failed: gh ...`\n- `json()` also throws on empty stdout or invalid JSON.\n- Local validation errors throw `ToolError`, including:\n  - missing required per-op fields (`query`, `title unless fill=true`)\n  - invalid numeric `limit` / `tail`\n  - invalid `run` format\n  - `fill` combined with `title` or `body`\n  - missing git repo / branch / HEAD context for checkout, push, or watch\n  - `pr_push` on a branch without `gjcPrHeadRef` metadata\n  - conflicting existing worktree path or branch without `force`\n- `run_watch` treats failed-job log fetches specially: missing log content does not fail the watch; it marks that log `available: false` and prints `Log tail unavailable.` / `Full log unavailable.`.\n- `pr_create` swallows only the post-create best-effort `gh pr view` refresh; the create step itself still fails normally.\n\n## Notes\n- `appendRepoFlag()` intentionally skips `--repo` when the identifier argument is already a full GitHub URL; that lets `gh` derive repo/number from the URL.\n- `normalizePrIdentifierList()` accepts `reviewer`, `assignee`, and `label` arrays too; the helper name is broader than its callers.\n- `pr_push` depends on `pr_checkout` having run first for that local branch; there is no alternate metadata source.\n- `pr_checkout` stores push metadata in branch config, not in the worktree directory. Reusing the same `pr-<number>` branch reuses those config keys.\n- Worktree write serialization is keyed by the primary repo root, not the current worktree path, because git worktrees share `.git/config`, `packed-refs`, commit-graph, and worktree metadata files.\n- `search_repos` is the only search op that never forwards `repo`; repository scoping must be expressed in the query itself.\n- `run_watch` success on commit mode means “all observed runs succeeded and no additional runs appeared one poll later”, not merely “latest poll looked green”.\n- The TUI renderer collapses failed log previews unless the result view is expanded; the underlying text result still contains the same tailed lines plus any artifact reference.\n",
 	"tools/irc.md": "# irc\n\n> Send short prose messages to other live agents in the current process.\n\n## Source\n- Entry: `packages/coding-agent/src/tools/irc.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/irc.md`\n- Key collaborators:\n  - `packages/coding-agent/src/registry/agent-registry.ts` — process-global live agent directory.\n  - `packages/coding-agent/src/session/agent-session.ts` — side-channel reply generation and history injection.\n  - `packages/coding-agent/src/prompts/system/irc-incoming.md` — no-tools auto-reply prompt.\n  - `packages/coding-agent/src/tools/index.ts` — tool availability gating.\n  - `packages/coding-agent/src/config/settings-schema.ts` — `irc.enabled` default.\n  - `packages/coding-agent/src/modes/controllers/event-controller.ts` — renders IRC events into chat UI.\n  - `packages/coding-agent/src/modes/utils/ui-helpers.ts` — formats `[IRC]` transcript lines.\n  - `packages/coding-agent/src/task/executor.ts` — carries `irc.enabled` into subagents.\n\n## Inputs\n\n### `op: \"list\"`\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `op` | `\"list\"` | Yes | Lists peers visible to the caller. |\n\n### `op: \"send\"`\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `op` | `\"send\"` | Yes | Sends one message to one peer or to `\"all\"`. |\n| `to` | `string` | Yes | Peer id such as `0-Main`, or `\"all\"` for broadcast. Whitespace is trimmed. |\n| `message` | `string` | Yes | Message body. Whitespace is trimmed; empty-after-trim is rejected. |\n| `awaitReply` | `boolean` | No | Wait for prose replies. Defaults to `true` for direct messages and `false` for `to: \"all\"`. |\n\n## Outputs\n- Single-shot `AgentToolResult`; no streaming updates.\n- `content` is one text block.\n  - `list` returns either `No other live agents.` or a bullet list headed by `<n> peer(s):`.\n  - `send` returns delivery summary text, then optional `## Replies`, `## Failed`, and `Unknown / unavailable peers:` sections.\n- `details` is structured metadata:\n  - `list`: `{ op, from, peers, channels }`\n  - `send`: `{ op, from, to, delivered, replies?, failed?, notFound? }`\n- The tool does not return raw IRC frames, message ids, or a transcript object.\n\n## Flow\n1. `IrcTool.createIf` only constructs the tool when `irc.enabled` is on and the session has both an `AgentRegistry` and `getAgentId` (`packages/coding-agent/src/tools/irc.ts`).\n2. Tool discovery adds another gate in `packages/coding-agent/src/tools/index.ts`: if the caller is `0-Main` and `async.enabled` is off, `irc` is hidden because the main agent cannot talk to concurrent peers in sync mode.\n3. `execute` resolves the process-global registry and sender id. Missing either returns a text error result instead of throwing.\n4. `op: \"list\"` calls `registry.listVisibleTo(senderId)`, which exposes every other agent in flat namespace whose status is `running` or `idle` (`packages/coding-agent/src/registry/agent-registry.ts`).\n5. `list` formats human-readable lines and returns `channels` as `['all', ...peerIds]`. These are logical targets only; there is no channel join state.\n6. `op: \"send\"` trims `to` and `message`; missing values produce text errors.\n7. `send` resolves targets:\n   - `to === \"all\"`: all visible peers.\n   - otherwise: one exact registry id, excluding self and excluding peers not in `running`/`idle`.\n8. `send` chooses `awaitReply = params.awaitReply ?? !isBroadcast`.\n9. Each target is dispatched in parallel via `target.session.respondAsBackground(...)`. One slow or failing peer does not block dispatch to the others.\n10. `respondAsBackground` accepts each delivery into the recipient's volatile current-session exchange queue before observing it in the recipient or main UI, and before reporting sender delivery success:\n    - `awaitReply === false`: accepts/queues the incoming message, then emits its `irc_message` event and forwards the display-only relay to the main session UI.\n    - `awaitReply === true`: renders `packages/coding-agent/src/prompts/system/irc-incoming.md` and runs `runEphemeralTurn` with `toolChoice: \"none\"`. After a reply succeeds, it constructs and accepts/queues the ordered incoming + auto-reply pair, commits its IRC roster claim, then emits both `irc_message` events and forwards both display-only relays. A failed or aborted reply turn accepts and surfaces nothing.\n11. Deferred injection waits until the recipient is no longer streaming; `#flushPendingBackgroundExchanges` appends accepted custom messages through normal `message_start`/`message_end` external events so persistence and listeners see them.\n12. `send` aggregates `delivered`, `replies`, `failed`, and `notFound`, then returns one text summary plus matching `details`.\n\n## Modes / Variants\n- `list`: enumerate visible peers and logical channels.\n- `send` direct message: one exact peer id, default synchronous auto-reply.\n- `send` broadcast: `to: \"all\"`, default fire-and-forget (`awaitReply: false`) to every visible peer.\n- `send` with `awaitReply: false`: recipient records the incoming message but does not generate a reply.\n- `send` with `awaitReply: true`: recipient performs a no-tools ephemeral LLM turn and returns prose.\n\n## Side Effects\n- Session state\n  - Reads from the process-global `AgentRegistry`.\n  - Accepts each IRC delivery into a process-local, volatile recipient exchange queue before recipient/main observations and sender success. This acceptance is not durable delivery.\n  - Emits `irc_message` session events on recipient sessions after acceptance.\n  - Flushes accepted IRC custom messages into recipient history after the current stream finishes.\n  - For non-main recipients, forwards display-only relay observations into the main session UI after acceptance; these relays are not persisted to the main agent history. Observer failures are isolated from accepted delivery.\n  - Subagents inherit `irc.enabled` from task executor settings.\n- User-visible prompts / interactive UI\n  - IRC events render as `[IRC]` transcript lines in the TUI.\n  - Auto-replies are generated from `packages/coding-agent/src/prompts/system/irc-incoming.md` and explicitly forbid tool use.\n- Background work / cancellation\n  - `send` starts one background `respondAsBackground` call per target.\n  - The caller's `AbortSignal` is forwarded into each background reply turn.\n- Network\n  - No IRC server connection.\n  - When `awaitReply: true`, the recipient may make model-provider API calls through `runEphemeralTurn`.\n- Filesystem\n  - No direct filesystem writes in the tool itself.\n\n## Limits & Caps\n- Availability gates:\n  - `irc.enabled` defaults to `true` in `packages/coding-agent/src/config/settings-schema.ts`.\n  - Main agent tool discovery suppresses `irc` when `async.enabled` is off (`packages/coding-agent/src/tools/index.ts`).\n- Visibility scope: only peers in status `running` or `idle` are addressable via `listVisibleTo`.\n- Reply execution:\n  - No tools are available in auto-reply turns (`toolChoice: \"none\"` in `runEphemeralTurn`).\n  - No internal timeout, retry, backoff, rate limit, or reply length cap is defined in `irc.ts`; behavior relies on the underlying model stream and any upstream API limits.\n- Flush scheduling: deferred history injection polls every `50` ms while the recipient is still streaming (`#scheduleBackgroundExchangeFlush` in `packages/coding-agent/src/session/agent-session.ts`).\n\n## Errors\n- The tool returns text errors, not thrown exceptions, for:\n  - missing registry: `IRC is unavailable in this session.`\n  - missing sender id: `IRC is unavailable: caller has no agent id.`\n  - missing `to`: `` `to` is required for op=\"send\". ``\n  - missing `message`: `` `message` is required for op=\"send\". ``\n  - unknown op: `Unknown irc op.`\n- Unknown, self-addressed, non-running, and non-idle direct targets are reported under `details.notFound` and in the text footer `Unknown / unavailable peers:`.\n- If a target has no attached session, it is treated as not found.\n- Exceptions from reply generation before awaited-exchange acceptance are caught per-target and surfaced under `details.failed` as `{ id, error }`; other recipients still complete. A provider failure or sender abort therefore emits no `irc_message` observations and accepts no recipient exchange. Recipient/main observer failures after acceptance are isolated and do not turn a delivered exchange into a sender failure.\n- If no target succeeds, `send` still returns normally with `No recipients received the message.` and optional `failed`/`notFound` metadata.\n\n## Notes\n- This is IRC-like naming only. There are no servers, sockets, nick registration, auth handshakes, channels beyond `all`, or commands such as join/part/topic.\n- Addressing is by exact agent id from the registry; there is no fuzzy lookup or aliasing.\n- `channels` in `list` is synthetic output: `all` plus visible peer ids. Nothing is persisted across calls as channel membership.\n- Recipient history, not sender history, receives accepted IRC custom messages when the recipient flushes its current-session queue. Acceptance is process-local and volatile: it does not promise durable storage, fsync, recovery, deduplication, or replay across process loss.\n- The main UI may show IRC relays for conversations it was not part of, but those relay records are explicitly display-only.\n- Because reply generation snapshots in-flight assistant text, a recipient can answer based on partially streamed context.\n- Direct self-messaging is rejected by resolving the target as unavailable.\n\n## Sidebar\n\n- `irc.sidebar.enabled` defaults to `true`: the read-only sidebar is available when `irc.enabled` is also enabled, but starts closed. `app.irc.sidebar.toggle` (default `Alt+I`, remappable) opens or hides it.\n- The sidebar retains the active runtime UI session's IRC observations only. It is not written to disk or restored into another session. Each arrival decides its inline lifetime once: arrivals while the panel is visible expire 10 seconds after observation; arrivals while it is closed persist inline. Later toggles do not change that decision.\n- An eligible first live inline arrival while the sidebar is closed shows a one-time hint using the resolved toggle key (for example, `Alt+I opens sidebar`). Rebuilds do not show or consume this hint.\n- When open, the transcript/sidebar split targets 70:30. The sidebar keeps a 30-column minimum only while the transcript can retain at least half the usable width; below that boundary the sidebar yields completely and the transcript renders full width. Retained sidebar messages are Discord-style blocks: `sender → recipient · HH:mm`, followed by the retained body with a two-column indent and one blank row between messages. Sender and recipient display fields are normalized and bounded to 256 UTF-8 bytes at complete grapheme boundaries.\n- The sidebar retains at most 10,000 observations and 16 MiB of UTF-8 message payload per runtime UI session, evicting the oldest observations first. An individual observation larger than the 16 MiB budget is omitted rather than truncated or admitted by evicting the rest of the backlog. Replay suppression tracks at most 100,000 unique observation identities and then fails closed for unseen arrivals until the runtime UI instance ends, preventing forgotten identities from resurrecting across eviction or fork cleanup while keeping memory bounded. Both inline transcript and sidebar body rendering independently materialize at most 2,048 rows from a bounded 64 KiB UTF-8 source projection, preferring recent retained content and showing explicit message/backlog elision markers when necessary. The bounded, runtime-only, read-only backlog does not affect welcome-screen row reservation, which counts transcript rows only.\n- While the sidebar is visible, Kitty terminals keep rendering real images in the transcript (Kitty placements are cursor-neutral and compose safely with the split). Cursor-advancing protocols — iTerm2 inline images and raw SIXEL sequences — are represented by compact text placeholders so they cannot corrupt the split. Hiding the sidebar restores normal rendering for every protocol.\n- A successful `/fork` starts a new logical UI session: it clears the sidebar ledger, hides the panel, and resets roster-delivery state. Failed or cancelled forks preserve the current runtime sidebar state.\n\n## Hidden peer roster reminders\n\nWhen the live peer roster changes, an eligible model turn receives one hidden single-line reminder listing stable agent ids and roster labels. The initial empty roster produces no reminder; a later transition to empty does. Running/idle status changes alone do not count as a roster change.\n\nNormal turns commit an atomic roster claim on successful completion. Awaited IRC auto-replies defer that commit until their incoming + auto-reply exchange is accepted; failed or aborted reply turns release the claim for a later retry. Isolated `/btw` turns do not acquire or commit roster claims. These reminders are context-only and never appear in the transcript or persisted history.",
@@ -142,9 +143,9 @@ export const EMBEDDED_DOCS: Readonly<Record<string, string>> = {
 	"tools/search.md": "# search\n\n> Search file contents with a regex across files, directories, globs, and internal URLs.\n\n## Source\n- Entry: `packages/coding-agent/src/tools/search.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/search.md`\n- Key collaborators:\n  - `packages/coding-agent/src/tools/match-line-format.ts` — model-facing anchor formatting.\n  - `packages/coding-agent/src/tools/path-utils.ts` — path normalization, glob splitting, internal URL resolution.\n  - `packages/coding-agent/src/tools/file-recorder.ts` — file ordering for grouped output.\n  - `packages/coding-agent/src/tools/grouped-file-output.ts` — grouped per-file text layout.\n  - `packages/coding-agent/src/session/streaming-output.ts` — line truncation and final byte truncation.\n  - `packages/coding-agent/src/config/settings-schema.ts` — default context lines.\n  - `packages/natives/native/index.d.ts` — native `grep()` types exposed to TS.\n  - `crates/pi-natives/src/grep.rs` — native regex/file search implementation.\n  - `docs/natives-text-search-pipeline.md` — native search pipeline overview.\n\n## Inputs\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `pattern` | `string` | Yes | Regex pattern. `search.ts` trims it and rejects empty input. The native matcher enables multiline only when the pattern text contains a literal newline or the two-character sequence `\\\\n`. The model prompt explicitly documents literal-brace escaping such as ``interface\\\\{\\\\}``, although the native layer also auto-escapes braces that cannot be valid repetition quantifiers. |\n| `paths` | `string[]` | Yes | One or more file paths, directory paths, glob-like paths, or internal URLs. Empty strings are rejected after trimming/quote stripping. Internal URLs must resolve to a backing file and cannot contain glob characters. |\n| `i` | `boolean` | No | Case-insensitive search. Defaults to `false`. Passed to native `ignoreCase`. |\n| `gitignore` | `boolean` | No | Respect `.gitignore` during directory scans. Defaults to `true`. Passed to native `gitignore`. |\n| `skip` | `number` | No | Global match offset. Defaults to `0`. `search.ts` floors finite numbers and rejects negative or non-finite values. |\n\n## Outputs\nThe tool returns a single text block in `content[0].text` plus structured `details`.\n\n- Match lines are formatted by `formatMatchLine()` as `*<anchor>|<line>` for matches and ` <anchor>|<line>` for context.\n  - Hashline mode: `*5th|content`, ` 9x}|content`.\n  - Plain mode: `*5|content`, ` 9|content`.\n- Directory results are grouped by file, with `# <path>` headings and blank lines between groups.\n- `details` may include:\n  - `scopePath` — formatted search scope.\n  - `matchCount`, `fileCount`, `files`, `fileMatches` — counts for the returned page, not necessarily total corpus counts.\n  - `matchLimitReached` — visible-page limit hit (`100`).\n  - `resultLimitReached` — native preselection limit hit (`500`).\n  - `linesTruncated` — one or more matched lines were shortened to `1024` chars plus `…`.\n  - `truncated` and `meta.truncation` — final text output was head-truncated by `truncateHead()`.\n  - `displayContent` — TUI-only rendering text with `│` gutters instead of model anchors.\n  - `missingPaths` — multi-path entries skipped because their base path did not exist.\n- No-match result text is `No matches found`, optionally followed by `Skipped missing paths: ...`.\n\n## Flow\n1. `SearchTool.execute()` validates and normalizes input in `packages/coding-agent/src/tools/search.ts`:\n   - trims `pattern`, rejects empty patterns;\n   - normalizes `skip` to a non-negative integer;\n   - reads `search.contextBefore` and `search.contextAfter` from session settings (`1` and `3` by default);\n   - enables multiline only when `pattern` contains `\\n` or an actual newline.\n2. Each `paths` entry is normalized with `normalizePathLikeInput()`.\n3. Internal URLs are resolved through `session.internalRouter`:\n   - glob metacharacters (`*`, `?`, `[`, `{`) are rejected for internal URLs;\n   - URLs without `resource.sourcePath` fail;\n   - immutable sources are tracked so output can suppress editable hashline anchors per file.\n4. For multi-path calls, `partitionExistingPaths()` skips only ENOENT entries. If every entry is missing, the tool errors.\n5. Path resolution branches:\n   - one entry: `parseSearchPath()` splits `basePath` and optional glob;\n   - multiple entries: `resolveExplicitSearchPaths()` computes a common base directory, brace-union glob, exact-file list, or degenerate-root target list.\n6. `search.ts` stats the resolved base path to decide file vs directory behavior.\n7. It calls native `grep()` from `@gajae-code/natives` with:\n   - `pattern`, `ignoreCase`, `multiline`, `gitignore`;\n   - `hidden: true`;\n   - `cache: false`;\n   - `contextBefore` / `contextAfter` from settings;\n   - `maxColumns: 1024`;\n   - `mode: content`.\n8. Native execution happens in `crates/pi-natives/src/grep.rs`:\n   - `build_matcher()` sanitizes non-quantifier braces before regex compile;\n   - if compile fails with unopened/unclosed-group errors, it retries after escaping previously unescaped parentheses;\n   - directory scans use the grep pipeline described in `docs/natives-text-search-pipeline.md`.\n9. Search dispatch differs by resolved path set:\n   - exact explicit files or degenerate-root multi-targets: JS loops over targets and merges `grep()` results itself;\n   - single file/directory base: one `grep()` call handles offset/limit natively.\n10. JS output shaping then:\n   - round-robins directory matches down to `100` visible matches so one file does not monopolize the page;\n   - keeps the first `100` file matches for single-file searches;\n   - formats lines through `formatMatchLine()` for the model and `formatCodeFrameLine()` for TUI;\n   - records non-truncated matched/context lines into the session file-read cache with `recordSparse()`.\n11. Final text is passed through `truncateHead(rawOutput, { maxLines: Number.MAX_SAFE_INTEGER })`, so the effective cap is the default byte cap from `streaming-output.ts`, not the default line cap.\n12. `toolResult()` attaches text plus limit/truncation metadata.\n\n## Modes / Variants\n1. **Single file path**\n   - `grep()` searches one file.\n   - Output is a flat list of match/context lines.\n   - Visible limit is the first `100` matches after native offset handling.\n2. **Single directory path or single glob-like path**\n   - `parseSearchPath()` may split the input into `path` + `glob`.\n   - One native `grep()` scans the directory tree with `gitignore` and `hidden:true`.\n   - Native `offset` handles `skip` globally across files.\n   - JS round-robins the returned matches to `100` visible rows.\n3. **Multiple explicit paths/globs**\n   - `resolveExplicitSearchPaths()` collapses them into a common base and either a brace-union glob, an explicit file list, or per-target searches when the only common base is the filesystem root.\n   - Missing entries are skipped non-fatally unless all are missing.\n4. **Internal URL paths**\n   - Supported only when the internal resource resolves to a real backing file.\n   - No internal-URL globbing.\n   - Immutable sources switch to the immutable display mode when formatting anchors.\n\n## Side Effects\n- Filesystem\n  - Stats resolved search roots and input paths.\n  - Reads matched files through native `grep()`.\n  - Records sparse matched/context lines into the session file-read cache via `getFileReadCache(...).recordSparse(...)`.\n- Session state (transcript, memory, jobs, checkpoints, registries)\n  - Reads session settings for context defaults.\n  - Uses `session.internalRouter` to resolve internal URLs.\n  - Populates tool `details.meta` with truncation/limit metadata.\n- Background work / cancellation\n  - Wrapped in `untilAborted(signal, ...)` at the JS level.\n  - `search.ts` does not pass `signal` or `timeoutMs` into native `grep()`, so native grep cancellation/timeouts are not used by this tool.\n\n## Limits & Caps\n- Visible page limit: `100` matches (`DEFAULT_MATCH_LIMIT` in `packages/coding-agent/src/tools/search.ts`).\n- Native preselection limit: `500` matches (`internalLimit = Math.min(DEFAULT_MATCH_LIMIT * 5, 2000)` in `packages/coding-agent/src/tools/search.ts`).\n- Line truncation: `1024` characters per emitted line (`DEFAULT_MAX_COLUMN` in `packages/coding-agent/src/session/streaming-output.ts`). Native grep marks truncated lines; JS reports `linesTruncated`.\n- Final text truncation: `truncateHead()` default byte cap `50 * 1024` bytes (`DEFAULT_MAX_BYTES` in `packages/coding-agent/src/session/streaming-output.ts`). `search.ts` overrides `maxLines` to `Number.MAX_SAFE_INTEGER`, so normal search output is byte-capped, not line-capped.\n- Context defaults: `search.contextBefore = 1`, `search.contextAfter = 3` in `packages/coding-agent/src/config/settings-schema.ts`.\n- Pagination: `skip` is a global match offset. In single-base searches it is pushed into native `offset`; in exact-file/multi-target aggregation it is applied in JS with `matches.slice(skip)`.\n- Native directory-scan cache: available in `grep.rs`, but this tool always sets `cache: false`.\n\n## Errors\n- `Pattern must not be empty` when trimmed `pattern` is empty.\n- `Skip must be a non-negative number` for negative or non-finite `skip`.\n- `` `paths` must contain non-empty paths or globs `` when any normalized path is empty.\n- `Glob patterns are not supported for internal URLs: ...` for internal URL + glob metacharacters.\n- `Cannot search internal URL without a backing file: ...` when the router resolves a virtual resource without `sourcePath`.\n- `Path not found: ...` when the resolved base path is missing, or when every multi-path entry is missing.\n- Regex compile failures bubble from native `grep()` as tool errors. `search.ts` has a special catch for messages beginning with `regex parse error`, then otherwise rethrows.\n- Multi-file native scans skip per-file open/search failures inside `grep.rs`; the scan continues with surviving files.\n\n## Notes\n- The model-facing prompt documents standard regex syntax plus two search-specific rules: escape literal braces, and use `\\n` or a literal newline for cross-line matching.\n- Native `build_matcher()` already auto-escapes braces that cannot be valid quantifiers, so patterns like `${platform}` become searchable instead of failing. Valid quantifiers like `a{2,4}` remain unchanged.\n- Native compile retry also escapes unescaped literal parentheses only after an unopened/unclosed-group parse error. It is a fallback, not a general parser mode.\n- Internal URLs are resolved before path existence checks. After resolution, the native layer sees ordinary filesystem paths.\n- `hidden:true` is hard-coded in `search.ts`; there is no model-facing flag to exclude dotfiles.\n- `gitignore:false` only affects native directory traversal. It does not disable the tool's own path normalization or explicit-file handling.\n- When `paths` resolves to multiple exact files, `search.ts` does not apply the native `500` match cap and reports `totalMatches` internally as the post-skip length for that branch.\n- The anchor suffix in hashline mode comes from `computeLineHash()` in `packages/coding-agent/src/hashline/hash.ts`; `search` itself only formats it.\n",
 	"tools/search_tool_bm25.md": "# search_tool_bm25\n\n> Search the hidden tool-discovery index and activate the top matches for the current session.\n\n## Source\n- Entry: `packages/coding-agent/src/tools/search-tool-bm25.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/search-tool-bm25.md`\n- Key collaborators:\n  - `packages/coding-agent/src/tool-discovery/tool-index.ts` — discoverable-tool metadata and BM25 index/search.\n  - `packages/coding-agent/src/session/agent-session.ts` — session discovery mode, corpus assembly, activation, cache invalidation.\n  - `packages/coding-agent/src/sdk/session.ts` — initial hiding of discoverable built-ins and prompt-time discoverable summary.\n  - `packages/coding-agent/src/tools/index.ts` — tool-session discovery hooks, essential/discoverable load modes, registry wiring.\n  - `packages/coding-agent/src/config/settings-schema.ts` — `tools.discoveryMode` and legacy `mcp.discoveryMode` settings.\n\n## Inputs\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `query` | `string` | Yes | Natural-language or keyword query. Trimmed before search; empty-after-trim is rejected. |\n| `limit` | `integer` | No | Max matches to return and activate. Minimum `1`. Defaults to `8` (`DEFAULT_LIMIT`). |\n\n## Outputs\n- Single-shot `AgentToolResult`.\n- Model-visible `content` is one text part containing JSON with:\n\n```json\n{\"query\":\"...\",\"activated_tools\":[\"...\"],\"match_count\":2,\"total_tools\":17}\n```\n\n- Runtime-only `details` carries the ranked matches used by the TUI renderer:\n  - `query`, `limit`, `total_tools`\n  - `activated_tools`: tool names activated by this call\n  - `active_selected_tools`: cumulative discovered-tool selections still active\n  - `tools`: array of match objects with\n    - `name`\n    - `label`\n    - `description` (`tool.summary`; this is the only snippet-like field)\n    - optional `server_name`\n    - optional `mcp_tool_name`\n    - `schema_keys`\n    - `score` rounded to 6 decimals\n- The renderer shows a status line plus up to 5 collapsed tree items by default (`COLLAPSED_MATCH_LIMIT`), each with label, optional server name, score to 3 decimals, and truncated description. The ranked match list is not serialized into `content`.\n\n## Flow\n1. `SearchToolBm25Tool.createIf()` in `packages/coding-agent/src/tools/search-tool-bm25.ts` exposes the tool only when `tools.discoveryMode !== \"off\"` and the session implements discovery hooks.\n2. `description` is rendered once from `packages/coding-agent/src/prompts/tools/search-tool-bm25.md` via zero-argument `renderSearchToolBm25Description()` and remains static across discovery activations.\n3. `execute()` re-checks capability and settings:\n   - missing discovery hooks -> `ToolError(\"Tool discovery is unavailable in this session.\")`\n   - discovery disabled -> `ToolError(\"Tool discovery is disabled. Enable tools.discoveryMode or mcp.discoveryMode to use search_tool_bm25.\")`\n4. `query` is trimmed and validated; `limit` is defaulted/validated.\n5. `getDiscoverableToolSearchIndexForExecution()` fetches the cached generic search index from the session when available, otherwise rebuilds an index from the current discoverable-tool list.\n6. `getSelectedToolNames()` reads the current discovered selections so already-selected tools can be excluded from fresh results.\n7. `searchDiscoverableTools()` in `packages/coding-agent/src/tool-discovery/tool-index.ts` tokenizes the query, scores every document with BM25, sorts by descending score then `tool.name`, and returns up to `searchIndex.documents.length` results; `execute()` then filters already-selected names and slices to `limit`.\n8. If any matches remain, `activateTools()` activates all matched tool names through `session.activateDiscoveredTools()`.\n9. `details` is assembled from the activated names, current selected names, corpus size, and formatted matches; `content` is reduced to the compact JSON summary from `buildSearchToolBm25Content()`.\n10. `searchToolBm25Renderer` renders either:\n   - the structured `details` view, or\n   - a fallback text-only warning block if `details` is absent.\n\n## Modes / Variants\n- Discovery-mode gating:\n  - `tools.discoveryMode = \"all\"`: searches hidden discoverable built-ins.\n- Search-index source:\n  - generic cached discoverable index from the session\n  - rebuilt ad hoc from the current discoverable-tool list when no cached generic index is available\n- Activation backend: generic `activateDiscoveredTools()`\n\n## Side Effects\n- Session state\n  - Adds matched tools to the active session tool set through `activateDiscoveredTools()`.\n  - Updates discovered-tool selection state so repeated searches accumulate selections instead of replacing them.\n  - Invalidates the cached discoverable search index when newly activated built-ins change the hidden corpus (`packages/coding-agent/src/session/agent-session.ts`).\n  - Tool availability changes before the next model call in the same turn; the prompt text says this explicitly.\n- User-visible prompts / interactive UI\n  - The tool description includes discoverable server summaries and total discoverable-tool count.\n  - The TUI renderer shows ranked matches, but the model-visible text summary does not.\n\n## Limits & Caps\n- Default result cap: `8` (`DEFAULT_LIMIT` in `packages/coding-agent/src/tools/search-tool-bm25.ts`).\n- `limit` must be a positive integer; no tool-level upper bound beyond corpus size.\n- Renderer collapsed list cap: `5` (`COLLAPSED_MATCH_LIMIT`).\n- Renderer truncation widths:\n  - label: `72` chars (`MATCH_LABEL_LEN`)\n  - description: `96` chars (`MATCH_DESCRIPTION_LEN`)\n- BM25 parameters in `packages/coding-agent/src/tool-discovery/tool-index.ts`:\n  - `BM25_K1 = 1.2`\n  - `BM25_B = 0.75`\n- Weighted corpus fields (`FIELD_WEIGHTS`):\n  - `name`: `6`\n  - `label`: `4`\n  - `mcpToolName`: `4`\n  - `serverName`: `2`\n  - `summary`: `2`\n  - each `schemaKey`: `1`\n- Summary fallback length for discoverable metadata: first `200` chars of `description` when no explicit summary exists (`getDiscoverableTool()` in `packages/coding-agent/src/tool-discovery/tool-index.ts`).\n\n## Errors\n- `execute()` throws `ToolError` for unavailable discovery hooks, disabled discovery mode, empty trimmed query, and non-positive/non-integer `limit`.\n- `searchDiscoverableTools()` throws `Error(\"Query must contain at least one letter or number.\")` if tokenization produces no alphanumeric tokens; `execute()` catches `Error` and rethrows `ToolError(error.message)`.\n- Empty corpus is not an error; search returns `[]`, activation is skipped, and the renderer message becomes either `No discoverable tools are currently loaded.` or `No matching tools found.`\n- `getDiscoverableToolsForDescription()` and `getDiscoverableToolSearchIndexForExecution()` swallow discovery-hook/cache errors and fall back to an empty corpus or rebuilt index.\n\n## Notes\n- The tool wire name stays `search_tool_bm25` for persisted-session back-compat, even though the source file is `search-tool-bm25.ts`.\n- Corpus composition is session-dependent and excludes already-active tools:\n  - Built-in entries appear only in `\"all\"` mode and only for registry tools whose `loadMode === \"discoverable\"` and are not currently active.\n  - Hidden/internal built-ins are intentionally excluded from the built-in corpus: `resolve`, `yield`, `report_finding`, `report_tool_issue` are called out in the `#collectDiscoverableBuiltinTools()` comment.\n- `AgentSession.getDiscoverableTools()` currently assembles built-in discoverable tools.\n- On startup, `packages/coding-agent/src/sdk/session.ts` hides non-essential discoverable built-ins in `tools.discoveryMode = \"all\"`; defaults are `read`, `bash`, `edit`, `write`, `search`, and `find` unless `tools.essentialOverride` changes them.\n- Query tokenization is simple and deterministic: camelCase is split, non-alphanumerics become spaces, tokens are lowercased, and only non-empty alphanumeric tokens survive.\n- Scores are rounded differently by surface: `details.tools[].score` keeps 6 decimals; the TUI line renders 3.\n",
 	"tools/ssh.md": "# ssh\n\n> Execute one remote command on a discovered SSH host.\n\n## Source\n- Entry: `packages/coding-agent/src/tools/ssh.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/ssh.md`\n- Key collaborators:\n  - `packages/coding-agent/src/ssh/ssh-executor.ts` — runs `ssh`, captures output\n  - `packages/coding-agent/src/ssh/connection-manager.ts` — master-connection reuse, host probing\n  - `packages/coding-agent/src/ssh/sshfs-mount.ts` — optional `sshfs` mount side effect\n  - `packages/coding-agent/src/discovery/ssh.ts` — discovers host configs\n  - `packages/coding-agent/src/capability/ssh.ts` — canonical host shape\n  - `packages/coding-agent/src/session/streaming-output.ts` — tail streaming, truncation, artifacts\n  - `packages/coding-agent/src/tools/tool-timeouts.ts` — timeout clamp rules\n  - `packages/utils/src/dirs.ts` — user/project ssh config paths\n\n## Inputs\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `host` | `string` | Yes | Host name key from discovered SSH config entries, not an arbitrary hostname/IP. |\n| `command` | `string` | Yes | Remote command string passed to `ssh` as the remote command. |\n| `cwd` | `string` | No | Remote working directory. The tool prepends a shell-specific `cd`/`Set-Location` wrapper. |\n| `timeout` | `number` | No | Timeout in seconds. Default `60`; clamped to `1..3600`. |\n\n## Outputs\nThe tool returns a standard text tool result built in `packages/coding-agent/src/tools/ssh.ts`:\n\n- `content`: one text block containing combined remote stdout+stderr, or `\"(no output)\"` when empty.\n- `details.meta.truncation`: present when output exceeded the in-memory tail window; derived from the executor summary.\n\nStreaming behavior:\n\n- While the command runs, `onUpdate` receives tail-only text snapshots built from `TailBuffer` in `packages/coding-agent/src/session/streaming-output.ts`.\n- Final output is single-shot after process exit.\n\nSide-channel artifacts:\n\n- When session artifact allocation is available and output exceeds the spill threshold, full output is written to a session artifact file and the returned summary carries its `artifactId` internally.\n- The ssh tool itself does not print the `artifact://...` URI into the result text.\n\nFailure behavior:\n\n- Unknown host, missing host config, timeout, cancellation, SSH startup failure, key validation failure, or non-zero remote exit all surface as thrown `ToolError`s.\n- Non-zero remote exit includes captured output plus `Command exited with code N`.\n\n## Flow\n1. `loadSshTool()` in `packages/coding-agent/src/tools/ssh.ts` calls `loadCapability(sshCapability.id, { cwd: session.cwd })` to discover hosts.\n2. `packages/coding-agent/src/discovery/ssh.ts` loads host entries from, in this order: project managed ssh config, user managed ssh config, `ssh.json` in the repo root, `.ssh.json` in the repo root.\n3. `getSSHConfigPath(\"project\")` and `getSSHConfigPath(\"user\")` in `packages/utils/src/dirs.ts` resolve those managed files to `.gjc/ssh.json` in the project and `~/.gjc/agent/ssh.json` in the user config dir. This tool does not read `~/.ssh/config`.\n4. Capability loading deduplicates by host name with first item winning; provider order is priority-sorted and the SSH JSON provider registers at priority `5`.\n5. `loadHosts()` in `packages/coding-agent/src/tools/ssh.ts` builds `hostsByName` and drops later duplicates again with `if (!hostsByName.has(host.name))`.\n6. Tool description text is built from `packages/coding-agent/src/prompts/tools/ssh.md` plus an `Available hosts:` list. Each host entry calls `getHostInfoForHost()` to show detected shell/OS when cached; otherwise it renders `detecting...`.\n7. On execute, `SshTool.execute()` rejects any `host` not in the discovered host-name set.\n8. `ensureHostInfo()` in `packages/coding-agent/src/ssh/connection-manager.ts` ensures an SSH master connection exists, loads cached host info from disk if present, and probes remote OS/shell when cache is missing or stale.\n9. `buildRemoteCommand()` in `packages/coding-agent/src/tools/ssh.ts` prepends a cwd change when `cwd` is provided:\n   - Unix-like or Windows compat shells: `cd -- '<cwd>' && <command>`\n   - Windows PowerShell: `Set-Location -Path '<cwd>'; <command>`\n   - Windows cmd: `cd /d \"<cwd>\" && <command>`\n10. `clampTimeout(\"ssh\", rawTimeout)` applies the `1..3600` second clamp from `packages/coding-agent/src/tools/tool-timeouts.ts`.\n11. `executeSSH()` in `packages/coding-agent/src/ssh/ssh-executor.ts` calls `ensureConnection(host)` again, opportunistically mounts the remote host root with `sshfs` if available, optionally wraps the command in `bash -c` or `sh -c` for Windows compat mode, then spawns `ssh` with `ptree.spawn`.\n12. Output from both stdout and stderr is piped into one `OutputSink`; chunks are sanitized and forwarded to streaming updates through `streamTailUpdates()`.\n13. On normal exit, the sink returns combined output plus truncation counters. On timeout or abort, `executeSSH()` returns `cancelled: true` and prefixes the output with a notice line such as `[SSH: ...]` or `[Command aborted: ...]`.\n14. `SshTool.execute()` converts `cancelled: true` into `ToolError`, converts non-zero exit codes into `ToolError`, otherwise returns the text result with truncation metadata.\n\n## Modes / Variants\n- **Tool unavailable**: `loadSshTool()` returns `null` when discovery finds no hosts, so the tool is not registered for that session.\n- **Unix-like target**: remote command is passed through directly, with optional `cd -- ... &&` prefix.\n- **Windows native shell**: cwd wrapper uses PowerShell `Set-Location` or cmd `cd /d`; command otherwise runs in the remote default Windows shell.\n- **Windows compat shell**: if host probing finds `bash` or `sh` on Windows, `executeSSH()` wraps the remote command as `bash -c '...'` or `sh -c '...'`. Host config can force compat on/off with `compat`.\n- **Cached vs probed host info**: shell/OS detection comes from in-memory cache, persisted JSON under the remote-host dir, or a fresh probe over SSH.\n- **Truncated vs untruncated output**: small output stays in memory; large output keeps only the last 50 KiB in memory and may spill full output to an artifact file.\n\n## Side Effects\n- Filesystem\n  - Reads managed SSH config JSON plus legacy `ssh.json` / `.ssh.json`.\n  - Validates private-key path existence and permissions before connecting.\n  - Persists probed host info as JSON under the remote-host cache dir via `persistHostInfo()`.\n  - May create the SSH control socket dir and, when `sshfs` exists, remote mount dirs.\n  - May write full command output to a session artifact file.\n- Network\n  - Opens SSH connections to the selected host.\n  - May issue extra probe commands to detect OS/shell and compat shells.\n- Subprocesses / native bindings\n  - Requires `ssh` on `PATH`; spawns it for connection checks, master startup, probing, and command execution.\n  - May call `sshfs`, `mountpoint`, `fusermount`/`fusermount3`, or `umount`.\n  - Sanitizes streamed text with `@gajae-code/natives` text sanitization.\n- Session state (transcript, memory, jobs, checkpoints, registries)\n  - Uses session artifact allocation when available.\n  - Registers postmortem cleanup hooks for SSH master connections and sshfs mounts.\n  - Tool concurrency is `exclusive`, so the agent scheduler should not run multiple ssh tool calls concurrently.\n- Background work / cancellation\n  - Process spawn receives the tool `AbortSignal`.\n  - Cancellation/timeout ends the running ssh process and returns a cancelled result that the tool turns into an error.\n\n## Limits & Caps\n- Timeout defaults/clamps: `default=60`, `min=1`, `max=3600` in `packages/coding-agent/src/tools/tool-timeouts.ts`.\n- Output tail window: `DEFAULT_MAX_BYTES = 50 * 1024` in `packages/coding-agent/src/session/streaming-output.ts`.\n- Output sink spill threshold defaults to the same `50 KiB`; once exceeded, only the tail remains in memory.\n- SSH master reuse persistence: `ControlPersist=3600` in `packages/coding-agent/src/ssh/connection-manager.ts` and `packages/coding-agent/src/ssh/sshfs-mount.ts`.\n- SSH host info schema version: `HOST_INFO_VERSION = 2` in `packages/coding-agent/src/ssh/connection-manager.ts`; stale cache entries are reprobed.\n- Streaming tail buffer compacts after more than `10` pending chunks (`MAX_PENDING`) before trimming.\n\n## Errors\n- `Unknown SSH host: ... Available hosts: ...` when the model passes a host name not present in discovery.\n- `SSH host not loaded: ...` if the discovered-name set and `hostsByName` map diverge.\n- `ssh binary not found on PATH` when `ssh` is unavailable.\n- `SSH key not found: ...`, `SSH key is not a file: ...`, or `SSH key permissions must be 600 or stricter: ...` from key validation.\n- `Failed to start SSH master for <target>: <stderr>` when control-master startup fails.\n- Non-zero remote command exit becomes `ToolError` with captured output and `Command exited with code N`.\n- Timeout becomes a cancelled result with output notice `[SSH: <timeout message>]`, then `ToolError`.\n- Abort becomes a cancelled result with output notice `[Command aborted: <message>]`, then `ToolError`.\n- `sshfs` mount failures are logged and ignored in `executeSSH()`; they do not fail the tool call.\n- Discovery parse problems do not fail tool loading; they become capability warnings. If all sources are empty/invalid, the tool simply does not load.\n\n## Notes\n- Host discovery is JSON-based only. The tool does not parse OpenSSH config files.\n- Discovery expands environment variables recursively in the parsed JSON and expands `~` in `key`/`keyPath`.\n- Host names are capability keys; the model must pass the config key, not the raw hostname.\n- Commands run without a PTY. `executeSSH()` uses `ptree.spawn(..., { stdin: \"pipe\", stderr: \"full\" })` and does not request an interactive terminal.\n- The tool exposes `cwd` but no `env`, `pty`, upload, download, or explicit file-transfer fields.\n- Lower layers support an `artifactId` for full output and a `remotePath` mount target, but `SshTool.execute()` does not expose those knobs.\n- Both stdout and stderr are merged into one output stream; ordering is whatever arrives through the two streams.\n- `StrictHostKeyChecking=accept-new` and `BatchMode=yes` are always set for connection checks, master startup, and command runs.\n- Connection reuse is keyed by discovered host name, not by raw target tuple alone.\n- `closeAllConnections()` and sshfs unmount cleanup run through postmortem hooks, not per-call teardown.\n",
-	"tools/task.md": "# task\n\n> Launch subagents for parallel, optionally isolated work.\n\n## Source\n- Entry: `packages/coding-agent/src/task/index.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/task.md`\n- Key collaborators:\n  - `packages/coding-agent/src/task/types.ts` — dynamic schema, progress/result types, output caps.\n  - `packages/coding-agent/src/task/discovery.ts` — resolve bundled GJC agents.\n  - `packages/coding-agent/src/task/agents.ts` — bundled agent definitions and frontmatter parsing.\n  - `packages/coding-agent/src/task/executor.ts` — create child sessions, run subagents, collect output.\n  - `packages/coding-agent/src/task/parallel.ts` — concurrency-limited scheduling and async semaphore.\n  - `packages/coding-agent/src/task/isolation-backend.ts` — isolation backend resolution and platform fallback.\n  - `packages/coding-agent/src/task/worktree.ts` — worktree / FUSE / ProjFS setup, patch capture, branch merge.\n  - `packages/coding-agent/src/task/output-manager.ts` — session-scoped `agent://` id allocation.\n  - `packages/coding-agent/src/task/simple-mode.ts` — `default` / `schema-free` / `independent` field gating.\n  - `packages/coding-agent/src/internal-urls/agent-protocol.ts` — resolve `agent://<id>` to saved subagent output.\n  - `packages/coding-agent/src/tools/index.ts` — tool registration and recursion-depth gating.\n  - `packages/coding-agent/src/sdk/session.ts` — child-session router/tool wiring and per-subagent `AgentOutputManager`.\n  - `docs/task-agent-discovery.md` — deeper discovery and precedence notes.\n  - `docs/handoff-generation-pipeline.md` — session artifact/handoff persistence patterns used by the wider session layer.\n\n## Inputs\n\n### Default mode (`task.simple = \"default\"`)\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `agent` | `string` | Yes | Exact agent name for every task item. Resolved at execution time through `discoverAgents(...)`. |\n| `tasks` | `Array<{ id: string; description: string; assignment: string; tier?: \"fast\" \\| \"balanced\" \\| \"strong\" }>` | Yes | Batch of small, self-contained task items. `id` max length 48 in schema; duplicate ids are rejected case-insensitively at runtime. `tier` is advisory unless autorouting is enabled. |\n| `context` | `string` | No | Shared background prepended to every subagent system prompt. Trimmed before use. |\n| `schema` | `string` | No | JSON-encoded JTD schema. Overrides agent/session output schema when this mode allows task-level schemas. |\n| `isolated` | `boolean` | No | Only present when the tool is created with isolation enabled. Requests isolated execution for the whole batch. |\n\n`tasks[].description` is UI-only. `tasks[].assignment` is the actual per-task instruction.\n\n### Working in another repository\n\n`tasks[].repositoryBinding` is a checked identity, not a destination or an authorization\ngrant. An omitted binding is captured from the active session. A declared binding cannot\nmove a session from repository A into repository B, even when B's worktree already exists.\nDeclared bindings are revalidated against the target worktree's canonical root and\ncommon Git directory; supplied branch and HEAD snapshots must still match. A symbolic\n`HEAD` string is not a commit snapshot. Omitted bindings are captured by the runtime.\nIsolation-created worktrees may differ from the source worktree while retaining its\ncommon Git repository identity.\n\nFor work explicitly requested in another repository, start a **new session** at its\napproved worktree, then delegate from that session:\n\n```sh\ngjc --cwd /absolute/path/to/approved-repository-worktree\n```\n\nAn existing linked Git worktree already isolates that session's edits from the main\ncheckout. Do not change a binding payload to bypass a rejection. The `isolated` field\nrequests additional per-task isolation in the session's own repository; it is exposed\nonly when `task.isolation.mode` enables an isolation backend.\n\n`move_session` only narrows to a descendant directory, not a sibling repository.\nUser-driven `/move` and SDK cwd relocation are separate surfaces; an already-created\ntask tool retains its original repository binding. A fresh target-rooted session avoids\ncarrying that old delegation authority across a repository move.\n\n`tasks[].tier` is inert while `task.autorouting.enabled` is `false`. When autorouting is active it selects the model chain for that item, an omitted `tier` routes as `balanced`, and the routed pin overrides the manual model chain. See [Autorouting](#autorouting).\n\n### Schema-free mode (`task.simple = \"schema-free\"`)\n\nSame as default, except `schema` is rejected by `validateTaskModeParams(...)` in `packages/coding-agent/src/task/index.ts`.\n\n### Independent mode (`task.simple = \"independent\"`)\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `agent` | `string` | Yes | Exact agent name. |\n| `tasks` | `Array<{ id: string; description: string; assignment: string }>` | Yes | Same item shape, but each `assignment` must carry all required background because shared `context` is disabled. |\n| `isolated` | `boolean` | No | Same conditional field as above. |\n\nIn this mode both `context` and `schema` are rejected.\n\n## Outputs\nThe tool returns one text block plus `details: TaskToolDetails`.\n\n`details` fields:\n- `projectAgentsDir: string | null` — nearest discovered project `agents/` dir.\n- `results: TaskResultReceipt[]` — receipt-safe per-task results; async launch responses start empty and later updates/final jobs carry receipts.\n- `totalDurationMs: number`\n- `usage?: Usage` — sum of per-subagent assistant-message usage.\n- raw output/patch filesystem paths are internal and are not exposed; readable artifacts use `agent://` / `local://` references.\n- `progress?: AgentProgress[]` — live or final per-task progress snapshots.\n- `async?: { state: \"running\" | \"completed\" | \"failed\"; jobId: string; type: \"task\" }` — present for background execution updates/results.\n\n`TaskResultReceipt` includes:\n- identity and status: `index`, `id`, `agent`, `agentSource`, `description`, `status`, `exitCode`\n- bounded output metadata: `preview`, `outputRef?`, duration/tokens/usage, retry/setup/abort summaries\n- isolated persistence: `persistence?: { outcome: \"applied\" | \"no_changes\" | \"recovery_available\"; ownerWorktreeApplied; recoveryRef? }`\n- recovery identity: `recoveryRef` uses a unique session-scoped `local://subagents/<id>-<snowflake>.patch` URI plus byte size and SHA-256; nested/error bundles are JSON-encoded in that artifact\n- branch/review/fork-context/repository-binding metadata that passed the receipt sanitizer\n\nArtifacts and side channels:\n- Every subagent with an artifacts dir writes `<id>.md`; `agent://<id>` resolves to that file.\n- If the output file is JSON, `agent://<id>/<path>` and `agent://<id>?q=<query>` perform JSON extraction in `packages/coding-agent/src/internal-urls/agent-protocol.ts`.\n- When the parent session persists artifacts, each subagent also gets `<id>.jsonl` session history.\n- Isolated execution writes a unique recovery artifact before cleanup whenever root changes, nested changes, or incomplete-capture evidence exists, including failed/paused/aborted tasks.\n- Async mode returns immediately after job registration, then emits `onUpdate(...)` progress snapshots and later hands completion to the session async-job pipeline.\n\n## Flow\n1. `TaskTool.create(...)` in `packages/coding-agent/src/task/index.ts` calls `discoverAgents(session.cwd)` once to build the dynamic prompt description from current agents and `task.simple` capabilities.\n2. `execute(...)` validates mode-gated fields with `validateTaskModeParams(...)`.\n3. It decides async vs sync:\n   - sync when `async.enabled` is false\n   - sync when the selected cached agent has `blocking === true`\n   - sync when `tasks.length === 0`\n   - otherwise async job scheduling\n4. Async path:\n   - allocate unique output ids with `AgentOutputManager.allocateBatch(...)`\n   - create one async job per task through `session.asyncJobManager.register(...)`\n   - limit concurrent job bodies with `Semaphore(task.maxConcurrency)` from `packages/coding-agent/src/task/parallel.ts`\n   - each job body calls `#executeSync(...)` with a one-task batch and the preallocated id\n   - `onUpdate(...)` emits aggregate `progress` snapshots and `details.async`\n5. Sync path (`#executeSync(...)`) rediscovers agents from disk via `discoverAgents(...)`, so runtime resolution can differ from the earlier prompt description.\n6. It resolves the requested agent with `getAgent(...)`, rejects unknown or disabled agents, and enforces parent spawn policy plus `GJC_BLOCKED_AGENT` self-recursion prevention.\n7. It derives the effective output schema in priority order: task call `schema` (if allowed) → agent frontmatter `output` → inherited parent session schema.\n8. It validates task ids: missing ids and case-insensitive duplicates are immediate errors.\n9. If `isolated` was requested, it requires a git repo (`getRepoRoot(...)` / `captureBaseline(...)`) and resolves the actual backend through `resolveIsolationBackendForTaskExecution(...)`.\n10. It chooses an artifacts dir from the parent session when available, otherwise a temp dir, and writes `context.md` there when `session.getCompactContext?.()` returns content.\n11. It allocates unique ids again if the caller did not preallocate them, then builds `tasksWithUniqueIds`.\n12. For each task, it seeds an `AgentProgress` entry and runs `runTask(...)` through `mapWithConcurrencyLimit(...)` using `task.maxConcurrency`.\n13. Non-isolated `runTask(...)` calls `runSubprocess(...)` directly with parent cwd.\n14. Isolated `runTask(...)`:\n   - creates an isolation workspace through the PAL backend\n   - binds the managed child session cwd to that execution workspace\n   - runs `runSubprocess(...)` inside the workspace\n   - captures root/nested deltas for every outcome before cleanup; incomplete nested capture preserves the root delta plus capture errors\n   - in branch mode, only successful task branches are merge candidates; in patch mode, only successful root patches are apply candidates\n   - always cleans up the isolation workspace/backend after the recovery artifact is durable\n15. `runSubprocess(...)` in `packages/coding-agent/src/task/executor.ts` creates a child agent session with:\n   - isolated settings snapshot via `Settings.isolated(...)`, forcing `async.enabled = false` and `bash.autoBackground.enabled = false`\n   - child `agentId` / `parentTaskPrefix` equal to the allocated task id\n   - child internal URL router and `AgentOutputManager` from `packages/coding-agent/src/sdk/session.ts`\n   - the shared `context`, optional `context.md` reference, optional isolation worktree path, output schema, and IRC peer roster in the system prompt template\n16. Child tool availability is derived from the agent definition plus runtime guards:\n   - explicit `agent.tools` if provided\n   - auto-add `task` when the agent has `spawns` and recursion depth allows it\n   - remove `task` at or past `task.maxRecursionDepth`\n   - expand `exec` to `eval` and `bash`\n   - strip parent-owned `todo_write` after session creation\n17. `runSubprocess(...)` subscribes to child agent events, coalesces progress updates every 150 ms, forwards lifecycle/progress events on the parent event bus, and extracts tool data through `subprocessToolRegistry`.\n18. The child must finish through the hidden `yield` tool. If it does not, `runSubprocess(...)` sends up to 3 reminder prompts; the last reminder forces `toolChoice = yield` when supported.\n19. Finalization uses `finalizeSubprocessOutput(...)` to reconcile raw assistant text, `yield` payloads, structured schemas, `report_finding` data, and abort states. Output is truncated with `MAX_OUTPUT_BYTES` / `MAX_OUTPUT_LINES` before returning to the parent, but the full raw output is still written to `<id>.md`.\n20. After sync task work finishes, `#executeSync(...)` aggregates receipts and reconciles isolation:\n   - branch mode records per-branch applied/recovery truth from the actual merged set, including partial merges\n   - patch mode dry-checks successful root patches, applies them, then proves the complete owner worktree against the captured baseline plus all applied patches\n   - merge/proof exceptions downgrade affected receipts to `recovery_available`\n   - nested repo patches apply without staging or committing unrelated owner state; missing/conflicting nested repos downgrade affected receipts\n21. The final summary renders receipt-safe `agent://` output and `local://` recovery handles; exit-zero `merge_failed` receipts make both batch and individual async jobs fail.\n\n## Modes / Variants\n- Execution mode\n  - Sync inline execution — default path.\n  - Async background execution — one async job per task item when `async.enabled` is on and the chosen agent is not marked `blocking`.\n- Simple mode\n  - `default` — accepts shared `context` and per-call `schema`.\n  - `schema-free` — accepts `context`, rejects `schema`.\n  - `independent` — rejects `context` and `schema`; each assignment stands alone.\n- Isolation backend\n  - `none` — no isolation.\n  - `worktree` — detached git worktree plus baseline replay.\n  - `fuse-overlay` — Unix FUSE overlay mount.\n  - `fuse-projfs` — Windows ProjFS overlay.\n- Isolation merge strategy\n  - Patch mode — capture/apply root patches, keep patch artifacts when application fails.\n  - Branch mode — commit each task onto `gjc/task/<id>` branch, cherry-pick into parent, preserve failed branches for manual resolution.\n- Agent source\n  - Project/user agents discovered from configured agent directories.\n  - Bundled GJC role agents — the retained canonical four-agent surface from `packages/coding-agent/src/task/agents.ts`.\n- Bundled agent types\n  - `executor` — bounded implementation, fixes, and refactors.\n  - `architect` — read-only architecture and code-review assessment.\n  - `planner` — read-only sequencing and acceptance criteria.\n  - `critic` — read-only plan critique and actionability review.\n\n## Autorouting\n\nOff by default. When `task.autorouting.enabled` is `true`, each task item is routed by its `tier` instead of the manual model chain.\n\n- Tier map source: `task.autorouting.tiers` (generated from `task.autorouting.setup`; provider order is seeded from `modelProviderOrder` and the model catalog). The removed `task.autorouting.preset` setting no longer participates in routing; enablement without usable tiers falls back to manual model resolution and reports a diagnostic. Contract in `packages/coding-agent/src/config/autorouting-contract.ts`.\n- Selectors are exact `provider/modelId` strings with an optional `:minimal|low|medium|high|xhigh` suffix. Globs, bare model ids, and `pi/<role>` aliases are rejected by the generated config schema.\n- An omitted `tier` routes as `balanced`. A tier with no usable chain falls back to manual resolution for that item alone, with a bounded reason recorded.\n- Preflight tries at most three unique candidates and only advances on transient failures observed before the run starts; there is no mid-run failover. Failed attempts run in staged sessions and attempt-scoped artifacts, so they leave no durable residue.\n- Resolved routing evidence (skips, attempts, terminal outcome) is attached to the task result, receipt, renderer, and task-summary prompt.\n- Setup: `/routing` opens the smart-routing panel (declare providers in priority order; chains are generated deterministically from the curated tier map and the model catalog, never from credentials). `/routing on|off|status` manages the toggle and prints effective chains.\n\nWith autorouting disabled, model resolution is byte-for-byte unchanged.\n\n## Side Effects\n- Filesystem\n  - Writes `context.md`, `<id>.jsonl`, and `<id>.md` under the session artifacts dir or a temp task dir.\n  - In isolated mode writes unique session-scoped recovery artifacts containing root patches or JSON root/nested/capture-error bundles.\n  - Creates/removes worktrees or overlay mount directories.\n  - In branch mode creates temporary worktrees and task branches.\n- Network\n  - Child sessions may use whichever networked tools/models their active tool set permits.\n- Subprocesses / native bindings\n  - `fuse-overlayfs` and `fusermount`/`fusermount3` for FUSE isolation.\n  - ProjFS native bindings via `@gajae-code/natives` on Windows.\n  - Git operations for baseline capture, patch apply/proof, worktrees, branches, stash, and cherry-pick; nested patches are left as working-tree changes rather than committing owner state.\n- Session state (transcript, memory, jobs, checkpoints, registries)\n  - Creates child `AgentSession` instances with isolated settings snapshots.\n  - Registers async jobs in `session.asyncJobManager` for background task mode.\n  - Emits `task:subagent:event`, `task:subagent:progress`, and `task:subagent:lifecycle` on the parent event bus.\n  - Allocates session-scoped output ids through `AgentOutputManager` so `agent://` remains unique across invocations and resumes.\n  - Shares the parent `local://` root with subagents by passing `localProtocolOptions` through `createAgentSession(...)`.\n- User-visible prompts / interactive UI\n  - Async mode streams aggregate progress updates.\n  - Missing-`yield` recovery sends up to three internal reminder prompts to the child session.\n  - Final summaries include `<system-notification>` blocks for isolation fallbacks or merge failures.\n- Background work / cancellation\n  - Parent abort stops scheduling new work, aborts active child sessions, and marks unscheduled tasks as skipped.\n  - Async jobs keep their own cancellation via `AsyncJobManager`.\n  - Await timeouts are observation windows only: they do not stop, fail, or make a subagent stale. Inspect/list and continue work; cancel only when the subagent has actually failed, gone off-track, or become unrecoverably wrong.\n\n## Limits & Caps\n- Per-subagent output truncation: `MAX_OUTPUT_BYTES = 500_000` and `MAX_OUTPUT_LINES = 5000` in `packages/coding-agent/src/task/types.ts`. Full raw output is still written to `<id>.md` before truncation is returned to the caller.\n- Progress coalescing in child execution: `PROGRESS_COALESCE_MS = 150` in `packages/coding-agent/src/task/executor.ts`.\n- Recent output tail for progress: `RECENT_OUTPUT_TAIL_BYTES = 8 * 1024` and `recentOutput` keeps the last 8 non-empty lines in `packages/coding-agent/src/task/executor.ts`.\n- Missing-`yield` reminder retries: `MAX_YIELD_RETRIES = 3` in `packages/coding-agent/src/task/executor.ts`.\n- Task id schema cap: `tasks[].id` `maxLength: 48` in `packages/coding-agent/src/task/types.ts`.\n- Prompt text says ids should be `≤32` chars, but the runtime schema allows 48; this mismatch is real.\n- Async/full sync parallelism both use `task.maxConcurrency` from settings:\n  - sync path: `mapWithConcurrencyLimit(...)`\n  - async path: `Semaphore(...)` around job bodies\n- Recursion depth gate: `task.maxRecursionDepth` from settings; `packages/coding-agent/src/tools/index.ts` hides the `task` tool at or beyond the limit, and `runSubprocess(...)` also strips child `task` access at max depth.\n- Final inline summary preview per task uses `fullOutputThreshold = 5000` chars in `packages/coding-agent/src/task/index.ts`; longer outputs are summarized while `agent://<id>` points to the full artifact.\n\n## Errors\n- Most validation failures are returned as normal tool text with empty `results`, not thrown:\n  - invalid simple-mode fields\n  - unknown/disabled agent\n  - missing tasks\n  - missing/duplicate task ids\n  - spawn-policy denial\n  - requesting `isolated` while isolation mode is `none`\n- Isolated execution without a git repo returns `Isolated task execution requires a git repository. ...`.\n- Backend resolution can return a hard error (`ProjFS isolation initialization failed...`) or a non-fatal warning with fallback to `worktree`.\n- `mapWithConcurrencyLimit(...)` fails fast on non-abort worker exceptions; already completed results are preserved only in the thrown path’s local state, not surfaced unless the caller catches and converts them.\n- Child-session failures retain failed/paused/aborted status; captured isolated changes remain recovery-only and are never auto-applied.\n- If the child omits `yield`, `finalizeSubprocessOutput(...)` injects warnings such as `SYSTEM WARNING: Subagent exited without calling yield tool after 3 reminders.`\n- Async scheduling failures are accumulated per task; if no jobs start, the tool returns `Failed to start background task jobs: ...`.\n- An async child with no receipt, or any receipt whose status is not `completed`, terminates its individual async job as failed (paused remains paused).\n- `agent://<id>` resolution errors are model-visible when another tool reads them: no session, no artifacts dir, missing id, conflicting extraction syntax, or invalid JSON for extraction.\n\n## Notes\n- Bundled agent definitions are embedded in `packages/coding-agent/src/task/agents.ts`.\n- `TaskTool.create(...)` caches discovered agents only for description rendering and the async blocking-agent decision. `#executeSync(...)` rediscovers agents each call.\n- Custom agent frontmatter can override bundled agents by name. Bundled definitions are embedded at build time in `packages/coding-agent/src/task/agents.ts`.\n- Child sessions do not inherit conversation history automatically. The only built-in carry-over is shared `context`, optional `context.md`, workspace tree/context files, and shared `local://` root.\n- `Settings.isolated(...)` gives each child a session-isolated settings snapshot; tool enablement is recomputed inside the child session rather than sharing mutable parent tool state.\n- Plan mode mutates an `effectiveAgent` with a read-only tool subset and plan-mode prompt text, but `runSubprocess(...)` is still invoked with `agent` rather than `effectiveAgent`. Model/thinking/schema overrides use the effective agent; prompt/tool/spawn restrictions do not fully flow through this call path.\n- Branch-mode merge temporarily stashes the parent repo before cherry-picking task branches. Partial/failed merges preserve per-branch applied truth and recovery handles.\n- Patch mode applies only successful root patches and requires exact owner-worktree proof before reporting `applied`.\n- Nested git repos are diffed independently. Recovery bundles include nested patches and capture errors; application never stages or commits pre-existing nested owner changes.\n- `agent://` ids are numeric-prefixed (`0-Task`, `1-Task`, nested like `0-Parent.0-Child`) by `AgentOutputManager`; this is what prevents artifact collisions across repeated or nested task invocations.\n",
+	"tools/task.md": "# task\n\n> Launch subagents for parallel, optionally isolated work.\n\n## Source\n- Entry: `packages/coding-agent/src/task/index.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/task.md`\n- Key collaborators:\n  - `packages/coding-agent/src/task/types.ts` — dynamic schema, progress/result types, output caps.\n  - `packages/coding-agent/src/task/discovery.ts` — resolve bundled GJC agents.\n  - `packages/coding-agent/src/task/agents.ts` — bundled agent definitions and frontmatter parsing.\n  - `packages/coding-agent/src/task/executor.ts` — create child sessions, run subagents, collect output.\n  - `packages/coding-agent/src/task/parallel.ts` — concurrency-limited scheduling and async semaphore.\n  - `packages/coding-agent/src/task/worktree.ts` — isolation backend resolution and platform fallback (`parseIsolationMode()`, `ensureIsolation()` over the native `isoResolve()`), worktree / FUSE / ProjFS setup, patch capture, branch merge.\n  - `packages/coding-agent/src/task/output-manager.ts` — session-scoped `agent://` id allocation.\n  - `packages/coding-agent/src/task/simple-mode.ts` — `default` / `schema-free` / `independent` field gating.\n  - `packages/coding-agent/src/internal-urls/agent-protocol.ts` — resolve `agent://<id>` to saved subagent output.\n  - `packages/coding-agent/src/tools/index.ts` — tool registration and recursion-depth gating.\n  - `packages/coding-agent/src/sdk/session.ts` — child-session router/tool wiring and per-subagent `AgentOutputManager`.\n  - `docs/handoff-generation-pipeline.md` — session artifact/handoff persistence patterns used by the wider session layer.\n\n## Inputs\n\n### Default mode (`task.simple = \"default\"`)\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `agent` | `string` | Yes | Exact agent name for every task item. Resolved at execution time through `discoverAgents(...)`. |\n| `tasks` | `Array<{ id: string; description: string; assignment: string; tier?: \"fast\" \\| \"balanced\" \\| \"strong\" }>` | Yes | Batch of small, self-contained task items. `id` max length 48 in schema; duplicate ids are rejected case-insensitively at runtime. `tier` is advisory unless autorouting is enabled. |\n| `context` | `string` | No | Shared background prepended to every subagent system prompt. Trimmed before use. |\n| `schema` | `string` | No | JSON-encoded JTD schema. Overrides agent/session output schema when this mode allows task-level schemas. |\n| `isolated` | `boolean` | No | Only present when the tool is created with isolation enabled. Requests isolated execution for the whole batch. |\n\n`tasks[].description` is UI-only. `tasks[].assignment` is the actual per-task instruction.\n\n### Working in another repository\n\n`tasks[].repositoryBinding` is a checked identity, not a destination or an authorization\ngrant. An omitted binding is captured from the active session. A declared binding cannot\nmove a session from repository A into repository B, even when B's worktree already exists.\nDeclared bindings are revalidated against the target worktree's canonical root and\ncommon Git directory; supplied branch and HEAD snapshots must still match. A symbolic\n`HEAD` string is not a commit snapshot. Omitted bindings are captured by the runtime.\nIsolation-created worktrees may differ from the source worktree while retaining its\ncommon Git repository identity.\n\nFor work explicitly requested in another repository, start a **new session** at its\napproved worktree, then delegate from that session:\n\n```sh\ngjc --cwd /absolute/path/to/approved-repository-worktree\n```\n\nAn existing linked Git worktree already isolates that session's edits from the main\ncheckout. Do not change a binding payload to bypass a rejection. The `isolated` field\nrequests additional per-task isolation in the session's own repository; it is exposed\nonly when `task.isolation.mode` enables an isolation backend.\n\n`move_session` only narrows to a descendant directory, not a sibling repository.\nUser-driven `/move` and SDK cwd relocation are separate surfaces; an already-created\ntask tool retains its original repository binding. A fresh target-rooted session avoids\ncarrying that old delegation authority across a repository move.\n\n`tasks[].tier` is inert while `task.autorouting.enabled` is `false`. When autorouting is active it selects the model chain for that item, an omitted `tier` routes as `balanced`, and the routed pin overrides the manual model chain. See [Autorouting](#autorouting).\n\n### Schema-free mode (`task.simple = \"schema-free\"`)\n\nSame as default, except `schema` is rejected by `validateTaskModeParams(...)` in `packages/coding-agent/src/task/index.ts`.\n\n### Independent mode (`task.simple = \"independent\"`)\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `agent` | `string` | Yes | Exact agent name. |\n| `tasks` | `Array<{ id: string; description: string; assignment: string }>` | Yes | Same item shape, but each `assignment` must carry all required background because shared `context` is disabled. |\n| `isolated` | `boolean` | No | Same conditional field as above. |\n\nIn this mode both `context` and `schema` are rejected.\n\n## Outputs\nThe tool returns one text block plus `details: TaskToolDetails`.\n\n`details` fields:\n- `projectAgentsDir: string | null` — nearest discovered project `agents/` dir.\n- `results: TaskResultReceipt[]` — receipt-safe per-task results; async launch responses start empty and later updates/final jobs carry receipts.\n- `totalDurationMs: number`\n- `usage?: Usage` — sum of per-subagent assistant-message usage.\n- raw output/patch filesystem paths are internal and are not exposed; readable artifacts use `agent://` / `local://` references.\n- `progress?: AgentProgress[]` — live or final per-task progress snapshots.\n- `async?: { state: \"running\" | \"completed\" | \"failed\"; jobId: string; type: \"task\" }` — present for background execution updates/results.\n\n`TaskResultReceipt` includes:\n- identity and status: `index`, `id`, `agent`, `agentSource`, `description`, `status`, `exitCode`\n- bounded output metadata: `preview`, `outputRef?`, duration/tokens/usage, retry/setup/abort summaries\n- isolated persistence: `persistence?: { outcome: \"applied\" | \"no_changes\" | \"recovery_available\"; ownerWorktreeApplied; recoveryRef? }`\n- recovery identity: `recoveryRef` uses a unique session-scoped `local://subagents/<id>-<snowflake>.patch` URI plus byte size and SHA-256; nested/error bundles are JSON-encoded in that artifact\n- branch/review/fork-context/repository-binding metadata that passed the receipt sanitizer\n\nArtifacts and side channels:\n- Every subagent with an artifacts dir writes `<id>.md`; `agent://<id>` resolves to that file.\n- If the output file is JSON, `agent://<id>/<path>` and `agent://<id>?q=<query>` perform JSON extraction in `packages/coding-agent/src/internal-urls/agent-protocol.ts`.\n- When the parent session persists artifacts, each subagent also gets `<id>.jsonl` session history.\n- Isolated execution writes a unique recovery artifact before cleanup whenever root changes, nested changes, or incomplete-capture evidence exists, including failed/paused/aborted tasks.\n- Async mode returns immediately after job registration, then emits `onUpdate(...)` progress snapshots and later hands completion to the session async-job pipeline.\n\n## Flow\n1. `TaskTool.create(...)` in `packages/coding-agent/src/task/index.ts` calls `discoverAgents(session.cwd)` once to build the dynamic prompt description from current agents and `task.simple` capabilities.\n2. `execute(...)` validates mode-gated fields with `validateTaskModeParams(...)`.\n3. It decides async vs sync:\n   - sync when `async.enabled` is false\n   - sync when the selected cached agent has `blocking === true`\n   - sync when `tasks.length === 0`\n   - otherwise async job scheduling\n4. Async path:\n   - allocate unique output ids with `AgentOutputManager.allocateBatch(...)`\n   - create one async job per task through `session.asyncJobManager.register(...)`\n   - limit concurrent job bodies with `Semaphore(task.maxConcurrency)` from `packages/coding-agent/src/task/parallel.ts`\n   - each job body calls `#executeSync(...)` with a one-task batch and the preallocated id\n   - `onUpdate(...)` emits aggregate `progress` snapshots and `details.async`\n5. Sync path (`#executeSync(...)`) rediscovers agents from disk via `discoverAgents(...)`, so runtime resolution can differ from the earlier prompt description.\n6. It resolves the requested agent with `getAgent(...)`, rejects unknown or disabled agents, and enforces parent spawn policy plus `GJC_BLOCKED_AGENT` self-recursion prevention.\n7. It derives the effective output schema in priority order: task call `schema` (if allowed) → agent frontmatter `output` → inherited parent session schema.\n8. It validates task ids: missing ids and case-insensitive duplicates are immediate errors.\n9. If `isolated` was requested, it requires a git repo (`getRepoRoot(...)` / `captureBaseline(...)`) and resolves the actual backend through `resolveIsolationBackendForTaskExecution(...)`.\n10. It chooses an artifacts dir from the parent session when available, otherwise a temp dir, and writes `context.md` there when `session.getCompactContext?.()` returns content.\n11. It allocates unique ids again if the caller did not preallocate them, then builds `tasksWithUniqueIds`.\n12. For each task, it seeds an `AgentProgress` entry and runs `runTask(...)` through `mapWithConcurrencyLimit(...)` using `task.maxConcurrency`.\n13. Non-isolated `runTask(...)` calls `runSubprocess(...)` directly with parent cwd.\n14. Isolated `runTask(...)`:\n   - creates an isolation workspace through the PAL backend\n   - binds the managed child session cwd to that execution workspace\n   - runs `runSubprocess(...)` inside the workspace\n   - captures root/nested deltas for every outcome before cleanup; incomplete nested capture preserves the root delta plus capture errors\n   - in branch mode, only successful task branches are merge candidates; in patch mode, only successful root patches are apply candidates\n   - always cleans up the isolation workspace/backend after the recovery artifact is durable\n15. `runSubprocess(...)` in `packages/coding-agent/src/task/executor.ts` creates a child agent session with:\n   - isolated settings snapshot via `Settings.isolated(...)`, forcing `async.enabled = false` and `bash.autoBackground.enabled = false`\n   - child `agentId` / `parentTaskPrefix` equal to the allocated task id\n   - child internal URL router and `AgentOutputManager` from `packages/coding-agent/src/sdk/session.ts`\n   - the shared `context`, optional `context.md` reference, optional isolation worktree path, output schema, and IRC peer roster in the system prompt template\n16. Child tool availability is derived from the agent definition plus runtime guards:\n   - explicit `agent.tools` if provided\n   - auto-add `task` when the agent has `spawns` and recursion depth allows it\n   - remove `task` at or past `task.maxRecursionDepth`\n   - expand `exec` to `eval` and `bash`\n   - strip parent-owned `todo_write` after session creation\n17. `runSubprocess(...)` subscribes to child agent events, coalesces progress updates every 150 ms, forwards lifecycle/progress events on the parent event bus, and extracts tool data through `subprocessToolRegistry`.\n18. The child must finish through the hidden `yield` tool. If it does not, `runSubprocess(...)` sends up to 3 reminder prompts; the last reminder forces `toolChoice = yield` when supported.\n19. Finalization uses `finalizeSubprocessOutput(...)` to reconcile raw assistant text, `yield` payloads, structured schemas, `report_finding` data, and abort states. Output is truncated with `MAX_OUTPUT_BYTES` / `MAX_OUTPUT_LINES` before returning to the parent, but the full raw output is still written to `<id>.md`.\n20. After sync task work finishes, `#executeSync(...)` aggregates receipts and reconciles isolation:\n   - branch mode records per-branch applied/recovery truth from the actual merged set, including partial merges\n   - patch mode dry-checks successful root patches, applies them, then proves the complete owner worktree against the captured baseline plus all applied patches\n   - merge/proof exceptions downgrade affected receipts to `recovery_available`\n   - nested repo patches apply without staging or committing unrelated owner state; missing/conflicting nested repos downgrade affected receipts\n21. The final summary renders receipt-safe `agent://` output and `local://` recovery handles; exit-zero `merge_failed` receipts make both batch and individual async jobs fail.\n\n## Modes / Variants\n- Execution mode\n  - Sync inline execution — default path.\n  - Async background execution — one async job per task item when `async.enabled` is on and the chosen agent is not marked `blocking`.\n- Simple mode\n  - `default` — accepts shared `context` and per-call `schema`.\n  - `schema-free` — accepts `context`, rejects `schema`.\n  - `independent` — rejects `context` and `schema`; each assignment stands alone.\n- Isolation backend\n  - `none` — no isolation.\n  - `worktree` — detached git worktree plus baseline replay.\n  - `fuse-overlay` — Unix FUSE overlay mount.\n  - `fuse-projfs` — Windows ProjFS overlay.\n- Isolation merge strategy\n  - Patch mode — capture/apply root patches, keep patch artifacts when application fails.\n  - Branch mode — commit each task onto `gjc/task/<id>` branch, cherry-pick into parent, preserve failed branches for manual resolution.\n- Agent source\n  - Project/user agents discovered from configured agent directories.\n  - Bundled GJC role agents — the retained canonical four-agent surface from `packages/coding-agent/src/task/agents.ts`.\n- Bundled agent types\n  - `executor` — bounded implementation, fixes, and refactors.\n  - `architect` — read-only architecture and code-review assessment.\n  - `planner` — read-only sequencing and acceptance criteria.\n  - `critic` — read-only plan critique and actionability review.\n\n## Autorouting\n\nOff by default. When `task.autorouting.enabled` is `true`, each task item is routed by its `tier` instead of the manual model chain.\n\n- Tier map source: `task.autorouting.tiers` (generated from `task.autorouting.setup`; provider order is seeded from `modelProviderOrder` and the model catalog). The removed `task.autorouting.preset` setting no longer participates in routing; enablement without usable tiers falls back to manual model resolution and reports a diagnostic. Contract in `packages/coding-agent/src/config/autorouting-contract.ts`.\n- Selectors are exact `provider/modelId` strings with an optional `:minimal|low|medium|high|xhigh` suffix. Globs, bare model ids, and `pi/<role>` aliases are rejected by the generated config schema.\n- An omitted `tier` routes as `balanced`. A tier with no usable chain falls back to manual resolution for that item alone, with a bounded reason recorded.\n- Preflight tries at most three unique candidates and only advances on transient failures observed before the run starts; there is no mid-run failover. Failed attempts run in staged sessions and attempt-scoped artifacts, so they leave no durable residue.\n- Resolved routing evidence (skips, attempts, terminal outcome) is attached to the task result, receipt, renderer, and task-summary prompt.\n- Setup: `/routing` opens the smart-routing panel (declare providers in priority order; chains are generated deterministically from the curated tier map and the model catalog, never from credentials). `/routing on|off|status` manages the toggle and prints effective chains.\n\nWith autorouting disabled, model resolution is byte-for-byte unchanged.\n\n## Side Effects\n- Filesystem\n  - Writes `context.md`, `<id>.jsonl`, and `<id>.md` under the session artifacts dir or a temp task dir.\n  - In isolated mode writes unique session-scoped recovery artifacts containing root patches or JSON root/nested/capture-error bundles.\n  - Creates/removes worktrees or overlay mount directories.\n  - In branch mode creates temporary worktrees and task branches.\n- Network\n  - Child sessions may use whichever networked tools/models their active tool set permits.\n- Subprocesses / native bindings\n  - `fuse-overlayfs` and `fusermount`/`fusermount3` for FUSE isolation.\n  - ProjFS native bindings via `@gajae-code/natives` on Windows.\n  - Git operations for baseline capture, patch apply/proof, worktrees, branches, stash, and cherry-pick; nested patches are left as working-tree changes rather than committing owner state.\n- Session state (transcript, memory, jobs, checkpoints, registries)\n  - Creates child `AgentSession` instances with isolated settings snapshots.\n  - Registers async jobs in `session.asyncJobManager` for background task mode.\n  - Emits `task:subagent:event`, `task:subagent:progress`, and `task:subagent:lifecycle` on the parent event bus.\n  - Allocates session-scoped output ids through `AgentOutputManager` so `agent://` remains unique across invocations and resumes.\n  - Shares the parent `local://` root with subagents by passing `localProtocolOptions` through `createAgentSession(...)`.\n- User-visible prompts / interactive UI\n  - Async mode streams aggregate progress updates.\n  - Missing-`yield` recovery sends up to three internal reminder prompts to the child session.\n  - Final summaries include `<system-notification>` blocks for isolation fallbacks or merge failures.\n- Background work / cancellation\n  - Parent abort stops scheduling new work, aborts active child sessions, and marks unscheduled tasks as skipped.\n  - Async jobs keep their own cancellation via `AsyncJobManager`.\n  - Await timeouts are observation windows only: they do not stop, fail, or make a subagent stale. Inspect/list and continue work; cancel only when the subagent has actually failed, gone off-track, or become unrecoverably wrong.\n\n## Limits & Caps\n- Per-subagent output truncation: `MAX_OUTPUT_BYTES = 500_000` and `MAX_OUTPUT_LINES = 5000` in `packages/coding-agent/src/task/types.ts`. Full raw output is still written to `<id>.md` before truncation is returned to the caller.\n- Progress coalescing in child execution: `PROGRESS_COALESCE_MS = 150` in `packages/coding-agent/src/task/executor.ts`.\n- Recent output tail for progress: `RECENT_OUTPUT_TAIL_BYTES = 8 * 1024` and `recentOutput` keeps the last 8 non-empty lines in `packages/coding-agent/src/task/executor.ts`.\n- Missing-`yield` reminder retries: `MAX_YIELD_RETRIES = 3` in `packages/coding-agent/src/task/executor.ts`.\n- Task id schema cap: `tasks[].id` `maxLength: 48` in `packages/coding-agent/src/task/types.ts`.\n- Prompt text says ids should be `≤32` chars, but the runtime schema allows 48; this mismatch is real.\n- Async/full sync parallelism both use `task.maxConcurrency` from settings:\n  - sync path: `mapWithConcurrencyLimit(...)`\n  - async path: `Semaphore(...)` around job bodies\n- Recursion depth gate: `task.maxRecursionDepth` from settings; `packages/coding-agent/src/tools/index.ts` hides the `task` tool at or beyond the limit, and `runSubprocess(...)` also strips child `task` access at max depth.\n- Final inline summary preview per task uses `fullOutputThreshold = 5000` chars in `packages/coding-agent/src/task/index.ts`; longer outputs are summarized while `agent://<id>` points to the full artifact.\n\n## Errors\n- Most validation failures are returned as normal tool text with empty `results`, not thrown:\n  - invalid simple-mode fields\n  - unknown/disabled agent\n  - missing tasks\n  - missing/duplicate task ids\n  - spawn-policy denial\n  - requesting `isolated` while isolation mode is `none`\n- Isolated execution without a git repo returns `Isolated task execution requires a git repository. ...`.\n- Backend resolution can return a hard error (`ProjFS isolation initialization failed...`) or a non-fatal warning with fallback to `worktree`.\n- `mapWithConcurrencyLimit(...)` fails fast on non-abort worker exceptions; already completed results are preserved only in the thrown path’s local state, not surfaced unless the caller catches and converts them.\n- Child-session failures retain failed/paused/aborted status; captured isolated changes remain recovery-only and are never auto-applied.\n- If the child omits `yield`, `finalizeSubprocessOutput(...)` injects warnings such as `SYSTEM WARNING: Subagent exited without calling yield tool after 3 reminders.`\n- Async scheduling failures are accumulated per task; if no jobs start, the tool returns `Failed to start background task jobs: ...`.\n- An async child with no receipt, or any receipt whose status is not `completed`, terminates its individual async job as failed (paused remains paused).\n- `agent://<id>` resolution errors are model-visible when another tool reads them: no session, no artifacts dir, missing id, conflicting extraction syntax, or invalid JSON for extraction.\n\n## Notes\n- Bundled agent definitions are embedded in `packages/coding-agent/src/task/agents.ts`.\n- `TaskTool.create(...)` caches discovered agents only for description rendering and the async blocking-agent decision. `#executeSync(...)` rediscovers agents each call.\n- Custom agent frontmatter can override bundled agents by name. Bundled definitions are embedded at build time in `packages/coding-agent/src/task/agents.ts`.\n- Child sessions do not inherit conversation history automatically. The only built-in carry-over is shared `context`, optional `context.md`, workspace tree/context files, and shared `local://` root.\n- `Settings.isolated(...)` gives each child a session-isolated settings snapshot; tool enablement is recomputed inside the child session rather than sharing mutable parent tool state.\n- Plan mode mutates an `effectiveAgent` with a read-only tool subset and plan-mode prompt text, but `runSubprocess(...)` is still invoked with `agent` rather than `effectiveAgent`. Model/thinking/schema overrides use the effective agent; prompt/tool/spawn restrictions do not fully flow through this call path.\n- Branch-mode merge temporarily stashes the parent repo before cherry-picking task branches. Partial/failed merges preserve per-branch applied truth and recovery handles.\n- Patch mode applies only successful root patches and requires exact owner-worktree proof before reporting `applied`.\n- Nested git repos are diffed independently. Recovery bundles include nested patches and capture errors; application never stages or commits pre-existing nested owner changes.\n- `agent://` ids are numeric-prefixed (`0-Task`, `1-Task`, nested like `0-Parent.0-Child`) by `AgentOutputManager`; this is what prevents artifact collisions across repeated or nested task invocations.\n",
 	"tools/todo_write.md": "# todo_write\n\n> Applies ordered mutations to the session todo list and returns a text summary plus the full phase/task state.\n\n## Source\n- Entry: `packages/coding-agent/src/tools/todo-write.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/todo-write.md`\n- Key collaborators:\n  - `packages/coding-agent/src/tools/index.ts` — registers tool, exposes session hooks, gates availability.\n  - `packages/coding-agent/src/modes/controllers/event-controller.ts` — updates the visible todo UI on tool completion.\n  - `packages/coding-agent/src/session/agent-session.ts` — stores cached phases, auto-clears done/dropped tasks, emits failure reminders.\n  - `packages/coding-agent/src/modes/controllers/todo-command-controller.ts` — `/todo` command path, custom-entry persistence, transcript reminder injection.\n  - `packages/coding-agent/src/tools/render-utils.ts` — collapsed-preview cap for renderer trees.\n\n## Inputs\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `ops` | `TodoOpEntry[]` | Yes | Ordered operations to apply. `minItems: 1`.\n\n### `TodoOpEntry`\n\n| Op | Required fields | Optional fields | Effect |\n| --- | --- | --- | --- |\n| `init` | `list` | None of the other fields are used | Replaces the entire list with `list`; every new task starts `pending` before normalization. |\n| `start` | `task` | None | Marks one task `in_progress`; any other `in_progress` task is demoted to `pending`. |\n| `done` | `task` or `phase` | None | Marks the target task or phase `completed`. |\n| `drop` | `task` or `phase` | None | Marks the target task or phase `abandoned`. |\n| `rm` | `task` or `phase` or neither | None | Removes the target task, clears the phase's task list, or clears all task lists. |\n| `append` | `phase`, `items` | None | Appends new `pending` tasks to a phase; creates the phase if missing. |\n| `note` | `task`, `text` | None | Appends one trimmed note string to the task's `notes` array. |\n\n### Fields used inside ops\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `op` | `\"init\" | \"start\" | \"done\" | \"rm\" | \"drop\" | \"append\" | \"note\"` | Yes | Operation discriminator. |\n| `list` | `{ phase: string; items: string[] }[]` | For `init` | Full replacement payload. Each `items` array has `minItems: 1`. |\n| `task` | `string` | For `start`; for task-targeted `done`/`drop`/`rm`/`note` | Exact task content match. |\n| `phase` | `string` | For `append`; for phase-targeted `done`/`drop`/`rm`; required when `done`/`drop` omit `task` | Exact phase name match, except `append` lazily creates a missing phase. |\n| `items` | `string[]` | For `append` | Tasks to append. `minItems: 1`. |\n| `text` | `string` | For `note` | Note text; trailing whitespace is stripped before storing. Empty-after-trim is rejected. |\n\n## Outputs\nThe tool returns a single-shot `AgentToolResult`:\n\n- `content`: one text part containing the summary from `formatSummary(...)`.\n  - Empty final state with no errors: `Todo list cleared.`\n  - Non-empty final state: remaining-item list, current phase progress, then a per-phase tree.\n  - If the active `in_progress` task has notes, the summary includes the note bodies inline.\n  - If any op produced validation/runtime errors, the summary starts with `Errors: ...` but still returns the mutated state.\n- `details`:\n  - `phases: TodoPhase[]`\n  - `storage: \"session\" | \"memory\"`\n\n`TodoPhase` / `TodoItem` state model:\n\n- `TodoPhase`: `{ name: string, tasks: TodoItem[] }`\n- `TodoItem`: `{ content: string, status: \"pending\" | \"in_progress\" | \"completed\" | \"abandoned\", notes?: string[] }`\n\nThe TUI renderer (`todoWriteToolRenderer`) merges call and result into one transcript block, renders phases as a tree, shows note counts as superscripts, and renders the note bodies only for the current `in_progress` task. Collapsed transcript previews cap tree items at `PREVIEW_LIMITS.COLLAPSED_ITEMS` (`8`).\n\n## Flow\n1. `TodoWriteTool.execute(...)` clones the current cached phases from `session.getTodoPhases?.() ?? []` (`packages/coding-agent/src/tools/todo-write.ts`).\n2. `applyParams(...)` walks `params.ops` in order and applies each entry with `applyEntry(...)`.\n3. Each op mutates the working phase array:\n   - `initPhases(...)` rebuilds the list from scratch.\n   - `start` resolves a task by exact `content`, demotes every other `in_progress` task to `pending`, then marks the target `in_progress`.\n   - `done` / `drop` use `getTaskTargets(...)` to target one task or one phase; raw validation rejects either operation when both targets are absent.\n   - `rm` removes one task, clears one phase's `tasks`, or clears all phases' task arrays.\n   - `appendItems(...)` resolves or creates the target phase and pushes new `pending` tasks unless the same task content already exists anywhere.\n   - `note` trims trailing whitespace, rejects empty text, and appends the note to `task.notes`.\n4. Missing task/phase references are recorded in an `errors` array by `resolveTaskOrError(...)` / `resolvePhaseOrError(...)`; execution continues through the rest of the batch.\n5. After the full batch, `normalizeInProgressTask(...)` enforces the single-active-task invariant:\n   - if multiple tasks are `in_progress`, only the first stays active and the rest become `pending`;\n   - if none are `in_progress`, the first `pending` task in phase/task order is auto-promoted to `in_progress`.\n6. `execute(...)` stores the normalized phases with `session.setTodoPhases?.(...)` and reports `storage` as `\"session\"` when `session.getSessionFile()` exists, else `\"memory\"`.\n7. The agent runtime also watches `todo_write` tool results in `packages/coding-agent/src/session/agent-session.ts`; successful results refresh cached todos, failed results inject a hidden next-turn reminder telling the model that todo progress is not visible until it retries.\n8. The event controller updates the visible todo UI from `result.details.phases` on success, or shows a warning on error (`packages/coding-agent/src/modes/controllers/event-controller.ts`).\n\n## Modes / Variants\n### State transitions\n\n| Current status | `start` | `done` | `drop` | `rm` | `append` | `note` |\n| --- | --- | --- | --- | --- | --- | --- |\n| `pending` | `in_progress` on target | `completed` | `abandoned` | Removed | New tasks enter as `pending` | No status change |\n| `in_progress` | Target stays `in_progress`; non-target active tasks become `pending` | `completed` | `abandoned` | Removed | No status change | No status change |\n| `completed` | Can be set back to `in_progress` if targeted | Stays `completed` | Becomes `abandoned` if targeted | Removed | No status change | No status change |\n| `abandoned` | Can be set back to `in_progress` if targeted | Becomes `completed` if targeted | Stays `abandoned` | Removed | No status change | No status change |\n\nNormalization then re-applies the single-active-task rule after the full op batch.\n\n### Op targeting rules\n- `done`, `drop`:\n  - `task` set: affect one exact-content task.\n  - else `phase` must be set: affect every task in that exact-name phase.\n- `rm`:\n  - `task` set: remove one exact-content task.\n  - else `phase` set: clear every task in that exact-name phase.\n  - else: clear every task in every phase.\n- `append` is the only op that creates a missing phase.\n- `note` only targets a single task.\n- `init` discards previous phases entirely.\n\n### Markdown round-trip helpers\nThe same file also exposes non-tool helpers used by `/todo`:\n- `phasesToMarkdown(...)` serializes phases as headings plus checklist items (`[ ]`, `[/]`, `[x]`, `[-]`) with blockquote note bodies.\n- `markdownToPhases(...)` parses that format, defaults orphan tasks into a `Todos` phase, accepts `>` as an `in_progress` marker and `~` as `abandoned`, and runs the same normalization step.\n\n## Side Effects\n- Filesystem\n  - None in the tool itself.\n- Session state (transcript, memory, jobs, checkpoints, registries)\n  - Mutates the session todo cache through `setTodoPhases`.\n  - `storage` reports whether the session has a backing session file, but the tool does not append a custom session entry itself.\n  - Successful tool-result messages carry `details.phases`; `getLatestTodoPhasesFromEntries(...)` can reconstruct state later from those transcript entries.\n  - Failed `todo_write` results cause `agent-session` to enqueue a hidden next-turn reminder (`customType: \"todo-write-error-reminder\"`).\n- User-visible prompts / interactive UI\n  - Transcript block is rendered by `todoWriteToolRenderer` and merged with the call line.\n  - `event-controller` updates the visible todo panel from successful results.\n  - On error, `event-controller` shows `Todo update failed...`; the visible panel may stay stale until a later successful call.\n- Background work / cancellation\n  - `AgentSession.setTodoPhases(...)` schedules auto-clear timers for `completed` / `abandoned` tasks via `tasks.todoClearDelay`.\n\n## Limits & Caps\n- `ops` array: `minItems: 1` (`todoWriteSchema`).\n- `init.list[*].items`: `minItems: 1`.\n- `append.items`: `minItems: 1`.\n- Renderer collapsed preview: `PREVIEW_LIMITS.COLLAPSED_ITEMS = 8` (`packages/coding-agent/src/tools/render-utils.ts`).\n- Auto-clear delay: `tasks.todoClearDelay` default `60` seconds; `< 0` disables auto-clear, `0` clears on the next microtask (`packages/coding-agent/src/session/agent-session.ts`).\n- Tool execution mode: `concurrency = \"exclusive\"`, `strict = true`, `loadMode = \"discoverable\"`.\n\n## Errors\n- The tool does not throw for ordinary bad op payloads; it accumulates human-readable strings in `errors` and still returns success with the mutated state.\n- Error strings come from the helpers in `packages/coding-agent/src/tools/todo-write.ts`, including:\n  - `Missing list for init operation`\n  - `Missing task content`\n  - `Task \"...\" not found` with an extra empty-list hint when applicable\n  - `Missing phase name`\n  - `Phase \"...\" not found`\n  - `Missing phase name for append operation`\n  - `Missing items for append operation`\n  - `Task \"...\" already exists`\n  - `Missing text for note operation`\n- Because ops are processed in order, earlier errors do not roll back later ops.\n- Runtime-level tool failure is handled outside the tool body: `agent-session` injects a hidden reminder and the event controller warns the user that visible progress may be stale.\n- Idempotency is op-specific:\n  - `init` is a full replacement; replaying the same payload yields the same state.\n  - `start`, `done`, and `drop` are effectively idempotent on an existing target state, but `start` also demotes any other active task.\n  - `rm` is not idempotent for targeted removals: the second call errors because the task or phase is gone.\n  - `append` is not idempotent: duplicate task content is rejected with `Task \"...\" already exists`.\n  - `note` is append-only and never idempotent; replaying it adds another note entry.\n\n## Notes\n- Task lookup is exact string equality inside the tool. The model-facing prompt says task content and phase names are identifiers and should stay unique; `append` enforces task uniqueness globally, but `init` does not validate duplicate task or phase names.\n- `findTaskByContent(...)` returns the first matching task across phases. Duplicate task contents make later targeted ops ambiguous.\n- `normalizeInProgressTask(...)` runs after the whole batch, not after each op. A single call can intentionally build an intermediate invalid state and rely on final normalization.\n- `storage: \"session\"` means the session has a session-file backing; it does not mean this tool wrote a durable custom entry.\n- Reload persistence differs by path:\n  - plain `todo_write` calls survive in transcript tool-result details;\n  - `/todo` command edits additionally append `customType: \"user_todo_edit\"` entries and inject a visible-to-model `<system-reminder>` developer message describing the manual edit.\n- On session resume, `AgentSession.#syncTodoPhasesFromBranch()` strips `completed` and `abandoned` tasks before restoring the cached list. The `/todo` command works around that by reading the latest transcript/custom-entry state so historical done/dropped tasks still appear to the user.\n- Tool availability is gated by `todo.enabled`, and the registry excludes it when `includeYield` is enabled (`packages/coding-agent/src/tools/index.ts`).\n- Subagents do not inherit `todo_write`; `packages/coding-agent/src/task/executor.ts` filters it out as a parent-owned tool.\n",
-	"tools/web_search.md": "# web_search\n\n> Run one web query through the first available search provider and return LLM-formatted answer, source URLs, and optional citations.\n\n> Note: the selectable, keyless `insane` provider uses native safe public routes for supported platforms. It is separate from the vendored `insane-search` compatibility path in `read`; that fallback is production-disabled even when `web.insaneFallback` is enabled. See `docs/tools/read.md`.\n\n## Source\n- Entry: `packages/coding-agent/src/web/search/index.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/web-search.md`\n- Key collaborators:\n  - `packages/coding-agent/src/web/search/provider.ts` — lazy provider registry; availability chain.\n  - `packages/coding-agent/src/web/search/types.ts` — unified `SearchResponse` / `SearchProviderError` types.\n  - `packages/coding-agent/src/web/search/render.ts` — TUI renderer details type.\n  - `packages/coding-agent/src/web/search/providers/base.ts` — provider interface and shared params contract.\n  - `packages/coding-agent/src/web/search/providers/utils.ts` — credential lookup; source normalization.\n  - `packages/coding-agent/src/web/search/providers/anthropic.ts` — Anthropic model web-search provider.\n  - `packages/coding-agent/src/web/search/providers/brave.ts` — Brave Search API adapter.\n  - `packages/coding-agent/src/web/search/providers/duckduckgo.ts` — keyless DuckDuckGo html/lite scrape adapter (permissionless default/fallback).\n  - `packages/coding-agent/src/web/search/providers/insane.ts` — keyless safe public-route adapter inspired by upstream `fivetaku/insane-search`.\n  - `packages/coding-agent/src/web/search/providers/openai-code.ts` — OpenAI code provider SSE adapter.\n  - `packages/coding-agent/src/web/search/providers/exa.ts` — Exa API adapter.\n  - `packages/coding-agent/src/web/search/providers/gemini.ts` — Gemini grounding SSE adapter.\n  - `packages/coding-agent/src/web/search/providers/jina.ts` — Jina Reader search adapter.\n  - `packages/coding-agent/src/web/search/providers/kagi.ts` — Kagi provider wrapper.\n  - `packages/coding-agent/src/web/search/providers/kimi.ts` — Kimi search adapter.\n  - `packages/coding-agent/src/web/search/providers/parallel.ts` — Parallel provider wrapper.\n  - `packages/coding-agent/src/web/search/providers/perplexity.ts` — Perplexity API / OAuth adapter.\n  - `packages/coding-agent/src/web/search/providers/searxng.ts` — self-hosted SearXNG adapter.\n  - `packages/coding-agent/src/web/search/providers/synthetic.ts` — Synthetic search adapter.\n  - `packages/coding-agent/src/web/search/providers/tavily.ts` — Tavily search adapter.\n  - `packages/coding-agent/src/web/search/providers/zai.ts` — Z.AI remote search adapter.\n  - `packages/coding-agent/src/web/parallel.ts` — Parallel search/extract HTTP client.\n  - `packages/coding-agent/src/web/kagi.ts` — Kagi HTTP client.\n  - `packages/coding-agent/src/tools/index.ts` — built-in tool registration and enable flag.\n\n## Inputs\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `query` | `string` | Yes | Search query. `executeSearch()` rewrites any `2020`-`2029` substring to the current year before dispatch. |\n| `recency` | `\"day\" \\| \"week\" \\| \"month\" \\| \"year\"` | No | Time filter. Only providers that implement it use it. Prompt text says Brave and Perplexity; code also maps it for Tavily and SearXNG. |\n| `limit` | `number` | No | Max results to return. Usually becomes the provider request's result-count parameter when `num_search_results` is absent. |\n| `max_tokens` | `number` | No | Passed through as `maxOutputTokens` / `max_tokens` only by Anthropic, Gemini, and Perplexity API-key mode. Ignored by the other providers. |\n| `temperature` | `number` | No | Passed through only by Anthropic, Gemini, and Perplexity API-key mode. Ignored by the other providers. |\n| `num_search_results` | `number` | No | Requested upstream search breadth. For most providers this is the same count used for returned sources. Perplexity is the only adapter that keeps it distinct from `limit`. |\n\n## Outputs\nThe tool returns a single text content block plus structured `details`.\n\n- `content`: `[{ type: \"text\", text: string }]`\n- `details`: `SearchRenderDetails` from `packages/coding-agent/src/web/search/render.ts`\n  - `response: SearchResponse`\n  - `error?: string`\n\n`text` is produced by `formatForLLM()` in `packages/coding-agent/src/web/search/index.ts`:\n\n- If `response.answer` exists, it is emitted first.\n- If sources exist, a `## Sources` section follows with a source count, then one entry per source:\n  - `[n] <title> (<formatted age or published date>)`\n  - `    <url>`\n  - optional snippet line truncated to 240 chars.\n- If citations exist, a `## Citations` section follows with URL/title plus optional cited text truncated to 240 chars.\n- If related questions exist, a `## Related` bullet list follows.\n- If search queries exist, a `Search queries: <n>` section follows, capped to the first 3 queries and 120 chars each.\n\nFailure output is not thrown at the tool boundary when at least one provider was attempted. Instead the tool returns:\n\n- `content[0].text = \"Error: ...\"`\n- `details.response.provider = <last attempted provider> | \"none\"`\n- `details.error = ...`\n\nStreaming: none. `WebSearchTool.execute()` does not forward its `_signal` argument into `executeSearch()`, so provider cancellation is only available to internal callers that place `signal` inside `SearchQueryParams`.\n\n## Flow\n1. `WebSearchTool.execute()` in `packages/coding-agent/src/web/search/index.ts` delegates directly to `executeSearch()`.\n2. `executeSearch()` resolves the provider list via a single `resolveProviderChain(authStorage, params.provider ?? \"auto\", activeModelProvider)` call. The active model's provider is threaded in from `WebSearchTool` (`this.#session.model?.provider`, falling back to parsing `getActiveModelString()`) and from the CustomTool path (`ctx.model?.provider`).\n3. `resolveProviderChain()` is active-model-gated, not credential-scanning:\n   - an explicitly preferred/selected provider that is `isAvailable()` becomes the primary;\n   - otherwise the active model's own native search (`MODEL_PROVIDER_TO_SEARCH` + `inferNativeProviderFromModel()`) becomes the primary, when that provider's canonical credentials exist (`isAvailable()`);\n   - failing that, **native-over-proxy** kicks in: `activeContextNativeId()` matches the active model's wire `api` (+ model-id family) to a native provider, and if the active model's OWN credential resolves (`getApiKey(ctx.provider, { baseUrl, modelId })`), that native provider is attempted reusing those credentials and `ctx.baseUrl`. Dispatch: `anthropic-messages`+`claude-*`→`anthropic`, `openai-responses`/`openai-completions`→`openai-compatible`, `google-generative-ai`+`gemini-*`→`gemini`;\n   - keyed standalone providers are never auto-selected — explicit selection only.\n4. DuckDuckGo (keyless, `isAvailable()` always true) is always appended as the terminal fallback, so a missing primary — or a primary runtime failure — still returns results with zero configuration. There is no longer a \"No web search provider configured\" path.\n5. For each provider in order, `executeSearch()` calls `provider.search()` with:\n   - `query` after year-rewrite,\n   - `limit`, `recency`, `temperature`, `maxOutputTokens`, `numSearchResults`,\n   - `systemPrompt` from `packages/coding-agent/src/prompts/tools/web-search.md`.\n6. On the first successful `SearchResponse`, `formatForLLM()` renders answer/sources/citations/related/search-queries into one text block and returns it with `details.response`.\n7. If a provider throws, `executeSearch()` records the error and tries the next provider. Fallback is sequential, with one exception: when DuckDuckGo is a non-primary chain member, `executeSearch()` fires it as a background hedge after `DDG_HEDGE_DELAY_MS` (3s). A successful primary aborts the hedge; a failing primary reuses the (typically already-settled) hedge result, collapsing fallback latency from `t(primary failure) + t(ddg)` to `max(t(primary failure), t(ddg))`.\n8. After all candidates fail, `formatProviderError()` normalizes the last error:\n   - Anthropic `404` becomes `Anthropic web search returned 404 (model or endpoint not found).`\n   - `401`/`403` become `<Provider> authorization failed ...` except Z.AI, which preserves its raw message.\n   - other `SearchProviderError`s surface `error.message`.\n9. If more than one provider was attempted, the final message is `All web search providers failed (<labels>). Last error: <message>`; otherwise it is just the normalized last error.\n\n## Modes / Variants\n- **Provider selection**\n  - **Forced provider**: internal callers may pass `provider`; an unavailable forced provider falls back to the chain (which always ends in DuckDuckGo) instead of hard-failing (`packages/coding-agent/src/web/search/index.ts`). This field is not in the model-facing schema.\n  - **Preferred provider**: `setPreferredSearchProvider()` sets a module-global default consumed by `resolveProviderChain()`. `packages/coding-agent/src/sdk/session.ts` and `packages/coding-agent/src/modes/controllers/selector-controller.ts` wire this from settings.\n  - **Tavily selection**: set `providers.webSearch` to `tavily` and provide `TAVILY_API_KEY` (or a stored Tavily provider credential). In `auto`, Tavily is not scanned just because an env key exists, so keyless/default behavior remains unchanged until Tavily is selected or listed as an available fallback.\n  - **Active-model-gated auto**: in `auto` mode, resolution first maps the active model's provider to its own native search via `MODEL_PROVIDER_TO_SEARCH` (`openai|openai-codex→codex`, `anthropic→anthropic`, `google|google-gemini-cli|google-antigravity|gemini→gemini`, `moonshot|kimi-code|kimi→kimi`, `zai`, `perplexity`, `synthetic`) and `inferNativeProviderFromModel()`, used when that provider's canonical creds exist. When no canonical native is selected, `activeContextNativeId()` drives native search through the active model's OWN credential + `baseUrl` (native-over-proxy), dispatched by wire `api`: `anthropic-messages`+`claude-*`→`anthropic` (reuses `ctx` key/baseUrl via `searchAnthropic`), `openai-responses`/`openai-completions`→`openai-compatible`, `google-generative-ai`+`gemini-*`→`gemini` (Generative Language `generateContent`). The native provider fails closed (and the chain falls through to DuckDuckGo) if the endpoint does not actually support web search. `SEARCH_PROVIDER_ORDER` no longer drives auto credential scanning — it is retained for explicit selection, labels, and CLI option lists.\n- **Provider adapters**\n  - **Insane** — `packages/coding-agent/src/web/search/providers/insane.ts`\n    - Availability: always available; no API key, OAuth, cookies, browser profile, subprocess, or auto-installed dependency.\n    - Querying: if the query is a supported public URL, tries deterministic no-auth public routes first; otherwise uses DuckDuckGo discovery and enriches supported result URLs through the same safe routes.\n    - Safe upstream concepts ported: Phase 0 public route table and route-attempt metadata for Reddit RSS, X/Twitter tweet-result/oEmbed/syndication, YouTube oEmbed/channel feed, and Hacker News Firebase item metadata.\n    - Explicitly not ported from upstream: TLS impersonation, Playwright/browser fallback, cookie warming/storage, CAPTCHA/paywall/login bypasses, credential storage, and auto dependency installation. Unsupported or blocked routes fail closed with a provider error.\n    - `limit` / `num_search_results`: collapsed together, clamped to `1..20`, default `10`.\n    - Output: `sources` only, with snippets annotated by the public route used and `searchQueries` containing compact route-attempt diagnostics.\n  - **Tavily** — `packages/coding-agent/src/web/search/providers/tavily.ts`\n    - Availability: API key from env or `agent.db` via `findCredential()`.\n    - Querying: POST `https://api.tavily.com/search`.\n    - `recency` maps to Tavily `time_range`; code explicitly keeps `topic` at default general scope instead of narrowing to news.\n    - `limit` / `num_search_results`: adapter uses `params.numSearchResults ?? params.limit`, clamped to `5..20` with default `5`.\n    - Output: `answer`, `sources`, `requestId`, `authMode: \"api_key\"`.\n  - **Perplexity** — `packages/coding-agent/src/web/search/providers/perplexity.ts`\n    - Availability: auth precedence is `PERPLEXITY_COOKIES` -> OAuth token in `agent.db` -> `PERPLEXITY_API_KEY` / `PPLX_API_KEY`.\n    - OAuth/cookie mode: POSTs to `https://www.perplexity.ai/rest/sse/perplexity_ask`, consumes SSE, merges partial events, extracts answer and source URLs, sets `authMode: \"oauth\"`.\n    - API-key mode: POSTs to `https://api.perplexity.ai/chat/completions` with `model: \"sonar-pro\"`, `search_mode: \"web\"`, `num_search_results`, optional `search_recency_filter`, `max_tokens`, `temperature`.\n    - `num_search_results` controls upstream API breadth only in API-key mode. `limit` is preserved separately as `num_results` and slices returned `sources` after parsing in both auth modes.\n    - Output may include `answer`, `sources`, `citations`, `usage`, `model`, `requestId`, `authMode`.\n  - **Brave** — `packages/coding-agent/src/web/search/providers/brave.ts`\n    - Availability: `BRAVE_API_KEY` only.\n    - Querying: GET `https://api.search.brave.com/res/v1/web/search` with `count`, `extra_snippets=true`, and `freshness=pd|pw|pm|py` for `recency`.\n    - `limit` / `num_search_results`: `params.numSearchResults ?? params.limit`, clamped to `1..20`, default `10`.\n    - Output: `sources`, `requestId`.\n  - **Jina** — `packages/coding-agent/src/web/search/providers/jina.ts`\n    - Availability: `JINA_API_KEY` only.\n    - Querying: GET-like fetch to `https://s.jina.ai/<encoded query>` with bearer auth.\n    - Ignores `recency`, `max_tokens`, and `temperature`.\n    - `limit` / `num_search_results`: adapter slices sources to `params.numSearchResults ?? params.limit` when provided; otherwise returns all payload items.\n    - Output: `sources` only.\n  - **Kimi** — `packages/coding-agent/src/web/search/providers/kimi.ts`\n    - Availability: `MOONSHOT_SEARCH_API_KEY`, `KIMI_SEARCH_API_KEY`, `MOONSHOT_API_KEY`, or `agent.db` credentials for `moonshot` / `kimi-code`.\n    - Querying: POST to `MOONSHOT_SEARCH_BASE_URL` / `KIMI_SEARCH_BASE_URL` / default `https://api.kimi.com/coding/v1/search` with `text_query`, `limit`, `enable_page_crawling`, `timeout_seconds: 30`.\n    - `limit` / `num_search_results`: `params.numSearchResults ?? params.limit`, clamped to `1..20`, default `10`.\n    - Output: `sources`, `requestId`.\n  - **Anthropic** — `packages/coding-agent/src/web/search/providers/anthropic.ts`\n    - Availability: `findAnthropicAuth()` from `@gajae-code/ai`.\n    - Querying: Anthropic model Messages API with web-search tool enabled.\n    - `max_tokens` and `temperature` pass through.\n    - `limit` and `num_search_results` are collapsed together before dispatch: `num_results = params.numSearchResults ?? params.limit`.\n    - Output may include `answer`, `sources`, `citations`, `searchQueries`, `usage.searchRequests`, `model`, `requestId`.\n    - When a search ran (`web_search_tool_result` / `server_tool_use` / `usage.server_tool_use.web_search_requests`) but only inline citations were emitted, sources are recovered from the answer text via `providers/text-citations.ts`. If no search ran and nothing is grounded, it fails closed (`424`) so the chain falls through to DuckDuckGo.\n  - **Gemini** — `packages/coding-agent/src/web/search/providers/gemini.ts`\n    - Availability: OAuth credentials in `agent.db` for `google-gemini-cli` or `google-antigravity`.\n    - Querying: SSE `streamGenerateContent` call with Google Search grounding enabled. Antigravity auth tries two fallback endpoints and retries `401/403/400 invalid auth` once after token refresh; `429/5xx` retry with exponential backoff and server-provided retry delay, capped by a `30 * 1000` ms rate-limit budget (the chain always terminates in keyless DuckDuckGo, so a rate-limited Gemini fails through fast instead of parking the chain).\n    - `max_tokens` and `temperature` pass through as `generationConfig.maxOutputTokens` / `generationConfig.temperature`.\n    - `limit` and `num_search_results` are collapsed together before dispatch.\n    - Output may include `answer`, `sources`, `citations`, `searchQueries`, `usage`, `model`.\n  - **OpenAI-compatible** — `packages/coding-agent/src/web/search/providers/openai-compatible.ts`\n    - Reuses the active model's resolved credentials, headers, base URL, and wire model ID.\n    - Requests `stream: true` from `/responses` with the `web_search` tool, including when the model normally uses Chat Completions. Only HTTP `404`/`405` falls back to `/chat/completions` with `web_search_options` and streaming enabled.\n    - Accepts JSON responses and consumes SSE responses incrementally. Responses results use the completed response snapshot, or completed output-item events when that snapshot omits its output; Chat results accumulate text and citation annotations. Failed, incomplete, malformed, or prematurely ended streams are rejected rather than returned as partial search results.\n    - Only `url_citation` annotations count as grounding. Inline links are recovered only when `web_search_call` or positive `tool_usage.web_search.num_requests` proves that a search ran; ordinary model answers with ungrounded URLs fail closed (`424`).\n    - Caller cancellation and the LLM search timeout cover response-body consumption as well as the HTTP request.\n  - **OpenAI code** — `packages/coding-agent/src/web/search/providers/openai-code.ts`\n    - Availability: non-expired OAuth credential for `openai-code` in `agent.db`.\n    - Querying: SSE POST to `https://chatgpt.com/backend-api/openai-code/responses` with `tool_choice: { type: \"web_search\" }` and `search_context_size: \"high\"` by default.\n    - Ignores `recency`, `max_tokens`, and `temperature` in this tool path.\n    - `limit` and `num_search_results` are collapsed together before dispatch.\n    - Output may include `answer`, `sources`, `usage`, `model`, `requestId`. If the streamed response has no `url_citation` annotations, the adapter falls back to scraping markdown links and bare URLs from the answer text.\n  - **Z.AI** — `packages/coding-agent/src/web/search/providers/zai.ts`\n    - Availability: env or `agent.db` credential for `zai`.\n    - Querying: JSON-RPC `tools/call` against the Z.AI `web_search_prime` search endpoint.\n    - Fallback chain inside the provider: tries `{query,count}`, then `{search_query,count}`, then `{search_query, search_engine:\"search-prime\", count}` when earlier attempts fail with argument-shape errors.\n    - `limit` and `num_search_results` are collapsed together before dispatch.\n    - Output may include parsed free-text `answer`, `sources`, `requestId`.\n  - **Exa** — `packages/coding-agent/src/web/search/providers/exa.ts`\n    - Availability: requires `EXA_API_KEY` and settings must not disable `exa.enabled` or `exa.enableSearch`.\n    - Querying: POST `https://api.exa.ai/search` with `EXA_API_KEY`. No no-key fallback is used.\n    - `limit` and `num_search_results` are collapsed together before dispatch.\n    - Output: synthesized `answer` from up to 3 result summaries, `sources`, `requestId`.\n  - **Parallel** — `packages/coding-agent/src/web/search/providers/parallel.ts`, `packages/coding-agent/src/web/parallel.ts`\n    - Availability: env or `agent.db` credential for `parallel`.\n    - Querying: POST `https://api.parallel.ai/v1beta/search` with `objective=query`, `search_queries=[query]`, `mode:\"fast\"`, `max_chars_per_result: 10000`, beta header `search-extract-2025-10-10`.\n    - There is no provider fan-out here despite the name; the current adapter always sends a one-element `search_queries` array.\n    - `limit` and `num_search_results` are collapsed together before dispatch, clamped to `1..40`, default `10`.\n    - Output: `sources`, `requestId`.\n  - **Kagi** — `packages/coding-agent/src/web/search/providers/kagi.ts`, `packages/coding-agent/src/web/kagi.ts`\n    - Availability: env or `agent.db` credential for `kagi`.\n    - Querying: GET `https://kagi.com/api/v0/search?q=<query>&limit=<n>` with `Authorization: Bot <key>`.\n    - `limit` and `num_search_results` are collapsed together before dispatch, clamped to `1..40`, default `10`.\n    - Output: `sources`, `relatedQuestions`, `requestId`.\n  - **Synthetic** — `packages/coding-agent/src/web/search/providers/synthetic.ts`\n    - Availability: env or `agent.db` credential for `synthetic`.\n    - Querying: POST `https://api.synthetic.new/v2/search` with `{ query }`.\n    - Ignores `recency`, `max_tokens`, and `temperature`.\n    - `limit` and `num_search_results` are collapsed together before dispatch.\n    - Output: `sources` only.\n  - **SearXNG** — `packages/coding-agent/src/web/search/providers/searxng.ts`\n    - Availability: endpoint from `searxng.endpoint` setting or `SEARXNG_ENDPOINT` env.\n    - Querying: GET `<endpoint>/search?format=json&q=...`; optional settings add `categories` and `language`.\n    - Auth precedence: Basic auth (`searxng.basicUsername` / `searxng.basicPassword` or env equivalents) over bearer token (`searxng.token` / `SEARXNG_TOKEN`). Basic credentials are validated for RFC 7617 restrictions.\n    - `recency` maps to `time_range`; `week` is downgraded to `month` because SearXNG does not support week.\n    - `limit` and `num_search_results` are collapsed together before dispatch, clamped to `1..20`, default `10`.\n    - Output: `sources`, `relatedQuestions` from `suggestions`.\n\n## Side Effects\n- Network\n  - Calls one or more external search providers over HTTPS until one succeeds or all fail.\n  - Provider-specific transports include JSON POST, JSON GET, SSE streaming (Perplexity OAuth/API, Gemini, OpenAI code), and JSON-RPC over HTTP (Z.AI).\n- Subprocesses / native bindings\n  - None.\n- Session state (transcript, memory, jobs, checkpoints, registries)\n  - Uses a module-global provider-instance cache in `packages/coding-agent/src/web/search/provider.ts`.\n  - Uses a WeakMap-keyed resolved-chain cache (per AuthStorage, 60s TTL) in the same file; `WebSearchTool`'s constructor prewarms it via `prewarmSearchProviders()`.\n  - Uses a module-global preferred-provider setting in the same file.\n  - `packages/coding-agent/src/tools/index.ts` gates tool availability behind `session.settings.get(\"web_search.enabled\")`.\n- Background work / cancellation\n  - Many provider adapters accept `AbortSignal`, but `WebSearchTool.execute()` does not pass its `_signal` into `executeSearch()`. Internal callers can still use cancellation by calling `runSearchQuery()` / `executeSearch()` with `signal` embedded in params.\n\n## Limits & Caps\n- Provider registry size: 16 providers (`SEARCH_PROVIDER_ORDER` in `packages/coding-agent/src/web/search/provider.ts`), including the keyless `duckduckgo` default/fallback and selectable `insane` safe-public-route provider. `SEARCH_PROVIDER_ORDER` no longer drives auto selection — see \"Active-model-gated auto\" above.\n- Insane result count: default `10`, max `20` (`packages/coding-agent/src/web/search/providers/insane.ts`).\n- Insane public-route response bodies are limited to 1 MiB after transfer/content decoding; oversized declared or streamed bodies are cancelled and that route fails closed (`packages/coding-agent/src/web/search/providers/insane.ts`).\n- `formatForLLM()` truncates source snippets and citation text to 240 chars (`packages/coding-agent/src/web/search/index.ts`).\n- `formatForLLM()` emits at most 3 search queries, each truncated to 120 chars (`packages/coding-agent/src/web/search/index.ts`).\n- Brave result count: default `10`, max `20` (`DEFAULT_NUM_RESULTS`, `MAX_NUM_RESULTS` in `packages/coding-agent/src/web/search/providers/brave.ts`).\n- Tavily result count: default `5`, max `20` (`packages/coding-agent/src/web/search/providers/tavily.ts`).\n- Kimi result count: default `10`, max `20`; request timeout field fixed to `30` seconds (`packages/coding-agent/src/web/search/providers/kimi.ts`).\n- Parallel result count: default `10`, max `40`; per-result excerpt cap `10_000` chars (`packages/coding-agent/src/web/search/providers/parallel.ts`, `packages/coding-agent/src/web/parallel.ts`).\n- Kagi result count: default `10`, max `40` (`packages/coding-agent/src/web/search/providers/kagi.ts`).\n- SearXNG result count: default `10`, max `20` (`packages/coding-agent/src/web/search/providers/searxng.ts`).\n- Perplexity API-key mode defaults: `max_tokens = 8192`, `temperature = 0.2`, `num_search_results = 10` (`packages/coding-agent/src/web/search/providers/perplexity.ts`).\n- Anthropic defaults: model `anthropic-model-haiku-4-5`, `DEFAULT_MAX_TOKENS = 4096` when the provider omits `max_tokens` (`packages/coding-agent/src/web/search/providers/anthropic.ts`).\n- Gemini retries: up to `3` retries per endpoint, base delay `1000` ms, rate-limit delay budget `30 * 1000` ms (`packages/coding-agent/src/web/search/providers/gemini.ts`).\n- Hard timeouts are class-based (`packages/coding-agent/src/web/search/providers/utils.ts`): pure search APIs `SEARCH_API_TIMEOUT_MS = 15_000`, LLM-mediated providers `SEARCH_LLM_TIMEOUT_MS = 120_000`, legacy fallback `SEARCH_HARD_TIMEOUT_MS = 300_000` for untagged call sites. Kimi uses an explicit `KIMI_HARD_TIMEOUT_MS = 35_000` aligned with its upstream `timeout_seconds: 30` budget. An explicitly configured `web_search.timeout` overrides class defaults (`applyConfiguredSearchTimeout()` gates on `settings.has`, so the schema default 300 does not reinstall a uniform ceiling).\n- DuckDuckGo hedge delay: `DDG_HEDGE_DELAY_MS = 3_000` (`packages/coding-agent/src/web/search/index.ts`).\n- Resolved provider chains are cached per `AuthStorage` instance for `CHAIN_CACHE_TTL_MS = 60_000`, keyed on the storage credential generation so login/logout invalidates immediately; `setPreferredSearchProvider()` / `setSearchFallbackProviders()` clear the cache (`packages/coding-agent/src/web/search/provider.ts`).\n\n## Errors\n- There is no \"no provider configured\" case: DuckDuckGo (keyless) is always appended as the terminal fallback, so the chain is never empty.\n- Tool-level all-failed case also returns a normal tool result with `Error: ...`; failures are summarized from the last attempted provider.\n- Provider adapters usually throw `SearchProviderError(provider, message, status)` for HTTP or protocol failures.\n- Availability probes intentionally swallow lookup errors and report `false` in many providers via `isApiKeyAvailable()`.\n- Per-provider notable failures:\n  - Anthropic: missing credentials throw a plain `Error`; a `404` is remapped to a special final message by `formatProviderError()`.\n  - Perplexity: missing auth throws a plain `Error`; OAuth stream `error_code` events become `SearchProviderError(\"perplexity\", ...)`.\n  - Gemini: auth refresh, endpoint fallback, and retry logic are internal; final exhausted failures surface as `SearchProviderError(\"gemini\", ...)`.\n  - OpenAI code and Gemini both fail if the HTTP response has no body after a `200`.\n  - Z.AI treats malformed SSE/JSON-RPC payloads as provider errors and retries only argument-shape failures across request variants.\n  - SearXNG `findAuth()` can throw configuration errors before any HTTP call if Basic auth fields are incomplete or invalid.\n\n## Notes\n- The model-facing schema does not expose `provider`, but internal callers can force one through `SearchQueryParams`.\n- `resolveProviderChain()` lazily imports provider modules and caches singleton instances. Just asking for labels via `getSearchProviderLabel()` does not trigger those imports.\n- Most providers treat `limit` and `num_search_results` as the same number because adapters pass `params.numSearchResults ?? params.limit`. Perplexity is the only implementation that preserves both concepts.\n- The prompt says `recency` is for Brave and Perplexity, but code also implements it for Tavily and SearXNG.\n- The year rewrite in `executeSearch()` is blunt: any `2020`-`2029` substring is replaced with the current year.\n- `packages/coding-agent/src/config/settings-schema.ts` exposes provider preferences for `auto`, `duckduckgo`, `insane`, `exa`, `brave`, `jina`, `kimi`, `perplexity`, `anthropic`, `gemini`, `codex`, `xai`, `zai`, `tavily`, `kagi`, `synthetic`, `parallel`, and `searxng`.\n- Exa availability fails closed unless `EXA_API_KEY` is present and Exa settings remain enabled.\n",
+	"tools/web_search.md": "# web_search\n\n> Run one web query through the first available search provider and return LLM-formatted answer, source URLs, and optional citations.\n\n> Note: the selectable, keyless `insane` provider uses native safe public routes for supported platforms. It is separate from the vendored `insane-search` compatibility path in `read`; that fallback is production-disabled even when `web.insaneFallback` is enabled. See `docs/tools/read.md`.\n\n## Source\n- Entry: `packages/coding-agent/src/web/search/index.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/web-search.md`\n- Key collaborators:\n  - `packages/coding-agent/src/web/search/provider.ts` — lazy provider registry; availability chain.\n  - `packages/coding-agent/src/web/search/types.ts` — unified `SearchResponse` / `SearchProviderError` types.\n  - `packages/coding-agent/src/web/search/render.ts` — TUI renderer details type.\n  - `packages/coding-agent/src/web/search/providers/base.ts` — provider interface and shared params contract.\n  - `packages/coding-agent/src/web/search/providers/utils.ts` — credential lookup; source normalization.\n  - `packages/coding-agent/src/web/search/providers/anthropic.ts` — Anthropic model web-search provider.\n  - `packages/coding-agent/src/web/search/providers/brave.ts` — Brave Search API adapter.\n  - `packages/coding-agent/src/web/search/providers/duckduckgo.ts` — keyless DuckDuckGo html/lite scrape adapter (permissionless default/fallback).\n  - `packages/coding-agent/src/web/search/providers/insane.ts` — keyless safe public-route adapter inspired by upstream `fivetaku/insane-search`.\n  - `packages/coding-agent/src/web/search/providers/openai-code.ts` — OpenAI code provider SSE adapter.\n  - `packages/coding-agent/src/web/search/providers/exa.ts` — Exa API adapter.\n  - `packages/coding-agent/src/web/search/providers/gemini.ts` — Gemini grounding SSE adapter.\n  - `packages/coding-agent/src/web/search/providers/jina.ts` — Jina Reader search adapter.\n  - `packages/coding-agent/src/web/search/providers/kagi.ts` — Kagi provider wrapper.\n  - `packages/coding-agent/src/web/search/providers/kimi.ts` — Kimi search adapter.\n  - `packages/coding-agent/src/web/search/providers/parallel.ts` — Parallel provider wrapper.\n  - `packages/coding-agent/src/web/search/providers/perplexity.ts` — Perplexity API / OAuth adapter.\n  - `packages/coding-agent/src/web/search/providers/searxng.ts` — self-hosted SearXNG adapter.\n  - `packages/coding-agent/src/web/search/providers/synthetic.ts` — Synthetic search adapter.\n  - `packages/coding-agent/src/web/search/providers/tavily.ts` — Tavily search adapter.\n  - `packages/coding-agent/src/web/search/providers/zai.ts` — Z.AI remote search adapter.\n  - `packages/coding-agent/src/web/parallel.ts` — Parallel search/extract HTTP client.\n  - `packages/coding-agent/src/web/kagi.ts` — Kagi HTTP client.\n  - `packages/coding-agent/src/tools/index.ts` — built-in tool registration and enable flag.\n\n## Inputs\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `query` | `string` | Yes | Search query. `executeSearch()` rewrites any `2020`-`2029` substring to the current year before dispatch. |\n| `recency` | `\"day\" \\| \"week\" \\| \"month\" \\| \"year\"` | No | Time filter. Only providers that implement it use it. Prompt text says Brave and Perplexity; code also maps it for Tavily and SearXNG. |\n| `limit` | `number` | No | Max results to return. Usually becomes the provider request's result-count parameter when `num_search_results` is absent. |\n| `max_tokens` | `number` | No | Passed through as `maxOutputTokens` / `max_tokens` only by Anthropic, Gemini, and Perplexity API-key mode. Ignored by the other providers. |\n| `temperature` | `number` | No | Passed through only by Anthropic, Gemini, and Perplexity API-key mode. Ignored by the other providers. |\n| `num_search_results` | `number` | No | Requested upstream search breadth. For most providers this is the same count used for returned sources. Perplexity is the only adapter that keeps it distinct from `limit`. |\n\n## Outputs\nThe tool returns a single text content block plus structured `details`.\n\n- `content`: `[{ type: \"text\", text: string }]`\n- `details`: `SearchRenderDetails` from `packages/coding-agent/src/web/search/render.ts`\n  - `response: SearchResponse`\n  - `error?: string`\n\n`text` is produced by `formatSearchResponseForLlm()` in `packages/coding-agent/src/web/search/index.ts`:\n\n- If `response.answer` exists, it is emitted first.\n- If sources exist, a `## Sources` section follows with a source count, then one entry per source:\n  - `[n] <title> (<formatted age or published date>)`\n  - `    <url>`\n  - optional snippet line truncated to 240 chars.\n- If citations exist, a `## Citations` section follows with URL/title plus optional cited text truncated to 240 chars.\n- If related questions exist, a `## Related` bullet list follows.\n- If search queries exist, a `Search queries: <n>` section follows, capped to the first 3 queries and 120 chars each.\n\nFailure output is not thrown at the tool boundary when at least one provider was attempted. Instead the tool returns:\n\n- `content[0].text = \"Error: ...\"`\n- `details.response.provider = <last attempted provider> | \"none\"`\n- `details.error = ...`\n\nStreaming: none. `WebSearchTool.execute()` does not forward its `_signal` argument into `executeSearch()`, so provider cancellation is only available to internal callers that place `signal` inside `SearchQueryParams`.\n\n## Flow\n1. `WebSearchTool.execute()` in `packages/coding-agent/src/web/search/index.ts` delegates directly to `executeSearch()`.\n2. `executeSearch()` resolves the provider list via a single `resolveProviderChain(authStorage, params.provider ?? \"auto\", activeModelProvider)` call. The active model's provider is threaded in from `WebSearchTool` (`this.#session.model?.provider`, falling back to parsing `getActiveModelString()`) and from the CustomTool path (`ctx.model?.provider`).\n3. `resolveProviderChain()` is active-model-gated, not credential-scanning:\n   - an explicitly preferred/selected provider that is `isAvailable()` becomes the primary;\n   - otherwise the active model's own native search (`MODEL_PROVIDER_TO_SEARCH` + `inferNativeProviderFromModel()`) becomes the primary, when that provider's canonical credentials exist (`isAvailable()`);\n   - failing that, **native-over-proxy** kicks in: `activeContextNativeId()` matches the active model's wire `api` (+ model-id family) to a native provider, and if the active model's OWN credential resolves (`getApiKey(ctx.provider, { baseUrl, modelId })`), that native provider is attempted reusing those credentials and `ctx.baseUrl`. Dispatch: `anthropic-messages`+`claude-*`→`anthropic`, `openai-responses`/`openai-completions`→`openai-compatible`, `google-generative-ai`+`gemini-*`→`gemini`;\n   - keyed standalone providers are never auto-selected — explicit selection only.\n4. DuckDuckGo (keyless, `isAvailable()` always true) is always appended as the terminal fallback, so a missing primary — or a primary runtime failure — still returns results with zero configuration. There is no longer a \"No web search provider configured\" path.\n5. For each provider in order, `executeSearch()` calls `provider.search()` with:\n   - `query` after year-rewrite,\n   - `limit`, `recency`, `temperature`, `maxOutputTokens`, `numSearchResults`,\n   - `systemPrompt` from `packages/coding-agent/src/prompts/tools/web-search.md`.\n6. On the first successful `SearchResponse`, `formatSearchResponseForLlm()` renders answer/sources/citations/related/search-queries into one text block and returns it with `details.response`.\n7. If a provider throws, `executeSearch()` records the error and tries the next provider. Fallback is sequential, with one exception: when DuckDuckGo is a non-primary chain member, `executeSearch()` fires it as a background hedge after `DDG_HEDGE_DELAY_MS` (3s). A successful primary aborts the hedge; a failing primary reuses the (typically already-settled) hedge result, collapsing fallback latency from `t(primary failure) + t(ddg)` to `max(t(primary failure), t(ddg))`.\n8. After all candidates fail, `formatProviderError()` normalizes the last error:\n   - Anthropic `404` becomes `Anthropic web search returned 404 (model or endpoint not found).`\n   - `401`/`403` become `<Provider> authorization failed ...` except Z.AI, which preserves its raw message.\n   - other `SearchProviderError`s surface `error.message`.\n9. If more than one provider was attempted, the final message is `All web search providers failed (<labels>). Last error: <message>`; otherwise it is just the normalized last error.\n\n## Modes / Variants\n- **Provider selection**\n  - **Forced provider**: internal callers may pass `provider`; an unavailable forced provider falls back to the chain (which always ends in DuckDuckGo) instead of hard-failing (`packages/coding-agent/src/web/search/index.ts`). This field is not in the model-facing schema.\n  - **Preferred provider**: `setPreferredSearchProvider()` sets a module-global default consumed by `resolveProviderChain()`. `packages/coding-agent/src/sdk/session.ts` and `packages/coding-agent/src/modes/controllers/selector-controller.ts` wire this from settings.\n  - **Tavily selection**: set `providers.webSearch` to `tavily` and provide `TAVILY_API_KEY` (or a stored Tavily provider credential). In `auto`, Tavily is not scanned just because an env key exists, so keyless/default behavior remains unchanged until Tavily is selected or listed as an available fallback.\n  - **Active-model-gated auto**: in `auto` mode, resolution first maps the active model's provider to its own native search via `MODEL_PROVIDER_TO_SEARCH` (`openai|openai-codex→codex`, `anthropic→anthropic`, `google|google-gemini-cli|google-antigravity|gemini→gemini`, `moonshot|kimi-code|kimi→kimi`, `zai`, `perplexity`, `synthetic`) and `inferNativeProviderFromModel()`, used when that provider's canonical creds exist. When no canonical native is selected, `activeContextNativeId()` drives native search through the active model's OWN credential + `baseUrl` (native-over-proxy), dispatched by wire `api`: `anthropic-messages`+`claude-*`→`anthropic` (reuses `ctx` key/baseUrl via `searchAnthropic`), `openai-responses`/`openai-completions`→`openai-compatible`, `google-generative-ai`+`gemini-*`→`gemini` (Generative Language `generateContent`). The native provider fails closed (and the chain falls through to DuckDuckGo) if the endpoint does not actually support web search. `SEARCH_PROVIDER_ORDER` no longer drives auto credential scanning — it is retained for explicit selection, labels, and CLI option lists.\n- **Provider adapters**\n  - **Insane** — `packages/coding-agent/src/web/search/providers/insane.ts`\n    - Availability: always available; no API key, OAuth, cookies, browser profile, subprocess, or auto-installed dependency.\n    - Querying: if the query is a supported public URL, tries deterministic no-auth public routes first; otherwise uses DuckDuckGo discovery and enriches supported result URLs through the same safe routes.\n    - Safe upstream concepts ported: Phase 0 public route table and route-attempt metadata for Reddit RSS, X/Twitter tweet-result/oEmbed/syndication, YouTube oEmbed/channel feed, and Hacker News Firebase item metadata.\n    - Explicitly not ported from upstream: TLS impersonation, Playwright/browser fallback, cookie warming/storage, CAPTCHA/paywall/login bypasses, credential storage, and auto dependency installation. Unsupported or blocked routes fail closed with a provider error.\n    - `limit` / `num_search_results`: collapsed together, clamped to `1..20`, default `10`.\n    - Output: `sources` only, with snippets annotated by the public route used and `searchQueries` containing compact route-attempt diagnostics.\n  - **Tavily** — `packages/coding-agent/src/web/search/providers/tavily.ts`\n    - Availability: API key from env or `agent.db` via `findCredential()`.\n    - Querying: POST `https://api.tavily.com/search`.\n    - `recency` maps to Tavily `time_range`; code explicitly keeps `topic` at default general scope instead of narrowing to news.\n    - `limit` / `num_search_results`: adapter uses `params.numSearchResults ?? params.limit`, clamped to `5..20` with default `5`.\n    - Output: `answer`, `sources`, `requestId`, `authMode: \"api_key\"`.\n  - **Perplexity** — `packages/coding-agent/src/web/search/providers/perplexity.ts`\n    - Availability: auth precedence is `PERPLEXITY_COOKIES` -> OAuth token in `agent.db` -> `PERPLEXITY_API_KEY` / `PPLX_API_KEY`.\n    - OAuth/cookie mode: POSTs to `https://www.perplexity.ai/rest/sse/perplexity_ask`, consumes SSE, merges partial events, extracts answer and source URLs, sets `authMode: \"oauth\"`.\n    - API-key mode: POSTs to `https://api.perplexity.ai/chat/completions` with `model: \"sonar-pro\"`, `search_mode: \"web\"`, `num_search_results`, optional `search_recency_filter`, `max_tokens`, `temperature`.\n    - `num_search_results` controls upstream API breadth only in API-key mode. `limit` is preserved separately as `num_results` and slices returned `sources` after parsing in both auth modes.\n    - Output may include `answer`, `sources`, `citations`, `usage`, `model`, `requestId`, `authMode`.\n  - **Brave** — `packages/coding-agent/src/web/search/providers/brave.ts`\n    - Availability: `BRAVE_API_KEY` only.\n    - Querying: GET `https://api.search.brave.com/res/v1/web/search` with `count`, `extra_snippets=true`, and `freshness=pd|pw|pm|py` for `recency`.\n    - `limit` / `num_search_results`: `params.numSearchResults ?? params.limit`, clamped to `1..20`, default `10`.\n    - Output: `sources`, `requestId`.\n  - **Jina** — `packages/coding-agent/src/web/search/providers/jina.ts`\n    - Availability: `JINA_API_KEY` only.\n    - Querying: GET-like fetch to `https://s.jina.ai/<encoded query>` with bearer auth.\n    - Ignores `recency`, `max_tokens`, and `temperature`.\n    - `limit` / `num_search_results`: adapter slices sources to `params.numSearchResults ?? params.limit` when provided; otherwise returns all payload items.\n    - Output: `sources` only.\n  - **Kimi** — `packages/coding-agent/src/web/search/providers/kimi.ts`\n    - Availability: `MOONSHOT_SEARCH_API_KEY`, `KIMI_SEARCH_API_KEY`, `MOONSHOT_API_KEY`, or `agent.db` credentials for `moonshot` / `kimi-code`.\n    - Querying: POST to `MOONSHOT_SEARCH_BASE_URL` / `KIMI_SEARCH_BASE_URL` / default `https://api.kimi.com/coding/v1/search` with `text_query`, `limit`, `enable_page_crawling`, `timeout_seconds: 30`.\n    - `limit` / `num_search_results`: `params.numSearchResults ?? params.limit`, clamped to `1..20`, default `10`.\n    - Output: `sources`, `requestId`.\n  - **Anthropic** — `packages/coding-agent/src/web/search/providers/anthropic.ts`\n    - Availability: `findAnthropicAuth()` from `@gajae-code/ai`.\n    - Querying: Anthropic model Messages API with web-search tool enabled.\n    - `max_tokens` and `temperature` pass through.\n    - `limit` and `num_search_results` are collapsed together before dispatch: `num_results = params.numSearchResults ?? params.limit`.\n    - Output may include `answer`, `sources`, `citations`, `searchQueries`, `usage.searchRequests`, `model`, `requestId`.\n    - When a search ran (`web_search_tool_result` / `server_tool_use` / `usage.server_tool_use.web_search_requests`) but only inline citations were emitted, sources are recovered from the answer text via `providers/text-citations.ts`. If no search ran and nothing is grounded, it fails closed (`424`) so the chain falls through to DuckDuckGo.\n  - **Gemini** — `packages/coding-agent/src/web/search/providers/gemini.ts`\n    - Availability: OAuth credentials in `agent.db` for `google-gemini-cli` or `google-antigravity`.\n    - Querying: SSE `streamGenerateContent` call with Google Search grounding enabled. Antigravity auth tries two fallback endpoints and retries `401/403/400 invalid auth` once after token refresh; `429/5xx` retry with exponential backoff and server-provided retry delay, capped by a `30 * 1000` ms rate-limit budget (the chain always terminates in keyless DuckDuckGo, so a rate-limited Gemini fails through fast instead of parking the chain).\n    - `max_tokens` and `temperature` pass through as `generationConfig.maxOutputTokens` / `generationConfig.temperature`.\n    - `limit` and `num_search_results` are collapsed together before dispatch.\n    - Output may include `answer`, `sources`, `citations`, `searchQueries`, `usage`, `model`.\n  - **OpenAI-compatible** — `packages/coding-agent/src/web/search/providers/openai-compatible.ts`\n    - Reuses the active model's resolved credentials, headers, base URL, and wire model ID.\n    - Requests `stream: true` from `/responses` with the `web_search` tool, including when the model normally uses Chat Completions. Only HTTP `404`/`405` falls back to `/chat/completions` with `web_search_options` and streaming enabled.\n    - Accepts JSON responses and consumes SSE responses incrementally. Responses results use the completed response snapshot, or completed output-item events when that snapshot omits its output; Chat results accumulate text and citation annotations. Failed, incomplete, malformed, or prematurely ended streams are rejected rather than returned as partial search results.\n    - Only `url_citation` annotations count as grounding. Inline links are recovered only when `web_search_call` or positive `tool_usage.web_search.num_requests` proves that a search ran; ordinary model answers with ungrounded URLs fail closed (`424`).\n    - Caller cancellation and the LLM search timeout cover response-body consumption as well as the HTTP request.\n  - **OpenAI code** — `packages/coding-agent/src/web/search/providers/openai-code.ts`\n    - Availability: non-expired OAuth credential for `openai-code` in `agent.db`.\n    - Querying: SSE POST to `https://chatgpt.com/backend-api/openai-code/responses` with `tool_choice: { type: \"web_search\" }` and `search_context_size: \"high\"` by default.\n    - Ignores `recency`, `max_tokens`, and `temperature` in this tool path.\n    - `limit` and `num_search_results` are collapsed together before dispatch.\n    - Output may include `answer`, `sources`, `usage`, `model`, `requestId`. If the streamed response has no `url_citation` annotations, the adapter falls back to scraping markdown links and bare URLs from the answer text.\n  - **Z.AI** — `packages/coding-agent/src/web/search/providers/zai.ts`\n    - Availability: env or `agent.db` credential for `zai`.\n    - Querying: JSON-RPC `tools/call` against the Z.AI `web_search_prime` search endpoint.\n    - Fallback chain inside the provider: tries `{query,count}`, then `{search_query,count}`, then `{search_query, search_engine:\"search-prime\", count}` when earlier attempts fail with argument-shape errors.\n    - `limit` and `num_search_results` are collapsed together before dispatch.\n    - Output may include parsed free-text `answer`, `sources`, `requestId`.\n  - **Exa** — `packages/coding-agent/src/web/search/providers/exa.ts`\n    - Availability: requires `EXA_API_KEY` and settings must not disable `exa.enabled` or `exa.enableSearch`.\n    - Querying: POST `https://api.exa.ai/search` with `EXA_API_KEY`. No no-key fallback is used.\n    - `limit` and `num_search_results` are collapsed together before dispatch.\n    - Output: synthesized `answer` from up to 3 result summaries, `sources`, `requestId`.\n  - **Parallel** — `packages/coding-agent/src/web/search/providers/parallel.ts`, `packages/coding-agent/src/web/parallel.ts`\n    - Availability: env or `agent.db` credential for `parallel`.\n    - Querying: POST `https://api.parallel.ai/v1beta/search` with `objective=query`, `search_queries=[query]`, `mode:\"fast\"`, `max_chars_per_result: 10000`, beta header `search-extract-2025-10-10`.\n    - There is no provider fan-out here despite the name; the current adapter always sends a one-element `search_queries` array.\n    - `limit` and `num_search_results` are collapsed together before dispatch, clamped to `1..40`, default `10`.\n    - Output: `sources`, `requestId`.\n  - **Kagi** — `packages/coding-agent/src/web/search/providers/kagi.ts`, `packages/coding-agent/src/web/kagi.ts`\n    - Availability: env or `agent.db` credential for `kagi`.\n    - Querying: GET `https://kagi.com/api/v0/search?q=<query>&limit=<n>` with `Authorization: Bot <key>`.\n    - `limit` and `num_search_results` are collapsed together before dispatch, clamped to `1..40`, default `10`.\n    - Output: `sources`, `relatedQuestions`, `requestId`.\n  - **Synthetic** — `packages/coding-agent/src/web/search/providers/synthetic.ts`\n    - Availability: env or `agent.db` credential for `synthetic`.\n    - Querying: POST `https://api.synthetic.new/v2/search` with `{ query }`.\n    - Ignores `recency`, `max_tokens`, and `temperature`.\n    - `limit` and `num_search_results` are collapsed together before dispatch.\n    - Output: `sources` only.\n  - **SearXNG** — `packages/coding-agent/src/web/search/providers/searxng.ts`\n    - Availability: endpoint from `searxng.endpoint` setting or `SEARXNG_ENDPOINT` env.\n    - Querying: GET `<endpoint>/search?format=json&q=...`; optional settings add `categories` and `language`.\n    - Auth precedence: Basic auth (`searxng.basicUsername` / `searxng.basicPassword` or env equivalents) over bearer token (`searxng.token` / `SEARXNG_TOKEN`). Basic credentials are validated for RFC 7617 restrictions.\n    - `recency` maps to `time_range`; `week` is downgraded to `month` because SearXNG does not support week.\n    - `limit` and `num_search_results` are collapsed together before dispatch, clamped to `1..20`, default `10`.\n    - Output: `sources`, `relatedQuestions` from `suggestions`.\n\n## Side Effects\n- Network\n  - Calls one or more external search providers over HTTPS until one succeeds or all fail.\n  - Provider-specific transports include JSON POST, JSON GET, SSE streaming (Perplexity OAuth/API, Gemini, OpenAI code), and JSON-RPC over HTTP (Z.AI).\n- Subprocesses / native bindings\n  - None.\n- Session state (transcript, memory, jobs, checkpoints, registries)\n  - Uses a module-global provider-instance cache in `packages/coding-agent/src/web/search/provider.ts`.\n  - Uses a WeakMap-keyed resolved-chain cache (per AuthStorage, 60s TTL) in the same file; `WebSearchTool`'s constructor prewarms it via `prewarmSearchProviders()`.\n  - Uses a module-global preferred-provider setting in the same file.\n  - `packages/coding-agent/src/tools/index.ts` gates tool availability behind `session.settings.get(\"web_search.enabled\")`.\n- Background work / cancellation\n  - Many provider adapters accept `AbortSignal`, but `WebSearchTool.execute()` does not pass its `_signal` into `executeSearch()`. Internal callers can still use cancellation by calling `runSearchQuery()` / `executeSearch()` with `signal` embedded in params.\n\n## Limits & Caps\n- Provider registry size: 16 providers (`SEARCH_PROVIDER_ORDER` in `packages/coding-agent/src/web/search/provider.ts`), including the keyless `duckduckgo` default/fallback and selectable `insane` safe-public-route provider. `SEARCH_PROVIDER_ORDER` no longer drives auto selection — see \"Active-model-gated auto\" above.\n- Insane result count: default `10`, max `20` (`packages/coding-agent/src/web/search/providers/insane.ts`).\n- Insane public-route response bodies are limited to 1 MiB after transfer/content decoding; oversized declared or streamed bodies are cancelled and that route fails closed (`packages/coding-agent/src/web/search/providers/insane.ts`).\n- `formatSearchResponseForLlm()` truncates source snippets and citation text to 240 chars (`packages/coding-agent/src/web/search/index.ts`).\n- `formatSearchResponseForLlm()` emits at most 3 search queries, each truncated to 120 chars (`packages/coding-agent/src/web/search/index.ts`).\n- Brave result count: default `10`, max `20` (`DEFAULT_NUM_RESULTS`, `MAX_NUM_RESULTS` in `packages/coding-agent/src/web/search/providers/brave.ts`).\n- Tavily result count: default `5`, max `20` (`packages/coding-agent/src/web/search/providers/tavily.ts`).\n- Kimi result count: default `10`, max `20`; request timeout field fixed to `30` seconds (`packages/coding-agent/src/web/search/providers/kimi.ts`).\n- Parallel result count: default `10`, max `40`; per-result excerpt cap `10_000` chars (`packages/coding-agent/src/web/search/providers/parallel.ts`, `packages/coding-agent/src/web/parallel.ts`).\n- Kagi result count: default `10`, max `40` (`packages/coding-agent/src/web/search/providers/kagi.ts`).\n- SearXNG result count: default `10`, max `20` (`packages/coding-agent/src/web/search/providers/searxng.ts`).\n- Perplexity API-key mode defaults: `max_tokens = 8192`, `temperature = 0.2`, `num_search_results = 10` (`packages/coding-agent/src/web/search/providers/perplexity.ts`).\n- Anthropic defaults: model `anthropic-model-haiku-4-5`, `DEFAULT_MAX_TOKENS = 4096` when the provider omits `max_tokens` (`packages/coding-agent/src/web/search/providers/anthropic.ts`).\n- Gemini retries: up to `3` retries per endpoint, base delay `1000` ms, rate-limit delay budget `30 * 1000` ms (`packages/coding-agent/src/web/search/providers/gemini.ts`).\n- Hard timeouts are class-based (`packages/coding-agent/src/web/search/providers/utils.ts`): pure search APIs `SEARCH_API_TIMEOUT_MS = 15_000`, LLM-mediated providers `SEARCH_LLM_TIMEOUT_MS = 120_000`, legacy fallback `SEARCH_HARD_TIMEOUT_MS = 300_000` for untagged call sites. Kimi uses an explicit `KIMI_HARD_TIMEOUT_MS = 35_000` aligned with its upstream `timeout_seconds: 30` budget. An explicitly configured `web_search.timeout` overrides class defaults (`applyConfiguredSearchTimeout()` gates on `settings.has`, so the schema default 300 does not reinstall a uniform ceiling).\n- DuckDuckGo hedge delay: `DDG_HEDGE_DELAY_MS = 3_000` (`packages/coding-agent/src/web/search/index.ts`).\n- Resolved provider chains are cached per `AuthStorage` instance for `CHAIN_CACHE_TTL_MS = 60_000`, keyed on the storage credential generation so login/logout invalidates immediately; `setPreferredSearchProvider()` / `setSearchFallbackProviders()` clear the cache (`packages/coding-agent/src/web/search/provider.ts`).\n\n## Errors\n- There is no \"no provider configured\" case: DuckDuckGo (keyless) is always appended as the terminal fallback, so the chain is never empty.\n- Tool-level all-failed case also returns a normal tool result with `Error: ...`; failures are summarized from the last attempted provider.\n- Provider adapters usually throw `SearchProviderError(provider, message, status)` for HTTP or protocol failures.\n- Availability probes are each provider's `isAvailable()` (abstract in `packages/coding-agent/src/web/search/providers/base.ts`): cheap credential/setting presence checks that never call the provider. `exa.ts` additionally tolerates uninitialized settings and falls back to the API-key check.\n- Per-provider notable failures:\n  - Anthropic: missing credentials throw a plain `Error`; a `404` is remapped to a special final message by `formatProviderError()`.\n  - Perplexity: missing auth throws a plain `Error`; OAuth stream `error_code` events become `SearchProviderError(\"perplexity\", ...)`.\n  - Gemini: auth refresh, endpoint fallback, and retry logic are internal; final exhausted failures surface as `SearchProviderError(\"gemini\", ...)`.\n  - OpenAI code and Gemini both fail if the HTTP response has no body after a `200`.\n  - Z.AI treats malformed SSE/JSON-RPC payloads as provider errors and retries only argument-shape failures across request variants.\n  - SearXNG `findAuth()` can throw configuration errors before any HTTP call if Basic auth fields are incomplete or invalid.\n\n## Notes\n- The model-facing schema does not expose `provider`, but internal callers can force one through `SearchQueryParams`.\n- `resolveProviderChain()` lazily imports provider modules and caches singleton instances. Just asking for labels via `getSearchProviderLabel()` does not trigger those imports.\n- Most providers treat `limit` and `num_search_results` as the same number because adapters pass `params.numSearchResults ?? params.limit`. Perplexity is the only implementation that preserves both concepts.\n- The prompt says `recency` is for Brave and Perplexity, but code also implements it for Tavily and SearXNG.\n- The year rewrite in `executeSearch()` is blunt: any `2020`-`2029` substring is replaced with the current year.\n- `packages/coding-agent/src/config/settings-schema.ts` exposes provider preferences for `auto`, `duckduckgo`, `insane`, `exa`, `brave`, `jina`, `kimi`, `perplexity`, `anthropic`, `gemini`, `codex`, `xai`, `zai`, `tavily`, `kagi`, `synthetic`, `parallel`, and `searxng`.\n- Exa availability fails closed unless `EXA_API_KEY` is present and Exa settings remain enabled.\n",
 	"tools/write.md": "# write\n\n> Create or overwrite a file, archive entry, or SQLite row.\n\n## Source\n- Entry: `packages/coding-agent/src/tools/write.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/write.md`\n- Key collaborators:\n  - `packages/coding-agent/src/tools/archive-reader.ts` — parse `archive.ext:entry` selectors.\n  - `packages/coding-agent/src/tools/sqlite-reader.ts` — detect SQLite paths and perform row insert/update/delete.\n  - `packages/coding-agent/src/lsp/index.ts` — format-on-write and diagnostics writethrough.\n  - `packages/coding-agent/src/tools/auto-generated-guard.ts` — block overwriting generated files.\n  - `packages/coding-agent/src/tools/fs-cache-invalidation.ts` — invalidate shared FS scan caches after writes.\n  - `packages/coding-agent/src/tools/atomic-file-write.ts` — sibling temp + rename so a failed write never leaves a 0-byte destination.\n  - `packages/coding-agent/src/tools/plan-mode-guard.ts` — resolve paths and enforce plan-mode write policy.\n\n## Inputs\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | Yes | Target path. Plain file path writes a filesystem file. `archive.ext:inner/path` writes an archive entry for `.tar`, `.tar.gz`, `.tgz`, or `.zip`. `db.sqlite:table` inserts a row. `db.sqlite:table:key` updates or deletes a row. |\n| `content` | `string` | Yes | Full replacement file content, archive entry content, or SQLite row payload. SQLite non-delete writes must parse as a JSON5 object. Empty or whitespace-only content deletes a SQLite row when `path` includes a row key. |\n\nWorked examples:\n\n```text\npath: \"src/generated/config.json\"\ncontent: \"{\\n  \\\"enabled\\\": true\\n}\\n\"\n```\n\n```text\npath: \"fixtures/archive.zip:templates/email.txt\"\ncontent: \"hello\\n\"\n```\n\n```text\npath: \"data/app.sqlite:users:42\"\ncontent: \"{name: 'Ada', active: true}\"\n```\n\n## Outputs\nSingle-shot result.\n\n- Success always returns a text block.\n  - Plain file write: `Successfully wrote <bytes> bytes to <relative-path>`.\n  - Archive write: `Successfully wrote <bytes> bytes to <relative-archive-path>:<entry-path>`.\n  - SQLite write: one of `Inserted row into <table>`, `Updated row '<key>' in <table>`, `No row updated ...`, `Deleted row ...`, `No row deleted ...`.\n- If hashline prefixes were copied from `read` output and stripped first, the first text block gets an extra note.\n- Plain file writes may also return `details.diagnostics` plus `details.meta.diagnostics` when LSP diagnostics-on-write is enabled.\n- SQLite writes use `toolResult(...).sourcePath(...)`, so `details.meta.sourcePath` points at the database file.\n- Archive writes return empty `details`.\n\n## Flow\n1. `WriteTool.execute()` in `packages/coding-agent/src/tools/write.ts` strips `LINE+ID|` hashline prefixes from `content` when the session is in hashline display mode.\n2. It calls `#resolveArchiveWritePath()` first. That uses `parseArchivePathCandidates()` from `packages/coding-agent/src/tools/archive-reader.ts`, checks candidate archive files on disk, and falls back to the longest matching archive suffix even when the archive file does not exist yet.\n3. Archive writes call `enforcePlanModeWrite(..., { op: exists ? \"update\" : \"create\" })`, then `#writeArchiveEntry()`.\n   - `.zip` archives are read with `fflate.unzipSync()`, the target entry is replaced in an in-memory map, and the complete archive is reconstructed with `fflate.zipSync()` and published through the same guarded sibling-temp atomic writer as plain files.\n   - `.tar`, `.tar.gz`, and `.tgz` archives are read with `Bun.Archive`, existing entries are copied into an object map, the target entry is replaced, and `Bun.Archive.bytes()` reconstructs the archive before atomic publication.\n   - The reconstructed ZIP/TAR bytes are published through `writeFileAtomically()`, which creates parents only after trust-boundary validation. A failed reconstruction or publication leaves an existing archive byte-identical and removes the owned staging file.\n   - `invalidateFsScanAfterWrite()` runs on the archive file path.\n4. If the path is not treated as an archive, `execute()` calls `#resolveSqliteWritePath()`. That uses `parseSqlitePathCandidates()` and `isSqliteFile()` from `packages/coding-agent/src/tools/sqlite-reader.ts`. Existing non-SQLite files suppress the SQLite path interpretation.\n5. SQLite writes call `enforcePlanModeWrite(..., { op: \"update\" })`, then `#writeSqliteRow()`.\n   - The database must already exist; missing DBs throw `SQLite database '<path>' not found`.\n   - The tool opens `new Database(..., { create: false, strict: true })` and sets `PRAGMA busy_timeout = 3000`.\n   - Whitespace-only `content` with a row key deletes a row.\n   - Non-empty `content` is parsed with `Bun.JSON5.parse()`, must be a JSON object, and is routed to insert/update helpers from `packages/coding-agent/src/tools/sqlite-reader.ts`.\n   - `invalidateFsScanAfterWrite()` runs on the DB path and the connection is closed in `finally`.\n6. Otherwise the tool treats `path` as a plain filesystem file.\n   - `enforcePlanModeWrite(..., { op: \"create\" })` runs before path resolution.\n   - Existing files are checked by `assertEditableFile()` to block overwriting detected generated files.\n   - The session’s writethrough callback writes content. With LSP enabled and `lsp.formatOnWrite` / `lsp.diagnosticsOnWrite` settings on, `createLspWritethrough()` may format content, sync it through LSP servers, save it, and collect diagnostics. Otherwise `writethroughNoop()` writes through `writeFileAtomically()` (sibling temp, then rename). Permission errors (`EACCES`/`EPERM`/`EROFS`) become a `ToolError` that says the original file was left unchanged.\n   - `invalidateFsScanAfterWrite()` and `fileReadCache.invalidate()` run on the file path.\n7. The tool returns a text result and optional diagnostics metadata.\n\n## Modes / Variants\n### Plain file path\n- Target is any path that does not resolve as an archive selector and does not resolve as an existing-or-new SQLite selector.\n- Existing files are overwritten.\n- Parent directories are created by `writeFileAtomically()`. A failed write never truncates an existing destination to 0 bytes.\n- Existing referents must be writable and are checked before publication. Hard-linked regular files are rejected rather than silently leaving aliases with stale bytes; this preserves the no-truncate guarantee instead of switching to an unsafe in-place fallback.\n- On Windows, a writable file held with write sharing but without delete sharing falls back to a rollback-capable in-place update after bounded rename retries, preserving the existing inode and editability.\n\nExample:\n\n```text\npath: \"tmp/output.txt\"\ncontent: \"hello\\n\"\n```\n\n### Archive entry write\n- Selector syntax: `archive.ext:inner/path`.\n- Supported archive suffixes come from `parseArchivePathCandidates()`: `.tar`, `.tar.gz`, `.tgz`, `.zip`.\n- The inner path is normalized to `/`, strips empty and `.` segments, rejects `..`, and rejects directory targets ending in `/`.\n- Rewrites the whole archive file after replacing one entry.\n- Creates the parent directory only inside the guarded atomic publication path after destination trust validation.\n\nExample:\n\n```text\npath: \"build/assets.tar.gz:css/app.css\"\ncontent: \"body { color: black; }\\n\"\n```\n\n### SQLite table insert\n- Selector syntax: `db.sqlite:table`.\n- `content` must parse as a JSON5 object.\n- Empty object is allowed and becomes `INSERT INTO <table> DEFAULT VALUES`.\n- Query parameters are rejected for SQLite writes.\n\nExample:\n\n```text\npath: \"data/app.db:users\"\ncontent: \"{name: 'Ada', active: true}\"\n```\n\n### SQLite row update / delete\n- Selector syntax: `db.sqlite:table:key`.\n- Non-empty `content` updates the row.\n- Empty or whitespace-only `content` deletes the row.\n- Row lookup uses the single-column primary key if present; otherwise it falls back to `rowid`. Composite primary keys and `WITHOUT ROWID` tables are rejected for key-based writes.\n\nExample update:\n\n```text\npath: \"data/app.sqlite:users:42\"\ncontent: \"{email: 'ada@example.com'}\"\n```\n\nExample delete:\n\n```text\npath: \"data/app.sqlite:users:42\"\ncontent: \"\"\n```\n\n## Publication contract\n\nPlain-file writes stage to a sibling temp and publish with a same-directory `rename(2)`. A write that fails at any point before that rename leaves the destination byte-identical to its prior contents -- a failed write never truncates the target or leaves a 0-byte file -- and the staging file it created is removed. Successful writes leave no residue beside the destination.\n\nThe staged bytes are fsynced before publication, but the parent directory is not, so publication is **not** crash-durable: a rename can be lost across a system crash.\n\nOverwrites are **last-writer-wins**. Destination identity is revalidated immediately before the rename, which rejects a target that was replaced or retargeted while staging, but the rename commits against the pathname. A concurrent writer that publishes a successor between that check and the rename is overwritten rather than detected.\n\nDestination symlinks are followed: the referent is replaced and the link is preserved. Hard-linked targets are rejected, because replacement would split the link group.\n\n## Side Effects\n- Filesystem\n  - Creates or overwrites plain files.\n  - Reconstructs and atomically publishes entire archive files when writing an archive entry; failed publication preserves an existing archive and cleans owned staging residue.\n  - Creates parent directories for plain files and archive files only after the destination boundary has been validated.\n  - Mutates existing SQLite databases; never creates a new SQLite DB.\n- Subprocesses / native bindings\n  - Uses Bun SQLite bindings via `bun:sqlite`.\n  - Uses Bun archive APIs and lazily imports `fflate` for ZIP reads/writes.\n  - May talk to configured LSP servers through `packages/coding-agent/src/lsp/index.ts`.\n- Session state (transcript, memory, jobs, checkpoints, registries)\n  - Invalidates shared filesystem scan cache entries through `invalidateFsScanAfterWrite()`.\n  - Enforces plan-mode write restrictions before mutating the target.\n- Background work / cancellation\n  - Marks the tool `nonAbortable = true` and `concurrency = \"exclusive\"` in `WriteTool`.\n  - LSP writethrough can schedule deferred diagnostics fetches after a timeout, but plain `write.ts` only consumes the immediate return value.\n\n## Limits & Caps\n- `WriteTool` itself exposes no byte cap beyond storing `content` in memory and, for archives, rebuilding the archive in memory.\n- Generated-file detection reads at most `CHECK_BYTE_COUNT = 1024` bytes and `HEADER_LINE_LIMIT = 40` header lines from an existing file in `packages/coding-agent/src/tools/auto-generated-guard.ts`.\n- SQLite writes set `PRAGMA busy_timeout = 3000`.\n- LSP writethrough uses a `5_000` ms operation timeout in `runLspWritethrough()` and may schedule a deferred diagnostics fetch with `AbortSignal.timeout(25_000)` in `scheduleDeferredDiagnosticsFetch()`.\n\n## Errors\n- Invalid archive subpaths throw `ToolError` with messages such as:\n  - `Archive write path must target a file inside the archive`\n  - `Archive write path must target a file, not a directory`\n  - `Archive path cannot contain '..'`\n- SQLite path parsing throws on unsupported forms:\n  - `SQLite write paths do not support query parameters`\n  - `SQLite write path must target a table`\n  - `SQLite row writes require a non-empty row key`\n- Missing SQLite DBs surface as `SQLite database '<path>' not found`.\n- SQLite content errors are model-visible `ToolError`s, including invalid JSON5, non-object payloads, unknown columns, non-scalar values, empty update objects, composite primary keys, and `WITHOUT ROWID` tables.\n- Existing plain files may be rejected by `assertEditableFile()` when they look generated.\n- Archive read/write failures and unexpected SQLite exceptions are wrapped in `ToolError(error.message)`.\n- If no LSP server matches or LSP formatting/diagnostics times out, file writes still fall back to writing content; diagnostics may be omitted.\n\n## Notes\n- Archive path detection runs before SQLite detection. A path that matches an archive selector is never treated as SQLite.\n- SQLite detection declines when an existing file with a `.sqlite` / `.db` suffix is present but does not have SQLite magic bytes; then the path falls back to a plain file write.\n- ZIP entry content is encoded with `new TextEncoder().encode(content)` in `#writeArchiveEntry()`. Non-ZIP archive entries are reconstructed with `Bun.Archive.bytes()` and both formats publish through `writeFileAtomically()`.\n- The prompt forbids two common anti-patterns: using `write` for routine edits that should use `edit`, and creating `*.md` / `README` files unless explicitly requested. It also forbids emojis unless requested.\n- Plain file writes report byte count using `cleanContent.length`, which is UTF-16 code units in JS, not an on-disk byte measurement.\n- `stripWriteContent()` only removes hashline prefixes when the session’s file display mode has `hashLines` enabled; otherwise content is written unchanged.\n",
 	"tree.md": "# `/tree` Command Reference\n\n`/tree` opens the interactive **Session Tree** navigator. It lets you jump to any entry in the current session file and continue from that point.\n\nThis is an in-file leaf move, not a new session export.\n\n## What `/tree` does\n\n- Builds a tree from current session entries (`SessionManager.getTree()`)\n- Opens `TreeSelectorComponent` with keyboard navigation, filters, and search\n- On selection, calls `AgentSession.navigateTree(targetId, { summarize, customInstructions })`\n- Rebuilds visible chat from the new leaf path\n- Optionally prefills editor text when selecting a user/custom message\n\nPrimary implementation:\n\n- `src/modes/controllers/input-controller.ts` (`/tree`, keybinding wiring, double-escape behavior)\n- `src/modes/controllers/selector-controller.ts` (tree UI launch + summary prompt flow)\n- `src/modes/components/tree-selector.ts` (navigation, filters, search, labels, rendering)\n- `src/session/agent-session.ts` (`navigateTree` leaf switching + optional summary)\n- `src/session/session-manager.ts` (`getTree`, `branch`, `branchWithSummary`, `resetLeaf`, label persistence)\n\n## How to open it\n\nThe following open the tree selector:\n\n- `/tree`\n- configured keybinding action `tree`\n- double-escape on an empty editor when `doubleEscapeAction = \"tree\"` (default)\n\nWith `doubleEscapeAction = \"branch\"`, double Escape opens the user-message branch picker instead; the `app.session.fork` action opens that picker directly.\n\n## Tree UI model\n\nThe tree is rendered from session entry parent pointers (`id` / `parentId`).\n\n- Children are sorted by timestamp ascending (older first, newer lower)\n- Active branch (path from root to current leaf) is marked with a bullet\n- Labels (if present) render as `[label]` before node text\n- If multiple roots exist (orphaned/broken parent chains), they are shown under a virtual branching root\n\n```text\nExample tree view (active path marked with •):\n\n├─ user: \"Start task\"\n│  └─ assistant: \"Plan\"\n│     ├─ • user: \"Try approach A\"\n│     │  └─ • assistant: \"A result\"\n│     │     └─ • [milestone] user: \"Continue A\"\n│     └─ user: \"Try approach B\"\n│        └─ assistant: \"B result\"\n```\n\nThe selector recenters around current selection and shows up to:\n\n- `max(5, floor(terminalHeight / 2))` rows\n\n## Keybindings inside tree selector\n\n- `Up` / `Down`: move selection (wraps)\n- `Left` / `Right`: page up / page down\n- `Enter`: select node\n- `Esc`: clear search if active; otherwise close selector\n- `Ctrl+C`: close selector\n- `Type`: append to search query\n- `Backspace`: delete search character\n- `Shift+L`: edit/clear label on selected entry\n- `Ctrl+O`: cycle filter forward\n- `Shift+Ctrl+O`: cycle filter backward\n- `Alt+D/T/U/L/A`: jump directly to specific filter mode\n\n## Filters and search semantics\n\nFilter modes (`TreeList`):\n\n1. `default`\n2. `no-tools`\n3. `user-only`\n4. `labeled-only`\n5. `all`\n\n### `default`\n\nShows most conversational nodes, but hides bookkeeping entry types:\n\n- `label`\n- `custom`\n- `model_change`\n- `thinking_level_change`\n\n### `no-tools`\n\nSame as `default`, plus hides `toolResult` messages.\n\n### `user-only`\n\nOnly `message` entries where role is `user`.\n\n### `labeled-only`\n\nOnly entries that currently resolve to a label.\n\n### `all`\n\nEverything in the session tree, including bookkeeping/custom entries.\n\n### Tool-only assistant node behavior\n\nAssistant messages that contain **only tool calls** (no text) are hidden by default in all filtered views unless:\n\n- message is error/aborted (`stopReason` not `stop`/`toolUse`), or\n- it is the current leaf (always kept visible)\n\n### Search behavior\n\n- Query is tokenized by spaces\n- Matching is case-insensitive\n- All tokens must match (AND semantics)\n- Searchable text includes label, role, and type-specific content (message text, branch summary text, custom type, tool command snippets, etc.)\n\n## Selection outcomes (important)\n\n`navigateTree` computes new leaf behavior from selected entry type:\n\n### Selecting `user` message\n\n- New leaf becomes selected entry’s `parentId`\n- If parent is `null` (root user message), leaf resets to root (`resetLeaf()`)\n- Selected message text is copied to editor for editing/resubmit\n\n### Selecting `custom_message`\n\n- Same leaf rule as user messages (`parentId`)\n- Text content is extracted and copied to editor\n\n### Selecting non-user node (assistant/tool/summary/compaction/custom bookkeeping/etc.)\n\n- New leaf becomes selected node id\n- Editor is not prefilled\n\n### Selecting current leaf\n\n- No-op; selector closes with “Already at this point”\n\n```text\nSelection decision (simplified):\n\nselected node\n   │\n   ├─ is current leaf? ── yes ──> close selector (no-op)\n   │\n   ├─ is user/custom_message? ── yes ──> leaf := parentId (or resetLeaf for root)\n   │                                     + prefill editor text\n   │\n   └─ otherwise ──> leaf := selected node id\n                    + no editor prefill\n```\n\n## Summary-on-switch flow\n\nSummary prompt is controlled by `branchSummary.enabled` (default: `false`).\n\nWhen enabled, after picking a node the UI asks:\n\n- `No summary`\n- `Summarize`\n- `Summarize with custom prompt`\n\nFlow details:\n\n- Escape in summary prompt reopens tree selector\n- Custom prompt cancellation returns to summary choice loop\n- During summarization, UI shows loader and binds `Esc` to `abortBranchSummary()`\n- If summarization aborts, tree selector reopens and no move is applied\n\n`navigateTree` internals:\n\n- Collects abandoned-branch entries from old leaf to common ancestor\n- Emits `session_before_tree` (extensions can cancel or inject summary)\n- Uses default summarizer only if requested and needed\n- Applies move with:\n  - `branchWithSummary(...)` when summary exists\n  - `branch(newLeafId)` for non-root move without summary\n  - `resetLeaf()` for root move without summary\n- Replaces agent conversation with rebuilt session context\n- Emits `session_tree`\n\nNote: if user requests summary but there is nothing to summarize, navigation proceeds without creating a summary entry.\n\n## Labels\n\nLabel edits in tree UI call `appendLabelChange(targetId, label)`.\n\n- non-empty label sets/updates resolved label\n- empty label clears it\n- labels are stored as append-only `label` entries\n- tree nodes display resolved label state, not raw label-entry history\n\n## `/tree` vs adjacent operations\n\n| Operation | Scope                                          | Result                                                                                                                                                     |\n| --------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `/tree`   | Current session file                           | Moves leaf to selected point (same file)                                                                                                                   |\n| `app.session.fork` action or branch-configured double Escape | Selected user prompt; new persistent session file | Opens the same picker as `/fork`, with the same persistence and active-work guards |\n| `/fork`   | Selected user prompt; new persistent session file | Opens the same picker, copies history before the selected prompt into an independent session, switches to it, and prefills the prompt without submitting |\n| `/resume` | Session list                                   | Switches to another session file                                                                                                                           |\n\nKey distinction: `/tree` is a navigation/repositioning tool inside one session file. `/fork`, `app.session.fork`, and branch-configured double Escape share a persistent prompt-fork lifecycle. Opening an admitted picker closes any active `/btw` side chat, including when the picker is subsequently cancelled. `/resume` remains unchanged.\n\n## Operator workflows\n\n### Re-run from an earlier user prompt without losing current branch\n\n1. `/tree`\n2. search/select earlier user message\n3. choose `No summary` (or summarize if needed)\n4. edit prefilled text in editor\n5. submit\n\nEffect: new branch grows from selected point within same session file.\n\n### Leave current branch with context breadcrumb\n\n1. enable `branchSummary.enabled`\n2. `/tree` and select target node\n3. choose `Summarize` (or custom prompt)\n\nEffect: a `branch_summary` entry is appended at the target position before continuing.\n\n### Investigate hidden bookkeeping entries\n\n1. `/tree`\n2. press `Alt+A` (all)\n3. search for `model`, `thinking`, `custom`, or labels\n\nEffect: inspect full internal timeline, not just conversational nodes.\n\n### Bookmark pivot points for later jumps\n\n1. `/tree`\n2. move to entry\n3. `Shift+L` and set label\n4. later use `Alt+L` (`labeled-only`) to jump quickly\n\nEffect: fast navigation among durable branch landmarks.\n",
 	"ttsr-injection-lifecycle.md": "# TTSR Injection Lifecycle\n\nThis document covers the current Time Traveling Stream Rules (TTSR) runtime path from rule discovery to stream interruption, retry injection, extension notifications, and session-state handling.\n\n## Implementation files\n\n- [`../src/sdk/session.ts`](../packages/coding-agent/src/sdk/session.ts)\n- [`../src/export/ttsr.ts`](../packages/coding-agent/src/export/ttsr.ts)\n- [`../src/session/agent-session.ts`](../packages/coding-agent/src/session/agent-session.ts)\n- [`../src/session/session-manager.ts`](../packages/coding-agent/src/session/session-manager.ts)\n- [`../src/prompts/system/ttsr-interrupt.md`](../packages/coding-agent/src/prompts/system/ttsr-interrupt.md)\n- [`../src/capability/index.ts`](../packages/coding-agent/src/capability/index.ts)\n- [`../src/extensibility/extensions/types.ts`](../packages/coding-agent/src/extensibility/extensions/types.ts)\n- [`../src/extensibility/hooks/types.ts`](../packages/coding-agent/src/extensibility/hooks/types.ts)\n- [`../src/extensibility/custom-tools/types.ts`](../packages/coding-agent/src/extensibility/custom-tools/types.ts)\n- [`../src/modes/controllers/event-controller.ts`](../packages/coding-agent/src/modes/controllers/event-controller.ts)\n\n## 1. Discovery feed and rule registration\n\nAt session creation, `createAgentSession()` loads discovered rules and constructs a `TtsrManager`:\n\n```ts\nconst ttsrSettings = settings.getGroup(\"ttsr\");\nconst ttsrManager = new TtsrManager(ttsrSettings);\nconst rulesResult = await loadCapability<Rule>(ruleCapability.id, { cwd });\nfor (const rule of rulesResult.items) {\n  if (rule.condition?.length && ttsrManager.addRule(rule)) continue;\n  // non-TTSR rules continue through normal rule handling\n}\n```\n\n### Pre-registration dedupe behavior\n\n`loadCapability(\"rules\")` deduplicates by `rule.name` with first-wins semantics (higher provider priority first). Shadowed duplicates are removed before TTSR registration.\n\n### `TtsrManager.addRule()` behavior\n\nRegistration is skipped when:\n\n- `rule.condition` is absent or all condition regexes fail to compile\n- a rule with the same `rule.name` was already registered in this manager\n- the rule scope excludes all monitored streams\n\nInvalid regex conditions and unreachable scopes are logged as warnings and ignored; session startup continues.\n\n### Setting caveat\n\n`TtsrSettings.enabled=false` makes `TtsrManager` no-op (`addRule`, `checkDelta`, `hasRules`, `restoreInjected`), so no conditional rules are registered or injected.\n\n## 2. Streaming monitor lifecycle\n\nTTSR detection runs inside `AgentSession.#handleAgentEvent`.\n\n### Turn start\n\nOn `turn_start`, the stream buffer is reset:\n\n- `ttsrManager.resetBuffer()`\n\n### During stream (`message_update`)\n\nWhen assistant updates arrive and rules exist:\n\n- monitor `text_delta`, `thinking_delta`, and `toolcall_delta`\n- append delta into a source/tool scoped manager buffer\n- call `checkDelta(delta, matchContext)`\n\n`checkDelta()` iterates registered rules and returns all matching rules that pass scope, global-path, condition, and repeat policy checks.\n\n## 3. Trigger decision and immediate abort path\n\nWhen one or more rules match and at least one matched rule allows interruption:\n\n1. Matched rules are deduplicated into `#pendingTtsrInjections`.\n2. `#ttsrAbortPending = true` and a TTSR resume gate is created.\n3. `agent.abort()` is called immediately.\n4. `ttsr_triggered` event is emitted asynchronously (fire-and-forget).\n5. retry work is scheduled via the post-prompt task scheduler with a 50ms delay.\n\nAbort is not blocked on extension callbacks.\n\n## 4. Retry scheduling, context mode, and reminder injection\n\nAfter the 50ms timeout:\n\n1. `#ttsrAbortPending = false`\n2. read `ttsrManager.getSettings().contextMode`\n3. if `contextMode === \"discard\"`, drop the targeted partial assistant output with `agent.replaceMessages(...slice(0, targetAssistantIndex))`\n4. build injection content from pending rules using `ttsr-interrupt.md` template\n5. append and persist a hidden `custom_message`/runtime custom message with `customType: \"ttsr-injection\"` and `details.rules`\n6. mark those rule names injected, persist a `ttsr_injection` entry, and call `agent.continue()` to retry generation\n\nTemplate payload is:\n\n```xml\n<system-interrupt reason=\"rule_violation\" rule=\"{{name}}\" path=\"{{path}}\">\n...\n{{content}}\n</system-interrupt>\n```\n\nPending injections are cleared after content generation.\n\n### `contextMode` behavior on partial output\n\n- `discard`: partial/aborted assistant message is removed before retry.\n- `keep`: partial assistant output remains in conversation state; reminder is appended after it.\n\n### Non-interrupting matches\n\nNon-interrupting matches split by `matchContext.source`:\n\n- **`source === \"tool\"` (tool-source match).** The rule is bucketed into `#perToolTtsrInjections`, keyed by the matched tool call's `id`. There is **no** deferred follow-up turn and the stream is not aborted. When the tool actually produces a result, the `afterToolCall` hook prepends a rendered `ttsr-tool-reminder.md` block to `ctx.result.content` (a single `text` block inserted ahead of the tool's own content), and persists a `ttsr_injection` entry with the consumed rule names. The template payload is:\n\n  ```xml\n  <system-reminder reason=\"rule_violation\" rule=\"{{name}}\" path=\"{{path}}\">\n  ...\n  {{content}}\n  </system-reminder>\n  ```\n\n- **`source === \"text\"` / `\"thinking\"` (prose-source match).** Behavior is unchanged: the rule is queued in `#pendingTtsrInjections` and, after a successful non-error, non-aborted assistant message, `AgentSession` injects the hidden `ttsr-injection` custom message as a follow-up and schedules continuation.\n\nWithin a single matching batch, each rule is attached to exactly one sibling tool call — if multiple sibling tool calls would satisfy the same rule, deduplication picks one and the others are left untouched. Multiple distinct rules can still fold onto the same tool call.\n\n#### Implications for tool authors and transcript readers\n\n- The tool's own `toolResult` content is preserved verbatim; the reminder is **prepended** as an additional leading text block. Renderers that assume `content[0]` is the tool's primary output must scan past any block whose text begins with `<system-reminder reason=\"rule_violation\"` (or filter on the wrapper tag) to find the real payload.\n- The reminder is in-band on the tool result, not a separate `custom_message`/`ttsr-injection` entry. Transcript readers looking for non-interrupting TTSR activity on tool-source rules MUST inspect tool results (and the persisted `ttsr_injection` entry list), not just synthetic injection entries.\n- A single tool result may carry reminders for several rules concatenated with a blank line between rendered templates.\n- If the assistant message ends with `stopReason === \"aborted\"` or `\"error\"` before the matched tools run, the pending per-tool buckets are cleared — those rules are **not** persisted as injected and remain eligible to re-trigger on a future turn (subject to repeat policy).\n\n## 5. Repeat policy and gap logic\n\n`TtsrManager` tracks `#messageCount` and per-rule `lastInjectedAt`.\n\n### `repeatMode: \"once\"`\n\nA rule can trigger only once after it has an injection record.\n\n### `repeatMode: \"after-gap\"`\n\nA rule can re-trigger only when:\n\n- `messageCount - lastInjectedAt >= repeatGap`\n\n`messageCount` increments on `turn_end`, so gap is measured in completed turns, not stream chunks.\n\n## 6. Event emission and extension/hook surfaces\n\n### Session event\n\n`AgentSessionEvent` includes:\n\n```ts\n{ type: \"ttsr_triggered\"; rules: Rule[] }\n```\n\n### Extension runner\n\n`#emitSessionEvent()` routes the event to:\n\n- extension listeners (`ExtensionRunner.emit({ type: \"ttsr_triggered\", rules })`)\n- local session subscribers\n\n### Hook and custom-tool typing\n\n- extension API exposes `on(\"ttsr_triggered\", ...)`\n- hook API exposes `on(\"ttsr_triggered\", ...)`\n- custom tools receive `onSession({ reason: \"ttsr_triggered\", rules })`\n\n### Interactive-mode rendering difference\n\nInteractive mode uses `session.isTtsrAbortPending` to suppress showing the aborted assistant stop reason as a visible failure during TTSR interruption, and renders a `TtsrNotificationComponent` when the event arrives.\n\n## 7. Persistence and resume state (current implementation)\n\n`SessionManager` persists injected-rule state:\n\n- entry type: `ttsr_injection`\n- append API: `appendTtsrInjection(ruleNames)`\n- query API: `getInjectedTtsrRules()`\n- context reconstruction includes `SessionContext.injectedTtsrRules`\n\n`TtsrManager` supports restoration via `restoreInjected(ruleNames)`.\n\n### Current wiring status\n\nIn the current runtime path:\n\n- interrupted injections append a hidden `custom_message` with `customType: \"ttsr-injection\"` and append a `ttsr_injection` entry via `appendTtsrInjection(...)`\n- deferred non-interrupting prose-source injections are marked/persisted when their queued custom message reaches `message_end`\n- non-interrupting tool-source injections are marked at match time and persisted via `appendTtsrInjection(...)` from the `afterToolCall` hook when the matched tool's result is produced\n- `createAgentSession()` restores `existingSession.injectedTtsrRules` into `ttsrManager`\n\nNet effect: injected-rule suppression is persisted/restored across session reload/resume for the current branch path.\n\n## 8. Race boundaries and ordering guarantees\n\n### Abort vs retry callback\n\n- abort is synchronous from TTSR handler perspective (`agent.abort()` called immediately)\n- retry is deferred by timer (`50ms`)\n- extension notification is asynchronous and intentionally not awaited before abort/retry scheduling\n\n### Multiple matches in same stream window\n\n`checkDelta()` returns all currently matching eligible rules for that scoped buffer. Pending injections are deduplicated by rule name before injection.\n\n### Between abort and continue\n\nDuring the timer window, state can change (user interruption, mode actions, additional events). The retry call is best-effort: `agent.continue().catch(() => {})` swallows follow-up errors.\n\n## 9. Edge cases summary\n\n- Invalid `condition` regex: skipped with warning; other conditions/rules continue.\n- Duplicate rule names at capability layer: lower-priority duplicates are shadowed before registration.\n- Duplicate names at manager layer: second registration is ignored.\n- `contextMode: \"keep\"`: partial violating output can remain in context before reminder retry. **Cost warning:** every aborted partial turn is retained, so context (and token spend) grows each time a rule fires. Prefer the default `discard` unless the partial output is specifically needed.\n- `interruptMode: \"never\"`: prose-source matches queue a deferred hidden injection after a successful assistant message; tool-source matches fold an in-band `<system-reminder>` into the matched tool call's `toolResult` content via the `afterToolCall` hook (no mid-stream abort, no separate follow-up turn).\n- Tool-source non-interrupting buckets are cleared when the parent assistant message ends with `stopReason === \"aborted\"` or `\"error\"`, so rules whose target tool never produced a result remain eligible to re-trigger.\n- Repeat-after-gap depends on turn count increments at `turn_end`; mid-turn chunks do not advance gap counters.\n",