Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python

Merge main (#1484: #1478-#1481, #1483) into release/v0.0.302.18

justrach5510c53de32f
diff --cc docs/adr/0244-saved-workspaces-have-durable-discovery.md
index 50e3102e,00000000..c9bea0e2
mode 100644,000000..100644
--- a/docs/adr/0244-saved-workspaces-have-durable-discovery.md
+++ b/docs/adr/0244-saved-workspaces-have-durable-discovery.md
@@@ -1,19 -1,0 +1,19 @@@
- # 0239. Saved workspaces have durable device-local discovery
++# 0244. Saved workspaces have durable device-local discovery
+
+Status: accepted 2026-10-02
+
+## Context
+
+The live registry exposes sessions in unrelated repositories, while saved-session discovery covered only cwd, linked worktrees and home. A visible session could not be resumed, and removing the live process removed the only clue to its location (#1457–#1462).
+
+## Decision
+
+Remember workspace roots in a device-local index when saving meaningful conversation state. Use a separate file per root so unrelated saves do not race on a shared read-modify-write document. Discover saves in those roots without recursively scanning the device. The index contains paths, not conversation contents.
+
+Absolute `.graff/sessions/KEY.session.json` paths are explicit resume targets. Pickers and listings use these for remote saves so equal keys in different workspaces remain selectable. Bare keys retain cwd-first compatibility. Qualified resume enters the selected workspace before restoring history and refuses to proceed if entering fails. Home-origin saves retain ADR 0059's history-only behavior.
+
+ACP `session/load` retains its explicit client-cwd contract (ADR 0202); a client selects a remote save with that workspace and its basename. Slash-command resume and the TUI use the same engine discovery and restore paths.
+
+## Consequences
+
+Saved roots remain discoverable after their processes exit. Existing unindexed roots can be reached by an explicit target and become indexed on their next save. Stale roots contribute no rows; no global filesystem crawl or copying session files is required. The local index is metadata and must not be published.
diff --cc docs/adr/0245-fullscreen-tui-is-an-external-client.md
index 29258559,00000000..c830012f
mode 100644,000000..100644
--- a/docs/adr/0245-fullscreen-tui-is-an-external-client.md
+++ b/docs/adr/0245-fullscreen-tui-is-an-external-client.md
@@@ -1,23 -1,0 +1,23 @@@
- # 0240. Fullscreen TUI is an external client
++# 0245. Fullscreen TUI is an external client
+
+Status: accepted 2026-10-02
+
+Supersedes ADR 0041, ADR 0042 and the fullscreen portion of ADR 0142.
+
+## Context
+
+The fullscreen terminal UI is maintained separately. Keeping its former Zig renderer and in-process adapters here leaves a second implementation to build, test and maintain alongside the engine and line REPL.
+
+## Decision
+
+Remove the embedded `TUI/` implementation, its `src/tui*` adapters, build targets and UI-specific regression tooling. Keep shared engine behavior, ACP, the line REPL and its terminal checks here; rendering coverage belongs with the separate client.
+
+`graff tui [args...]` launches an installed `graff-tui` before argument parsing, credentials, MCP or session creation. Resolve beside the running executable first, then on `PATH`, and forward the remaining arguments unchanged. POSIX uses process replacement; Windows inherits standard handles and waits for the child. Missing installations fail with installation guidance, without downloads or engine startup. `graff -p "tui"` remains a prompt.
+
+TTY `graff repl` uses the normal line REPL; piped `graff repl` keeps its scripted model. No engine path claims the fullscreen client's alternate screen.
+
+## Consequences
+
+The default build installs only `graff`, and `tui-test` is retired. Launcher subprocess tests use fake executables to cover lookup order, argument and standard-stream forwarding, process replacement, exit status and missing installations without starting a real UI.
+
+The unit-count floor is adjusted for removed adapter tests, not weakened to hide unreachable engine tests. Automatic verified downloads and compatibility negotiation from #1444 remain separate work: no release-asset contract is invented here, and the installed-only launcher works offline.
diff --cc docs/adr/README.md
index c62ceebb,9b3cc551..ec639dae
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@@ -265,8 -265,11 +265,13 @@@ record only when you need the evidence
| [0236](0236-rlm-takes-json-literals-and-each-maps-plain-values.md) | `rlm` takes JSON array/object literals as arguments and binds (`name = [...]`, bound names allowed inside); its splitters nest `[]`/`{}`; `each(arr, tool[, field])` passes plain items as is, picks `field` from objects (default: an MCP tool's first parameter) and names the fields it found; an unsupported statement lists the forms that work. |
| [0237](0237-deepseek-thinks-at-its-low-level-by-default.md) | DeepSeek's default effort (`medium`) sends `reasoning_effort: low` with thinking enabled; `/effort low` still turns thinking off (ADR 0054), and `high` and above are unchanged. |
| [0238](0238-rlm-binds-keep-the-whole-mcp-result.md) | An MCP call inside an rlm script binds the whole result; `print()` shows the slim view (each item of an `each()` bind cut on its own), `project(x, field)` reads any field (`n`/`latest_author` through a comment list's fold), and `write_file` saves the whole result; inside rlm, `read_tool_result("tr_N")` with no range binds a stored result whole. |
- | [0239](0239-saved-workspaces-have-durable-discovery.md) | Remember saved workspace roots locally; remote picker targets are workspace-qualified, and resume must enter the selected tree before restoring it. |
- | [0240](0240-fullscreen-tui-is-an-external-client.md) | The fullscreen UI is maintained separately; `graff tui` launches installed `graff-tui` before engine startup, sibling first then PATH, without downloading. TTY `graff repl` uses the line REPL. Supersedes 0041, 0042 and the fullscreen portion of 0142. |
+ | [0239](0239-heads-ups-are-one-line-and-a-computed-answer-is-its-own-proof.md) | Heads-ups are one short line in the same response as their tool calls; a script that computes an answer is its own proof (no second derivation); `read_file` is required only before editing an existing file. |
+ | [0240](0240-a-slim-view-names-its-fields-and-one-script-fetches-and-computes.md) | A slim view names the whole value's fields (`; fields: ...` on rlm print and direct-call handle markers); the slim rule says to compute over results inside the same rlm script; an unbound host call or `each()` in rlm prints its result. |
+ | [0241](0241-prose-tightens-the-stall-budget-only-until-its-item-closes.md) | On the Responses wire, prose tightens the stall budget only while its output item is open; `response.output_item.done` restores the full budget for the next item (WS and SSE alike). |
+ | [0242](0242-the-shell-tool-names-python3s-version.md) | The `shell` tool's OS clause names python3's version, read at startup from where `python3` on PATH resolves (never by running it); unknown versions leave the description unchanged. |
+ | [0243](0243-repo-context-rides-as-an-input-item-on-responses.md) | On the Responses wire for codex, chatgpt-new and openai, root turns send the project-instructions section and the layout as one developer input item ahead of the conversation, so the instructions are byte-identical across repos and cache on turn 1. |
++| [0244](0244-saved-workspaces-have-durable-discovery.md) | Remember saved workspace roots locally; remote picker targets are workspace-qualified, and resume must enter the selected tree before restoring it. |
++| [0245](0245-fullscreen-tui-is-an-external-client.md) | The fullscreen UI is maintained separately; `graff tui` launches installed `graff-tui` before engine startup, sibling first then PATH, without downloading. TTY `graff repl` uses the line REPL. Supersedes 0041, 0042 and the fullscreen portion of 0142. |
## When to write one