graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
//! Task workspace = one Git worktree + one branch + one checkout.
//! Concurrent root sessions auto-isolate so they never share `index.lock`.
const std = @import("std");
const builtin = @import("builtin");
const Io = std.Io;
const Allocator = std.mem.Allocator;
const process_runner = @import("process_runner.zig");
const runCapped = process_runner.runCapped;
const ranOk = process_runner.ranOk;
const lease = @import("worktree_lease.zig");
const presence = @import("presence.zig");
const proc_identity = @import("proc_identity.zig");
const main_mod = @import("main.zig");
const tool_spill = @import("tool_spill.zig");
const agent_worktree = @import("agent_worktree.zig");
const worktree_prune = @import("worktree_prune.zig");
const workspace_prepare = @import("workspace_prepare.zig");
pub const CreateError = error{ NotAGitRepo, InvalidName, NameCollision, CreateFailed, Unsupported };
pub const ArchiveError = error{ InvalidName, NotFound, ArchiveFailed, TeardownFailed };
pub const UpdateError = error{ InvalidName, NotFound, Dirty, MergeFailed };
pub const AutoIsolate = union(enum) {
skip,
isolated: Workspace,
failed: anyerror,
};
pub const ArchiveResult = struct {
removed: bool,
reason: agent_worktree.KeepReason,
path: []const u8,
branch: []const u8,
};
pub const CreateOpts = struct {
slug: []const u8,
base: []const u8 = "",
cwd: []const u8 = ".",
unique: bool = false,
};
pub const Workspace = struct {
name: []const u8,
path: []const u8,
branch: []const u8,
base: []const u8 = "",
copied: usize = 0,
linked: usize = 0,
setup_ran: bool = false,
setup_ok: bool = true,
};
pub const AutoOpts = struct {
already_isolated: bool = false,
lean: bool = false,
is_git: bool = false,
claimed: bool = false,
windows: bool = false,
};
/// Concurrent interactive sessions isolate. Lean/-p oneshots stay put (ADR 0024).
/// `-w` already isolated. Non-git folders stay plain folders. Windows has no chdir.
pub fn shouldAutoIsolate(opts: AutoOpts) bool {
if (opts.windows or opts.already_isolated or opts.lean or !opts.is_git) return false;
return opts.claimed;
}
pub fn sanitizeSlug(s: []const u8) ?[]const u8 {
const t = std.mem.trim(u8, s, " \t\r\n");
if (t.len == 0 or t.len > 64) return null;
if (std.mem.indexOfScalar(u8, t, '/') != null or std.mem.indexOfScalar(u8, t, '\\') != null) return null;
if (std.mem.eql(u8, t, ".") or std.mem.eql(u8, t, "..")) return null;
for (t) |c| {
const ok = std.ascii.isAlphanumeric(c) or c == '-' or c == '_' or c == '.';
if (!ok) return null;
}
return t;
}
pub fn names(arena: Allocator, slug: []const u8) !Workspace {
const name = sanitizeSlug(slug) orelse return error.InvalidName;
return .{
.name = name,
.path = try std.fmt.allocPrint(arena, ".graff/worktrees/{s}", .{name}),
.branch = try std.fmt.allocPrint(arena, "worktree-{s}", .{name}),
};
}
pub fn autoSlug(arena: Allocator, pid: i32, nonce: []const u8) ![]const u8 {
return std.fmt.allocPrint(arena, "session-{d}-{s}", .{ pid, nonce });
}
/// `{git-dir}/index.lock` — distinct per worktree, shared object DB is fine.
pub fn indexLockPath(arena: Allocator, git_dir: []const u8) ?[]const u8 {
const dir = std.mem.trimEnd(u8, git_dir, "/");
if (dir.len == 0) return null;
return std.fs.path.join(arena, &.{ dir, "index.lock" }) catch null;
}
pub fn gitDirAt(gpa: Allocator, io: Io, arena: Allocator, checkout: []const u8) []const u8 {
return lease.identityAt(gpa, io, arena, checkout).id;
}
/// Auto-isolation always writes under the owning main checkout, even when
/// the new session was launched from another linked worktree.
pub fn autoIsolationRoot(gpa: Allocator, io: Io, arena: Allocator, checkout: []const u8) ?[]const u8 {
const common = lease.gitCommonDirAt(gpa, io, arena, checkout);
const root = worktree_prune.mainWorktreePath(common);
return if (root.len > 0) root else null;
}
fn isGitAt(gpa: Allocator, io: Io, cwd: []const u8) bool {
const r = runCapped(gpa, io, &.{ "git", "-C", cwd, "rev-parse", "--is-inside-work-tree" }, 4096, 4096, 15_000) catch return false;
defer {
gpa.free(r.stdout);
gpa.free(r.stderr);
}
return ranOk(r);
}
fn dirExists(io: Io, path: []const u8) bool {
return (Io.Dir.cwd().statFile(io, path, .{}) catch null) != null;
}
fn joinCwd(arena: Allocator, cwd: []const u8, rel: []const u8) ![]const u8 {
if (std.fs.path.isAbsolute(rel)) return arena.dupe(u8, rel);
if (std.mem.eql(u8, cwd, ".") or cwd.len == 0) return arena.dupe(u8, rel);
return std.fs.path.join(arena, &.{ cwd, rel });
}
fn refExists(gpa: Allocator, io: Io, cwd: []const u8, branch: []const u8) bool {
const ref = std.fmt.allocPrint(gpa, "refs/heads/{s}", .{branch}) catch return false;
defer gpa.free(ref);
const r = runCapped(gpa, io, &.{ "git", "-C", cwd, "show-ref", "--verify", "--quiet", ref }, 4096, 4096, 15_000) catch return false;
defer {
gpa.free(r.stdout);
gpa.free(r.stderr);
}
return ranOk(r);
}
fn revExists(gpa: Allocator, io: Io, cwd: []const u8, rev: []const u8) bool {
const r = runCapped(gpa, io, &.{ "git", "-C", cwd, "rev-parse", "--verify", "--quiet", rev }, 4096, 4096, 15_000) catch return false;
defer {
gpa.free(r.stdout);
gpa.free(r.stderr);
}
return ranOk(r);
}
fn remoteHead(gpa: Allocator, io: Io, arena: Allocator, cwd: []const u8) []const u8 {
const r = runCapped(gpa, io, &.{ "git", "-C", cwd, "symbolic-ref", "--quiet", "refs/remotes/origin/HEAD" }, 4096, 4096, 15_000) catch return "";
defer {
gpa.free(r.stdout);
gpa.free(r.stderr);
}
if (!ranOk(r)) return "";
const ref = std.mem.trim(u8, r.stdout, " \t\r\n");
const prefix = "refs/remotes/";
const short = if (std.mem.startsWith(u8, ref, prefix)) ref[prefix.len..] else ref;
return arena.dupe(u8, short) catch "";
}
/// Conductor create: an explicit base wins; else origin/HEAD, origin/main, origin/master; else local HEAD.
pub fn preferRemoteBase(requested: []const u8, origin_head: []const u8, has_origin_main: bool, has_origin_master: bool) []const u8 {
if (requested.len > 0) return requested;
if (origin_head.len > 0) return origin_head;
if (has_origin_main) return "origin/main";
if (has_origin_master) return "origin/master";
return "";
}
pub fn resolveCreateBase(gpa: Allocator, io: Io, arena: Allocator, cwd: []const u8, requested: []const u8) []const u8 {
if (requested.len > 0) return requested;
if (runCapped(gpa, io, &.{ "git", "-C", cwd, "fetch", "--quiet", "origin" }, 4096, 4096, 60_000)) |r| {
gpa.free(r.stdout);
gpa.free(r.stderr);
} else |_| {}
return preferRemoteBase(
requested,
remoteHead(gpa, io, arena, cwd),
revExists(gpa, io, cwd, "origin/main"),
revExists(gpa, io, cwd, "origin/master"),
);
}
pub fn envIsolationFallback(val: ?[]const u8) bool {
const v = val orelse return false;
return std.mem.eql(u8, v, "1") or std.mem.eql(u8, v, "true") or std.mem.eql(u8, v, "yes");
}
/// Shared-checkout fixtures / explicit same-tree work. Default remains isolate.
pub fn envSkipAutoIsolate(val: ?[]const u8) bool {
const v = val orelse return false;
return std.mem.eql(u8, v, "0") or std.mem.eql(u8, v, "off") or std.mem.eql(u8, v, "false");
}
fn absPath(io: Io, arena: Allocator, path: []const u8) ![]const u8 {
var buf: [4096]u8 = undefined;
const n = Io.Dir.cwd().realPathFile(io, path, &buf) catch return arena.dupe(u8, path);
return arena.dupe(u8, buf[0..n]);
}
fn readHead(gpa: Allocator, io: Io, arena: Allocator, path: []const u8) []const u8 {
const r = runCapped(gpa, io, &.{ "git", "-C", path, "rev-parse", "HEAD" }, 4096, 4096, 15_000) catch return "";
defer {
gpa.free(r.stdout);
gpa.free(r.stderr);
}
if (!ranOk(r)) return "";
return arena.dupe(u8, std.mem.trim(u8, r.stdout, " \t\r\n")) catch "";
}
fn mintOnce(gpa: Allocator, io: Io, arena: Allocator, cwd: []const u8, rel: []const u8, branch: []const u8, base: []const u8) !void {
const dest = try joinCwd(arena, cwd, rel);
const parent = std.fs.path.dirname(dest) orelse dest;
Io.Dir.cwd().createDirPath(io, parent) catch {};
const add = if (base.len > 0)
runCapped(gpa, io, &.{ "git", "-C", cwd, "worktree", "add", dest, "-b", branch, base }, 8192, 8192, 60_000)
else
runCapped(gpa, io, &.{ "git", "-C", cwd, "worktree", "add", dest, "-b", branch }, 8192, 8192, 60_000);
const r = add catch return error.CreateFailed;
defer {
gpa.free(r.stdout);
gpa.free(r.stderr);
}
if (!ranOk(r)) return error.CreateFailed;
if (std.mem.indexOf(u8, rel, ".graff/") != null) @import("graff_dir.zig").ensureIgnoreAt(io, cwd); // #1273
}
pub fn create(gpa: Allocator, io: Io, arena: Allocator, opts: CreateOpts) (CreateError || Allocator.Error)!Workspace {
if (!isGitAt(gpa, io, opts.cwd)) return error.NotAGitRepo;
var named = try names(arena, opts.slug);
var dest = try joinCwd(arena, opts.cwd, named.path);
if (dirExists(io, dest) or refExists(gpa, io, opts.cwd, named.branch)) {
if (!opts.unique) return error.NameCollision;
var raw: [4]u8 = undefined;
io.random(&raw);
const nonce = std.fmt.bytesToHex(raw, .lower);
const slug = try std.fmt.allocPrint(arena, "{s}-{s}", .{ named.name, nonce[0..8] });
named = try names(arena, slug);
dest = try joinCwd(arena, opts.cwd, named.path);
if (dirExists(io, dest) or refExists(gpa, io, opts.cwd, named.branch)) return error.NameCollision;
}
const base = resolveCreateBase(gpa, io, arena, opts.cwd, opts.base);
try mintOnce(gpa, io, arena, opts.cwd, named.path, named.branch, base);
@import("worktree_base.zig").record(gpa, io, arena, opts.cwd, named.branch, base);
const path = try absPath(io, arena, dest);
const prep = workspace_prepare.afterCreate(gpa, io, arena, opts.cwd, path, named.name);
return .{
.name = named.name,
.path = path,
.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,
};
}
/// Reuse an existing checkout, or mint one. `-w` tabs come through here.
pub fn ensure(gpa: Allocator, io: Io, arena: Allocator, opts: CreateOpts) (CreateError || Allocator.Error)!Workspace {
if (!isGitAt(gpa, io, opts.cwd)) return error.NotAGitRepo;
const named = try names(arena, opts.slug);
const dest = try joinCwd(arena, opts.cwd, named.path);
if (dirExists(io, dest)) {
const path = try absPath(io, arena, dest);
return .{
.name = named.name,
.path = path,
.branch = named.branch,
.base = readHead(gpa, io, arena, path),
};
}
return create(gpa, io, arena, opts);
}
/// Fetch the remote base and merge it into the task workspace. Dirty trees stay untouched.
pub fn update(gpa: Allocator, io: Io, arena: Allocator, cwd: []const u8, slug: []const u8) (UpdateError || Allocator.Error)!Workspace {
const named = try names(arena, slug);
const dest = try joinCwd(arena, cwd, named.path);
if (!dirExists(io, dest)) return error.NotFound;
const path = try absPath(io, arena, dest);
const st = runCapped(gpa, io, &.{ "git", "-C", dest, "status", "--porcelain" }, 1 << 16, 8192, 30_000) catch return error.MergeFailed;
defer {
gpa.free(st.stdout);
gpa.free(st.stderr);
}
if (!ranOk(st)) return error.MergeFailed;
if (std.mem.trim(u8, st.stdout, " \t\r\n").len > 0) return error.Dirty;
const stored_base = @import("worktree_base.zig").read(gpa, io, arena, cwd, named.branch);
const remote = resolveCreateBase(gpa, io, arena, cwd, stored_base);
const base = if (remote.len > 0) remote else readHead(gpa, io, arena, cwd);
if (base.len == 0) return error.MergeFailed;
const m = runCapped(gpa, io, &.{ "git", "-C", dest, "merge", "--no-edit", base }, 1 << 16, 1 << 16, 60_000) catch return error.MergeFailed;
defer {
gpa.free(m.stdout);
gpa.free(m.stderr);
}
if (!ranOk(m)) return error.MergeFailed;
return .{
.name = named.name,
.path = path,
.branch = named.branch,
.base = readHead(gpa, io, arena, path),
};
}
pub fn updateFailureText(err: anyerror) []const u8 {
return switch (err) {
error.InvalidName => createFailureText(error.InvalidName),
error.NotFound => archiveFailureText(error.NotFound),
error.Dirty => "workspace has uncommitted changes — commit or stash them first, then update",
error.MergeFailed => "could not merge the remote base into this workspace (conflict or missing origin)",
else => "could not update the task workspace",
};
}
/// Archive removes a clean tree whose commits exist elsewhere. Dirty or unique-commit trees stay.
pub fn archive(gpa: Allocator, io: Io, arena: Allocator, cwd: []const u8, slug: []const u8) (ArchiveError || Allocator.Error)!ArchiveResult {
return archiveChecked(gpa, io, arena, cwd, slug, false);
}
pub fn archiveMerged(gpa: Allocator, io: Io, arena: Allocator, cwd: []const u8, slug: []const u8) (ArchiveError || Allocator.Error)!ArchiveResult {
return archiveChecked(gpa, io, arena, cwd, slug, true);
}
fn archiveChecked(gpa: Allocator, io: Io, arena: Allocator, cwd: []const u8, slug: []const u8, merged_only: bool) (ArchiveError || Allocator.Error)!ArchiveResult {
const named = try names(arena, slug);
const dest = try joinCwd(arena, cwd, named.path);
if (!dirExists(io, dest)) return error.NotFound;
const path = try absPath(io, arena, dest);
const kept = ArchiveResult{ .removed = false, .reason = .unverifiable, .path = path, .branch = named.branch };
if (!std.mem.eql(u8, @import("worktree_base.zig").branch(gpa, io, arena, dest), named.branch)) return kept;
const st = runCapped(gpa, io, &.{ "git", "-C", dest, "status", "--porcelain" }, 1 << 16, 8192, 30_000) catch return kept;
defer {
gpa.free(st.stdout);
gpa.free(st.stderr);
}
const head = readHead(gpa, io, arena, dest);
const own = try std.fmt.allocPrint(arena, "refs/heads/{s}", .{named.branch});
const refs = runCapped(gpa, io, &.{ "git", "-C", cwd, "branch", "--all", "--contains", head, "--format=%(refname)" }, 1 << 16, 8192, 30_000) catch return kept;
defer {
gpa.free(refs.stdout);
gpa.free(refs.stderr);
}
const merged = merged_only and @import("worktree_reap.zig").prMerged(gpa, io, cwd, named.branch, head);
if (merged_only and !merged) return .{ .removed = false, .reason = .committed, .path = path, .branch = named.branch };
const contained = merged or (ranOk(refs) and worktree_prune.containedElsewhere(refs.stdout, own));
const reason = agent_worktree.worktreeKeepReason(ranOk(st), st.stdout, worktree_prune.containmentBase(head, contained), head);
if (reason != .removed) return .{ .removed = false, .reason = reason, .path = path, .branch = named.branch };
if (!workspace_prepare.beforeArchive(gpa, io, arena, cwd, path, named.name)) return error.TeardownFailed;
if (runCapped(gpa, io, &.{ "git", "-C", cwd, "worktree", "remove", dest }, 8192, 8192, 30_000)) |r| {
defer {
gpa.free(r.stdout);
gpa.free(r.stderr);
}
if (!ranOk(r)) return error.ArchiveFailed;
} else |_| return error.ArchiveFailed;
if (runCapped(gpa, io, &.{ "git", "-C", cwd, "branch", "-D", named.branch }, 8192, 8192, 30_000)) |r| {
gpa.free(r.stdout);
gpa.free(r.stderr);
} else |_| {}
return .{ .removed = true, .reason = .removed, .path = path, .branch = named.branch };
}
/// Live foreign owner of THIS checkout, if any. Read-only: does not announce.
pub fn checkoutClaimed(gpa: Allocator, io: Io, arena: Allocator, home: []const u8) bool {
if (home.len == 0) return false;
const identity = lease.currentIdentity(gpa, io, arena);
if (identity.id.len == 0 or identity.kind == .not_git) return false;
const dir_path = std.fmt.allocPrint(arena, "{s}/{s}", .{ home, presence.registry_subdir }) catch return false;
var dir = Io.Dir.cwd().openDir(io, dir_path, .{ .iterate = true }) catch return false;
defer dir.close(io);
const peers = presence.listPeers(io, arena, dir);
const self = proc_identity.selfPid();
return lease.duplicateOwner(peers.records, peers.probes, identity.id, self) != null;
}
/// Take this checkout's startup claim, or report that a peer holds it (#1200).
fn startupContended(gpa: Allocator, io: Io, arena: Allocator, home: []const u8) bool {
if (home.len == 0) return false;
const identity = lease.currentIdentity(gpa, io, arena);
if (identity.id.len == 0 or identity.kind == .not_git) return false;
const dir_path = std.fmt.allocPrint(arena, "{s}/{s}", .{ home, presence.registry_subdir }) catch return false;
Io.Dir.cwd().createDirPath(io, dir_path) catch return false;
var dir = Io.Dir.cwd().openDir(io, dir_path, .{}) catch return false;
defer dir.close(io);
var buf: [48]u8 = undefined;
const claim = @import("startup_claim.zig");
return claim.heldByOther(io, dir, claim.fileName(&buf, identity.id), @import("util.zig").unixMs(io));
}
pub fn enter(io: Io, arena: Allocator, wt: Workspace) !void {
if (builtin.os.tag == .windows) return error.Unsupported;
const z = try arena.dupeSentinel(u8, wt.path, 0);
if (std.posix.system.chdir(z.ptr) != 0) return error.ChdirFailed;
// Session arena outlives the process; GPA dupes leaked at shutdown.
main_mod.g_cwd_display = try arena.dupe(u8, wt.path);
main_mod.g_worktree_branch = try arena.dupe(u8, wt.branch);
tool_spill.enable(.{ .io = io, .dir = .cwd(), .base_abs = main_mod.g_cwd_display });
}
/// Session-start hook: if another live session owns this checkout, mint and enter a tree.
/// A failed `git worktree add` is an isolation failure — do not stay on the claimed tree.
pub fn maybeAutoIsolate(gpa: Allocator, io: Io, arena: Allocator, home: []const u8, already_isolated: bool, lean: bool) AutoIsolate {
if (builtin.os.tag == .windows) return .skip;
const is_git = isGitAt(gpa, io, ".");
const eligible = shouldAutoIsolate(.{ .already_isolated = already_isolated, .lean = lean, .is_git = is_git, .claimed = true, .windows = false });
// #1200: a live peer, or one that started with us and has not announced yet.
if (!eligible or !(checkoutClaimed(gpa, io, arena, home) or startupContended(gpa, io, arena, home))) return .skip;
var raw: [4]u8 = undefined;
io.random(&raw);
const nonce = std.fmt.bytesToHex(raw, .lower);
const slug = autoSlug(arena, proc_identity.selfPid(), nonce[0..8]) catch return .{ .failed = error.CreateFailed };
const project = autoIsolationRoot(gpa, io, arena, ".") orelse return .{ .failed = error.CreateFailed };
const wt = create(gpa, io, arena, .{ .slug = slug, .cwd = project, .unique = true }) catch |err| return .{ .failed = err };
enter(io, arena, wt) catch |err| return .{ .failed = err };
return .{ .isolated = wt };
}
pub fn createFailureText(err: anyerror) []const u8 {
return switch (err) {
error.NotAGitRepo => "not a git repository — a task workspace needs a git repo; a plain folder stays a plain folder",
error.InvalidName => "workspace name must be 1-64 letters, digits, '.', '_' or '-' (no slashes)",
error.NameCollision => "that workspace name is already a worktree or branch — pick another name",
error.CreateFailed => "git worktree add failed (dirty HEAD, a name collision, or a git error) — isolation failed; set GRAFF_ISOLATION_FALLBACK=1 only to stay on the shared checkout",
else => "could not create a task workspace",
};
}
pub fn archiveFailureText(err: anyerror) []const u8 {
return switch (err) {
error.InvalidName => createFailureText(error.InvalidName),
error.NotFound => "no such task workspace — `graff worktree list` to see them",
error.ArchiveFailed => "git worktree remove failed — the checkout was kept",
error.TeardownFailed => "archive script failed; workspace kept",
else => "could not archive the task workspace",
};
}