@sayknow-cli/coding-agent 0.4.7 → 0.5.1

package/src/skc-runtime/repository-binding.ts

@@ -0,0 +1,267 @@
+/**
+ * Authoritative repository/worktree binding for plans and delegated tasks (#2901).
+ *
+ * Multi-repo parent directories must not let QA/review lanes infer a sibling repo
+ * from prose. Bindings carry a validated worktree root + git common-dir identity
+ * so spawn/handoff can fail closed on mismatch.
+ */
+import * as fssync from "node:fs";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { type GitRepository, head, repo } from "../utils/git";
+
+export const REPOSITORY_BINDING_SCHEMA = "skc.repository_binding.v1" as const;
+
+export interface RepositoryBinding {
+	schema: typeof REPOSITORY_BINDING_SCHEMA;
+	/** Canonical realpath of the git worktree root (or resolved cwd root). */
+	worktreeRoot: string;
+	/** Git common dir realpath when available; null outside a git checkout. */
+	commonDir: string | null;
+	/** Optional repo-relative subdirectory the lane should operate under. */
+	relativeSubdir?: string;
+	/** Optional display path (may be non-canonical); never used for authority. */
+	displayPath?: string;
+	/** Optional baseline HEAD at capture time. */
+	head?: string;
+	/** Optional branch name at capture time (when not detached). */
+	branch?: string;
+}
+
+export type RepositoryBindingErrorCode =
+	| "not_a_repository"
+	| "identity_mismatch"
+	| "path_outside_root"
+	| "invalid_binding";
+
+export class RepositoryBindingError extends Error {
+	readonly code: RepositoryBindingErrorCode;
+
+	constructor(code: RepositoryBindingErrorCode, message: string) {
+		super(message);
+		this.name = "RepositoryBindingError";
+		this.code = code;
+	}
+}
+
+async function realpathOrResolve(target: string): Promise<string> {
+	try {
+		return await fs.realpath(target);
+	} catch {
+		return path.resolve(target);
+	}
+}
+
+/** Sync realpath for path-under-root checks (handles macOS /var → /private/var). */
+function realpathSyncOrResolve(target: string): string {
+	try {
+		return fssync.realpathSync(target);
+	} catch {
+		return path.resolve(target);
+	}
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
+}
+
+/** Capture a durable binding from the active cwd/worktree. */
+export async function captureRepositoryBinding(
+	cwd: string,
+	options: { relativeSubdir?: string; displayPath?: string } = {},
+): Promise<RepositoryBinding> {
+	const resolvedCwd = await realpathOrResolve(cwd);
+	const repository = await repo.resolve(resolvedCwd);
+	const worktreeRoot = repository ? await realpathOrResolve(repository.repoRoot) : resolvedCwd;
+	const commonDir = repository ? await realpathOrResolve(repository.commonDir) : null;
+
+	let headSha: string | undefined;
+	let branch: string | undefined;
+	if (repository) {
+		const headState = await head.resolve(resolvedCwd);
+		if (headState) {
+			headSha = headState.commit || undefined;
+			branch = headState.kind === "ref" ? headState.branchName || undefined : undefined;
+		}
+	}
+
+	const binding: RepositoryBinding = {
+		schema: REPOSITORY_BINDING_SCHEMA,
+		worktreeRoot,
+		commonDir,
+		...(options.relativeSubdir ? { relativeSubdir: normalizeRelativeSubdir(options.relativeSubdir) } : {}),
+		...(options.displayPath ? { displayPath: options.displayPath } : {}),
+		...(headSha ? { head: headSha } : {}),
+		...(branch ? { branch } : {}),
+	};
+	return binding;
+}
+
+function normalizeRelativeSubdir(relative: string): string {
+	const normalized = relative
+		.replaceAll("\\", "/")
+		.replace(/^\.\/+/u, "")
+		.replace(/\/+$/u, "");
+	if (normalized === "" || normalized === ".") {
+		throw new RepositoryBindingError("invalid_binding", "relativeSubdir must be a non-empty relative path");
+	}
+	if (path.isAbsolute(normalized) || normalized.split("/").includes("..")) {
+		throw new RepositoryBindingError("invalid_binding", "relativeSubdir must be repo-relative without '..' segments");
+	}
+	return normalized;
+}
+
+/** Parse a binding from JSON/plan payload; fail closed on malformed shapes. */
+export function parseRepositoryBinding(value: unknown): RepositoryBinding {
+	if (!isObject(value)) {
+		throw new RepositoryBindingError("invalid_binding", "repository binding must be an object");
+	}
+	const schema = nonEmptyString(value.schema);
+	if (schema !== REPOSITORY_BINDING_SCHEMA) {
+		throw new RepositoryBindingError(
+			"invalid_binding",
+			`repository binding schema must be ${REPOSITORY_BINDING_SCHEMA}`,
+		);
+	}
+	const worktreeRoot = nonEmptyString(value.worktreeRoot ?? value.worktree_root);
+	if (!worktreeRoot) {
+		throw new RepositoryBindingError("invalid_binding", "repository binding requires worktreeRoot");
+	}
+	const commonDirRaw = value.commonDir ?? value.common_dir;
+	const commonDir =
+		commonDirRaw === null || commonDirRaw === undefined
+			? null
+			: (nonEmptyString(commonDirRaw) ??
+				(() => {
+					throw new RepositoryBindingError("invalid_binding", "commonDir must be a string or null");
+				})());
+	const relativeSubdirRaw = value.relativeSubdir ?? value.relative_subdir;
+	const relativeSubdir =
+		relativeSubdirRaw === undefined ? undefined : normalizeRelativeSubdir(String(relativeSubdirRaw));
+	const displayPath = nonEmptyString(value.displayPath ?? value.display_path);
+	const head = nonEmptyString(value.head);
+	const branch = nonEmptyString(value.branch);
+	return {
+		schema: REPOSITORY_BINDING_SCHEMA,
+		worktreeRoot: path.resolve(worktreeRoot),
+		commonDir: commonDir === null ? null : path.resolve(commonDir),
+		...(relativeSubdir ? { relativeSubdir } : {}),
+		...(displayPath ? { displayPath } : {}),
+		...(head ? { head } : {}),
+		...(branch ? { branch } : {}),
+	};
+}
+
+/** True when two bindings refer to the same repository identity (linked worktrees ok). */
+export function repositoryBindingsMatch(left: RepositoryBinding, right: RepositoryBinding): boolean {
+	if (left.commonDir && right.commonDir) {
+		return path.resolve(left.commonDir) === path.resolve(right.commonDir);
+	}
+	// Non-git workspaces: require exact worktree root match.
+	return path.resolve(left.worktreeRoot) === path.resolve(right.worktreeRoot);
+}
+
+/**
+ * Ensure `cwd` is inside the bound repository (or the same linked worktree family).
+ * Fails closed on sibling-repo drift.
+ */
+export async function assertCwdMatchesRepositoryBinding(
+	cwd: string,
+	binding: RepositoryBinding,
+): Promise<RepositoryBinding> {
+	const active = await captureRepositoryBinding(cwd);
+	if (!repositoryBindingsMatch(active, binding)) {
+		throw new RepositoryBindingError(
+			"identity_mismatch",
+			`Active worktree does not match plan/task repository binding. active=${active.worktreeRoot} (commonDir=${active.commonDir ?? "none"}) bound=${binding.worktreeRoot} (commonDir=${binding.commonDir ?? "none"}).`,
+		);
+	}
+	return active;
+}
+
+/** Ensure a declared target path resolves under the bound worktree root. */
+export function assertPathUnderRepositoryBinding(binding: RepositoryBinding, targetPath: string): string {
+	const root = realpathSyncOrResolve(binding.worktreeRoot);
+	const base = binding.relativeSubdir ? realpathSyncOrResolve(path.resolve(root, binding.relativeSubdir)) : root;
+	const candidate = path.isAbsolute(targetPath) ? path.resolve(targetPath) : path.resolve(base, targetPath);
+	// Prefer realpath when the path exists so macOS /var ↔ /private/var aliases match.
+	const resolved = realpathSyncOrResolve(candidate);
+	const relative = path.relative(root, resolved);
+	if (relative.startsWith("..") || path.isAbsolute(relative)) {
+		throw new RepositoryBindingError(
+			"path_outside_root",
+			`Path escapes bound repository root: ${targetPath} (root=${root})`,
+		);
+	}
+	return resolved;
+}
+
+/**
+ * Public identity snapshot for receipts/handoffs (no display-only fields required).
+ * Always includes the schema + durable roots so downstream lanes can re-verify.
+ */
+export function publicRepositoryBinding(binding: RepositoryBinding): RepositoryBinding {
+	return {
+		schema: REPOSITORY_BINDING_SCHEMA,
+		worktreeRoot: path.resolve(binding.worktreeRoot),
+		commonDir: binding.commonDir === null ? null : path.resolve(binding.commonDir),
+		...(binding.relativeSubdir ? { relativeSubdir: binding.relativeSubdir } : {}),
+		...(binding.displayPath ? { displayPath: binding.displayPath } : {}),
+		...(binding.head ? { head: binding.head } : {}),
+		...(binding.branch ? { branch: binding.branch } : {}),
+	};
+}
+
+/**
+ * Resolve the authoritative binding for a delegated task before discovery/spawn.
+ *
+ * - Missing declaration → stamp from session cwd (never leave authority implicit).
+ * - Declared binding → parse + fail closed unless it matches the active session worktree.
+ * - relativeSubdir (when present) must resolve under the bound root.
+ */
+export async function resolveTaskRepositoryBinding(
+	sessionCwd: string,
+	declared: unknown | undefined,
+): Promise<RepositoryBinding> {
+	const sessionBinding = await captureRepositoryBinding(sessionCwd, { displayPath: sessionCwd });
+	if (declared === undefined || declared === null) {
+		return publicRepositoryBinding(sessionBinding);
+	}
+	const taskBinding = parseRepositoryBinding(declared);
+	await assertCwdMatchesRepositoryBinding(sessionCwd, taskBinding);
+	if (taskBinding.relativeSubdir) {
+		assertPathUnderRepositoryBinding(taskBinding, ".");
+	}
+	return publicRepositoryBinding(taskBinding);
+}
+
+/**
+ * Ensure an execution/isolation root (cwd or worktree) still matches the bound identity.
+ * Used after isolation workspace creation so linked worktrees keep the source repository.
+ */
+export async function assertExecutionRootMatchesRepositoryBinding(
+	executionRoot: string,
+	binding: RepositoryBinding,
+): Promise<RepositoryBinding> {
+	return await assertCwdMatchesRepositoryBinding(executionRoot, binding);
+}
+
+/** Optional helper for tests and diagnostics. */
+export function bindingFromGitRepository(
+	repository: GitRepository,
+	options: { relativeSubdir?: string; displayPath?: string; head?: string; branch?: string } = {},
+): RepositoryBinding {
+	return {
+		schema: REPOSITORY_BINDING_SCHEMA,
+		worktreeRoot: path.resolve(repository.repoRoot),
+		commonDir: path.resolve(repository.commonDir),
+		...(options.relativeSubdir ? { relativeSubdir: normalizeRelativeSubdir(options.relativeSubdir) } : {}),
+		...(options.displayPath ? { displayPath: options.displayPath } : {}),
+		...(options.head ? { head: options.head } : {}),
+		...(options.branch ? { branch: options.branch } : {}),
+	};
+}

