@narumitw/pi-subagents 0.49.3 → 0.52.0

package/src/work-item-persistence.ts

@@ -0,0 +1,223 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { redactPrivateText } from "./context.js";
+import { WorkItemLedger, type WorkItemLedgerSnapshot } from "./work-item-ledger.js";
+
+const WORKFLOW_STATE_DIRECTORY = "pi-subagents-workflows";
+const DEFAULT_MAX_STORED_WORKFLOWS = 64;
+const DEFAULT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+const MAX_WORKFLOW_STATE_BYTES = 1024 * 1024;
+
+export interface SessionWorkflowPersistenceOptions {
+	stateDir?: string;
+	maxStoredWorkflows?: number;
+	retentionMs?: number;
+}
+
+export interface SessionWorkflowInspection {
+	workflows: WorkItemLedgerSnapshot[];
+	invalid: number;
+	omitted: number;
+}
+
+export class WorkItemPersistence {
+	constructor(
+		readonly filePath: string,
+		private readonly afterSave?: () => Promise<void>,
+	) {}
+
+	async save(snapshot: WorkItemLedgerSnapshot): Promise<void> {
+		const filePath = path.resolve(this.filePath);
+		const sanitized = sanitizeWorkflowSnapshot(snapshot);
+		const content = `${JSON.stringify(sanitized)}\n`;
+		if (Buffer.byteLength(content, "utf8") > MAX_WORKFLOW_STATE_BYTES) {
+			throw new Error("WorkItem workflow state exceeds the persistence size limit");
+		}
+		await withFileMutationQueue(filePath, async () => {
+			await fs.promises.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
+			const temporary = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+			try {
+				await fs.promises.writeFile(temporary, content, { mode: 0o600 });
+				await fs.promises.rename(temporary, filePath);
+			} finally {
+				await fs.promises.rm(temporary, { force: true });
+			}
+		});
+		await this.afterSave?.();
+	}
+
+	load(): WorkItemLedger | undefined {
+		const filePath = path.resolve(this.filePath);
+		let source: string;
+		try {
+			const stat = fs.statSync(filePath);
+			if (stat.size > MAX_WORKFLOW_STATE_BYTES)
+				throw new Error("workflow state exceeds size limit");
+			source = fs.readFileSync(filePath, "utf8");
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+			throw error;
+		}
+		try {
+			return WorkItemLedger.restore(JSON.parse(source) as WorkItemLedgerSnapshot);
+		} catch {
+			const quarantine = `${filePath}.invalid-${Date.now()}`;
+			try {
+				fs.renameSync(filePath, quarantine);
+			} catch {
+				// A concurrent owner may already have handled the invalid file.
+			}
+			return undefined;
+		}
+	}
+}
+
+export function createSessionWorkItemPersistence(
+	owner: string,
+	workflowId: string,
+	options: SessionWorkflowPersistenceOptions = {},
+): WorkItemPersistence {
+	const maxStoredWorkflows = options.maxStoredWorkflows ?? DEFAULT_MAX_STORED_WORKFLOWS;
+	const retentionMs = options.retentionMs ?? DEFAULT_RETENTION_MS;
+	if (!Number.isSafeInteger(maxStoredWorkflows) || maxStoredWorkflows < 1) {
+		throw new Error("maxStoredWorkflows must be a positive safe integer");
+	}
+	if (!Number.isFinite(retentionMs) || retentionMs <= 0) {
+		throw new Error("workflow retentionMs must be a positive finite number");
+	}
+	const stateDir = resolveStateDirectory(options.stateDir);
+	const prefix = sessionPrefix(owner);
+	const filePath = path.join(stateDir, `${prefix}-${stableId(workflowId)}.json`);
+	return new WorkItemPersistence(filePath, () =>
+		pruneSessionWorkflows(stateDir, prefix, maxStoredWorkflows, retentionMs),
+	);
+}
+
+export function inspectSessionWorkflows(
+	owner: string,
+	options: SessionWorkflowPersistenceOptions = {},
+): SessionWorkflowInspection {
+	const stateDir = resolveStateDirectory(options.stateDir);
+	const prefix = `${sessionPrefix(owner)}-`;
+	const limit = options.maxStoredWorkflows ?? DEFAULT_MAX_STORED_WORKFLOWS;
+	if (!Number.isSafeInteger(limit) || limit < 1) {
+		throw new Error("maxStoredWorkflows must be a positive safe integer");
+	}
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(stateDir, { withFileTypes: true });
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			return { workflows: [], invalid: 0, omitted: 0 };
+		}
+		throw error;
+	}
+	const candidates = entries
+		.filter(
+			(entry) => entry.isFile() && entry.name.startsWith(prefix) && entry.name.endsWith(".json"),
+		)
+		.map((entry) => {
+			const filePath = path.join(stateDir, entry.name);
+			return { filePath, modifiedAt: safeModifiedAt(filePath) };
+		})
+		.sort((left, right) => right.modifiedAt - left.modifiedAt);
+	const workflows: WorkItemLedgerSnapshot[] = [];
+	let invalid = 0;
+	for (const candidate of candidates.slice(0, limit)) {
+		try {
+			const stat = fs.statSync(candidate.filePath);
+			if (stat.size > MAX_WORKFLOW_STATE_BYTES)
+				throw new Error("workflow state exceeds size limit");
+			const source = fs.readFileSync(candidate.filePath, "utf8");
+			workflows.push(
+				WorkItemLedger.restore(JSON.parse(source) as WorkItemLedgerSnapshot).snapshot(),
+			);
+		} catch {
+			invalid++;
+		}
+	}
+	return { workflows, invalid, omitted: Math.max(0, candidates.length - limit) };
+}
+
+function safeModifiedAt(filePath: string): number {
+	try {
+		return fs.statSync(filePath).mtimeMs;
+	} catch {
+		return 0;
+	}
+}
+
+function resolveStateDirectory(stateDir: string | undefined): string {
+	return path.resolve(stateDir ?? path.join(getAgentDir(), WORKFLOW_STATE_DIRECTORY));
+}
+
+function sessionPrefix(owner: string): string {
+	return stableId(`session:${owner}`);
+}
+
+function stableId(value: string): string {
+	return createHash("sha256").update(value).digest("hex").slice(0, 24);
+}
+
+async function pruneSessionWorkflows(
+	stateDir: string,
+	prefix: string,
+	maxStoredWorkflows: number,
+	retentionMs: number,
+): Promise<void> {
+	await withFileMutationQueue(path.join(stateDir, `${prefix}.prune`), async () => {
+		const cutoff = Date.now() - retentionMs;
+		const entries = (await fs.promises.readdir(stateDir, { withFileTypes: true }))
+			.filter(
+				(entry) =>
+					entry.isFile() && entry.name.startsWith(`${prefix}-`) && entry.name.endsWith(".json"),
+			)
+			.map((entry) => path.join(stateDir, entry.name));
+		const records = await Promise.all(
+			entries.map(async (filePath) => ({
+				filePath,
+				modifiedAt: (await fs.promises.stat(filePath)).mtimeMs,
+			})),
+		);
+		records.sort((left, right) => right.modifiedAt - left.modifiedAt);
+		await Promise.all(
+			records
+				.filter((record, index) => index >= maxStoredWorkflows || record.modifiedAt < cutoff)
+				.map((record) => fs.promises.rm(record.filePath, { force: true })),
+		);
+	});
+}
+
+function sanitizeWorkflowSnapshot(snapshot: WorkItemLedgerSnapshot): WorkItemLedgerSnapshot {
+	const sanitized = structuredClone(snapshot);
+	for (const item of sanitized.items) {
+		item.objective = redact(item.objective);
+		item.selectedAgentName = item.selectedAgentName ? redact(item.selectedAgentName) : undefined;
+		item.requiredCapabilities = item.requiredCapabilities.map(redact);
+		item.requiredTools = item.requiredTools.map(redact);
+		item.readPaths = item.readPaths.map(redact);
+		item.writePaths = item.writePaths.map(redact);
+		item.ownershipKeys = item.ownershipKeys.map(redact);
+		item.acceptanceCriteria = item.acceptanceCriteria.map(redact);
+		item.invalidationReasons = item.invalidationReasons.map(redact);
+		item.outcomeReason = item.outcomeReason ? redact(item.outcomeReason) : undefined;
+		if (item.verificationReceipt) {
+			item.verificationReceipt.summary = redact(item.verificationReceipt.summary);
+			item.verificationReceipt.evidence = item.verificationReceipt.evidence.map(redact);
+			item.verificationReceipt.limitations = item.verificationReceipt.limitations.map(redact);
+		}
+		for (const artifact of [...item.artifacts, ...item.artifactHistory]) {
+			artifact.kind = redact(artifact.kind);
+			artifact.version = redact(artifact.version);
+			artifact.digest = artifact.digest ? redact(artifact.digest) : undefined;
+		}
+	}
+	WorkItemLedger.restore(sanitized);
+	return sanitized;
+}
+
+function redact(value: string): string {
+	return redactPrivateText(value).trim();
+}

