@iowarp/clio-coder 0.4.9 → 0.5.0

package/src/tools/task-worktree.ts

@@ -1,19 +1,67 @@
 import { execFileSync } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
-import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import {
+	existsSync,
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	realpathSync,
+	renameSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { currentProcessLease, ownerIsAlive, type ProcessLease, validProcessLease } from "./process-lease.js";
+import { diskWorktreeParent } from "./worktree-root.js";
 
 export type TaskWorktreeApply = "merge" | "preserve";
 
 export interface TaskWorktree {
 	root: string;
 	runId: string;
+	/** `<parent>/<runId>`. */
 	path: string;
+	/**
+	 * Directory the working tree was created in: the project-root location or
+	 * the resolved `fleet.worktrees.root`. Absent on a value built before the
+	 * root was configurable, which always means the project-root location.
+	 */
+	parent?: string;
 	branch: string;
 	base: string;
 	ownerToken: string;
 }
 
+/**
+ * Where a claim stands. `active` is a run in flight, or one whose owner died
+ * before it settled. `settled` is a finished run that kept its worktree on
+ * purpose (apply mode preserve, a failed run, a merge conflict). `abandoned`
+ * is a dead owner's worktree that restart recovery found holding work and
+ * kept for the operator; it is reported once at startup and listed by doctor.
+ */
+export type TaskWorktreeState = "active" | "settled" | "abandoned";
+
+/** A task worktree that outlived its run, as doctor and recovery report it. */
+export interface PreservedTaskWorktree {
+	runId: string;
+	path: string;
+	/** The claim file, always under the project root. */
+	claimPath: string;
+	branch: string;
+	base: string;
+	state: TaskWorktreeState;
+	/** ISO UTC instant the claim was written; null for a claim older than recovery. */
+	createdAt: string | null;
+	/** Why recovery kept it rather than removing it. */
+	reason: string;
+}
+
+export interface TaskWorktreeRecoveryResult {
+	removed: string[];
+	preserved: PreservedTaskWorktree[];
+	failed: Array<{ runId: string; message: string }>;
+}
+
 export interface TaskWorktreeReceipt {
 	path: string;
 	branch: string;
@@ -166,35 +214,67 @@ export function gitCheckoutRoot(cwd: string): string | null {
 	}
 }
 
-export function createTaskWorktree(root: string, runId: string, base?: string): TaskWorktree {
+/** The claim always lives on disk with the repository, wherever the working tree is. */
+function claimPathFor(root: string, runId: string): string {
+	return join(diskWorktreeParent(root), `${runId}${OWNER_FILE_SUFFIX}`);
+}
+
+export function createTaskWorktree(
+	root: string,
+	runId: string,
+	base?: string,
+	apply: TaskWorktreeApply = "merge",
+	/** Resolved `fleet.worktrees.root` parent; the project-root location when absent. */
+	worktreeParent?: string,
+): TaskWorktree {
 	validateRunId(runId);
 	const canonical = realpathSync(root);
 	const resolvedBase = base ?? git(canonical, ["rev-parse", "HEAD"]);
-	const parent = join(canonical, ".clio-coder", "worktrees");
+	const claimParent = diskWorktreeParent(canonical);
+	const parent = worktreeParent ?? claimParent;
 	const path = join(parent, runId);
 	const branch = `clio-coder/task/${runId}`;
-	mkdirSync(parent, { recursive: true });
+	mkdirSync(claimParent, { recursive: true });
+	// Off the project root the directory may sit on a filesystem other users
+	// share (/dev/shm), so it is ours alone.
+	mkdirSync(parent, { recursive: true, mode: 0o700 });
 	if (!isCanonicalWorktreePathInside(parent, path))
 		throw new Error(`task worktree path escapes its parent for run ${runId}`);
 	git(canonical, ["worktree", "add", "-b", branch, path, resolvedBase]);
 	const ownerToken = randomBytes(16).toString("hex");
 	writeFileSync(
-		`${path}${OWNER_FILE_SUFFIX}`,
-		`${JSON.stringify({ version: 1, kind: TASK_WORKTREE_KIND, root: canonical, runId, branch, base: resolvedBase, ownerToken }, null, 2)}\n`,
+		claimPathFor(canonical, runId),
+		`${JSON.stringify(
+			{
+				version: 2,
+				kind: TASK_WORKTREE_KIND,
+				root: canonical,
+				runId,
+				branch,
+				base: resolvedBase,
+				ownerToken,
+				// What restart recovery needs to tell a crashed run from a live one.
+				state: "active" satisfies TaskWorktreeState,
+				apply,
+				createdAt: new Date().toISOString(),
+				owner: currentProcessLease(),
+				path,
+			},
+			null,
+			2,
+		)}\n`,
 		{ encoding: "utf8", flag: "wx" },
 	);
-	return { root: canonical, runId, path, branch, base: resolvedBase, ownerToken };
+	return { root: canonical, runId, path, parent, branch, base: resolvedBase, ownerToken };
 }
 
 function assertOwnership(worktree: TaskWorktree): void {
-	const expected = join(worktree.root, ".clio-coder", "worktrees", worktree.runId);
-	if (
-		resolve(worktree.path) !== resolve(expected) ||
-		!isCanonicalWorktreePathInside(join(worktree.root, ".clio-coder", "worktrees"), worktree.path)
-	) {
+	const parent = worktree.parent ?? diskWorktreeParent(worktree.root);
+	const expected = join(parent, worktree.runId);
+	if (resolve(worktree.path) !== resolve(expected) || !isCanonicalWorktreePathInside(parent, worktree.path)) {
 		throw new Error(`task worktree ${worktree.runId} has an invalid ownership path`);
 	}
-	const ownerPath = `${worktree.path}${OWNER_FILE_SUFFIX}`;
+	const ownerPath = claimPathFor(worktree.root, worktree.runId);
 	if (!existsSync(ownerPath)) throw new Error(`task worktree ${worktree.runId} has no ownership file`);
 	let marker: Record<string, unknown>;
 	try {
@@ -205,13 +285,15 @@ function assertOwnership(worktree: TaskWorktree): void {
 		throw new Error(`task worktree ${worktree.runId} has an invalid ownership file`);
 	}
 	if (
-		marker.version !== 1 ||
+		(marker.version !== 1 && marker.version !== 2) ||
 		(marker.kind !== TASK_WORKTREE_KIND && marker.kind !== LEGACY_TASK_WORKTREE_KIND) ||
 		marker.root !== worktree.root ||
 		marker.runId !== worktree.runId ||
 		marker.branch !== worktree.branch ||
 		marker.base !== worktree.base ||
-		marker.ownerToken !== worktree.ownerToken
+		marker.ownerToken !== worktree.ownerToken ||
+		// A claim that names a path names this one; an older claim names none.
+		(marker.path !== undefined && marker.path !== worktree.path)
 	) {
 		throw new Error(`task worktree ${worktree.runId} ownership facts do not match`);
 	}
@@ -265,5 +347,202 @@ export function cleanupTaskWorktree(worktree: TaskWorktree, deleteBranch: boolea
 		git(worktree.root, ["worktree", "prune"]);
 	}
 	if (deleteBranch) git(worktree.root, ["branch", "-D", worktree.branch]);
-	rmSync(`${worktree.path}${OWNER_FILE_SUFFIX}`, { force: true });
+	rmSync(claimPathFor(worktree.root, worktree.runId), { force: true });
+}
+
+function replaceMarker(ownerPath: string, marker: Record<string, unknown>): void {
+	const temporary = `${ownerPath}.${randomBytes(6).toString("hex")}.tmp`;
+	writeFileSync(temporary, `${JSON.stringify(marker, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+	renameSync(temporary, ownerPath);
+}
+
+/**
+ * Record that a run ended and kept its worktree on purpose, so restart
+ * recovery does not read the claim as a crash. A claim written before recovery
+ * existed carries no state and is left as it is.
+ */
+export function settleTaskWorktree(worktree: TaskWorktree): void {
+	assertOwnership(worktree);
+	const ownerPath = claimPathFor(worktree.root, worktree.runId);
+	const marker = JSON.parse(readFileSync(ownerPath, "utf8")) as Record<string, unknown>;
+	if (marker.version !== 2) return;
+	replaceMarker(ownerPath, { ...marker, state: "settled" satisfies TaskWorktreeState });
+}
+
+interface TaskClaim {
+	runId: string;
+	path: string;
+	ownerPath: string;
+	marker: Record<string, unknown>;
+	branch: string;
+	base: string;
+	state: TaskWorktreeState;
+	createdAt: string | null;
+	owner: ProcessLease | null;
+}
+
+/**
+ * Every task claim under the root whose facts are internally consistent: the
+ * marker names this root, its own run id, the canonical branch, and a path
+ * that is exactly `<parent>/<runId>` under an allowed parent. Anything else is not provably ours and
+ * is never returned, so recovery never touches it.
+ */
+function readTaskClaims(canonical: string, allowedParents: ReadonlyArray<string>): TaskClaim[] {
+	const parent = diskWorktreeParent(canonical);
+	let names: string[];
+	try {
+		names = readdirSync(parent);
+	} catch {
+		return [];
+	}
+	const claims: TaskClaim[] = [];
+	for (const name of names.sort()) {
+		if (!name.endsWith(OWNER_FILE_SUFFIX)) continue;
+		const runId = name.slice(0, -OWNER_FILE_SUFFIX.length);
+		if (!SAFE_RUN_ID.test(runId)) continue;
+		const ownerPath = join(parent, name);
+		let marker: Record<string, unknown>;
+		try {
+			const value = JSON.parse(readFileSync(ownerPath, "utf8")) as unknown;
+			if (typeof value !== "object" || value === null || Array.isArray(value)) continue;
+			marker = value as Record<string, unknown>;
+		} catch {
+			continue;
+		}
+		// The claim names where its working tree is. It is believed only when
+		// that is `<allowed parent>/<runId>`; recovery runs git and rm on it.
+		const path = typeof marker.path === "string" ? marker.path : join(parent, runId);
+		const pathParent = allowedParents.find((allowed) => resolve(allowed) === resolve(dirname(path)));
+		if (pathParent === undefined || basename(path) !== runId) continue;
+		if (
+			(marker.version !== 1 && marker.version !== 2) ||
+			(marker.kind !== TASK_WORKTREE_KIND && marker.kind !== LEGACY_TASK_WORKTREE_KIND) ||
+			marker.root !== canonical ||
+			marker.runId !== runId ||
+			(marker.branch !== `clio-coder/task/${runId}` && marker.branch !== `clio/task/${runId}`) ||
+			typeof marker.base !== "string" ||
+			!/^[0-9a-f]{40,64}$/u.test(marker.base) ||
+			(existsSync(path) && !isCanonicalWorktreePathInside(pathParent, path))
+		) {
+			continue;
+		}
+		const state: TaskWorktreeState = marker.state === "settled" || marker.state === "abandoned" ? marker.state : "active";
+		claims.push({
+			runId,
+			path,
+			ownerPath,
+			marker,
+			branch: marker.branch,
+			base: marker.base,
+			state,
+			createdAt: typeof marker.createdAt === "string" ? marker.createdAt : null,
+			owner: marker.version === 2 && validProcessLease(marker.owner) ? marker.owner : null,
+		});
+	}
+	return claims;
+}
+
+/**
+ * Why a dead owner's worktree must be kept, or null when it holds nothing: no
+ * commit beyond its base and no modified, staged, or untracked file. Any git
+ * failure is a reason to keep it.
+ */
+function workHeldBy(canonical: string, claim: TaskClaim): string | null {
+	try {
+		const commits = Number.parseInt(git(canonical, ["rev-list", "--count", `${claim.base}..${claim.branch}`]), 10);
+		if (!Number.isSafeInteger(commits)) return "its commits could not be counted";
+		if (commits > 0) {
+			return existsSync(claim.path)
+				? `${commits} commit(s) beyond its base`
+				: `${commits} commit(s) beyond its base (its working tree is gone)`;
+		}
+		// Gone with a tmpfs root at reboot: whatever was uncommitted went with it.
+		if (!existsSync(claim.path)) return null;
+		const dirty = git(claim.path, ["status", "--porcelain", "--untracked-files=all"]);
+		return dirty.length > 0 ? `${dirty.split("\n").length} uncommitted path(s)` : null;
+	} catch (error) {
+		return `git could not inspect it: ${error instanceof Error ? (error.message.split("\n")[0] ?? "error") : String(error)}`;
+	}
+}
+
+function preservedView(claim: TaskClaim, state: TaskWorktreeState, reason: string): PreservedTaskWorktree {
+	return {
+		runId: claim.runId,
+		path: claim.path,
+		claimPath: claim.ownerPath,
+		branch: claim.branch,
+		base: claim.base,
+		state,
+		createdAt: claim.createdAt,
+		reason,
+	};
+}
+
+/**
+ * Restart recovery for `worktree: true` dispatch. A crash used to leave the
+ * worktree, its branch, and its claim under `.clio-coder/worktrees/` forever.
+ * Only an `active` claim whose owner is provably gone is acted on: one that
+ * holds no work is removed with its branch, and one that holds commits or
+ * uncommitted files becomes `abandoned` and is returned for the startup
+ * report. It is never merged and never deleted. A live owner, an owner on
+ * another host, a claim without a lease, and a settled or already abandoned
+ * claim are left exactly as they are.
+ */
+export function recoverTaskWorktrees(
+	root: string,
+	/** Defaults to the project-root location; pass allowedWorktreeParents() to cover a configured root. */
+	allowedParents?: ReadonlyArray<string>,
+): TaskWorktreeRecoveryResult {
+	const result: TaskWorktreeRecoveryResult = { removed: [], preserved: [], failed: [] };
+	let canonical: string;
+	try {
+		canonical = realpathSync(root);
+	} catch {
+		return result;
+	}
+	for (const claim of readTaskClaims(canonical, allowedParents ?? [diskWorktreeParent(canonical)])) {
+		if (claim.state !== "active" || claim.owner === null || ownerIsAlive(claim.owner)) continue;
+		try {
+			const held = workHeldBy(canonical, claim);
+			if (held !== null) {
+				replaceMarker(claim.ownerPath, { ...claim.marker, state: "abandoned" satisfies TaskWorktreeState });
+				result.preserved.push(preservedView(claim, "abandoned", held));
+				continue;
+			}
+			if (existsSync(claim.path)) git(canonical, ["worktree", "remove", "--force", claim.path]);
+			else git(canonical, ["worktree", "prune"]);
+			git(canonical, ["branch", "-D", claim.branch]);
+			rmSync(claim.ownerPath, { force: true });
+			result.removed.push(claim.runId);
+		} catch (error) {
+			result.failed.push({ runId: claim.runId, message: error instanceof Error ? error.message : String(error) });
+		}
+	}
+	return result;
+}
+
+/**
+ * The task worktrees that outlived their run, for doctor: settled ones kept on
+ * purpose, abandoned ones recovery kept, and claims too old to carry a lease.
+ * A claim whose owner is still alive is a run in flight and is not listed.
+ */
+export function listPreservedTaskWorktrees(
+	root: string,
+	allowedParents?: ReadonlyArray<string>,
+): PreservedTaskWorktree[] {
+	let canonical: string;
+	try {
+		canonical = realpathSync(root);
+	} catch {
+		return [];
+	}
+	const out: PreservedTaskWorktree[] = [];
+	for (const claim of readTaskClaims(canonical, allowedParents ?? [diskWorktreeParent(canonical)])) {
+		if (claim.state === "settled") out.push(preservedView(claim, "settled", "kept by its run"));
+		else if (claim.state === "abandoned") out.push(preservedView(claim, "abandoned", "its owner died holding work"));
+		else if (claim.owner === null) out.push(preservedView(claim, "active", "its claim predates restart recovery"));
+		else if (!ownerIsAlive(claim.owner))
+			out.push(preservedView(claim, "active", "its owner is gone; the next start recovers it"));
+	}
+	return out;
 }

package/src/tools/tasks.ts

@@ -115,14 +115,25 @@ function taskTitlesArg(args: Record<string, unknown>): string[] {
 }
 
 function mutationFromArgs(action: TasksAction, args: Record<string, unknown>): TaskBoardMutation | { error: string } {
+	const initialStatus = args.initialStatus;
+	if (initialStatus !== undefined && initialStatus !== "pending" && initialStatus !== "blocked") {
+		return { error: "tasks: initialStatus must be pending or blocked" };
+	}
+	if (initialStatus !== undefined && action !== "plan" && action !== "add") {
+		return { error: "tasks: initialStatus applies only to plan and add" };
+	}
+	const initial: { initialStatus?: "pending" | "blocked"; reason?: string } = {
+		...(initialStatus ? { initialStatus } : {}),
+		...(initialStatus === "blocked" ? { reason: stringArg(args, "note") ?? "" } : {}),
+	};
 	switch (action) {
 		case "plan": {
 			const title = stringArg(args, "title");
 			if (!title) return { error: 'tasks: plan requires title (the board name), e.g. title="Fix the flaky test"' };
-			return { op: "plan", title, tasks: taskTitlesArg(args) };
+			return { op: "plan", title, tasks: taskTitlesArg(args), ...initial };
 		}
 		case "add":
-			return { op: "add", tasks: taskTitlesArg(args) };
+			return { op: "add", tasks: taskTitlesArg(args), ...initial };
 		case "pick":
 			return { error: "pick is resolved from the durable operator task inbox" };
 		case "start":
@@ -163,16 +174,20 @@ export function createTasksTool(deps: TasksToolDeps): ToolSpec {
 			"pick moves one operator task uN onto the board; start marks one task active (the current focus); " +
 			"done completes a task (started or still pending) and requires note as the " +
 			"evidence the work actually finished; block parks it with a required reason; drop cancels it; list shows the board. " +
-			"For an operator handoff, pick the intended uN before work and use its returned linked tN; CLI hand alone does not pick it. " +
-			"Never pick unrelated inbox tasks. Before claiming operator completion, list and confirm the linked board row is completed " +
-			"and the durable operator status is done with the same session/board link; report those IDs and actual states. " +
+			"For operator handoff, pick the intended uN and use its linked tN; CLI hand does not pick it. Never pick unrelated tasks. " +
+			"Before claiming completion, list: the linked row must be completed and the operator task done on the same session/board link; report IDs and states. " +
 			"Work that did not happen is blocked or dropped, never done. A self-created plan is not operator authorization. " +
-			"For proposal-only work, block deferred implementation with note naming the pending operator decision, or drop it; " +
+			"For proposal-only work, plan/add with initialStatus=blocked and note naming the pending operator decision; " +
 			"wait for an explicit operator go-ahead before start or implementation. A skill-install choice does not grant that go-ahead.",
 		parameters: Type.Object({
 			action: StringEnum(TASKS_ACTIONS, { description: "Board action." }),
 			title: Type.Optional(Type.String({ description: "Board title (plan)." })),
 			tasks: Type.Optional(Type.Array(Type.String(), { description: "Task titles (plan, add)." })),
+			initialStatus: Type.Optional(
+				StringEnum(["pending", "blocked"], {
+					description: "Initial state for plan/add; use blocked plus note for proposals awaiting a decision.",
+				}),
+			),
 			id: Type.Optional(Type.String({ description: 'Task id like "t2", or operator id "u2" for pick.' })),
 			note: Type.Optional(
 				Type.String({ description: "Evidence of completion (required for done) or the reason (block, drop)." }),
@@ -199,7 +214,14 @@ export function createTasksTool(deps: TasksToolDeps): ToolSpec {
 			}
 			return prepared;
 		},
-		async run(args): Promise<ToolResult> {
+		async run(args, options): Promise<ToolResult> {
+			if (options?.turnConstraints?.mode === "proposal" && (args.action === "plan" || args.action === "add")) {
+				args = {
+					...args,
+					initialStatus: "blocked",
+					note: stringArg(args, "note") ?? "Awaiting the operator's decision on this proposal.",
+				};
+			}
 			const action = typeof args.action === "string" ? args.action : "";
 			if (!(TASKS_ACTIONS as ReadonlyArray<string>).includes(action)) {
 				return { kind: "error", message: `tasks: action must be one of ${TASKS_ACTIONS.join(", ")}; got '${action}'` };

package/src/tools/worker-evidence.ts

@@ -1,5 +1,9 @@
 import { mentionsWorkerToolCallCap } from "../core/guardrails.js";
-import { RESULT_SUMMARY_MAX_BYTES_CEILING, resultContractAuthorship } from "../domains/agents/result-contract.js";
+import {
+	RESULT_SUMMARY_MAX_BYTES_CEILING,
+	resultContractAuthorship,
+	type StructuredHelperResult,
+} from "../domains/agents/result-contract.js";
 import {
 	formatBudgetPolicy,
 	formatBudgetReasons,
@@ -11,6 +15,47 @@ import type { RunReceipt, RunReceiptVerification } from "../domains/dispatch/typ
 import { formatTrustAxes, formatTrustSummary } from "../domains/evidence/trust-projection.js";
 import { adaptRunReceiptTrustStatus, type CanonicalTrustStatus } from "../domains/evidence/trust-status.js";
 import { receiptGatewayRoutingLabel, receiptResponseModelIdObservationLabel } from "./dispatch-event-text.js";
+import { truncateUtf8 } from "./truncate-utf8.js";
+
+/** Expose only a completed, sealed handoff. Conformance does not imply evidence quality. */
+export function receiptHelperResult(
+	receipt: RunReceipt,
+	integrity: ReceiptIntegrityResult,
+): StructuredHelperResult | null {
+	const output = receipt.output;
+	if (
+		!integrity.ok ||
+		receipt.exitCode !== 0 ||
+		receipt.outcome !== "succeeded" ||
+		output?.state !== "final" ||
+		output.truncated ||
+		receipt.quality?.resultContract?.conformance !== "pass"
+	)
+		return null;
+	return output.structured ?? null;
+}
+
+export function compactHelperResultLines(
+	receipt: RunReceipt,
+	integrity: ReceiptIntegrityResult,
+	maxBytes: number,
+): string[] | null {
+	const result = receiptHelperResult(receipt, integrity);
+	if (result === null) return null;
+	const quality = receipt.quality?.resultContract?.quality ?? "unmeasured";
+	return [
+		`- ${receipt.agentId} · run ${receipt.runId} · ${result.kind} · quality=${quality}`,
+		...(quality !== "pass"
+			? [
+					result.kind === "scout-report"
+						? "  Findings without path and line are ungrounded leads; do not present them as verified facts."
+						: "  Content is contract-valid; its factual accuracy is unmeasured.",
+				]
+			: []),
+		`  ${truncateUtf8(JSON.stringify(result.data), maxBytes, "\n[helper result preview truncated; inspect the receipt for the full result]")}`,
+		`  Receipt available on demand: monitor(mode="receipt", run_id=${JSON.stringify(receipt.runId)}).`,
+	];
+}
 
 /** Matches a source citation the parent can independently spot-check. */
 const SOURCE_CITATION_PATTERN = /([\w./~-]+):(\d+)/g;
@@ -162,6 +207,20 @@ export function receiptEvidenceLabels(
 		...documenterDeliveryLabels(receipt),
 		`evidence_verification=${verification.state}/${verification.basis}`,
 		`host_verification=${receipt.hostVerification?.status ?? "not_requested"}`,
+		...(receipt.hostVerification?.checks.length
+			? [
+					`Host check evidence is separate from the worker report: ${receipt.hostVerification.checks
+						.map((check) => {
+							const source = check.memo
+								? "reused prior host result"
+								: receipt.hostVerification?.strategy === "batch-settled"
+									? "executed after the worker batch"
+									: "executed after the worker";
+							return `${JSON.stringify(check.check)} (${source}; exit ${check.exitCode})`;
+						})
+						.join(", ")}.`,
+				]
+			: []),
 		...(responseModelIdObservation ? [responseModelIdObservation] : []),
 		...(gatewayRouting ? [gatewayRouting] : []),
 		...budget,