graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
//! Ownership records for background jobs (#199): `~/.codegraff/jobs/<pid>.json`,
//! one per live job, written at spawn and removed when the pump reaps it.
//! The record is what outlives a graff that died without running its defers
//! (SIGKILL, a closed terminal): the process tree may still be alive, and
//! `graff servers` reads these to find it, show its ports, and stop it — only
//! ever a tree graff itself started, checked against the leader's pid AND
//! start identity (#413) so a recycled pid never gets an unrelated process
//! killed. A pinned job the session keeps on exit stays here, `retained`.
//!
//! Ports are not stored: a server is not listening yet when it is spawned.
//! They are read live (`lsof` by process group) when someone looks.
const std = @import("std");
const builtin = @import("builtin");
const Io = std.Io;
const Allocator = std.mem.Allocator;
const proc_identity = @import("proc_identity.zig");
const process_runner = @import("process_runner.zig");
const posix = builtin.os.tag != .windows and builtin.os.tag != .wasi;
/// The process $HOME, pinned at startup beside oauth.initHome. "" (tests, no
/// HOME) means no on-disk record; the in-session pool is unaffected.
pub var home: []const u8 = "";
pub const Record = struct {
pid: i32,
start_id: u64 = 0,
owner_pid: i32 = 0,
owner_start_id: u64 = 0,
cmd: []const u8,
cwd: []const u8 = "",
started_ms: i64 = 0,
pinned: bool = false,
retained: bool = false,
retention_reason: ?enum { user_pin, unverified_consumers } = null,
};
pub fn dirPath(buf: []u8, base: []const u8) ?[]const u8 {
if (base.len == 0) return null;
return std.fmt.bufPrint(buf, "{s}/.codegraff/jobs", .{base}) catch null;
}
fn recordPath(buf: []u8, base: []const u8, pid: i32) ?[]const u8 {
if (base.len == 0) return null;
return std.fmt.bufPrint(buf, "{s}/.codegraff/jobs/{d}.json", .{ base, pid }) catch null;
}
/// Write (or rewrite) one record. Best-effort: no HOME or an unwritable dir
/// costs the cross-session view, never the job.
pub fn write(io: Io, base: []const u8, rec: Record) void {
var dbuf: [std.fs.max_path_bytes]u8 = undefined;
const dir = dirPath(&dbuf, base) orelse return;
Io.Dir.cwd().createDirPath(io, dir) catch return;
var pbuf: [std.fs.max_path_bytes]u8 = undefined;
const path = recordPath(&pbuf, base, rec.pid) orelse return;
var jbuf: [16 * 1024]u8 = undefined;
var w: Io.Writer = .fixed(&jbuf);
var s: std.json.Stringify = .{ .writer = &w };
s.write(rec) catch return;
Io.Dir.cwd().writeFile(io, .{ .sub_path = path, .data = w.buffered() }) catch return;
}
pub fn forget(io: Io, base: []const u8, pid: i32) void {
var pbuf: [std.fs.max_path_bytes]u8 = undefined;
const path = recordPath(&pbuf, base, pid) orelse return;
Io.Dir.cwd().deleteFile(io, path) catch {};
}
fn earlier(_: void, a: Record, b: Record) bool {
return a.started_ms < b.started_ms;
}
/// Every record on disk, oldest first, arena-owned.
pub fn list(io: Io, arena: Allocator, base: []const u8) []const Record {
var out: std.ArrayList(Record) = .empty;
var dbuf: [std.fs.max_path_bytes]u8 = undefined;
const dir_path = dirPath(&dbuf, base) orelse return &.{};
var dir = Io.Dir.cwd().openDir(io, dir_path, .{ .iterate = true }) catch return &.{};
defer dir.close(io);
var it = dir.iterate();
while (it.next(io) catch null) |entry| {
if (entry.kind != .file or !std.mem.endsWith(u8, entry.name, ".json")) continue;
const data = dir.readFileAlloc(io, entry.name, arena, .limited(64 * 1024)) catch continue;
const rec = std.json.parseFromSliceLeaky(Record, arena, data, .{ .ignore_unknown_fields = true }) catch continue;
out.append(arena, rec) catch break;
}
@import("stable_sort.zig").sort(Record, out.items, {}, earlier);
return out.items;
}
pub const State = enum { running, gone, unverifiable };
/// Is the recorded leader still the process we started? A live pid with a
/// different start identity is a recycled pid: gone, and never signalled.
pub fn state(io: Io, rec: Record) State {
if (rec.pid <= 1) return .unverifiable;
return stateOf(rec.start_id, proc_identity.probe(io, rec.pid));
}
pub fn stateOf(start_id: u64, live: proc_identity.Probe) State {
return switch (live) {
.gone => .gone,
.unknown => .unverifiable,
.id => |v| if (start_id == 0 or v == 0) .unverifiable else if (v == start_id) .running else .gone,
};
}
/// Is the graff session that started it still alive?
pub fn ownerAlive(io: Io, rec: Record) bool {
if (rec.owner_pid <= 0) return false;
return stateOf(rec.owner_start_id, proc_identity.probe(io, rec.owner_pid)) != .gone;
}
/// Listening TCP sockets of the job's process group, `127.0.0.1:3002, *:3003`
/// style, or "" (Windows, no lsof, nothing listening). The leader was spawned
/// as its own group, so the group id is its pid.
pub fn listenPorts(gpa: Allocator, io: Io, arena: Allocator, pid: i32) []const u8 {
if (!posix) return "";
var pidbuf: [16]u8 = undefined;
const pid_s = std.fmt.bufPrint(&pidbuf, "{d}", .{pid}) catch return "";
const run = process_runner.runCapped(gpa, io, &.{ "lsof", "-a", "-P", "-n", "-iTCP", "-sTCP:LISTEN", "-g", pid_s, "-Fn" }, 64 * 1024, 4096, 5_000) catch return "";
defer {
gpa.free(run.stdout);
gpa.free(run.stderr);
}
return parseLsofPorts(arena, run.stdout);
}
/// `lsof -Fn`: one `n<addr>` line per socket (`n127.0.0.1:3002`, `n*:3003`)
/// between `p<pid>` / `f<fd>` lines. Deduped, joined with ", ".
pub fn parseLsofPorts(arena: Allocator, text: []const u8) []const u8 {
var out: std.ArrayList(u8) = .empty;
var seen: std.ArrayList([]const u8) = .empty;
var it = std.mem.splitScalar(u8, text, '\n');
while (it.next()) |raw| {
const line = std.mem.trim(u8, raw, "\r");
if (line.len < 2 or line[0] != 'n') continue;
const addr = line[1..];
var dup = false;
for (seen.items) |s| {
if (std.mem.eql(u8, s, addr)) dup = true;
}
if (dup) continue;
seen.append(arena, addr) catch break;
if (out.items.len > 0) out.appendSlice(arena, ", ") catch break;
out.appendSlice(arena, addr) catch break;
}
return out.items;
}
pub const StopResult = @import("job_registry_stop.zig").Result;
/// TERM the whole group, give it 2s, then KILL — only when the leader still
/// carries the recorded start identity.
pub fn stopTree(io: Io, rec: Record) StopResult {
if (!posix) return .unsupported;
const stop = @import("job_registry_stop.zig");
return stop.stop(rec.pid, rec.start_id, stop.Native{ .io = io });
}
/// Session end for a pinned job: hand each of its pipes to a detached
/// `cat >/dev/null` so the server never sees EPIPE once graff's read ends
/// close with the process (a Node dev server dies on its next log line
/// otherwise), then rewrite the record as retained. False when a drainer
/// could not start — the caller kills the job rather than leak a
/// half-detached one.
pub fn retain(io: Io, base: []const u8, rec: Record, stdout: ?Io.File, stderr: ?Io.File) bool {
if (!posix) return false;
for ([_]?Io.File{ stdout, stderr }) |maybe| {
const f = maybe orelse continue;
_ = std.process.spawn(io, .{
.argv = &.{ "/bin/sh", "-c", "exec cat >/dev/null 2>&1" },
.stdin = .{ .file = f },
.stdout = .ignore,
.stderr = .ignore,
.pgid = 0,
}) catch return false;
}
var kept = rec;
kept.retained = true;
kept.retention_reason = if (rec.pinned) .user_pin else .unverified_consumers;
write(io, base, kept);
return true;
}
test "parseLsofPorts: n lines only, deduped, joined" {
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const arena = arena_state.allocator();
const text = "p4242\nf12\nn127.0.0.1:3002\nf13\nn127.0.0.1:3002\np4250\nf5\nn*:3003\n";
try std.testing.expectEqualStrings("127.0.0.1:3002, *:3003", parseLsofPorts(arena, text));
try std.testing.expectEqualStrings("", parseLsofPorts(arena, ""));
try std.testing.expectEqualStrings("", parseLsofPorts(arena, "p1\nf2\n"));
}
test "stateOf: recycled pid is gone, opaque and legacy identities are unverifiable" {
try std.testing.expectEqual(State.running, stateOf(77, .{ .id = 77 }));
try std.testing.expectEqual(State.gone, stateOf(77, .{ .id = 78 }));
try std.testing.expectEqual(State.unverifiable, stateOf(0, .{ .id = 78 }));
try std.testing.expectEqual(State.gone, stateOf(77, .gone));
try std.testing.expectEqual(State.unverifiable, stateOf(77, .unknown));
}
test "records: write, list oldest-first, forget; no HOME means no record" {
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const arena = arena_state.allocator();
var buf: [std.fs.max_path_bytes]u8 = undefined;
const n = try tmp.dir.realPath(io, &buf);
const base = try arena.dupe(u8, buf[0..n]);
write(io, base, .{ .pid = 200, .start_id = 5, .cmd = "next dev", .cwd = "/srv/site", .started_ms = 2_000 });
write(io, base, .{ .pid = 100, .start_id = 4, .owner_pid = 9, .cmd = "sleep 30", .started_ms = 1_000, .pinned = true });
const recs = list(io, arena, base);
try std.testing.expectEqual(@as(usize, 2), recs.len);
try std.testing.expectEqual(@as(i32, 100), recs[0].pid);
try std.testing.expect(recs[0].pinned);
try std.testing.expectEqual(@as(i32, 9), recs[0].owner_pid);
try std.testing.expectEqualStrings("next dev", recs[1].cmd);
try std.testing.expectEqualStrings("/srv/site", recs[1].cwd);
try std.testing.expectEqual(@as(u64, 5), recs[1].start_id);
forget(io, base, 200);
try std.testing.expectEqual(@as(usize, 1), list(io, arena, base).len);
write(io, "", .{ .pid = 300, .cmd = "nowhere" });
try std.testing.expectEqual(@as(usize, 0), list(io, arena, "").len);
}
test "stopTree never signals a pid whose start identity is not ours" {
if (!posix) return error.SkipZigTest;
const io = std.testing.io;
const me = proc_identity.selfRecord(io);
if (me.start_id == 0) return error.SkipZigTest; // no identity source here
// Our own pid with a wrong start id reads as a recycled pid: gone, no kill.
const forged: Record = .{ .pid = me.pid, .start_id = me.start_id +% 1, .cmd = "not us" };
try std.testing.expectEqual(State.gone, state(io, forged));
try std.testing.expectEqual(StopResult.gone, stopTree(io, forged));
const real: Record = .{ .pid = me.pid, .start_id = me.start_id, .cmd = "us" };
try std.testing.expectEqual(State.running, state(io, real));
}
test "retention preserves user pin intent and records why cleanup deferred" {
if (!posix) return error.SkipZigTest;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const arena = arena_state.allocator();
var path: [std.fs.max_path_bytes]u8 = undefined;
const n = try tmp.dir.realPath(io, &path);
for ([_]bool{ false, true }) |pinned| {
try std.testing.expect(retain(io, path[0..n], .{ .pid = 321, .cmd = "fixture", .pinned = pinned }, null, null));
const records = list(io, arena, path[0..n]);
try std.testing.expectEqual(@as(usize, 1), records.len);
try std.testing.expect(records[0].retained);
try std.testing.expectEqual(pinned, records[0].pinned);
try std.testing.expectEqualStrings(if (pinned) "user_pin" else "unverified_consumers", @tagName(records[0].retention_reason.?));
}
const legacy = try std.json.parseFromSliceLeaky(Record, arena, "{\"pid\":321,\"cmd\":\"legacy\",\"pinned\":true,\"retained\":true}", .{});
try std.testing.expect(legacy.retention_reason == null);
}