package/src/workflow-planning.ts

@@ -0,0 +1,162 @@
+import type { AgentConfig } from "./agents.js";
+import { routeByCapability } from "./capability-router.js";
+import { normalizeDelegationContract } from "./delegation-contract.js";
+import type { SubagentParams } from "./params.js";
+import { type WorkItemDefinition, WorkItemLedger } from "./work-item-ledger.js";
+
+export type WorkflowTask = NonNullable<SubagentParams["workflow"]>["tasks"][number];
+export type ResolvedWorkflowTask = WorkflowTask & { agent: string };
+type Aggregator = NonNullable<SubagentParams["aggregator"]>;
+
+type WorkRequest = {
+	contract?: unknown;
+	inputArtifacts?: string[];
+	inputArtifactVersions?: Record<string, string>;
+	requiredCapabilities?: string[];
+	requiredTools?: string[];
+	agent?: string;
+	sideEffectPolicy?: "read-only" | "idempotent" | "mutating";
+	readPaths?: string[];
+	writePaths?: string[];
+	ownershipKeys?: string[];
+	acceptanceCriteria?: string[];
+	integrationOwner?: boolean;
+	verifierFor?: string;
+	dependencyPolicy?: "completed" | "settled";
+};
+
+export function resolveWorkflowTasks(
+	params: SubagentParams,
+	agents: readonly AgentConfig[],
+): ResolvedWorkflowTask[] {
+	return (params.workflow?.tasks ?? []).map((task) => {
+		const contract = normalizeDelegationContract(task.contract);
+		const route = routeByCapability(agents, {
+			agent: task.agent,
+			requiredCapabilities: [
+				...(task.requiredCapabilities ?? []),
+				...(contract?.requestedAuthority?.capabilities ?? []),
+			],
+			requiredTools: [
+				...(task.requiredTools ?? []),
+				...(contract?.requestedAuthority?.tools ?? []),
+			],
+			requiredVerificationRole: task.requiredVerificationRole,
+			requiredSideEffectClass: contract?.sideEffectPolicy === "read-only" ? "read-only" : undefined,
+			preferredCostHint: task.preferredCostHint,
+			preferredLatencyHint: task.preferredLatencyHint,
+		});
+		return { ...task, agent: route.agent.name };
+	});
+}
+
+export function createBlockingWorkLedger(
+	params: SubagentParams,
+	resolvedWorkflowTasks: ResolvedWorkflowTask[],
+	aggregator: Aggregator | undefined,
+): WorkItemLedger | undefined {
+	if (params.agent && params.task) {
+		return WorkItemLedger.create({
+			workflowId: "blocking-single",
+			items: [definition("task-1", params.task, [], params)],
+		});
+	}
+	if (params.chain?.length) {
+		return WorkItemLedger.create({
+			workflowId: "blocking-chain",
+			items: params.chain.map((step, index) =>
+				definition(`step-${index + 1}`, step.task, index === 0 ? [] : [`step-${index}`], step),
+			),
+		});
+	}
+	if (params.tasks?.length) {
+		const items = params.tasks.map((task, index) =>
+			definition(`task-${index + 1}`, task.task, [], task),
+		);
+		if (aggregator) {
+			items.push(
+				definition(
+					"aggregator",
+					aggregator.task,
+					params.tasks.map((_task, index) => `task-${index + 1}`),
+					{ ...aggregator, dependencyPolicy: "settled" },
+				),
+			);
+		}
+		return WorkItemLedger.create({ workflowId: "blocking-parallel", items });
+	}
+	if (params.workflow && resolvedWorkflowTasks.length > 0) {
+		const hasExplicitIntegrationOwner = resolvedWorkflowTasks.some(
+			(task) => task.integrationOwner === true,
+		);
+		let defaultIntegrationOwnerIndex = -1;
+		if (!hasExplicitIntegrationOwner) {
+			for (let index = resolvedWorkflowTasks.length - 1; index >= 0; index--) {
+				if (resolvedWorkflowTasks[index]?.verifierFor === undefined) {
+					defaultIntegrationOwnerIndex = index;
+					break;
+				}
+			}
+		}
+		if (!hasExplicitIntegrationOwner && defaultIntegrationOwnerIndex < 0) {
+			throw new Error("Workflow has no non-verifier integration owner candidate");
+		}
+		return WorkItemLedger.create({
+			workflowId: params.workflow.id ?? "blocking-workflow",
+			items: resolvedWorkflowTasks.map((task, index) =>
+				definition(task.id, task.task, task.dependsOn ?? [], {
+					...task,
+					integrationOwner:
+						task.integrationOwner ??
+						(!hasExplicitIntegrationOwner && index === defaultIntegrationOwnerIndex),
+				}),
+			),
+		});
+	}
+	return undefined;
+}
+
+function definition(
+	id: string,
+	task: string,
+	dependencies: string[],
+	request: WorkRequest,
+): WorkItemDefinition {
+	const contract = normalizeDelegationContract(request.contract);
+	return {
+		id,
+		objective: contract?.objective ?? task,
+		dependencies,
+		inputArtifacts: [
+			...(request.inputArtifacts ?? contract?.requiredInputs ?? []),
+			...(contract?.dependencies
+				.filter((dependency) => dependency.artifactId)
+				.map((dependency) => dependency.artifactId as string) ?? []),
+		],
+		inputArtifactVersions: {
+			...Object.fromEntries(
+				(contract?.dependencies ?? [])
+					.filter((dependency) => dependency.artifactId && dependency.version)
+					.map((dependency) => [dependency.artifactId as string, dependency.version as string]),
+			),
+			...(request.inputArtifactVersions ?? {}),
+		},
+		requiredCapabilities: [
+			...(request.requiredCapabilities ?? []),
+			...(contract?.requestedAuthority?.capabilities ?? []),
+		],
+		requiredTools: [
+			...(request.requiredTools ?? []),
+			...(contract?.requestedAuthority?.tools ?? []),
+		],
+		selectedAgentName: request.agent,
+		sideEffectPolicy: contract?.sideEffectPolicy ?? request.sideEffectPolicy ?? "mutating",
+		readPaths: request.readPaths ?? contract?.requestedAuthority?.readPaths ?? [],
+		writePaths: request.writePaths ?? contract?.requestedAuthority?.writePaths ?? [],
+		ownershipKeys: request.ownershipKeys ?? [],
+		acceptanceCriteria: request.acceptanceCriteria ?? contract?.acceptanceCriteria ?? [],
+		integrationOwner: request.integrationOwner,
+		verifierFor: request.verifierFor,
+		dependencyPolicy: request.dependencyPolicy,
+	};
+}

