graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
Task worktrees honor .agents/prepare and .agents/linked (ADR 0283)
justrache1443bcc79e2
diff --git a/build.zig b/build.zigindex 48105ed5..c55644de 100644--- a/build.zig+++ b/build.zig@@ -206,6 +206,9 @@ pub fn build(b: *std.Build) void {const workspace_lifecycle_test = b.addSystemCommand(&.{ "python3", "scripts/test-workspace-lifecycle.py" });workspace_lifecycle_test.addArtifactArg(exe);test_step.dependOn(&workspace_lifecycle_test.step);+ const agents_prepare_test = b.addSystemCommand(&.{ "python3", "scripts/test-agents-prepare.py" });+ agents_prepare_test.addArtifactArg(exe);+ test_step.dependOn(&agents_prepare_test.step);const acp_workspace_test = b.addSystemCommand(&.{ "python3", "scripts/test-acp-workspace.py" });acp_workspace_test.addArtifactArg(exe);test_step.dependOn(&acp_workspace_test.step);diff --git a/docs/adr/0283-agents-prepare-and-linked.md b/docs/adr/0283-agents-prepare-and-linked.mdnew file mode 100644index 00000000..bc0e9018--- /dev/null+++ b/docs/adr/0283-agents-prepare-and-linked.md@@ -0,0 +1,40 @@+# 0283. New task worktrees honor `.agents/prepare` and `.agents/linked`++Status: accepted 2026-10-14++## Context++ADR 0153 gave task worktrees a setup step: copy gitignored include files from+the main checkout and run `scripts.setup` from `.graff/workspace.toml`. That+format is graff's own, so a repository prepared for agents in general (whose+setup lives in the shared `.agents/` directory, next to `.agents/skills`) got+no setup in a graff worktree. Copies also go stale: a `.env` edited in the main+checkout after the worktree was made is not the one the worktree reads.++## Decision++When graff mints a task worktree (`graff worktree create`, auto-isolation, an+ACP `-w` workspace):++- `.agents/linked` lists repository-relative literal paths, one per line (`#`+ comments, a leading `/` allowed). Each entry that is gitignored in the main+ checkout, exists there, and is absent in the new checkout becomes a symlink+ to the main checkout's copy. Tracked paths, `..`, globs and missing paths are+ skipped, and nothing is moved or deleted. Linking runs before the ADR 0153+ copy, so a linked path is a symlink, not a copy. Windows links nothing+ (symlinks need privileges); the `.env*` copy still applies there.+- `.agents/prepare`, committed in the checkout, runs from the checkout root as+ the setup script when `.graff/workspace.toml` names no `scripts.setup`. It+ is executed directly when executable, else through `sh`, with the same+ environment, deadline and report as `scripts.setup`.++`graff worktree create` reports the linked count beside the copied count.++## Consequences++A repository set up once for agents works in graff worktrees with no+graff-specific file, and shared local files stay current in every worktree.+`.graff/workspace.toml` keeps precedence, so existing setups are unchanged.+A prepare script should stay fast and safe to repeat: it runs for every new+worktree. Revisit if worktrees need per-checkout copies of a linked file+(today that means leaving it out of `.agents/linked`).diff --git a/docs/adr/README.md b/docs/adr/README.mdindex 2f96607c..ea733fb6 100644--- a/docs/adr/README.md+++ b/docs/adr/README.md@@ -293,6 +293,7 @@ record only when you need the evidence or the edge cases.| [0280](0280-mcp-servers-report-state-and-reconnect.md) | Every configured MCP server has one status row (`graff mcp status --json`, `/mcp`); `graff mcp reconnect` / `/mcp reconnect` run a real handshake and refresh its catalog; `graff mcp enable|disable` live in `~/.codegraff/mcp-state.json`; the catalog cache keys on cwd + env, and server `env` overlays graff's own. || [0281](0281-anthropic-console-sign-in-reads-the-sdk-profile.md) | Anthropic Console sign-in: graff reads the `user_oauth` profile Anthropic's CLI writes (`ant auth login`), in the SDK's precedence (API key wins), sends it as Bearer, and refreshes through `ant auth print-credentials`; `graff login anthropic` runs `ant auth login`. No claude.ai subscription login. || [0282](0282-claude-system-breakpoint-closes-before-the-repo-context.md) | On Claude, the system prompt is two text blocks with the same bytes: the cache breakpoint closes the static instructions, before the project instructions and layout, so every repo shares the tools + instructions prefix. |+| [0283](0283-agents-prepare-and-linked.md) | New task worktrees symlink the gitignored paths `.agents/linked` lists from the main checkout and run `.agents/prepare` when `.graff/workspace.toml` names no setup script. |## When to write onediff --git a/scripts/test-agents-prepare.py b/scripts/test-agents-prepare.pynew file mode 100644index 00000000..1f35aaeb--- /dev/null+++ b/scripts/test-agents-prepare.py@@ -0,0 +1,95 @@+#!/usr/bin/env python3+"""Offline: a new task worktree honors the tool-neutral .agents/prepare and .agents/linked.++Every mutation stays in a temporary repo. Windows links nothing (symlinks need+privileges there) and runs prepare through the same POSIX shell as other setup+scripts, so the script is skipped on Windows.+"""+import os+from pathlib import Path+import subprocess+import sys+import tempfile++if os.name == "nt":+ print("skip: .agents/linked symlinks are POSIX-only")+ sys.exit(0)++binary = str(Path(sys.argv[1] if len(sys.argv) > 1 else "zig-out/bin/graff").resolve())+++def git(root, *args):+ return subprocess.check_output(["git", "-C", str(root), *args], text=True, stderr=subprocess.STDOUT).strip()+++def make_repo(root, toml_setup=None):+ root.mkdir()+ git(root, "init", "-q", "-b", "main")+ git(root, "config", "user.name", "Test")+ git(root, "config", "user.email", "[email protected]")+ (root / "app.txt").write_text("app\n")+ (root / "tracked.cfg").write_text("tracked\n")+ (root / ".gitignore").write_text(".env\nsecrets/\n.graff/\nprepared\n")+ agents = root / ".agents"+ agents.mkdir()+ prepare = agents / "prepare"+ prepare.write_text("#!/bin/sh\nset -eu\npwd > prepared\n")+ prepare.chmod(0o755)+ (agents / "linked").write_text("# shared, never committed\n/.env\nsecrets/\ntracked.cfg\n../escape\n*.key\nmissing.txt\n")+ if toml_setup:+ (root / ".graff").mkdir()+ (root / ".graff/workspace.toml").write_text(f'[scripts]\nsetup = "{toml_setup}"\n')+ git(root, "add", ".")+ git(root, "commit", "-qm", "initial")+ # Gitignored, so they exist only in the main checkout.+ (root / ".env").write_text("TOKEN=one\n")+ (root / "secrets").mkdir()+ (root / "secrets/key").write_text("k\n")+++def create(root, name):+ r = subprocess.run([binary, "worktree", "create", name], cwd=root, text=True, capture_output=True, timeout=60)+ assert r.returncode == 0, (r.returncode, r.stdout, r.stderr)+ for line in r.stdout.splitlines():+ line = line.strip()+ if line.startswith("/") and Path(line).is_dir():+ return Path(line), r.stdout+ # Fall back to the newest worktree git knows about.+ paths = [l.split(" ", 1)[1] for l in git(root, "worktree", "list", "--porcelain").splitlines() if l.startswith("worktree ")]+ return Path(paths[-1]), r.stdout+++with tempfile.TemporaryDirectory(prefix="graff-agents-prepare-") as temporary:+ root = Path(temporary).resolve() / "repo"+ make_repo(root)+ wt, out = create(root, "t1")+ assert wt != root and wt.is_dir(), out++ # prepare ran from the new checkout's root.+ assert (wt / "prepared").read_text().strip() == str(wt.resolve()), out++ # Gitignored entries became symlinks to the main checkout's copy.+ for rel in (".env", "secrets"):+ p = wt / rel+ assert p.is_symlink(), (rel, out)+ assert Path(os.readlink(p)).resolve() == (root / rel).resolve(), (rel, os.readlink(p))+ assert "linked 2 shared file(s)" in out, out++ # Edited once in the main checkout, current in the worktree.+ (root / ".env").write_text("TOKEN=two\n")+ assert (wt / ".env").read_text() == "TOKEN=two\n"++ # Tracked, escaping, glob and missing entries are never linked.+ assert not (wt / "tracked.cfg").is_symlink()+ assert (wt / "tracked.cfg").read_text() == "tracked\n"+ assert not (Path(temporary) / "escape").exists()+ assert not (wt / "missing.txt").exists()++ # A setup script in .graff/workspace.toml still wins over .agents/prepare.+ root2 = Path(temporary).resolve() / "repo2"+ make_repo(root2, toml_setup="printf toml > from-toml")+ wt2, out2 = create(root2, "t2")+ assert (wt2 / "from-toml").read_text() == "toml", out2+ assert not (wt2 / "prepared").exists(), out2++print("ok: .agents/prepare runs in a new worktree; .agents/linked links gitignored paths only")diff --git a/src/agents_prepare.zig b/src/agents_prepare.zignew file mode 100644index 00000000..ae7b0af3--- /dev/null+++ b/src/agents_prepare.zig@@ -0,0 +1,93 @@+//! The tool-neutral project setup convention in `.agents/` (the directory+//! graff already reads skills from): what a fresh worktree needs before an+//! agent works in it.+//!+//! - `.agents/prepare`: an executable script run from the new checkout's root+//! once it exists. It should be fast and safe to repeat (install+//! dependencies, point tools at a shared cache). `.graff/workspace.toml`'s+//! `setup` still wins when it names one.+//! - `.agents/linked`: one repository-relative path per line (`#` comments and+//! blank lines ignored, a leading `/` allowed). Each listed path must be+//! gitignored; the new checkout gets a symlink to the main checkout's copy,+//! so a `.env` edited once is current in every worktree.+//!+//! Linking only ever adds a symlink where nothing exists: a path the main+//! checkout lacks, or one the new checkout already has, is left alone, and+//! nothing is moved or deleted.++const std = @import("std");+const builtin = @import("builtin");+const Io = std.Io;+const Allocator = std.mem.Allocator;+const process_runner = @import("process_runner.zig");++/// Shell command that runs the checkout's prepare script, or null when it has none.+pub fn setupCommand(arena: Allocator, io: Io, checkout: []const u8) ?[]const u8 {+ const abs = std.fs.path.join(arena, &.{ checkout, ".agents/prepare" }) catch return null;+ const st = Io.Dir.cwd().statFile(io, abs, .{}) catch return null;+ if (st.kind != .file) return null;+ return "if [ -x .agents/prepare ]; then ./.agents/prepare; else sh ./.agents/prepare; fi";+}++/// The linked list's text: the checkout's committed copy, else the main checkout's.+fn linkedText(arena: Allocator, io: Io, checkout: []const u8, root: []const u8) ?[]const u8 {+ for ([_][]const u8{ checkout, root }) |base| {+ const path = std.fs.path.join(arena, &.{ base, ".agents/linked" }) catch return null;+ if (Io.Dir.cwd().readFileAlloc(io, path, arena, .limited(64 * 1024))) |t| return t else |_| {}+ }+ return null;+}++/// One entry as a safe repository-relative path, or null to skip it.+pub fn entryPath(line: []const u8) ?[]const u8 {+ var p = std.mem.trim(u8, line, " \t\r");+ if (p.len == 0 or p[0] == '#') return null;+ while (p.len > 0 and p[0] == '/') p = p[1..];+ while (p.len > 0 and p[p.len - 1] == '/') p = p[0 .. p.len - 1];+ if (p.len == 0) return null;+ var it = std.mem.splitScalar(u8, p, '/');+ while (it.next()) |part| {+ if (part.len == 0 or std.mem.eql(u8, part, "..") or std.mem.eql(u8, part, ".")) return null;+ if (std.mem.indexOfAny(u8, part, "*?[\\") != null) return null; // literal paths, never globs+ }+ return p;+}++fn ignoredInRoot(gpa: Allocator, io: Io, root: []const u8, rel: []const u8) bool {+ const r = process_runner.runCapped(gpa, io, &.{ "git", "-C", root, "check-ignore", "-q", "--", rel }, 256, 256, 15_000) catch return false;+ defer {+ gpa.free(r.stdout);+ gpa.free(r.stderr);+ }+ return process_runner.ranOk(r);+}++/// Symlink each listed gitignored path from the main checkout into a new+/// checkout. Returns how many links were made. Windows needs privileges for+/// symlinks, so it links nothing there (the `.env*` copy still applies).+pub fn linkShared(gpa: Allocator, io: Io, arena: Allocator, root: []const u8, checkout: []const u8) usize {+ if (builtin.os.tag == .windows) return 0;+ if (std.mem.eql(u8, root, checkout)) return 0;+ const text = linkedText(arena, io, checkout, root) orelse return 0;+ var n: usize = 0;+ var lines = std.mem.splitScalar(u8, text, '\n');+ while (lines.next()) |line| {+ const rel = entryPath(line) orelse continue;+ const shared = std.fs.path.join(arena, &.{ root, rel }) catch continue;+ const local = std.fs.path.join(arena, &.{ checkout, rel }) catch continue;+ _ = Io.Dir.cwd().statFile(io, shared, .{}) catch continue; // the main checkout lacks it+ if (Io.Dir.cwd().statFile(io, local, .{ .follow_symlinks = false })) |_| continue else |_| {}+ if (!ignoredInRoot(gpa, io, root, rel)) continue; // tracked files are never redirected+ if (std.fs.path.dirname(local)) |parent| Io.Dir.cwd().createDirPath(io, parent) catch continue;+ Io.Dir.cwd().symLink(io, shared, local, .{}) catch continue;+ n += 1;+ }+ return n;+}++test "entryPath keeps literal repo-relative paths and drops the rest" {+ try std.testing.expectEqualStrings(".env", entryPath("/.env").?);+ try std.testing.expectEqualStrings("config/local", entryPath(" config/local/ \r").?);+ for ([_][]const u8{ "", " ", "# shared secrets", "/", "../outside", "a/../b", "./x", "*.env", "certs/**", "a//b" }) |bad|+ try std.testing.expect(entryPath(bad) == null);+}diff --git a/src/main.zig b/src/main.zigindex ab47b7b2..598db769 100644--- a/src/main.zig+++ b/src/main.zig@@ -565,7 +565,7 @@ test { // ── Unit tests (`zig build test`): pull in tests from imported modu_ = .{ @import("session_catalog.zig"), @import("session_prompt.zig"), @import("session_discovery.zig"), @import("session_workspaces.zig"), @import("commands_resume.zig"), @import("peer_live.zig"), @import("presence_tests.zig"), @import("mcp_rpc_tests.zig") };_ = .{ @import("prompt_astra.zig"), @import("prompt_guidance.zig"), @import("oauth_chatgpt.zig"), @import("chatgpt_reauth.zig") }; // per-model guidance (Astra, GPT-5.6); ChatGPT plan sign-in (ADR 0253)_ = .{ @import("agent_empty_completion.zig"), @import("agent_model_loop.zig"), @import("publication_policy_tests.zig"), @import("jobs_completion_tests.zig") };- _ = .{ @import("provider_routing_tests.zig"), @import("codegraff_messages_tests.zig"), @import("tool_result_empty_tests.zig"), @import("history_wire.zig"), @import("catalog_price.zig"), @import("readline_paste_number_tests.zig"), @import("test_hooks.zig"), @import("peer_wake_loop.zig") };+ _ = .{ @import("provider_routing_tests.zig"), @import("codegraff_messages_tests.zig"), @import("tool_result_empty_tests.zig"), @import("history_wire.zig"), @import("agents_prepare.zig"), @import("catalog_price.zig"), @import("readline_paste_number_tests.zig"), @import("test_hooks.zig"), @import("peer_wake_loop.zig") };_ = .{ @import("list_dir_nearmiss.zig"), @import("tool_preview_tests.zig") };_ = @import("repo_map.zig");_ = @import("agent_overflow_tests.zig"); // #414: and, through it, agent_overflow.zig's table testsdiff --git a/src/task_workspace.zig b/src/task_workspace.zigindex bbcc061a..bb587b0e 100644--- a/src/task_workspace.zig+++ b/src/task_workspace.zig@@ -48,6 +48,7 @@ pub const Workspace = struct {branch: []const u8,base: []const u8 = "",copied: usize = 0,+ linked: usize = 0,setup_ran: bool = false,setup_ok: bool = true,};@@ -255,6 +256,7 @@ pub fn create(gpa: Allocator, io: Io, arena: Allocator, opts: CreateOpts) (Creat.branch = named.branch,.base = readHead(gpa, io, arena, path),.copied = prep.copied,+ .linked = prep.linked,.setup_ran = prep.setup_ran,.setup_ok = prep.setup_ok,};diff --git a/src/workspace_prepare.zig b/src/workspace_prepare.zigindex c9437de9..c23ae09a 100644--- a/src/workspace_prepare.zig+++ b/src/workspace_prepare.zig@@ -1,5 +1,6 @@-//! After minting a task worktree: copy selected gitignored files and run-//! project scripts from `.graff/workspace.toml`.+//! After minting a task worktree: link and copy selected gitignored files and+//! run project scripts from `.graff/workspace.toml`, or the tool-neutral+//! `.agents/prepare` + `.agents/linked` (agents_prepare.zig).const std = @import("std");const Io = std.Io;@@ -28,6 +29,7 @@ pub const Scripts = struct {pub const Report = struct {copied: usize = 0,+ linked: usize = 0,setup_ran: bool = false,setup_ok: bool = true,};@@ -68,11 +70,14 @@ pub fn loadScripts(arena: Allocator, io: Io, root: []const u8) Scripts {pub fn afterCreate(gpa: Allocator, io: Io, arena: Allocator, cwd: []const u8, dest: []const u8, name: []const u8) Report {const root = mainCheckout(gpa, io, arena, cwd);var report: Report = .{};+ const agents = @import("agents_prepare.zig");+ // Link before copying, so a linked path becomes a symlink, not a stale copy.+ report.linked = agents.linkShared(gpa, io, arena, root, dest);report.copied = copyIgnored(gpa, io, arena, root, dest);const scripts = loadScripts(arena, io, root);- if (scripts.setup.len == 0) return report;+ const setup = if (scripts.setup.len > 0) scripts.setup else agents.setupCommand(arena, io, dest) orelse return report;report.setup_ran = true;- report.setup_ok = runScript(gpa, io, arena, scripts.setup, dest, root, name, setup_ms);+ report.setup_ok = runScript(gpa, io, arena, setup, dest, root, name, setup_ms);return report;}diff --git a/src/worktree_cmd.zig b/src/worktree_cmd.zigindex 938a5be2..3596fb8c 100644--- a/src/worktree_cmd.zig+++ b/src/worktree_cmd.zig@@ -244,6 +244,7 @@ fn runTo(gpa: Allocator, io: Io, arena: Allocator, args: []const []const u8, outreturn;};try out.print("✓ workspace {s}\n path {s}\n branch {s}\n", .{ wt.name, wt.path, wt.branch });+ if (wt.linked > 0) try out.print(" linked {d} shared file(s) from the main checkout\n", .{wt.linked});if (wt.copied > 0) try out.print(" copied {d} gitignored file(s)\n", .{wt.copied});if (wt.setup_ran) try out.print(" setup {s}\n", .{if (wt.setup_ok) "ok" else "failed (workspace kept)"});return;