graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
//! Session persistence: save/load the conversation (messages + provider id/
//! model + strict/goal/title flags) to `.graff/sessions/<name>.session.json`,
//! plus the list/rename/age helpers behind `/sessions`, `/resume`, and the
//! AI-title auto-rename. Split out of main.zig (600-line goal, #123).
//!
//! Every function here takes `*agent_mod.Agent` (several params are named
//! `root`, matching the harness-wide root-agent convention). saveSession/
//! loadSession/listSavedSessions/sessionAge/session_ext stay pub —
//! commands_session.zig, commands_misc.zig, and readline.zig import them
//! directly as `session.saveSession` etc.
//!
//! #273: `saveSession` is still synchronous and still reports its failures;
//! the interactive TURN path calls `saveSessionAsync`, which skips an unchanged
//! conversation outright and queues the write (session_writer.zig). This file's
//! unit tests live in session_tests.zig — the 600-line cap.
const std = @import("std");
const Io = std.Io;
const Value = std.json.Value;
const Allocator = std.mem.Allocator;
const agent_mod = @import("agent.zig");
const provider_mod = @import("provider.zig");
const util = @import("util.zig");
const goal_state = @import("goal_state.zig");
const session_writer = @import("session_writer.zig"); // #273: the fingerprint + the background write
const subagent_ledger = @import("subagent_ledger.zig"); // #753: persist background-agent handles
const shutdown_trace = @import("shutdown_trace.zig"); // #364: teardown phase stamps
const protocol_seq = @import("protocol_seq.zig"); // #330: the --json event sequence survives a resume
const http_headers = @import("http_headers.zig"); // the k3/codex prompt-cache key survives one too
const session_transcript = @import("session_transcript.zig"); // #441: the append-only history this file's rewrites discard
const session_peer = @import("session_peer.zig"); // ADR 0014: room cursor + inbox ride the session file
const tool_call_args = @import("tool_call_args.zig"); // #752: quarantine truncated tool-call arguments on resume
const Agent = agent_mod.Agent;
const Keys = provider_mod.Keys;
const unixMs = util.unixMs;
const utf8Prefix = util.utf8Prefix;
// The session INDEX (paths + the /sessions listing) lives in session_index.zig
// so this file stays under the 600-line cap. Re-exported: callers keep using
// `session.sessionPath`, `session.listSavedSessions`, and friends.
const session_index = @import("session_index.zig");
pub const session_ext = session_index.session_ext;
pub const sessions_dir = session_index.sessions_dir;
pub const sessionPath = session_index.sessionPath;
pub const validSessionName = session_index.validSessionName;
pub const sessionExists = session_index.sessionExists;
pub const SessionMeta = session_index.SessionMeta;
pub const sessionMetaFromBytes = session_index.sessionMetaFromBytes;
pub const sessionMeta = session_index.sessionMeta;
pub const sessionAge = session_index.sessionAge;
pub const SessionEntry = session_index.SessionEntry;
pub const listSavedSessions = session_index.listSavedSessions;
pub const listSavedSessionsAll = @import("session_discovery.zig").listAll;
pub const homeSessionPath = session_index.homeSessionPath;
pub const displayWorkspace = session_index.displayWorkspace;
/// Filesystem-safe slug of an AI title: lowercase alnum, any other run collapses
/// to one '-', trimmed, capped at 60. "Fixing the login bug" -> "fixing-the-login-bug".
/// Returns "" for an empty/symbol-only title.
pub fn slugifyTitle(arena: Allocator, title: []const u8) []const u8 {
var buf: std.ArrayList(u8) = .empty;
var last_dash = true; // suppress a leading '-'
for (title) |c| {
if (buf.items.len >= 60) break;
const lc = std.ascii.toLower(c);
if ((lc >= 'a' and lc <= 'z') or (lc >= '0' and lc <= '9')) {
buf.append(arena, lc) catch break;
last_dash = false;
} else if (!last_dash) {
buf.append(arena, '-') catch break;
last_dash = true;
}
}
var s = buf.items;
while (s.len > 0 and s[s.len - 1] == '-') s = s[0 .. s.len - 1];
return s;
}
/// Rename an as-yet-untitled (session-<ts>) session to a slug of its AI title:
/// point session_name at a free <slug>[-N], write it there, and remove the old
/// file. Best-effort; only fires for the default timestamp name, so a manual
/// /rename or a resumed session keeps its name.
pub fn renameSession(root: *Agent, arena: Allocator, slug: []const u8) void {
if (slug.len == 0) return;
if (!std.mem.startsWith(u8, root.session_name, "session-")) return; // already titled
if (std.mem.eql(u8, slug, root.session_name)) return;
var name = slug;
var n: usize = 2;
while (n < 100) : (n += 1) {
const p = sessionPath(arena, name) catch return;
if (Io.Dir.cwd().statFile(root.io, p, .{})) |_| {
name = std.fmt.allocPrint(arena, "{s}-{d}", .{ slug, n }) catch return;
} else |_| break; // free
}
const old_name = root.session_name;
const next_name = arena.dupe(u8, name) catch return;
@import("compaction_checkpoint.zig").rename(root, old_name, next_name) catch return;
root.session_name = next_name;
@import("subagent_interactive.zig").rename(root.io, old_name, root.session_name);
saveSession(root, arena, root.session_name) catch {};
if (sessionPath(arena, old_name)) |op| (Io.Dir.cwd().deleteFile(root.io, op) catch {}) else |_| {}
}
pub fn sessionTitle(root: *Agent) []const u8 {
if (root.session_title) |title| return title;
for (root.messages.items) |m| {
if (m != .object) continue;
if (!session_peer.isHumanUserTurn(m)) continue;
if (m.object.get("content")) |c| switch (c) {
.string => |text| {
const trimmed = std.mem.trim(u8, text, " \t\r\n");
if (trimmed.len > 0) return utf8Prefix(trimmed, 80);
},
.array => |arr| for (arr.items) |part| {
if (part == .object) {
const typ = if (part.object.get("type")) |v| (if (v == .string) v.string else "") else "";
if (std.mem.eql(u8, typ, "text") or std.mem.eql(u8, typ, "input_text")) {
if (part.object.get("text")) |tv| if (tv == .string) {
const trimmed = std.mem.trim(u8, tv.string, " \t\r\n");
if (trimmed.len > 0) return utf8Prefix(trimmed, 80);
};
}
}
},
else => {},
};
}
return "Untitled session";
}
/// A conversation is "meaningful" — worth persisting to disk — once it holds any
/// durable state a resume would want back. Concretely, at least one of:
/// - a user message (>= 1 message with role "user"),
/// - a non-null standing goal (/goal steering),
/// - a non-empty todo list,
/// - recorded tool activity this session, or
/// - a server compaction blob. In-stream compaction prunes every prompt
/// before the blob, so a text-only turn that compacted has no user
/// message left; the blob carries it.
/// A truly blank draft (no user turn, no goal, no todos, no tools) is NOT
/// meaningful, so saveSession skips it rather than leaving an "Untitled
/// session" file on disk (#184). Callers that only want to avoid the blank-draft
/// write get this for free by going through saveSession.
pub fn hasMeaningfulState(root: *Agent) bool {
if (root.goal != null) return true;
if (root.todos.items.len > 0) return true;
if (root.tools_used.entries.items.len > 0) return true;
if (@import("compaction_window.zig").latestBlob(root.messages.items) != null) return true;
for (root.messages.items) |m| {
if (m != .object) continue;
if (session_peer.isHumanUserTurn(m)) return true;
}
return false;
}
/// #273: a digest of every field saveSession persists, EXCEPT `updated_ms`
/// (a clock reading, not conversation state). Equal to the last successfully
/// written one means the file on disk is already this exact session, so the
/// whole save — serialize, lock, write — is skipped.
fn fingerprint(root: *Agent, name: []const u8) u64 {
var f: session_writer.Fingerprint = .init();
f.text(name);
f.text(root.provider.id);
f.text(root.provider.model);
f.flag(root.strict);
f.flag(root.ultracode_mode);
if (root.goal) |g| {
f.text(g.objective);
f.text(@tagName(g.status));
f.num(g.epoch);
f.flag(g.standing);
f.signed(g.created_ms);
f.signed(g.updated_ms);
} else f.flag(false);
f.num(root.todos.items.len);
for (root.todos.items) |t| {
f.text(t.content);
f.text(t.status);
f.num(t.epoch);
f.flag(t.retired); // #394: retiring a finished checklist is a real state change, so it must reach disk
f.text(t.reason); // #1520
}
if (root.session_parent) |parent| f.text(parent) else f.flag(false);
f.text(root.session_title orelse sessionTitle(root));
// The persisted meter's two inputs. Its third (system prompt + tool schema
// size) shifts `context_tokens` and `context_local_tokens` together, and
// resume only keeps their difference, so it cannot change what a resume
// restores and is deliberately left out.
f.num(root.last_context_tokens);
f.num(root.context_local_tokens);
f.num(protocol_seq.current());
f.json(Value{ .array = root.messages });
@import("session_catalog.zig").mixFingerprint(root, &f);
f.text(@import("session_prompt.zig").snapshot(root) orelse "");
session_peer.mixFingerprint(&f);
subagent_ledger.mixFingerprint(&f);
return f.final();
}
/// Save the conversation (messages + provider id/model + strict flag) to
/// <name>.session.json in the cwd. The JSON message array is already the
/// provider-native wire shape, so resume is a verbatim restore.
///
/// Synchronous, exactly like the pre-#273 save: the bytes are on disk (and any
/// failure is reported) by the time this returns. The TURN path uses
/// saveSessionAsync instead — see that function.
pub fn saveSession(root: *Agent, arena: Allocator, name: []const u8) !void {
const ticket = queueSave(root, arena, .cwd(), name) catch |err| {
flushSaves();
return err;
};
// Unconditional, so /clear, /new, /save and the exit save all drain even
// when this session had nothing new of its own to write.
flushSaves();
// Only THIS save's outcome: a background autosave that failed two turns ago
// is not /save's failure, and reporting it as one made /save print "save
// failed" (and skip the rename) for a file it had just written correctly.
if (session_writer.errorFor(ticket)) |err| return err;
}
/// #273: the interactive turn path's save. Skips entirely when nothing changed,
/// serializes here (root.messages is live, unlocked agent state and must not be
/// read from another thread), and leaves only the disk write in the background.
///
/// Callers MUST guarantee a drain before the process can exit — mainloop.run
/// defers flushSaves(), and every other saver in the harness is the synchronous
/// saveSession above.
pub fn saveSessionAsync(root: *Agent, arena: Allocator, name: []const u8) !void {
_ = try queueSave(root, arena, .cwd(), name);
}
/// Wait for any queued save to reach disk. The exit/quit/switch bound on how
/// long a background write may lag the conversation.
pub fn flushSaves() void {
session_writer.drain();
}
/// The same drain, named for the one caller that is a TEARDOWN step: the defer
/// mainloop.run registers, and therefore the first thing the quit path does.
/// Separate from `flushSaves` only so the #364 phase stamp marks that drain and
/// not the dozen mid-session ones `saveSession` performs (a teardown log that
/// also fires during the conversation cannot answer "did the loop exit?").
pub fn flushSavesAtExit() void {
shutdown_trace.mark("loop-exit: draining queued autosaves");
flushSaves();
}
/// The save itself, against an explicit base directory. Production always
/// passes the cwd (through saveSessionAsync/saveSession); the parameter exists
/// so the tests can exercise the real path against a tmp dir.
pub fn saveSessionTo(root: *Agent, arena: Allocator, dir: Io.Dir, name: []const u8) !void {
_ = try queueSave(root, arena, dir, name);
}
/// `saveSessionTo` plus the writer ticket for the save it queued — 0 when
/// nothing needed writing. A synchronous caller keeps the ticket so it can ask
/// `session_writer.errorFor` about ITS OWN write and not about someone else's.
fn queueSave(root: *Agent, arena: Allocator, dir: Io.Dir, name: []const u8) !u64 {
// #184: delay durable session creation until the conversation has meaningful
// state — never leave a blank draft as an "Untitled session" on disk. Existing
// files are untouched (we skip the write, we do not delete).
if (!hasMeaningfulState(root)) return 0;
if (dir.realPathFileAlloc(root.io, ".", arena)) |workspace|
@import("session_workspaces.zig").remember(root.io, arena, root.home, workspace)
else |_| {}
// #273: nothing has changed since the last successful write of this session
// AND that write is still what the file holds (a second graff, an editor or
// an rm all invalidate it — the skip is never taken on trust).
const fp = fingerprint(root, name);
const rel = try sessionPath(arena, name);
if (session_writer.alreadySaved(root.io, dir, rel, fp)) return 0;
// #441: the same observation point, one line per new message, appended to a
// file this function's in-place rewrite of `messages` can never reach.
session_transcript.record(root, dir, name);
var aw: Io.Writer.Allocating = .init(root.gpa);
defer aw.deinit();
var s: std.json.Stringify = .{ .writer = &aw.writer };
try s.beginObject();
try @import("session_catalog.zig").write(root, &s);
try @import("session_prompt.zig").write(root, &s);
try s.objectField("provider");
try s.write(root.provider.id);
try s.objectField("model");
try s.write(root.provider.model);
try s.objectField("strict");
try s.write(root.strict);
try s.objectField("ultracode_mode");
try s.write(root.ultracode_mode);
try s.objectField("goal");
if (root.goal) |g| {
try s.beginObject();
try s.objectField("objective");
try s.write(g.objective);
try s.objectField("status");
try s.write(@tagName(g.status));
try s.objectField("epoch");
try s.write(g.epoch);
try s.objectField("standing"); // a --goal objective resumes as one: the model still cannot retire it (#318)
try s.write(g.standing);
try s.objectField("created_ms");
try s.write(g.created_ms);
try s.objectField("updated_ms");
try s.write(g.updated_ms);
try s.endObject();
} else try s.write(null);
// #318: the checklist is durable, goal-scoped state - persist it with the
// epoch that authored each item so resume cannot mix goals and checklists.
try s.objectField("todos");
try s.beginArray();
for (root.todos.items) |t| {
try s.beginObject();
try s.objectField("content");
try s.write(t.content);
try s.objectField("status");
try s.write(t.status);
try s.objectField("epoch");
try s.write(t.epoch);
// #394: only when set, so a session with no retired history is written
// exactly as before and older builds read it back unchanged.
if (t.retired) {
try s.objectField("retired");
try s.write(true);
}
if (t.reason.len > 0) { // #1520: why a cancelled item was withdrawn; absent otherwise
try s.objectField("reason");
try s.write(t.reason);
}
try s.endObject();
}
try s.endArray();
try s.objectField("parent");
if (root.session_parent) |parent| try s.write(parent) else try s.write(null);
try s.objectField("title");
if (root.session_title) |title| try s.write(title) else try s.write(sessionTitle(root));
try s.objectField("updated_ms");
try s.write(unixMs(root.io));
try s.objectField("workspace");
try s.write(@import("main.zig").g_cwd_display);
try s.objectField("messages");
const saved_msgs = try session_peer.messagesForSave(arena, root.messages.items);
const messages_start = aw.writer.buffered().len;
try s.write(Value{ .array = saved_msgs });
const messages_bytes = aw.writer.buffered().len - messages_start;
const context_estimate = root.contextEstimateFromInputBytes(messages_bytes);
// Preserve the last authoritative provider reading across resume. Responses
// histories can contain compact encrypted-reasoning handles whose serialized
// byte size substantially underestimates their server-side token cost; without
// this floor a resumed near-limit session can miss pre-send compaction.
try s.objectField("context_tokens");
// std.json.Value represents parsed integers as i64, so keep the persisted
// value inside the range loadSession can round-trip even if a malformed
// provider once reported an extreme unsigned count.
try s.write(@min(context_estimate.effective, @as(u64, std.math.maxInt(i64))));
// Pair the provider reading with the locally measurable request component.
// On resume we can preserve only their hidden-token delta while replacing
// this component with today's prompt/tool-schema estimate.
try s.objectField("context_local_tokens");
try s.write(@min(context_estimate.local, @as(u64, std.math.maxInt(i64))));
// #1686: the local component above uses this process's count of the
// compaction state; a resume needs that count, not bytes/16.
try @import("opaque_state_persist.zig").write(&s, root.provider, Value{ .array = saved_msgs });
try root.compaction_window.write(&s);
// #330: the --json protocol sequence high-water mark. A REPLACEMENT graff
// resuming this session continues the numbering from here instead of
// reissuing ids the supervisor has already read off the event log.
try s.objectField("event_seq");
try s.write(@min(protocol_seq.current(), @as(u64, std.math.maxInt(i64))));
// kimi-code/codex key cache affinity on the durable conversation id; persisting ours keeps /resume warm.
try s.objectField("cache_key");
try s.write(http_headers.sessionId(root.io));
try s.objectField("prompt_cache_key");
try s.write(http_headers.projectRootId(root.io)); // idle-park resume must keep this partition
try session_peer.writeFields(&s);
try subagent_ledger.writeFields(&s, root.io);
try s.endObject();
// #289: two graffs in one workspace share this file — the writer makes the
// parent dirs and takes an exclusive advisory lock, so the loser reports.
// #273: it does that on its own thread, and owns these bytes from here.
const path = try root.gpa.dupe(u8, rel);
errdefer root.gpa.free(path); // only reachable if toOwnedSlice fails: submit owns both
return session_writer.submitInHome(root.gpa, root.io, dir, path, try aw.toOwnedSlice(), fp, root.home);
}
/// Parse the persisted `goal` field into a structured Goal (#223). A bare string
/// is a legacy session -> load as .active stamped with `now_ms`; an object carries
/// objective + status + created/updated timestamps (an unknown/missing status
/// falls back to .active). Pure (no Io) so it round-trips in unit tests. Returns
/// null for an empty/absent objective.
pub fn goalFromValue(v: Value, now_ms: i64) ?agent_mod.Goal {
if (v == .string) {
if (v.string.len == 0) return null;
return .{ .objective = v.string, .status = .active, .created_ms = now_ms, .updated_ms = now_ms };
}
if (v == .object) {
const go = v.object;
const txt = if (go.get("objective")) |o| (if (o == .string and o.string.len > 0) o.string else null) else null;
const objective = txt orelse return null;
const st: agent_mod.GoalStatus = if (go.get("status")) |s| (if (s == .string) (std.meta.stringToEnum(agent_mod.GoalStatus, s.string) orelse .active) else .active) else .active;
const ep: u64 = if (go.get("epoch")) |e| (if (e == .integer and e.integer >= 0) @intCast(e.integer) else 0) else 0;
const cms: i64 = if (go.get("created_ms")) |c| (if (c == .integer) c.integer else 0) else 0;
const ums: i64 = if (go.get("updated_ms")) |u| (if (u == .integer) u.integer else 0) else 0;
const standing = if (go.get("standing")) |b| (b == .bool and b.bool) else false; // absent in legacy sessions: a /goal objective the model may retire (#318)
return .{ .objective = objective, .status = st, .epoch = ep, .standing = standing, .created_ms = cms, .updated_ms = ums };
}
return null;
}
/// Parse the persisted `todos` array (#318). The caller clears the list first
/// so nothing from a previous conversation survives a resume. Pure (no Io) so
/// it round-trips in unit tests.
pub fn appendTodosFromValue(arena: Allocator, todos: *std.ArrayList(agent_mod.TodoItem), v: Value) !void {
if (v != .array) return;
for (v.array.items) |item| {
if (item != .object) continue;
const content = if (item.object.get("content")) |c| (if (c == .string) c.string else continue) else continue;
const status = if (item.object.get("status")) |s| (if (s == .string) s.string else "pending") else "pending";
const epoch: u64 = if (item.object.get("epoch")) |e| (if (e == .integer and e.integer >= 0) @intCast(e.integer) else 0) else 0;
// Absent in sessions written before #394: those items are live, and the
// first new ask retires them if they turn out to be a finished list.
const retired = if (item.object.get("retired")) |r| (r == .bool and r.bool) else false;
const reason = if (item.object.get("reason")) |r| (if (r == .string) r.string else "") else "";
try todos.append(arena, .{ .content = content, .status = status, .epoch = epoch, .retired = retired, .reason = reason });
}
}
pub fn contextTokensFromSession(obj: std.json.ObjectMap) u64 {
const v = obj.get("context_tokens") orelse return 0;
if (v != .integer or v.integer <= 0) return 0;
return @intCast(v.integer);
}
/// The persisted prompt-cache key; absent/malformed in pre-cache sessions, whose resume mints a fresh one as before.
pub fn cacheKeyFromSession(obj: std.json.ObjectMap) ?[]const u8 {
const v = obj.get("cache_key") orelse return null;
return if (v == .string and v.string.len == 36) v.string else null;
}
/// Git-root prompt-cache partition. Absent on pre-idle-park saves.
pub fn promptCacheKeyFromSession(obj: std.json.ObjectMap) ?[]const u8 {
const v = obj.get("prompt_cache_key") orelse return null;
return if (v == .string and v.string.len == 36) v.string else null;
}
/// The persisted --json sequence high-water mark (#330); 0 for sessions saved
/// before it existed, so a resume of one starts the numbering fresh.
pub fn eventSeqFromSession(obj: std.json.ObjectMap) u64 {
const v = obj.get("event_seq") orelse return 0;
if (v != .integer or v.integer <= 0) return 0;
return @intCast(v.integer);
}
pub fn contextLocalTokensFromSession(obj: std.json.ObjectMap) ?u64 {
const v = obj.get("context_local_tokens") orelse return null;
if (v != .integer or v.integer < 0) return null;
return @intCast(v.integer);
}
pub fn restoreContextMeter(root: *Agent, saved_context_tokens: u64, saved_local_tokens: ?u64) void {
const current_local = root.fullRequestEstimateTokens();
// A provider reading is meaningful across resume only after separating its
// locally measurable component. Preserve the server-only delta (encrypted
// reasoning, tokenizer differences, output usage), but replace the old
// prompt/tool-schema estimate with the current one. Files predating this
// paired field safely re-estimate instead of trusting an ungrounded meter.
const hidden_delta = if (saved_local_tokens) |saved_local|
saved_context_tokens -| saved_local
else
0;
root.last_context_tokens = current_local +| hidden_delta;
root.context_local_tokens = current_local;
root.last_cache_read = 0;
}
/// Restore a saved session: parse the file (arena-owned), rebuild the
/// provider, and replace the live history. The wire format must still match
/// the restored provider's kind — same provider id guarantees it.
pub fn loadSession(root: *Agent, keys: *Keys, arena: Allocator, name: []const u8) !void {
flushSaves(); // #273: a session switch never leaves the outgoing one queued
const found = @import("session_discovery.zig").locate(root, arena, name) orelse return error.FileNotFound;
const data = Io.Dir.cwd().readFileAlloc(root.io, found.path, arena, .limited(session_index.max_session_bytes)) catch |err|
return if (err == error.StreamTooLong) error.SessionTooLarge else error.FileNotFound;
const parsed = try std.json.parseFromSliceLeaky(Value, arena, data, .{ .allocate = .alloc_always });
if (parsed != .object) return error.BadSession;
const obj = parsed.object;
const pid = if (obj.get("provider")) |v| v.string else return error.BadSession;
const model = if (obj.get("model")) |v| v.string else return error.BadSession;
var msgs = if (obj.get("messages")) |v| (if (v == .array) v.array else return error.BadSession) else return error.BadSession;
const claude_import = if (obj.get("imported_from")) |v| v == .string and std.mem.eql(u8, v.string, "claude") else false;
const strict = if (obj.get("strict")) |v| (v == .bool and v.bool) else false;
const ultracode_mode = if (obj.get("ultracode_mode")) |v| (v == .bool and v.bool) else false;
const goal: ?agent_mod.Goal = if (obj.get("goal")) |v| goalFromValue(v, unixMs(root.io)) else null;
const parent = if (obj.get("parent")) |v| (if (v == .string and v.string.len > 0) v.string else null) else null;
// Older builds missed Responses input_text and persisted the placeholder.
const title = if (obj.get("title")) |v| (if (v == .string and v.string.len > 0 and !std.mem.eql(u8, v.string, "Untitled session")) v.string else null) else null;
// Optional for backward compatibility with sessions written before context
// metering was persisted. JSON integers are signed; ignore negative/wrong-type
// values instead of turning a corrupt session into an enormous unsigned count.
const saved_context_tokens = contextTokensFromSession(obj);
const saved_local_tokens = contextLocalTokensFromSession(obj);
// #330: continue the protocol sequence rather than restarting at 1. restore()
// only ever raises the counter, so a legacy session (no field) or a corrupt
// negative value simply leaves this process's numbering alone.
protocol_seq.restore(eventSeqFromSession(obj));
if (cacheKeyFromSession(obj)) |k| http_headers.restoreSessionId(k);
if (promptCacheKeyFromSession(obj)) |k| http_headers.restoreProjectRootId(k);
// #1556: an explicit cross-provider --model launch skipped this plan login.
if (!claude_import) @import("credential_failover.zig").preferPlanFor(root.io, root.gpa, root.arena, root.home, keys, pid);
root.ensureStoredKeys(keys);
if (!claude_import) {
if (std.mem.eql(u8, pid, "codex")) root.ensureModelCatalog(keys.*);
root.provider = try keys.providerById(pid, model);
} else {
// The source route is metadata. Import history into the configured
// graff provider without resolving any credentials for Claude Code.
msgs = try @import("adopt_conversation.zig").forProvider(arena, msgs, root.provider.kind);
}
// A resumed session may use a different wire format than the startup
// default. Materialize that catalog before rebasing its saved context
// meter, and keep every still-unused format lazy.
try @import("session_prompt.zig").restore(root, obj);
try @import("session_catalog.zig").restore(root, obj);
try root.ensureRootTools(root.provider.kind);
const compaction_window = try @import("compaction_window.zig").State.restore(arena, obj, msgs.items);
root.messages = msgs;
root.compaction_window = compaction_window;
@import("history_wire.zig").prepare(arena, root.provider.kind, &root.messages);
// #752: truncated `function.arguments` strings 400 every later request.
tool_call_args.repairHistory(root.gpa, arena, root.messages.items);
root.strict = strict;
root.ultracode_mode = ultracode_mode;
root.goal = goal;
root.todos.clearRetainingCapacity(); // never inherit another conversation's checklist (#318)
if (obj.get("todos")) |tv| try appendTodosFromValue(arena, &root.todos, tv);
root.todos_dirty = false; // restored todos are persisted state, never this-process completion evidence (#318)
// The completion double-check is per-PROCESS state (#318): a leftover arm
// short-circuited the resumed session's first attempt_completion.
root.completion_gate_armed = false;
root.completion_refused = false;
// #318: retire a restored-active goal whose checklist is already finished.
if (goal_state.reconcileRestored(root)) if (root.tracer) |t| t.note("goal", "reconciled-complete");
// Steering gate state belongs to the previous conversation (#318): drop any
// queued one-shot note and force a full goal-note re-statement next turn.
root.pending_goal_note = null;
root.goal_note_fp = 0;
root.goal_note_age = 0;
root.session_parent = parent;
root.session_title = title;
// #1686: reapply the saved count of this exact compaction state first, so
// the rebased meter does not fall back to bytes/16 in a new process.
@import("opaque_state_persist.zig").restore(root.provider, .{ .array = root.messages }, obj);
// Rebase the saved server-only delta onto today's prompt/tool-schema input.
restoreContextMeter(root, saved_context_tokens, saved_local_tokens);
root.cap_new = false; // per-provider (like sox/effort below); relearn on rejection
root.sox_json_object = false; // #543
root.effort_rejected = false;
root.ws_off = false; // transport failures belong to the prior live session
root.ws_transport_failures = 0;
// A restored history is a DIFFERENT conversation, not an extension, and
// codex_chain.usable detects no identity swap - it would chain onto the old one.
root.closeCodexWs();
root.compact_transport_failures = 0;
root.last_usage_includes_output = false;
root.last_request_context_overflow = false;
root.last_request_write_failed = false;
root.fallback_active = false;
root.fallback_blocked = false;
session_peer.restore(root, obj);
subagent_ledger.restore(root.gpa, root.io, obj.get("background_agents"));
const subagent = @import("subagent.zig");
if (subagent_ledger.nextId() > subagent.g_agent_jobs.next_id)
subagent.g_agent_jobs.next_id = subagent_ledger.nextId();
// ADR 0218: background jobs that outlived the last graff come back.
@import("job_recover.zig").onLoad(root.gpa, root.io, name);
}