package/src/workflow-tree-identity.ts

@@ -0,0 +1,289 @@
+import { execFile } from "node:child_process";
+import { createHash, type Hash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export const WORKFLOW_TREE_IDENTITY_VERSION = "pi-subagents:workflow-tree:v1" as const;
+export const DEFAULT_WORKFLOW_TREE_MAX_BYTES = 1024 * 1024;
+const MAX_UNTRACKED_FILES = 256;
+
+export interface WorkflowTreeIdentity {
+	version: typeof WORKFLOW_TREE_IDENTITY_VERSION;
+	kind: "git-commit" | "git-dirty";
+	digest: string;
+}
+
+export interface CaptureWorkflowTreeIdentityOptions {
+	maxBytes?: number;
+	signal?: AbortSignal;
+}
+
+export async function captureWorkflowTreeIdentity(
+	cwd: string,
+	options: CaptureWorkflowTreeIdentityOptions = {},
+): Promise<WorkflowTreeIdentity> {
+	const maxBytes = options.maxBytes ?? DEFAULT_WORKFLOW_TREE_MAX_BYTES;
+	if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
+		throw new Error("Workflow tree identity maxBytes must be a positive safe integer");
+	}
+	throwIfAborted(options.signal);
+	let canonicalCwd: string;
+	try {
+		canonicalCwd = await fs.promises.realpath(path.resolve(cwd));
+	} catch {
+		throw new Error("Workflow verification requires a readable Git repository directory");
+	}
+	const rootOutput = await git(
+		canonicalCwd,
+		["rev-parse", "--show-toplevel"],
+		64 * 1024,
+		options.signal,
+	).catch((error) => {
+		throw normalizedGitError(error, "Workflow verification requires a Git repository");
+	});
+	let repositoryRoot: string;
+	try {
+		repositoryRoot = await fs.promises.realpath(rootOutput.toString("utf8").trim());
+	} catch {
+		throw new Error("Workflow verification requires a readable Git repository root");
+	}
+	const relativeCwd = path.relative(repositoryRoot, canonicalCwd);
+	if (relativeCwd.startsWith("..") || path.isAbsolute(relativeCwd)) {
+		throw new Error("Workflow verification cwd is outside its Git repository");
+	}
+	const submodules = await git(
+		repositoryRoot,
+		["submodule", "status", "--recursive"],
+		64 * 1024,
+		options.signal,
+	).catch((error) => {
+		throw normalizedGitError(error, "Workflow tree identity could not inspect submodules");
+	});
+	if (submodules.toString("utf8").trim()) {
+		throw new Error("Workflow tree identity does not support repositories with submodules");
+	}
+	const head = (
+		await git(repositoryRoot, ["rev-parse", "HEAD"], 64 * 1024, options.signal).catch((error) => {
+			throw normalizedGitError(error, "Workflow verification requires a stable Git HEAD");
+		})
+	)
+		.toString("utf8")
+		.trim();
+	if (!/^[a-f0-9]{40,64}$/u.test(head)) {
+		throw new Error("Workflow verification requires a stable Git HEAD");
+	}
+	const commandLimit = maxBytes + 1;
+	const indexDiff = await git(
+		repositoryRoot,
+		["diff", "--binary", "--no-ext-diff", "--cached", "HEAD", "--"],
+		commandLimit,
+		options.signal,
+	).catch((error) => {
+		throw normalizedGitError(error, "Workflow tree identity exceeded its size limit");
+	});
+	const worktreeDiff = await git(
+		repositoryRoot,
+		["diff", "--binary", "--no-ext-diff", "--"],
+		commandLimit,
+		options.signal,
+	).catch((error) => {
+		throw normalizedGitError(error, "Workflow tree identity exceeded its size limit");
+	});
+	if (indexDiff.length > maxBytes || worktreeDiff.length > maxBytes) {
+		throw new Error("Workflow tree identity exceeded its size limit");
+	}
+	const untrackedOutput = await git(
+		repositoryRoot,
+		["ls-files", "--others", "--exclude-standard", "-z"],
+		commandLimit,
+		options.signal,
+	).catch((error) => {
+		throw normalizedGitError(error, "Workflow tree identity exceeded its size limit");
+	});
+	const untrackedEntries = splitNul(untrackedOutput).sort(Buffer.compare);
+	if (untrackedEntries.length > MAX_UNTRACKED_FILES) {
+		throw new Error("Workflow tree identity exceeded its untracked-file limit");
+	}
+	if (indexDiff.length === 0 && worktreeDiff.length === 0 && untrackedEntries.length === 0) {
+		return identity("git-commit", hashParts([Buffer.from("commit\0"), Buffer.from(head)]));
+	}
+	let consumed = indexDiff.length + worktreeDiff.length + untrackedOutput.length;
+	if (consumed > maxBytes) throw new Error("Workflow tree identity exceeded its size limit");
+	const hasher = createHash("sha256");
+	hasher.update("pi-subagents:workflow-tree:v1\0");
+	updateHashFrame(hasher, "head", head);
+	updateHashFrame(hasher, "index-diff", indexDiff);
+	updateHashFrame(hasher, "worktree-diff", worktreeDiff);
+	for (const rawRelativePath of untrackedEntries) {
+		throwIfAborted(options.signal);
+		const relativePath = decodeGitPath(rawRelativePath);
+		const candidate = path.resolve(repositoryRoot, relativePath);
+		const relative = path.relative(repositoryRoot, candidate);
+		if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+			throw new Error("Workflow tree identity encountered an unsafe untracked path");
+		}
+		let bytes: Buffer;
+		let kind: string;
+		try {
+			const stat = await fs.promises.lstat(candidate);
+			if (stat.isSymbolicLink()) {
+				kind = "symlink";
+				bytes = Buffer.from(await fs.promises.readlink(candidate), "utf8");
+			} else if (stat.isFile()) {
+				kind = "file";
+				if (stat.size > maxBytes - consumed) {
+					throw new Error("Workflow tree identity exceeded its size limit");
+				}
+				bytes = await readRegularFileNoFollow(candidate, stat, options.signal);
+			} else {
+				throw new Error("Workflow tree identity encountered an unsupported untracked file type");
+			}
+		} catch (error) {
+			if (error instanceof Error && error.name === "AbortError") throw error;
+			if (error instanceof Error && error.message.startsWith("Workflow tree identity")) {
+				throw error;
+			}
+			throw new Error("Workflow tree identity could not read an untracked entry");
+		}
+		consumed += rawRelativePath.length + bytes.length;
+		if (consumed > maxBytes) throw new Error("Workflow tree identity exceeded its size limit");
+		updateHashFrame(hasher, "untracked-kind", kind);
+		updateHashFrame(hasher, "untracked-path", rawRelativePath);
+		updateHashFrame(hasher, "untracked-content", bytes);
+	}
+	return identity("git-dirty", hasher.digest("hex"));
+}
+
+export function sameWorkflowTreeIdentity(
+	left: WorkflowTreeIdentity,
+	right: WorkflowTreeIdentity,
+): boolean {
+	return (
+		isWorkflowTreeIdentity(left) &&
+		isWorkflowTreeIdentity(right) &&
+		left.kind === right.kind &&
+		left.digest === right.digest
+	);
+}
+
+export function isWorkflowTreeIdentity(value: unknown): value is WorkflowTreeIdentity {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const candidate = value as Partial<WorkflowTreeIdentity>;
+	if (
+		Object.keys(value as Record<string, unknown>).some(
+			(key) => !["version", "kind", "digest"].includes(key),
+		)
+	) {
+		return false;
+	}
+	return (
+		candidate.version === WORKFLOW_TREE_IDENTITY_VERSION &&
+		(candidate.kind === "git-commit" || candidate.kind === "git-dirty") &&
+		typeof candidate.digest === "string" &&
+		/^[a-f0-9]{64}$/u.test(candidate.digest)
+	);
+}
+
+function identity(kind: WorkflowTreeIdentity["kind"], digest: string): WorkflowTreeIdentity {
+	return { version: WORKFLOW_TREE_IDENTITY_VERSION, kind, digest };
+}
+
+function hashParts(parts: Buffer[]): string {
+	const hash = createHash("sha256");
+	for (const part of parts) hash.update(part);
+	return hash.digest("hex");
+}
+
+function updateHashFrame(hash: Hash, label: string, value: string | Buffer): void {
+	const labelBytes = Buffer.from(label, "utf8");
+	const valueBytes = typeof value === "string" ? Buffer.from(value, "utf8") : value;
+	const header = Buffer.allocUnsafe(8);
+	header.writeUInt32BE(labelBytes.length, 0);
+	header.writeUInt32BE(valueBytes.length, 4);
+	hash.update(header);
+	hash.update(labelBytes);
+	hash.update(valueBytes);
+}
+
+function splitNul(value: Buffer): Buffer[] {
+	const entries: Buffer[] = [];
+	let start = 0;
+	for (let index = 0; index < value.length; index++) {
+		if (value[index] !== 0) continue;
+		if (index > start) entries.push(value.subarray(start, index));
+		start = index + 1;
+	}
+	if (start < value.length) entries.push(value.subarray(start));
+	return entries;
+}
+
+function decodeGitPath(value: Buffer): string {
+	const decoded = value.toString("utf8");
+	if (!decoded || decoded.includes("\0") || !Buffer.from(decoded, "utf8").equals(value)) {
+		throw new Error("Workflow tree identity encountered an unsupported Git path encoding");
+	}
+	return decoded;
+}
+
+async function readRegularFileNoFollow(
+	filePath: string,
+	expected: fs.Stats,
+	signal: AbortSignal | undefined,
+): Promise<Buffer> {
+	throwIfAborted(signal);
+	const handle = await fs.promises.open(filePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+	try {
+		const before = await handle.stat();
+		if (!before.isFile() || before.dev !== expected.dev || before.ino !== expected.ino) {
+			throw new Error("Workflow tree identity file changed during capture");
+		}
+		const content = await handle.readFile({ signal });
+		const after = await handle.stat();
+		if (
+			after.dev !== before.dev ||
+			after.ino !== before.ino ||
+			after.size !== before.size ||
+			after.mtimeMs !== before.mtimeMs
+		) {
+			throw new Error("Workflow tree identity file changed during capture");
+		}
+		return content;
+	} finally {
+		await handle.close();
+	}
+}
+
+function git(
+	cwd: string,
+	args: string[],
+	maxBuffer: number,
+	signal?: AbortSignal,
+): Promise<Buffer> {
+	throwIfAborted(signal);
+	return new Promise((resolve, reject) => {
+		execFile(
+			"git",
+			["-C", cwd, ...args],
+			{ encoding: "buffer", maxBuffer, signal },
+			(error, stdout) => {
+				if (error) reject(error);
+				else resolve(stdout);
+			},
+		);
+	});
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+	if (!signal?.aborted) return;
+	const error = new Error("Workflow tree identity capture was cancelled");
+	error.name = "AbortError";
+	throw error;
+}
+
+function normalizedGitError(error: unknown, fallback: string): Error {
+	if (error instanceof Error && error.name === "AbortError") return error;
+	const message = error instanceof Error ? error.message : String(error);
+	return new Error(
+		/maxBuffer|stdout.*large|SIGTERM/iu.test(message) ? `${fallback}: size limit` : fallback,
+	);
+}