graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
//! Simulator devices a session boots are shut down when it ends (#407).
//!
//! Agents verify iOS work with ad-hoc shell commands (`xcrun simctl boot`,
//! `xcodebuild test`, a project's run script). A device booted that way
//! outlives the command and the session: stopping the command's process
//! group does not shut a CoreSimulator device down. Finished runs left
//! devices booted with their apps running and the Simulator app open, and
//! parallel verification tasks piled them up.
//!
//! A shell command that looks like simulator work (`relevant`) is bracketed
//! by two snapshots of the booted devices. A device booted after the command
//! that was not booted before it is this session's: graff records it under
//! `~/.codegraff/simulators/<udid>/` with a lease naming this process. When
//! the session ends (`release`, from the job reaper), each recorded device
//! with no live lease left is shut down and its record removed.
//!
//! - A device that was already booted is never recorded, so the user's own
//! devices are never shut down.
//! - Another live graff session that runs simulator commands while a
//! recorded device is booted takes a lease on it too. The device stays up
//! until the last of them ends.
//! - A session that died without releasing leaves a dead lease; the next
//! session to end shuts that device down.
//! - The Simulator app is quit only when this session started it and no
//! device is booted any more.
//! - `GRAFF_KEEP_SIMULATORS=1` turns all of this off.
//!
//! A snapshot cannot tell who booted a device. One the user boots while a
//! bracketed command runs is attributed to that command, and a command that
//! does not look like simulator work is not bracketed.
const std = @import("std");
const builtin = @import("builtin");
const Io = std.Io;
const Allocator = std.mem.Allocator;
const proc_identity = @import("proc_identity.zig");
pub const keep_env = "GRAFF_KEEP_SIMULATORS";
pub const records_subdir = ".codegraff/simulators";
const booted_by = "booted-by";
const lease_prefix = "lease-";
/// A CoreSimulator UDID: a UUID, used as a directory name and an argument,
/// so anything else is rejected.
pub const Udid = [36]u8;
pub fn parseUdid(text: []const u8) ?Udid {
if (text.len != 36) return null;
for (text, 0..) |c, i| {
const dash = i == 8 or i == 13 or i == 18 or i == 23;
if (dash != (c == '-')) return null;
if (!dash and !std.ascii.isHex(c)) return null;
}
return text[0..36].*;
}
/// One host command's outcome. `code` is null when it did not run or did not
/// exit normally. `stdout` is gpa-owned.
pub const Run = struct { code: ?u8, stdout: []const u8 };
pub const Runner = *const fn (gpa: Allocator, io: Io, argv: []const []const u8) Run;
pub const Liveness = *const fn (io: Io, rec: proc_identity.Record) bool;
fn hostRun(gpa: Allocator, io: Io, argv: []const []const u8) Run {
const run = @import("process_runner.zig").runCapped(gpa, io, argv, 1 << 20, 4096, 60_000) catch
return .{ .code = null, .stdout = &.{} };
gpa.free(run.stderr);
const code: ?u8 = switch (run.term) {
.exited => |c| if (run.timed_out or run.cancelled) null else c,
else => null,
};
return .{ .code = code, .stdout = run.stdout };
}
fn isLive(io: Io, rec: proc_identity.Record) bool {
return proc_identity.stateOf(io, rec) == .held;
}
/// Whether a shell command looks like simulator work. Bracketing costs two
/// `simctl` runs, so ordinary commands are not.
pub fn relevant(cmd: []const u8) bool {
for ([_][]const u8{ "simctl", "simulator", "xcodebuild" }) |needle| {
if (@import("util.zig").indexOfIgnoreCase(cmd, needle) != null) return true;
}
// Whole words only: "ios" is in "scenarios".
var words = std.mem.tokenizeAny(u8, cmd, " \t\r\n/._-:=,;'\"()[]{}|&<>$`");
while (words.next()) |word| {
for ([_][]const u8{ "ios", "iphone", "ipad", "watchos", "tvos", "visionos", "xros" }) |w| {
if (std.ascii.eqlIgnoreCase(word, w)) return true;
}
}
return false;
}
pub const Gui = enum { running, stopped, unknown };
/// What `before` saw, handed back to `after`.
pub const Bracket = struct { gui: Gui };
pub const Ledger = struct {
/// Absolute records directory; empty turns the ledger off.
root: []const u8 = "",
run: Runner = hostRun,
live: Liveness = isLive,
self: proc_identity.Record = .{},
mutex: Io.Mutex = .init,
/// Devices seen booted before a bracketed command: never this session's.
foreign: std.ArrayList(Udid) = .empty,
/// A bracketed command was still running when its tool call returned.
pending: bool = false,
pending_gui: Gui = .unknown,
gui_started: bool = false,
fn enabled(l: *const Ledger) bool {
return l.root.len != 0; // `init` sets it on macOS only
}
/// Snapshot before a shell command. Null when the command is not
/// simulator work or the snapshot failed: nothing is attributed then.
pub fn before(l: *Ledger, gpa: Allocator, io: Io, cmd: []const u8) ?Bracket {
if (!l.enabled() or !relevant(cmd)) return null;
l.mutex.lockUncancelable(io);
defer l.mutex.unlock(io);
const booted = l.snapshot(gpa, io) orelse return null;
defer gpa.free(booted);
for (booted) |u| {
// A device a graff session booted: this one now uses it as well.
if (l.recorded(io, u)) l.lease(io, u) else l.addForeign(gpa, u);
}
return .{ .gui = l.gui(gpa, io) };
}
/// Snapshot after the command; record the devices it booted. `finished`
/// is false when the command is still running in the background.
pub fn after(l: *Ledger, gpa: Allocator, io: Io, bracket: Bracket, finished: bool) void {
l.mutex.lockUncancelable(io);
defer l.mutex.unlock(io);
l.attribute(gpa, io);
if (bracket.gui == .stopped and l.gui(gpa, io) == .running) l.gui_started = true;
if (!finished) {
l.pending = true;
if (bracket.gui == .stopped) l.pending_gui = .stopped;
}
}
fn attribute(l: *Ledger, gpa: Allocator, io: Io) void {
const booted = l.snapshot(gpa, io) orelse return;
defer gpa.free(booted);
for (booted) |u| {
if (l.isForeign(u) or l.recorded(io, u)) continue;
l.record(io, u);
}
}
/// Session end: shut down every recorded device no live session holds.
/// Returns how many devices were shut down.
pub fn release(l: *Ledger, gpa: Allocator, io: Io) usize {
if (!l.enabled()) return 0;
l.mutex.lockUncancelable(io);
defer l.mutex.unlock(io);
defer {
l.foreign.clearAndFree(gpa);
l.pending = false;
l.pending_gui = .unknown;
l.gui_started = false;
}
if (l.pending) {
// A command that outlived its tool call may have booted more.
l.attribute(gpa, io);
if (l.pending_gui == .stopped and l.gui(gpa, io) == .running) l.gui_started = true;
}
var shut: usize = 0;
const records = l.listRecords(gpa, io);
defer gpa.free(records);
if (records.len != 0) {
const booted = l.snapshot(gpa, io);
defer if (booted) |b| gpa.free(b);
for (records) |u| {
l.unlease(io, u);
if (l.heldByOther(io, u)) continue;
const up = if (booted) |b| contains(b, u) else true;
if (up) {
// Without a snapshot the device may still be up: keep its
// record so a later session retries.
if (booted == null) continue;
const r = l.run(gpa, io, &.{ "xcrun", "simctl", "shutdown", &u });
gpa.free(r.stdout);
if (r.code != 0) continue;
shut += 1;
}
l.forget(io, u);
}
}
if (l.gui_started) {
const left = l.snapshot(gpa, io);
defer if (left) |b| gpa.free(b);
if (left != null and left.?.len == 0) {
const r = l.run(gpa, io, &.{ "pkill", "-x", "Simulator" });
gpa.free(r.stdout);
}
}
return shut;
}
fn snapshot(l: *Ledger, gpa: Allocator, io: Io) ?[]Udid {
const r = l.run(gpa, io, &.{ "xcrun", "simctl", "list", "devices", "booted", "-j" });
defer gpa.free(r.stdout);
if (r.code != 0) return null;
return parseBooted(gpa, r.stdout) catch null;
}
fn gui(l: *Ledger, gpa: Allocator, io: Io) Gui {
const r = l.run(gpa, io, &.{ "pgrep", "-x", "Simulator" });
gpa.free(r.stdout);
return if (r.code == 0) .running else if (r.code == 1) .stopped else .unknown;
}
fn addForeign(l: *Ledger, gpa: Allocator, u: Udid) void {
if (l.isForeign(u)) return;
l.foreign.append(gpa, u) catch {};
}
fn isForeign(l: *const Ledger, u: Udid) bool {
return contains(l.foreign.items, u);
}
fn rootDir(l: *const Ledger, io: Io) ?Io.Dir {
return Io.Dir.cwd().openDir(io, l.root, .{ .iterate = true }) catch null;
}
fn recorded(l: *const Ledger, io: Io, u: Udid) bool {
var root = l.rootDir(io) orelse return false;
defer root.close(io);
var dir = root.openDir(io, &u, .{}) catch return false;
dir.close(io);
return true;
}
fn stamp(l: *const Ledger, buf: *[proc_identity.record_max]u8) []const u8 {
return proc_identity.formatRecord(buf, l.self);
}
fn leaseName(l: *const Ledger, buf: *[32]u8) []const u8 {
return std.fmt.bufPrint(buf, lease_prefix ++ "{d}", .{l.self.pid}) catch unreachable;
}
fn record(l: *Ledger, io: Io, u: Udid) void {
Io.Dir.cwd().createDirPath(io, l.root) catch return;
var root = l.rootDir(io) orelse return;
defer root.close(io);
root.createDirPath(io, &u) catch return;
var dir = root.openDir(io, &u, .{}) catch return;
defer dir.close(io);
var buf: [proc_identity.record_max]u8 = undefined;
dir.writeFile(io, .{ .sub_path = booted_by, .data = l.stamp(&buf) }) catch {};
l.leaseIn(io, dir);
}
fn lease(l: *Ledger, io: Io, u: Udid) void {
var root = l.rootDir(io) orelse return;
defer root.close(io);
var dir = root.openDir(io, &u, .{}) catch return;
defer dir.close(io);
l.leaseIn(io, dir);
}
fn leaseIn(l: *Ledger, io: Io, dir: Io.Dir) void {
var name_buf: [32]u8 = undefined;
var buf: [proc_identity.record_max]u8 = undefined;
dir.writeFile(io, .{ .sub_path = l.leaseName(&name_buf), .data = l.stamp(&buf) }) catch {};
}
fn unlease(l: *Ledger, io: Io, u: Udid) void {
var root = l.rootDir(io) orelse return;
defer root.close(io);
var dir = root.openDir(io, &u, .{}) catch return;
defer dir.close(io);
var name_buf: [32]u8 = undefined;
dir.deleteFile(io, l.leaseName(&name_buf)) catch {};
}
/// A lease from a live process other than this one.
fn heldByOther(l: *Ledger, io: Io, u: Udid) bool {
var root = l.rootDir(io) orelse return false;
defer root.close(io);
var dir = root.openDir(io, &u, .{ .iterate = true }) catch return false;
defer dir.close(io);
var it = dir.iterate();
while (it.next(io) catch return true) |entry| {
if (!std.mem.startsWith(u8, entry.name, lease_prefix)) continue;
const rec = proc_identity.readOwnerFile(io, dir, entry.name) orelse continue;
if (rec.pid == l.self.pid) continue;
if (l.live(io, rec)) return true;
}
return false;
}
fn forget(l: *Ledger, io: Io, u: Udid) void {
var root = l.rootDir(io) orelse return;
defer root.close(io);
root.deleteTree(io, &u) catch {};
}
pub fn listRecords(l: *Ledger, gpa: Allocator, io: Io) []const Udid {
var out: std.ArrayList(Udid) = .empty;
var root = l.rootDir(io) orelse return out.toOwnedSlice(gpa) catch &.{};
defer root.close(io);
var it = root.iterate();
while (it.next(io) catch null) |entry| {
if (entry.kind != .directory) continue;
const u = parseUdid(entry.name) orelse continue;
out.append(gpa, u) catch break;
}
return out.toOwnedSlice(gpa) catch &.{};
}
pub fn deinit(l: *Ledger, gpa: Allocator) void {
l.foreign.deinit(gpa);
}
};
fn contains(list: []const Udid, u: Udid) bool {
for (list) |item| if (std.mem.eql(u8, &item, &u)) return true;
return false;
}
/// The booted devices in `xcrun simctl list devices booted -j` output.
pub fn parseBooted(gpa: Allocator, text: []const u8) ![]Udid {
const parsed = try std.json.parseFromSlice(std.json.Value, gpa, text, .{});
defer parsed.deinit();
if (parsed.value != .object) return error.BadSimctlList;
const devices = parsed.value.object.get("devices") orelse return error.BadSimctlList;
if (devices != .object) return error.BadSimctlList;
var out: std.ArrayList(Udid) = .empty;
errdefer out.deinit(gpa);
var runtimes = devices.object.iterator();
while (runtimes.next()) |runtime| {
if (runtime.value_ptr.* != .array) continue;
for (runtime.value_ptr.array.items) |device| {
if (device != .object) continue;
const state = device.object.get("state") orelse continue;
if (state != .string or !std.mem.eql(u8, state.string, "Booted")) continue;
const udid = device.object.get("udid") orelse continue;
if (udid != .string) continue;
try out.append(gpa, parseUdid(udid.string) orelse continue);
}
}
return out.toOwnedSlice(gpa);
}
/// The process's ledger, on once startup knows HOME (`init`).
pub var g: Ledger = .{};
pub fn init(arena: Allocator, io: Io, home: []const u8, environ_map: anytype) void {
if (builtin.os.tag != .macos or home.len == 0) return;
if (environ_map.get(keep_env)) |v| if (!std.mem.eql(u8, v, "0")) return;
g.root = std.fmt.allocPrint(arena, "{s}/" ++ records_subdir, .{std.mem.trimEnd(u8, home, "/")}) catch return;
g.self = proc_identity.selfRecord(io);
}
test {
_ = @import("sim_ledger_tests.zig");
}