package/src/skc-runtime/session-state-sidecar.ts

@@ -911,15 +911,11 @@ async function operatorDispatchIdForOwner(
 	}
 }
 
-async function persistCoordinatorRuntimeStateFromOwnerTerminalPostmortem(
+async function observeOwnerTerminalPostmortem(
 	reason: postmortem.Reason,
-	context: RuntimeStateContext,
-	stateFile: string,
+	owner: OwnerTerminalContext,
 	sessionId: string,
-	previous: Record<string, unknown>,
-): Promise<void> {
-	const owner = context.ownerTerminal;
-	if (!owner) return;
+): Promise<OwnerVerdict | null> {
 	try {
 		const now = new Date().toISOString();
 		const observation: Omit<ObserveTerminalRequest, "operator_dispatch_id"> = {
@@ -937,10 +933,27 @@ async function persistCoordinatorRuntimeStateFromOwnerTerminalPostmortem(
 			reason: "process_postmortem",
 		};
 		const operatorDispatchId = await operatorDispatchIdForOwner(owner, observation);
-		const verdict = await observeOwnerTerminal({
+		return await observeOwnerTerminal({
 			...observation,
 			...(operatorDispatchId ? { operator_dispatch_id: operatorDispatchId } : {}),
 		});
+	} catch {
+		return null;
+	}
+}
+
+async function persistCoordinatorRuntimeStateFromOwnerTerminalPostmortem(
+	context: RuntimeStateContext,
+	stateFile: string,
+	sessionId: string,
+	previous: Record<string, unknown>,
+	verdict: OwnerVerdict | null,
+): Promise<void> {
+	const owner = context.ownerTerminal;
+	if (!owner) return;
+	try {
+		if (!verdict) throw new Error("owner terminal verdict unavailable");
+		const now = new Date().toISOString();
 		const expected = verdict.classification === "expected_operator_shutdown";
 		const state: RuntimeState = expected ? "completed" : "errored";
 		const payload = {
@@ -1009,6 +1022,9 @@ export async function persistCoordinatorRuntimeStateFromPostmortem(
 	const stateFile = runtimeStateFileForContext(context);
 	if (!stateFile) return;
 	const identity = normalizedIdentity(context);
+	const ownerTerminalVerdict = context.ownerTerminal
+		? await observeOwnerTerminalPostmortem(reason, context.ownerTerminal, identity.sessionId)
+		: null;
 	await serializeStateFileWrite(
 		stateFile,
 		async () =>
@@ -1033,11 +1049,11 @@ export async function persistCoordinatorRuntimeStateFromPostmortem(
 						}
 						if (context.ownerTerminal) {
 							await persistCoordinatorRuntimeStateFromOwnerTerminalPostmortem(
-								reason,
 								context,
 								stateFile,
 								identity.sessionId,
 								previous,
+								ownerTerminalVerdict,
 							);
 							return;
 						}

package/src/skc-runtime/state-runtime.ts

@@ -1,6 +1,9 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+// Subpath import keeps this module native-free for the skc-state-gates shards:
+// the package barrel pulls procmgr/ptree → @sayknow-cli/natives.
+import * as logger from "@sayknow-cli/utils/logger";
 import type { WorkflowHudSummary } from "../skill-state/active-state";
 import {
 	applyHandoffToActiveState,
@@ -265,7 +268,21 @@ async function describeStaleClearState(
 	return undefined;
 }
 
-async function readJsonFile(filePath: string): Promise<Record<string, unknown> | null> {
+/**
+ * Route a workflow-state warning through the TUI-safe centralized file logger
+ * (console transport off by default) so interactive sessions never paint raw
+ * bytes into the alternate-screen stream (#3002). CLI command handlers may also
+ * collect the warning via an `onWarning` sink to surface it on the structured
+ * {@link StateCommandResult.stderr} channel, so `skc state` automation still
+ * distinguishes corrupt state from absent state.
+ */
+function emitStateWarning(warning: string, context?: Record<string, unknown>): void {
+	logger.warn(warning, context);
+}
+
+type StateWarningSink = (warning: string) => void;
+
+async function readJsonFile(filePath: string, onWarning?: StateWarningSink): Promise<Record<string, unknown> | null> {
 	try {
 		const raw = await fs.readFile(filePath, "utf-8");
 		const parsed = JSON.parse(raw);
@@ -276,18 +293,22 @@ async function readJsonFile(filePath: string): Promise<Record<string, unknown> |
 	} catch (error) {
 		const err = error as NodeJS.ErrnoException;
 		if (err.code === "ENOENT") return null;
-		process.stderr.write(`WARNING: failed to read ${filePath}; ignoring corrupt state: ${err.message}\n`);
+		const warning = `WARNING: failed to read ${filePath}; ignoring corrupt state: ${err.message}`;
+		emitStateWarning(warning, { filePath, error: err.message });
+		onWarning?.(warning);
 		return null;
 	}
 }
 
-async function readJsonValue(filePath: string): Promise<unknown | null> {
+async function readJsonValue(filePath: string, onWarning?: StateWarningSink): Promise<unknown | null> {
 	try {
 		return JSON.parse(await fs.readFile(filePath, "utf-8"));
 	} catch (error) {
 		const err = error as NodeJS.ErrnoException;
 		if (err.code === "ENOENT") return null;
-		process.stderr.write(`WARNING: failed to read ${filePath}; ignoring corrupt state: ${err.message}\n`);
+		const warning = `WARNING: failed to read ${filePath}; ignoring corrupt state: ${err.message}`;
+		emitStateWarning(warning, { filePath, error: err.message });
+		onWarning?.(warning);
 		return null;
 	}
 }
@@ -836,7 +857,8 @@ function buildHudForMode(
 					: typeof payload.mode === "string"
 						? (payload.mode as string)
 						: undefined;
-			const verdict = typeof payload.verdict === "string" ? (payload.verdict as string) : undefined;
+			const rawVerdict = payload.last_review_verdict ?? payload.verdict;
+			const verdict = typeof rawVerdict === "string" ? rawVerdict : undefined;
 			const iteration = typeof payload.iteration === "number" ? (payload.iteration as number) : undefined;
 			const pendingApproval = payload.pending_approval === true || stage === "final";
 			return buildRalplanHudSummary({
@@ -1101,21 +1123,30 @@ export async function readWorkflowStateJson(
 	cwd: string,
 	skill: CanonicalSkcWorkflowSkill,
 	sessionId?: string,
+	onWarning?: StateWarningSink,
 ): Promise<Record<string, unknown>> {
 	const session = await resolveSkcSessionForRead(cwd, {
 		payloadSessionId: sessionId,
 		envSessionId: process.env.SKC_SESSION_ID,
 	});
-	return (await readJsonFile(modeStateFile(cwd, skill, session.skcSessionId))) ?? {};
+	return (await readJsonFile(modeStateFile(cwd, skill, session.skcSessionId), onWarning)) ?? {};
 }
 
 async function handleRead(args: readonly string[], cwd: string): Promise<StateCommandResult> {
 	const selectors = await resolveSelectors(args, cwd, "read");
 	const mode = selectors.mode ?? (await inferModeFromActiveState(cwd, selectors.skcSessionId));
 	const fields = parseFieldsFlag(args);
+	// Corrupt-state warnings are TUI-safe file-logged inside the readers; the CLI
+	// path also surfaces them on the command result so `skc state read`
+	// automation can tell corrupt state from absent state (#3002).
+	const warnings: string[] = [];
+	const warningStderr = (): Pick<StateCommandResult, "stderr"> =>
+		warnings.length ? { stderr: warnings.map(warning => `${warning}\n`).join("") } : {};
 	if (mode) {
 		const filePath = modeStateFile(cwd, mode, selectors.skcSessionId);
-		const existing = await readWorkflowStateJson(cwd, mode, selectors.skcSessionId);
+		const existing = await readWorkflowStateJson(cwd, mode, selectors.skcSessionId, warning =>
+			warnings.push(warning),
+		);
 		const envelope = { skill: mode, state: existing, storage_path: filePath };
 		const manifest = getSkillManifest(mode);
 		if (fields) {
@@ -1125,6 +1156,7 @@ async function handleRead(args: readonly string[], cwd: string): Promise<StateCo
 				stdout: hasFlag(args, "--json")
 					? `${JSON.stringify(projected, null, 2)}\n`
 					: renderStateMarkdown(mode, projected, manifest),
+				...warningStderr(),
 			};
 		}
 		if (hasFlag(args, "--compact")) {
@@ -1134,6 +1166,7 @@ async function handleRead(args: readonly string[], cwd: string): Promise<StateCo
 				stdout: hasFlag(args, "--json")
 					? `${JSON.stringify(compact, null, 2)}\n`
 					: renderStateMarkdown(mode, envelope, manifest),
+				...warningStderr(),
 			};
 		}
 		return {
@@ -1141,12 +1174,13 @@ async function handleRead(args: readonly string[], cwd: string): Promise<StateCo
 			stdout: hasFlag(args, "--json")
 				? `${JSON.stringify(envelope, null, 2)}\n`
 				: renderStateMarkdown(mode, envelope, manifest),
+			...warningStderr(),
 		};
 	}
 	const filePath = activeStateFile(cwd, selectors.skcSessionId);
-	const existingRaw = await readJsonValue(filePath);
+	const existingRaw = await readJsonValue(filePath, warning => warnings.push(warning));
 	const existing = isPlainObject(existingRaw) ? existingRaw : null;
-	return { status: 0, stdout: `${JSON.stringify(existing ?? {}, null, 2)}\n` };
+	return { status: 0, stdout: `${JSON.stringify(existing ?? {}, null, 2)}\n`, ...warningStderr() };
 }
 
 async function handleStatus(args: readonly string[], cwd: string): Promise<StateCommandResult> {
@@ -1159,7 +1193,8 @@ async function handleStatus(args: readonly string[], cwd: string): Promise<State
 		);
 	}
 	const filePath = modeStateFile(cwd, mode, selectors.skcSessionId);
-	const existing = await readWorkflowStateJson(cwd, mode, selectors.skcSessionId);
+	const warnings: string[] = [];
+	const existing = await readWorkflowStateJson(cwd, mode, selectors.skcSessionId, warning => warnings.push(warning));
 	const summary = buildStateStatusSummary(
 		mode,
 		{ skill: mode, state: existing, storage_path: filePath },
@@ -1169,6 +1204,7 @@ async function handleStatus(args: readonly string[], cwd: string): Promise<State
 	return {
 		status: 0,
 		stdout: hasFlag(args, "--json") ? `${JSON.stringify(summary, null, 2)}\n` : renderStateStatusLine(summary),
+		...(warnings.length ? { stderr: warnings.map(warning => `${warning}\n`).join("") } : {}),
 	};
 }
 
@@ -1603,7 +1639,7 @@ async function handleHandoffUnlocked(args: readonly string[], cwd: string): Prom
 			toPhase: "handoff",
 		});
 		await updateWorkflowTransactionJournal(cwd, sessionId, mutationId, { steps: ["caller-mode-state"] });
-		if (callerWrite.warning) process.stderr.write(`${callerWrite.warning}\n`);
+		if (callerWrite.warning) emitStateWarning(callerWrite.warning);
 		const stampedCallerReceipt = isPlainObject(callerWrite.stamped.receipt) ? callerWrite.stamped.receipt : {};
 		await syncSkillActiveState({
 			cwd,
@@ -1646,6 +1682,7 @@ async function handleHandoffUnlocked(args: readonly string[], cwd: string): Prom
 					active_state: activeStateFile(cwd, sessionId),
 				},
 			}),
+			...(callerWrite.warning ? { stderr: `${callerWrite.warning}\n` } : {}),
 		};
 	}
 
@@ -1746,7 +1783,7 @@ async function handleHandoffUnlocked(args: readonly string[], cwd: string): Prom
 	);
 	const stampedCallerReceipt = isPlainObject(callerWrite.stamped.receipt) ? callerWrite.stamped.receipt : {};
 	const stampedCalleeReceipt = isPlainObject(calleeWrite.stamped.receipt) ? calleeWrite.stamped.receipt : {};
-	for (const warning of warnings) process.stderr.write(`${warning}\n`);
+	for (const warning of warnings) emitStateWarning(warning);
 	if (process.env.SKC_STATE_HANDOFF_FAIL_AFTER_CALLER === mutationId) {
 		throw new StateCommandError(1, `injected handoff failure after caller write for ${mutationId}`);
 	}
@@ -1818,6 +1855,7 @@ async function handleHandoffUnlocked(args: readonly string[], cwd: string): Prom
 				active_state: activeStateFile(cwd, sessionId),
 			},
 		}),
+		...(warnings.length ? { stderr: warnings.map(warning => `${warning}\n`).join("") } : {}),
 	};
 }