@sayknow-cli/coding-agent 0.3.16 → 0.4.1

package/src/skc-runtime/tmux-owner-isolation-cli.ts

@@ -1,5 +1,6 @@
 /** Internal JSON-line facade for the tmux owner-isolation contract. */
 import * as fs from "node:fs/promises";
+import { readLinuxProcStartTime } from "./linux-proc";
 import {
 	type BootstrapRequest,
 	bootstrapTmuxOwnerIsolation,
@@ -31,17 +32,7 @@ async function readCgroup(pid = "self"): Promise<string | null> {
 }
 
 async function readProcessStartTime(pid: number): Promise<string | null> {
-	try {
-		const stat = await fs.readFile(`/proc/${pid}/stat`, "utf8");
-		return (
-			stat
-				.slice(stat.lastIndexOf(")") + 2)
-				.trim()
-				.split(/\s+/)[19] ?? null
-		);
-	} catch {
-		return null;
-	}
+	return readLinuxProcStartTime(pid);
 }
 
 function isKnownNoServerDiagnostic(stderr: string): boolean {
@@ -53,27 +44,63 @@ function isKnownNoServerDiagnostic(stderr: string): boolean {
 	);
 }
 
-async function tmuxServerProof(socketKey: string, tmuxControlArgv?: string[]): Promise<TmuxServerProof> {
-	void socketKey;
-	if (!tmuxControlArgv?.length) return { state: "unverifiable" };
-	const controlArgv = tmuxControlArgv;
+interface TmuxListSessionsResult {
+	exitCode: number | null;
+	stdout: string;
+	stderr: string;
+}
+
+interface TmuxServerProofOptions {
+	platform?: NodeJS.Platform;
+	runListSessions?: (argv: string[]) => TmuxListSessionsResult;
+}
+
+function runTmuxListSessions(controlArgv: string[]): TmuxListSessionsResult {
 	const subprocess = Bun.spawnSync([...controlArgv, "list-sessions", "-F", "#{pid}\t#{session_name}"], {
 		stdout: "pipe",
 		stderr: "pipe",
 	});
-	const stderr = Buffer.from(subprocess.stderr).toString();
+	return {
+		exitCode: subprocess.exitCode,
+		stdout: Buffer.from(subprocess.stdout).toString(),
+		stderr: Buffer.from(subprocess.stderr).toString(),
+	};
+}
+
+function parseTmuxSessionRows(stdout: string): { pid: number; sessionNames: string[] } | null {
+	const lines = stdout.split("\n");
+	if (lines[lines.length - 1] === "") lines.pop();
+	let pid: number | undefined;
+	const sessionNames: string[] = [];
+	for (const rawLine of lines) {
+		const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+		const columns = line.split("\t");
+		if (columns.length !== 2 || !/^[1-9]\d*$/.test(columns[0]) || !columns[1].trim()) return null;
+		const rowPid = Number(columns[0]);
+		if (!Number.isSafeInteger(rowPid) || (pid !== undefined && pid !== rowPid)) return null;
+		pid = rowPid;
+		sessionNames.push(columns[1]);
+	}
+	return pid === undefined ? null : { pid, sessionNames };
+}
+
+/** Probes a tmux server using an injectable list-sessions runner for platform-bounded callers. */
+export async function tmuxServerProof(
+	socketKey: string,
+	tmuxControlArgv?: string[],
+	options: TmuxServerProofOptions = {},
+): Promise<TmuxServerProof> {
+	void socketKey;
+	if (!tmuxControlArgv?.length) return { state: "unverifiable" };
+	const platform = options.platform ?? process.platform;
+	const subprocess = options.runListSessions?.(tmuxControlArgv) ?? runTmuxListSessions(tmuxControlArgv);
 	if (subprocess.exitCode !== 0)
-		return isKnownNoServerDiagnostic(stderr) ? { state: "absent" } : { state: "unverifiable" };
-	const lines = Buffer.from(subprocess.stdout)
-		.toString()
-		.split("\n")
-		.map(line => line.trim())
-		.filter(Boolean);
-	const [pidText] = lines[0]?.split("\t") ?? [];
-	const pid = Number(pidText);
-	const sessionNames = lines.map(line => line.split("\t")[1]).filter((name): name is string => Boolean(name));
-	if (!Number.isSafeInteger(pid) || pid <= 0) return { state: "unverifiable" };
-	if (process.platform !== "linux") {
+		return isKnownNoServerDiagnostic(subprocess.stderr) ? { state: "absent" } : { state: "unverifiable" };
+	if (!subprocess.stdout.trim()) return { state: "absent" };
+	const rows = parseTmuxSessionRows(subprocess.stdout);
+	if (!rows) return { state: "unverifiable" };
+	const { pid, sessionNames } = rows;
+	if (platform !== "linux") {
 		return {
 			state: "safe",
 			pid,
@@ -82,7 +109,7 @@ async function tmuxServerProof(socketKey: string, tmuxControlArgv?: string[]): P
 			sessionNames,
 		};
 	}
-	const cgroup = classifyCgroup({ platform: process.platform, cgroupText: await readCgroup(String(pid)) });
+	const cgroup = classifyCgroup({ platform, cgroupText: await readCgroup(String(pid)) });
 	const startTime = await readProcessStartTime(pid);
 	if (!startTime) return { state: "unverifiable", pid, cgroup, sessionNames };
 	return {

package/src/skc-runtime/tmux-owner-isolation.ts

@@ -11,7 +11,9 @@ import * as fsSync from "node:fs";
 import * as fs from "node:fs/promises";
 
 import * as path from "node:path";
+import { openRecoveryFsRoot } from "@sayknow-cli/natives";
 import { isCompiledBinary } from "@sayknow-cli/utils/env";
+import { parseLinuxProcStartTime } from "./linux-proc";
 
 export const TMUX_OWNER_ISOLATION_SCHEMA_VERSION = 1;
 export const TMUX_OWNER_ISOLATION_MAX_LINE_BYTES = 16 * 1024;
@@ -86,7 +88,10 @@ export function classifyCgroup(input: { platform: NodeJS.Platform; cgroupText?:
 			diagnostic: "service_cgroup_inheritance",
 		};
 	const scope = paths.find(value => /(?:^|\/)(?:user|session|app|init|skc)[^/]*\.scope(?:\/|$)/.test(value));
-	if (scope) return { classification: "safe", scope };
+	const vteScope = paths.find(value =>
+		/^\/user\.slice\/user-(\d+)\.slice\/user@\1\.service(?:\/[^/]+)*\/vte-spawn-[A-Za-z0-9_.-]+\.scope$/.test(value),
+	);
+	if (scope || vteScope) return { classification: "safe", scope: scope ?? vteScope };
 	if (paths.every(value => value === "/")) return { classification: "safe", scope: "/" };
 	return {
 		classification: "unverifiable",
@@ -96,14 +101,7 @@ export function classifyCgroup(input: { platform: NodeJS.Platform; cgroupText?:
 
 export function ownerProcessStartTime(platform: NodeJS.Platform, stat: string | null): string | null {
 	if (platform !== "linux") return "not_applicable";
-	if (!stat) return null;
-	const close = stat.lastIndexOf(")");
-	if (close < 0) return null;
-	const startTime = stat
-		.slice(close + 2)
-		.trim()
-		.split(/\s+/)[19];
-	return startTime && /^\d+$/.test(startTime) ? startTime : null;
+	return parseLinuxProcStartTime(stat);
 }
 
 export interface TmuxServerProof {
@@ -309,7 +307,7 @@ function validArgv(argv: unknown): argv is string[] {
 	);
 }
 
-function isSafeServerProof(
+export function isSafeServerProof(
 	server: TmuxServerProof,
 	platform: NodeJS.Platform = "linux",
 ): server is TmuxServerProof & {
@@ -328,6 +326,17 @@ function isSafeServerProof(
 			(platform !== "linux" && server.cgroup?.classification === "not_applicable"))
 	);
 }
+
+/** Compares the stable identity fields of independently observed tmux servers. */
+export function sameServerIdentity(left: TmuxServerProof, right: TmuxServerProof): boolean {
+	return (
+		left.pid === right.pid &&
+		left.startTime === right.startTime &&
+		left.cgroup?.classification === right.cgroup?.classification &&
+		left.cgroup?.scope === right.cgroup?.scope &&
+		left.cgroup?.diagnostic === right.cgroup?.diagnostic
+	);
+}
 /**
  * Synchronous equivalent of the target-server truth table for managed callers.
  * Attempt persistence is injected so a caller can use its existing atomic state writer.
@@ -1038,6 +1047,122 @@ function sameOwnerGenerationBaseline(left: OwnerGenerationBaseline, right: Owner
 	);
 }
 
+export interface ManagedOwnerPredecessorEvidence {
+	generation: string;
+	sessionId: string;
+	runId: string;
+	incarnation: string;
+	predecessorToken: string;
+}
+
+function exactManagedOwnerJson(authority: ReturnType<typeof openRecoveryFsRoot>, name: string): unknown {
+	const first = authority.read(name, 64 * 1024);
+	if (!first.ok || !first.data) throw new Error("managed_owner_replacement_evidence_unavailable");
+	const second = authority.read(name, 64 * 1024);
+	if (
+		!second.ok ||
+		!second.data ||
+		Buffer.compare(Buffer.from(first.data), Buffer.from(second.data)) !== 0 ||
+		JSON.stringify(first.identity) !== JSON.stringify(second.identity)
+	)
+		throw new Error("managed_owner_replacement_evidence_changed");
+	const content = Buffer.from(first.data).toString("utf8");
+	if (!content.endsWith("\n") || content.indexOf("\n") !== content.length - 1)
+		throw new Error("managed_owner_replacement_evidence_untrusted");
+	return JSON.parse(content);
+}
+
+/** Resolve one SIGABRT predecessor from the retained exact prior-generation root. */
+export function resolveManagedOwnerPredecessorSync(
+	stateDir: string,
+	sessionId: string,
+	baseline: OwnerGenerationBaseline,
+): ManagedOwnerPredecessorEvidence | undefined {
+	if (baseline.state === "absent") return undefined;
+	const root = lifecyclePaths(stateDir, sessionId, baseline.generation).root;
+	let entries: string[];
+	try {
+		entries = fsSync.readdirSync(root);
+	} catch {
+		throw new Error("managed_owner_replacement_evidence_unavailable");
+	}
+	const bindings = new Set<string>();
+	const receipts = new Set<string>();
+	for (const entry of entries) {
+		const binding = /^child-([^/]+)\.binding\.json$/.exec(entry);
+		const receipt = /^sigabrt-([^/]+)\.receipt\.json$/.exec(entry);
+		if (entry.startsWith("child-") && !binding) throw new Error("managed_owner_replacement_evidence_untrusted");
+		if (entry.startsWith("sigabrt-") && !receipt) throw new Error("managed_owner_replacement_evidence_untrusted");
+		if (binding) bindings.add(binding[1]!);
+		if (receipt) receipts.add(receipt[1]!);
+	}
+	if (bindings.size === 0 && receipts.size === 0) return undefined;
+	const tokens = [...bindings].filter(token => receipts.has(token));
+	if (tokens.length !== 1 || receipts.size !== 1) throw new Error("managed_owner_replacement_evidence_ambiguous");
+	const predecessorToken = tokens[0]!;
+	if (!/^[A-Za-z0-9._-]+$/.test(predecessorToken)) throw new Error("managed_owner_replacement_evidence_untrusted");
+	const authority = openRecoveryFsRoot(root);
+	try {
+		const binding = exactManagedOwnerJson(authority, `child-${predecessorToken}.binding.json`) as Record<
+			string,
+			unknown
+		>;
+		const receipt = exactManagedOwnerJson(authority, `sigabrt-${predecessorToken}.receipt.json`) as Record<
+			string,
+			unknown
+		>;
+		const command = binding.command;
+		const runId = binding.run_id;
+		const incarnation = binding.endpoint_incarnation;
+		const commandDigest =
+			Array.isArray(command) && command.length > 0 && command.every(value => typeof value === "string" && value)
+				? crypto.createHash("sha256").update(JSON.stringify(command)).digest("hex")
+				: "";
+		const valid =
+			binding.schema_version === 2 &&
+			binding.generation === baseline.generation &&
+			binding.session_id === sessionId &&
+			typeof runId === "string" &&
+			runId.length > 0 &&
+			typeof incarnation === "string" &&
+			incarnation.length > 0 &&
+			binding.child_token === predecessorToken &&
+			binding.command_sha256 === commandDigest &&
+			typeof binding.supervisor_pid === "number" &&
+			Number.isSafeInteger(binding.supervisor_pid) &&
+			binding.supervisor_pid > 0 &&
+			typeof binding.supervisor_start_time === "string" &&
+			typeof binding.created_at === "string" &&
+			receipt.schema_version === 2 &&
+			receipt.generation === binding.generation &&
+			receipt.session_id === binding.session_id &&
+			receipt.run_id === runId &&
+			receipt.endpoint_incarnation === incarnation &&
+			receipt.child_token === binding.child_token &&
+			receipt.command_sha256 === binding.command_sha256 &&
+			receipt.supervisor_pid === binding.supervisor_pid &&
+			receipt.supervisor_start_time === binding.supervisor_start_time &&
+			typeof receipt.child_pid === "number" &&
+			Number.isSafeInteger(receipt.child_pid) &&
+			receipt.child_pid > 0 &&
+			typeof receipt.child_start_time === "string" &&
+			typeof receipt.received_at === "string" &&
+			(receipt.exit_code === null || Number.isSafeInteger(receipt.exit_code)) &&
+			receipt.signal === "SIGABRT" &&
+			receipt.signal_number === 6;
+		if (!valid) throw new Error("managed_owner_replacement_evidence_untrusted");
+		return {
+			generation: baseline.generation,
+			sessionId,
+			runId,
+			incarnation,
+			predecessorToken,
+		};
+	} finally {
+		authority.close();
+	}
+}
+
 export async function captureOwnerGenerationBaseline(
 	stateDir: string,
 	sessionId: string,
@@ -1521,7 +1646,7 @@ export function isValidOwnerIntent(intent: unknown, request?: ObserveTerminalReq
 		intent.generation === request.owner_generation &&
 		intent.session_id === request.session_id &&
 		intent.server_key === request.socket_key &&
-		intent.dispatch_id === request.operator_dispatch_id &&
+		(request.operator_dispatch_id === undefined || intent.dispatch_id === request.operator_dispatch_id) &&
 		request.signal === "SIGTERM"
 	);
 }

package/src/skc-runtime/tmux-sessions.ts

@@ -3,6 +3,7 @@ import * as crypto from "node:crypto";
 import * as fsSync from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { readLinuxProcStartTime, readLinuxProcStartTimeSync } from "./linux-proc";
 import { resolveSkcTmuxBinary } from "./psmux-detect";
 import { tmuxRuntimeSessionPath } from "./session-layout";
 import {
@@ -49,6 +50,7 @@ import {
 	type TmuxOwnerIsolationExecutionResult,
 	type TmuxServerProof,
 } from "./tmux-owner-isolation";
+import { buildWindowsPowerShellInnerCommand } from "./windows-powershell-command";
 
 export interface SkcTmuxSessionStatus {
 	name: string;
@@ -128,6 +130,10 @@ export interface ForceCloseOwnerDependencies {
 const FORCE_CLOSE_VERDICT_TIMEOUT_MS = 5_000;
 const FORCE_CLOSE_VERDICT_POLL_MS = 50;
 
+export interface CreateSkcTmuxSessionOptions {
+	platform?: NodeJS.Platform;
+}
+
 export type CreateOwnerIsolationTestDependencies = {
 	probe?: Partial<OwnerIsolationProbeSync>;
 	execute?: (plan: PlanResponse, deps: TmuxOwnerIsolationExecutionDependencies) => TmuxOwnerIsolationExecutionResult;
@@ -354,15 +360,19 @@ export function statusSkcTmuxSession(sessionName: string, env: NodeJS.ProcessEnv
 	throw new Error(`skc_tmux_session_not_found:${sessionName}`);
 }
 
-export function createSkcTmuxSession(env: NodeJS.ProcessEnv = process.env): SkcTmuxSessionStatus {
-	const tmuxCommand = resolveSkcTmuxCommand(env);
+export function createSkcTmuxSession(
+	env: NodeJS.ProcessEnv = process.env,
+	options: CreateSkcTmuxSessionOptions = {},
+): SkcTmuxSessionStatus {
+	const platform = options.platform ?? process.platform;
+	const tmuxCommand = resolveSkcTmuxCommand(env, platform);
 	const sessionName = buildSkcTmuxSessionName(env);
 	const cwd = process.cwd();
 	const sessionId = env[SKC_COORDINATOR_SESSION_ID_ENV]?.trim() || sessionName;
 	const stateFile =
 		env[SKC_COORDINATOR_SESSION_STATE_FILE_ENV]?.trim() ||
 		tmuxRuntimeSessionPath(cwd, env.SKC_SESSION_ID?.trim() || sessionId, buildSkcTmuxSessionSlug(sessionName));
-	const stateDir = path.dirname(stateFile);
+	const stateDir = (platform === "win32" ? path.win32 : path).dirname(stateFile);
 	const generation = crypto.randomUUID();
 	const childEnvironment: Record<string, string> = {
 		SKC_TMUX_LAUNCHED: "1",
@@ -373,12 +383,9 @@ export function createSkcTmuxSession(env: NodeJS.ProcessEnv = process.env): SkcT
 		[SKC_COORDINATOR_SESSION_STATE_FILE_ENV]: stateFile,
 	};
 	const shellQuote = (value: string): string => `'${value.replace(/'/g, `'\\''`)}'`;
-	const powershellQuote = (value: string): string => `'${value.replace(/'/g, "''")}'`;
 	const command =
-		process.platform === "win32"
-			? `${Object.entries(childEnvironment)
-					.map(([name, value]) => `$env:${name} = ${powershellQuote(value)}`)
-					.join("; ")}; skc`
+		platform === "win32"
+			? buildWindowsPowerShellInnerCommand({ command: ["skc"], environment: childEnvironment })
 			: `exec env ${Object.entries(childEnvironment)
 					.map(([name, value]) => `${name}=${shellQuote(value)}`)
 					.join(" ")} skc`;
@@ -388,11 +395,11 @@ export function createSkcTmuxSession(env: NodeJS.ProcessEnv = process.env): SkcT
 		"-d",
 		"-s",
 		sessionName,
-		...(process.platform === "win32" ? [] : ["-P", "-F", "#{session_id}"]),
+		...(platform === "win32" ? [] : ["-P", "-F", "#{session_id}"]),
 		command,
 	];
 	function probeTmuxServer(tmuxCommand: string, env: NodeJS.ProcessEnv): TmuxServerProof {
-		if (process.platform !== "linux") {
+		if (platform !== "linux") {
 			return {
 				state: "safe",
 				pid: 1,
@@ -414,14 +421,10 @@ export function createSkcTmuxSession(env: NodeJS.ProcessEnv = process.env): SkcT
 		const pid = Number(result.stdout.toString().trim());
 		if (!Number.isSafeInteger(pid) || pid <= 0) return { state: "unverifiable" };
 		try {
-			const stat = fsSync.readFileSync(`/proc/${pid}/stat`, "utf8");
-			const startTime = stat
-				.slice(stat.lastIndexOf(")") + 2)
-				.trim()
-				.split(/\s+/)[19];
+			const startTime = readLinuxProcStartTimeSync(pid);
 			if (!startTime) return { state: "unverifiable" };
 			const cgroup = classifyCgroup({
-				platform: process.platform,
+				platform,
 				cgroupText: fsSync.readFileSync(`/proc/${pid}/cgroup`, "utf8"),
 			});
 			return {
@@ -484,7 +487,7 @@ export function createSkcTmuxSession(env: NodeJS.ProcessEnv = process.env): SkcT
 				}
 			}),
 	};
-	if (resolveSkcTmuxBinary({ env }).isPsmux)
+	if (resolveSkcTmuxBinary({ env, platform }).isPsmux)
 		throw new Error("skc_tmux_owner_isolation_native_session_identity_unavailable");
 
 	const baseline = captureOwnerGenerationBaselineSync(stateDir, sessionId);
@@ -492,7 +495,7 @@ export function createSkcTmuxSession(env: NodeJS.ProcessEnv = process.env): SkcT
 		{
 			schema_version: 1,
 			op: "plan",
-			platform: process.platform,
+			platform,
 			session_id: sessionId,
 			owner_generation: generation,
 			baseline,
@@ -744,11 +747,7 @@ function requireSafeTmuxServerForMutation(
 	const pid = Number(result.stdout.toString().trim());
 	if (!Number.isSafeInteger(pid) || pid <= 0) throw new Error("skc_tmux_owner_isolation_server_unverifiable");
 	try {
-		const stat = fsSync.readFileSync(`/proc/${pid}/stat`, "utf8");
-		const startTime = stat
-			.slice(stat.lastIndexOf(")") + 2)
-			.trim()
-			.split(/\s+/)[19];
+		const startTime = readLinuxProcStartTimeSync(pid);
 		const cgroup = classifyCgroup({
 			platform: process.platform,
 			cgroupText: fsSync.readFileSync(`/proc/${pid}/cgroup`, "utf8"),
@@ -961,17 +960,7 @@ export function removeSkcTmuxSession(
 }
 
 async function readProcessStartTime(pid: number): Promise<string | null> {
-	try {
-		const stat = await fs.readFile(`/proc/${pid}/stat`, "utf8");
-		const close = stat.lastIndexOf(")");
-		const fields = stat
-			.slice(close + 2)
-			.trim()
-			.split(/\s+/);
-		return fields[19] ?? null;
-	} catch {
-		return null;
-	}
+	return readLinuxProcStartTime(pid);
 }
 
 async function readCurrentGeneration(stateDir: string, sessionId: string): Promise<string | null> {

package/src/skc-runtime/ultragoal-change-set.ts

@@ -0,0 +1,172 @@
+import {
+	categorizeComputerChangePath,
+	isSettingsSchemaPath,
+	normalizeRepoPath,
+	type UltragoalChangeCategory,
+	type UltragoalChangeSet,
+	type UltragoalChangeSetPath,
+	type UltragoalChangeStatus,
+} from "./ultragoal-runtime";
+
+export async function spawnText(
+	command: string[],
+	options: { cwd: string; timeoutMs?: number },
+): Promise<{ ok: boolean; stdout: string; stderr: string }> {
+	try {
+		const proc = Bun.spawn(command, { cwd: options.cwd, stdout: "pipe", stderr: "pipe" });
+		const timeout = setTimeout(() => proc.kill(), options.timeoutMs ?? 5000);
+		const [stdout, stderr, exitCode] = await Promise.all([
+			new Response(proc.stdout).text(),
+			new Response(proc.stderr).text(),
+			proc.exited,
+		]);
+		clearTimeout(timeout);
+		return { ok: exitCode === 0, stdout, stderr };
+	} catch (error) {
+		return { ok: false, stdout: "", stderr: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+export async function resolveGitBase(cwd: string, branch?: string): Promise<string> {
+	if (branch) {
+		const exists = await spawnText(["git", "rev-parse", "--verify", branch], { cwd, timeoutMs: 3000 });
+		if (exists.ok) return branch;
+	} else {
+		// Prefer the NEAREST integration base (the branch this work actually forks
+		// from) rather than always `main`. A branch opened against `dev` must be
+		// scoped to `dev`; using a stale `main` sweeps in unrelated trunk history
+		// and mis-attributes other people's changes to this story (e.g. falsely
+		// tripping change-scoped gates). Among existing candidates, pick the one
+		// whose merge-base with HEAD is closest to HEAD (fewest commits ahead).
+		const candidates = ["origin/dev", "dev", "origin/main", "origin/master", "main", "master"];
+		let best: { ref: string; ahead: number } | undefined;
+		for (const candidate of candidates) {
+			const exists = await spawnText(["git", "rev-parse", "--verify", candidate], { cwd, timeoutMs: 3000 });
+			if (!exists.ok) continue;
+			const mergeBase = await spawnText(["git", "merge-base", "HEAD", candidate], { cwd, timeoutMs: 3000 });
+			if (!mergeBase.ok || !mergeBase.stdout.trim()) continue;
+			const count = await spawnText(["git", "rev-list", "--count", `${mergeBase.stdout.trim()}..HEAD`], {
+				cwd,
+				timeoutMs: 3000,
+			});
+			const ahead = Number.parseInt(count.stdout.trim(), 10);
+			if (!Number.isFinite(ahead)) continue;
+			if (!best || ahead < best.ahead) best = { ref: candidate, ahead };
+		}
+		if (best) return best.ref;
+	}
+	const mergeBase = await spawnText(["git", "merge-base", "HEAD", "origin/main"], { cwd, timeoutMs: 3000 });
+	if (mergeBase.ok && mergeBase.stdout.trim()) return mergeBase.stdout.trim();
+	return "HEAD~1";
+}
+
+export function parseGitNameStatus(output: string): UltragoalChangeSetPath[] {
+	const rows: UltragoalChangeSetPath[] = [];
+	for (const line of output.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		const parts = trimmed.split(/\s+/);
+		const statusCode = parts[0] ?? "";
+		let status: UltragoalChangeStatus = "unknown";
+		if (statusCode.startsWith("A")) status = "added";
+		else if (statusCode.startsWith("M")) status = "modified";
+		else if (statusCode.startsWith("D")) status = "deleted";
+		else if (statusCode.startsWith("R")) status = "renamed";
+		else if (statusCode.startsWith("C")) status = "copied";
+		const pathValue = status === "renamed" || status === "copied" ? parts[2] : parts[1];
+		if (!pathValue) continue;
+		const oldPath = status === "renamed" || status === "copied" ? parts[1] : undefined;
+		rows.push({
+			path: normalizeRepoPath(pathValue),
+			oldPath: oldPath ? normalizeRepoPath(oldPath) : undefined,
+			status,
+			category: categorizeComputerChangePath(pathValue),
+		});
+	}
+	return rows;
+}
+
+function categorizeCiChangedPath(value: string): UltragoalChangeCategory {
+	// CI_DEV_CHANGED_PATHS intentionally carries path names only. Mixed registries
+	// such as settings-schema.ts require diff-level narrowing; without the diff,
+	// treating the whole registry as computer-control source forces the mandatory
+	// computer red-team suite on unrelated settings changes.
+	if (isSettingsSchemaPath(value)) return "other";
+	return categorizeComputerChangePath(value);
+}
+
+function ciDevChangedPathRows(): UltragoalChangeSetPath[] {
+	const raw = process.env.CI_DEV_CHANGED_PATHS;
+	if (!raw) return [];
+	return raw
+		.split(/\r?\n/)
+		.map(row => row.trim())
+		.filter(Boolean)
+		.map(pathValue => ({
+			path: normalizeRepoPath(pathValue),
+			status: "unknown" as UltragoalChangeStatus,
+			category: categorizeCiChangedPath(pathValue),
+		}));
+}
+
+function mergeChangeSetPaths(groups: UltragoalChangeSetPath[][]): UltragoalChangeSetPath[] {
+	const byKey = new Map<string, UltragoalChangeSetPath>();
+	for (const row of groups.flat()) byKey.set(`${row.oldPath ?? ""}\u0000${row.path}`, row);
+	return [...byKey.values()];
+}
+
+export async function computeCheckpointChangeSet(cwd: string): Promise<UltragoalChangeSet | undefined> {
+	const ciChangedPaths = ciDevChangedPathRows();
+	const inGit = await spawnText(["git", "rev-parse", "--is-inside-work-tree"], { cwd, timeoutMs: 3000 });
+	if (!inGit.ok || inGit.stdout.trim() !== "true") {
+		if (ciChangedPaths.length === 0) return undefined;
+		return { source: "checkpoint-git", paths: ciChangedPaths, trusted: true };
+	}
+	const baseRef = await resolveGitBase(cwd);
+	const base = baseRef;
+	const mergeBase = await spawnText(["git", "merge-base", "HEAD", baseRef], { cwd, timeoutMs: 3000 });
+	const [committed, unstaged, staged, stat, committedDiff, unstagedDiff, stagedDiff] = await Promise.all([
+		spawnText(["git", "diff", "--name-status", `${base}...HEAD`], { cwd, timeoutMs: 5000 }),
+		spawnText(["git", "diff", "--name-status"], { cwd, timeoutMs: 5000 }),
+		spawnText(["git", "diff", "--cached", "--name-status"], { cwd, timeoutMs: 5000 }),
+		spawnText(["git", "diff", "--stat", `${base}...HEAD`], { cwd, timeoutMs: 5000 }),
+		spawnText(["git", "diff", `${base}...HEAD`], { cwd, timeoutMs: 5000 }),
+		spawnText(["git", "diff"], { cwd, timeoutMs: 5000 }),
+		spawnText(["git", "diff", "--cached"], { cwd, timeoutMs: 5000 }),
+	]);
+	if (!committed.ok && !unstaged.ok && !staged.ok && ciChangedPaths.length === 0) return undefined;
+	const gitPaths = mergeChangeSetPaths([
+		parseGitNameStatus(committed.stdout),
+		parseGitNameStatus(unstaged.stdout),
+		parseGitNameStatus(staged.stdout),
+	]);
+	const paths = gitPaths.length > 0 ? gitPaths : ciChangedPaths;
+	return {
+		source: "checkpoint-git",
+		baseRef,
+		mergeBase: mergeBase.ok && mergeBase.stdout.trim() ? mergeBase.stdout.trim() : undefined,
+		headRef: "HEAD",
+		paths,
+		rawDiffStat: stat.stdout,
+		rawDiff: [committedDiff.stdout, unstagedDiff.stdout, stagedDiff.stdout].filter(Boolean).join("\n"),
+		trusted: true,
+	};
+}
+
+export function parseUnifiedDiffPaths(diff: string): UltragoalChangeSetPath[] {
+	const paths: UltragoalChangeSetPath[] = [];
+	for (const line of diff.split("\n")) {
+		if (!line.startsWith("diff --git ")) continue;
+		const match = /^diff --git a\/(.+?) b\/(.+)$/.exec(line);
+		if (!match) continue;
+		const oldPath = normalizeRepoPath(match[1]!);
+		const newPath = normalizeRepoPath(match[2]!);
+		paths.push({
+			path: newPath,
+			oldPath: oldPath === newPath ? undefined : oldPath,
+			status: oldPath === newPath ? "modified" : "renamed",
+			category: categorizeComputerChangePath(newPath),
+		});
+	}
+	return paths;
+}