graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
//! Canonical worktree identity and the duplicate-owner preflight (#320).
//!
//! Two graff sessions started in different subdirectories of the same checkout
//! (or through a symlink) must resolve to ONE identity, while two separate
//! `git worktree add` checkouts must not collide. `git rev-parse --git-dir
//! --git-common-dir` answers both at once: the common dir is shared by a repo
//! and every worktree linked to it, so `git_dir == common_dir` means "the main
//! checkout" and anything else is a linked worktree whose git dir is already
//! unique per worktree. Both are resolved by git itself, so a symlinked or
//! nested cwd collapses onto the same string.
//!
//! What is deliberately NOT here: the durable lease registry. `ownerVerdict` is
//! the whole decision — given a record it says self / live-foreign / stale —
//! and it already honours #320's rule that a pid alone may never signal an
//! owner. Nothing writes records yet, so no root session is warned at startup;
//! that needs a registry file plus a call site in startup.zig.
//!
//! #413 supplied the missing half: `proc_identity` reads a pid's START
//! identity, so "is that pid still the process that recorded it" is now a
//! question the OS answers rather than one this file has to be handed.
const std = @import("std");
const Io = std.Io;
const Allocator = std.mem.Allocator;
const process_runner = @import("process_runner.zig");
const proc_identity = @import("proc_identity.zig");
const runCapped = process_runner.runCapped;
const ranOk = process_runner.ranOk;
pub const Identity = struct {
/// Stable string two sessions can compare. Empty only when even the cwd
/// fallback failed.
id: []const u8 = "",
kind: Kind = .not_git,
pub const Kind = enum { not_git, main_checkout, linked_worktree };
};
/// Trim and drop a trailing slash so `/repo/.git` and `/repo/.git/` compare
/// equal. Returns a slice of the input.
fn normalizePath(p: []const u8) []const u8 {
const t = std.mem.trim(u8, p, " \t\r\n");
if (t.len <= 1) return t;
return std.mem.trimEnd(u8, t, "/");
}
/// Pure half of the #320 identity: `git_dir`/`common_dir` are the `git rev-parse
/// --path-format=absolute --git-dir --git-common-dir` answers (empty when git
/// could not be asked), `fallback_path` the canonical cwd used outside a repo.
pub fn canonicalIdentity(git_dir: []const u8, common_dir: []const u8, fallback_path: []const u8) Identity {
const g = normalizePath(git_dir);
const c = normalizePath(common_dir);
if (g.len == 0) return .{ .id = normalizePath(fallback_path), .kind = .not_git };
// git_dir == common_dir is exactly "this is the repo's own checkout"; a
// linked worktree's git dir is <common>/worktrees/<name>, already unique.
if (c.len == 0 or std.mem.eql(u8, g, c)) return .{ .id = g, .kind = .main_checkout };
return .{ .id = g, .kind = .linked_worktree };
}
/// One recorded root-session owner of a worktree identity. `start_id` is the
/// process START identity, not just the pid: after a crash the OS may hand the
/// same pid to something unrelated, and #320 requires that never look like an
/// owner. `proc_identity` produces the value and knows its units.
pub const Owner = struct {
pid: i32 = 0,
start_id: proc_identity.StartId = 0,
session_id: []const u8 = "",
identity: []const u8 = "",
/// #469: the owner's last-known objective — the coordination payload a
/// peer reads to decide whether its work overlaps. Empty when unknown.
goal: []const u8 = "",
last_seen_ms: i64 = 0,
/// Last root-turn start/completion, not registry refresh. Zero means unknown.
last_activity_ms: i64 = 0,
activity: []const u8 = "connected",
/// #700: the human title from `.session.json`. Empty on older records.
title: []const u8 = "",
/// #700: durable saved-session file base (slug). Empty on older records.
session_base: []const u8 = "",
};
pub const OwnerVerdict = enum {
/// This record is the running session asking.
self,
/// A record for a different worktree — never a conflict.
other_worktree,
/// Another root session is alive in MY worktree: the #320 warning case.
live_foreign,
/// The pid is alive but its identity could not be read, so we cannot prove
/// it is NOT the recorded owner. Warned about like a live one (#413): the
/// cost of a needless warning is a line of text, the cost of staying quiet
/// is two sessions editing one tree.
live_unverified,
/// The owner exited (or its pid now belongs to something else).
stale_dead,
/// Not enough evidence to claim anyone owns it; treated as stale.
stale_unverifiable,
};
/// The record for this process, ready to be written to a registry.
pub fn selfOwner(io: Io, identity: []const u8, session_id: []const u8, now_ms: i64) Owner {
return .{
.pid = proc_identity.selfPid(),
.start_id = proc_identity.selfStartId(io),
.session_id = session_id,
.identity = identity,
.last_seen_ms = now_ms,
};
}
/// `live` is what the OS says about `rec.pid` right now (`proc_identity.probe`).
pub fn ownerVerdict(rec: Owner, my_identity: []const u8, my_pid: i32, live: proc_identity.Probe) OwnerVerdict {
if (rec.identity.len == 0 or my_identity.len == 0) return .stale_unverifiable;
if (!std.mem.eql(u8, rec.identity, my_identity)) return .other_worktree;
// A record with no start identity can only be matched by pid, and pid alone
// is precisely what #320 says must not signal an owner. Unlike a mutual
// exclusion lock — where honouring a legacy record is the safe answer —
// this one only prints a warning, so the false-positive is the harm.
if (rec.start_id == 0) return .stale_unverifiable;
const unverified = switch (live) {
.gone => return .stale_dead,
.id => |v| blk: {
if (v != rec.start_id) return .stale_dead; // pid reuse, not the owner
break :blk false;
},
.unknown => true,
};
if (rec.pid == my_pid) return .self;
return if (unverified) .live_unverified else .live_foreign;
}
/// The #320 preflight: the first live foreign owner of MY worktree, if any.
/// Everything else — my own record, another worktree's, a crashed or pid-reused
/// one — is silent, so a stale registry can never block a startup.
/// `probes[i]` pairs with `records[i]`; a record past the end of `probes` was
/// never probed at all, which is no evidence of anything and so is skipped.
pub fn duplicateOwner(records: []const Owner, probes: []const proc_identity.Probe, my_identity: []const u8, my_pid: i32) ?Owner {
for (records, 0..) |rec, i| {
if (i >= probes.len) break;
switch (ownerVerdict(rec, my_identity, my_pid, probes[i])) {
.live_foreign, .live_unverified => return rec,
else => {},
}
}
return null;
}
/// Probe every record's pid once into caller storage; the slice it returns is
/// what `duplicateOwner` expects.
pub fn probeOwners(io: Io, records: []const Owner, out: []proc_identity.Probe) []const proc_identity.Probe {
const n = @min(records.len, out.len);
for (records[0..n], out[0..n]) |rec, *slot| slot.* = proc_identity.probe(io, rec.pid);
return out[0..n];
}
pub fn duplicateOwnerWarning(arena: Allocator, rec: Owner, age_ms: i64) []const u8 {
const mins = @divTrunc(if (age_ms > 0) age_ms else 0, std.time.ms_per_min);
const goal = if (rec.goal.len > 0) std.fmt.allocPrint(arena, "\n goal: {s}", .{rec.goal}) catch "" else "";
return std.fmt.allocPrint(
arena,
"⚠ another graff session already owns this worktree\n pid {d} · session {s} · active {d}m{s}\n you would both be editing the same uncommitted tree — restart with -w for an isolated worktree, or continue knowing edits can collide\n",
.{ rec.pid, if (rec.session_id.len > 0) rec.session_id else "unknown", mins, goal },
) catch "⚠ another graff session already owns this worktree\n";
}
fn revParse(gpa: Allocator, io: Io, arena: Allocator, flag: []const u8) []const u8 {
// --path-format=absolute so a nested cwd yields the same string as the repo
// root. Old git without the flag just fails and we degrade to the cwd.
const r = runCapped(gpa, io, &.{ "git", "rev-parse", "--path-format=absolute", flag }, 8192, 8192, 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 "";
}
/// `<main checkout>/.git`, shared by the repo and every worktree linked to it.
pub fn gitCommonDir(gpa: Allocator, io: Io, arena: Allocator) []const u8 {
return revParse(gpa, io, arena, "--git-common-dir");
}
/// Same as `gitCommonDir`, but `git -C dir` so a worktree switch still hits
/// the shared `.git` of the repository.
pub fn gitCommonDirAt(gpa: Allocator, io: Io, arena: Allocator, dir: []const u8) []const u8 {
if (dir.len == 0) return gitCommonDir(gpa, io, arena);
return revParseAt(gpa, io, arena, dir, "--git-common-dir");
}
fn revParseAt(gpa: Allocator, io: Io, arena: Allocator, dir: []const u8, flag: []const u8) []const u8 {
const r = runCapped(gpa, io, &.{ "git", "-C", dir, "rev-parse", "--path-format=absolute", flag }, 8192, 8192, 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 "";
}
/// Live canonical identity for this process's working directory.
pub fn currentIdentity(gpa: Allocator, io: Io, arena: Allocator) Identity {
const git_dir = revParse(gpa, io, arena, "--git-dir");
const common = gitCommonDir(gpa, io, arena);
var buf: [4096]u8 = undefined;
const cwd = blk: {
const n = Io.Dir.cwd().realPathFile(io, ".", &buf) catch break :blk "";
break :blk arena.dupe(u8, buf[0..n]) catch "";
};
return canonicalIdentity(git_dir, common, cwd);
}
/// Identity of an explicit path (`git -C` / `cd` target), not the caller cwd.
pub fn identityAt(gpa: Allocator, io: Io, arena: Allocator, path: []const u8) Identity {
if (path.len == 0) return .{};
const git_dir = revParseAt(gpa, io, arena, path, "--git-dir");
const common = revParseAt(gpa, io, arena, path, "--git-common-dir");
var buf: [4096]u8 = undefined;
const cwd = blk: {
const n = Io.Dir.cwd().realPathFile(io, path, &buf) catch break :blk path;
break :blk arena.dupe(u8, buf[0..n]) catch path;
};
return canonicalIdentity(git_dir, common, cwd);
}
pub fn identityLine(arena: Allocator, id: Identity) []const u8 {
const kind = switch (id.kind) {
.main_checkout => "main checkout",
.linked_worktree => "linked worktree",
.not_git => "not a git repository",
};
return std.fmt.allocPrint(arena, "identity: {s} ({s})", .{ if (id.id.len > 0) id.id else "unknown", kind }) catch "identity: unknown";
}
test "canonicalIdentity: one id per worktree, distinct across linked worktrees (#320)" {
// Subdirectory / symlinked cwd: git resolves both to the same git dir, so
// the identity is the same string.
const main_a = canonicalIdentity("/repo/.git", "/repo/.git", "/repo");
const main_b = canonicalIdentity("/repo/.git/", "/repo/.git", "/repo/src/deep");
try std.testing.expectEqual(Identity.Kind.main_checkout, main_a.kind);
try std.testing.expectEqualStrings(main_a.id, main_b.id);
// A linked worktree has its own git dir, so it never collides with main…
const linked = canonicalIdentity("/repo/.git/worktrees/wt1", "/repo/.git", "/elsewhere/wt1");
try std.testing.expectEqual(Identity.Kind.linked_worktree, linked.kind);
try std.testing.expect(!std.mem.eql(u8, linked.id, main_a.id));
// …nor with a sibling worktree of the same repo.
const sibling = canonicalIdentity("/repo/.git/worktrees/wt2", "/repo/.git", "/elsewhere/wt2");
try std.testing.expect(!std.mem.eql(u8, linked.id, sibling.id));
// Outside a repo we still have an identity: the canonical cwd.
const loose = canonicalIdentity("", "", "/tmp/scratch/");
try std.testing.expectEqual(Identity.Kind.not_git, loose.kind);
try std.testing.expectEqualStrings("/tmp/scratch", loose.id);
}
test "ownerVerdict: only a verified live process in MY worktree is an owner (#320)" {
const me = "/repo/.git";
const rec: Owner = .{ .pid = 4242, .start_id = 777, .session_id = "s-1", .identity = me };
try std.testing.expectEqual(OwnerVerdict.live_foreign, ownerVerdict(rec, me, 99, .{ .id = 777 }));
try std.testing.expectEqual(OwnerVerdict.self, ownerVerdict(rec, me, 4242, .{ .id = 777 }));
// Separate git worktrees do not conflict.
try std.testing.expectEqual(OwnerVerdict.other_worktree, ownerVerdict(rec, "/repo/.git/worktrees/wt1", 99, .{ .id = 777 }));
// Crashed owner: the pid is simply gone.
try std.testing.expectEqual(OwnerVerdict.stale_dead, ownerVerdict(rec, me, 99, .gone));
// PID reuse: the pid is live but it is a different process.
try std.testing.expectEqual(OwnerVerdict.stale_dead, ownerVerdict(rec, me, 99, .{ .id = 778 }));
// No start identity recorded — unverifiable is stale, never a warning.
var no_start = rec;
no_start.start_id = 0;
try std.testing.expectEqual(OwnerVerdict.stale_unverifiable, ownerVerdict(no_start, me, 99, .{ .id = 777 }));
}
test "ownerVerdict: a pid we cannot identify is assumed to be the owner (#413)" {
const me = "/repo/.git";
const rec: Owner = .{ .pid = 4242, .start_id = 777, .session_id = "s-1", .identity = me };
// An unreadable identity is not evidence of death: warn rather than treat
// a possibly live session as stale.
try std.testing.expectEqual(OwnerVerdict.live_unverified, ownerVerdict(rec, me, 99, .unknown));
// …but it is still not somebody else when the pid is mine.
try std.testing.expectEqual(OwnerVerdict.self, ownerVerdict(rec, me, 4242, .unknown));
}
test "duplicateOwner: picks the live foreign session and ignores stale records (#320)" {
const me = "/repo/.git";
const records = [_]Owner{
.{ .pid = 1, .start_id = 10, .session_id = "dead", .identity = me },
.{ .pid = 2, .start_id = 20, .session_id = "other-wt", .identity = "/repo/.git/worktrees/wt1" },
.{ .pid = 3, .start_id = 30, .session_id = "mine", .identity = me },
.{ .pid = 4, .start_id = 40, .session_id = "live", .identity = me },
};
const live = [_]proc_identity.Probe{ .gone, .{ .id = 20 }, .{ .id = 30 }, .{ .id = 40 } };
const found = duplicateOwner(&records, &live, me, 3) orelse return error.ExpectedDuplicate;
try std.testing.expectEqualStrings("live", found.session_id);
try std.testing.expectEqual(@as(i32, 4), found.pid);
// Alone in the worktree: only my own record matches, so no warning.
const solo = [_]Owner{records[2]};
try std.testing.expect(duplicateOwner(&solo, &.{.{ .id = 30 }}, me, 3) == null);
// A registry we cannot read at all must not manufacture an owner.
try std.testing.expect(duplicateOwner(&records, &.{}, me, 3) == null);
}
test "selfOwner + probeOwners: this process records and verifies as itself (#413)" {
const io = std.testing.io;
const me = "/repo/.git";
const mine = selfOwner(io, me, "s-self", 1234);
try std.testing.expect(mine.pid > 0);
var probes: [1]proc_identity.Probe = undefined;
const live = probeOwners(io, &.{mine}, &probes);
try std.testing.expectEqual(@as(usize, 1), live.len);
// My own live record is `self`, never a duplicate owner…
try std.testing.expectEqual(OwnerVerdict.self, ownerVerdict(mine, me, mine.pid, live[0]));
try std.testing.expect(duplicateOwner(&.{mine}, live, me, mine.pid) == null);
// …and a record claiming my pid from a process that no longer exists is
// stale, which is the whole point: a recycled pid cannot hold a lease.
if (mine.start_id != 0) {
var recycled = mine;
recycled.start_id +%= 1;
try std.testing.expectEqual(OwnerVerdict.stale_dead, ownerVerdict(recycled, me, mine.pid, live[0]));
}
}
test "duplicateOwnerWarning: names the pid, the session and an escape hatch (#320)" {
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const text = duplicateOwnerWarning(arena_state.allocator(), .{ .pid = 4242, .start_id = 1, .session_id = "s-1" }, 5 * std.time.ms_per_min);
try std.testing.expect(std.mem.indexOf(u8, text, "4242") != null);
try std.testing.expect(std.mem.indexOf(u8, text, "s-1") != null);
try std.testing.expect(std.mem.indexOf(u8, text, "5m") != null);
try std.testing.expect(std.mem.indexOf(u8, text, "-w") != null);
}
test "identityLine: says which kind of checkout, and stays honest when unknown" {
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const a = arena_state.allocator();
try std.testing.expect(std.mem.indexOf(u8, identityLine(a, .{ .id = "/repo/.git", .kind = .main_checkout }), "main checkout") != null);
try std.testing.expect(std.mem.indexOf(u8, identityLine(a, .{ .id = "/repo/.git/worktrees/w", .kind = .linked_worktree }), "linked worktree") != null);
try std.testing.expect(std.mem.indexOf(u8, identityLine(a, .{}), "unknown") != null);
}
fn initBareRepo(gpa: Allocator, io: Io, path: []const u8) !void {
const r = try runCapped(gpa, io, &.{ "git", "init", "-q", path }, 4096, 4096, 15_000);
defer {
gpa.free(r.stdout);
gpa.free(r.stderr);
}
if (!ranOk(r)) return error.GitInitFailed;
}
test "#851 identityAt distinguishes isolated checkouts and matches a subdirectory" {
const io = std.testing.io;
const gpa = std.testing.allocator;
var arena_state = std.heap.ArenaAllocator.init(gpa);
defer arena_state.deinit();
const a = arena_state.allocator();
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const root = try tmp.dir.realPathFileAlloc(io, ".", a);
const path_a = try std.fmt.allocPrint(a, "{s}/a", .{root});
const path_b = try std.fmt.allocPrint(a, "{s}/b", .{root});
const path_sub = try std.fmt.allocPrint(a, "{s}/a/src", .{root});
try tmp.dir.createDirPath(io, "a/src");
try tmp.dir.createDirPath(io, "b");
try initBareRepo(gpa, io, path_a);
try initBareRepo(gpa, io, path_b);
const id_a = identityAt(gpa, io, a, path_a);
const id_b = identityAt(gpa, io, a, path_b);
const id_sub = identityAt(gpa, io, a, path_sub);
try std.testing.expect(id_a.id.len > 0);
try std.testing.expect(id_b.id.len > 0);
try std.testing.expect(!std.mem.eql(u8, id_a.id, id_b.id));
try std.testing.expectEqualStrings(id_a.id, id_sub.id);
}