@sayknow-cli/coding-agent 0.4.7 → 0.5.1

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

@@ -96,7 +96,6 @@ export interface GuardedStateWriterOptions extends StateWriterOptions {
 	policy: StateWritePolicy;
 	expectedRevision?: number;
 	sourceRevision?: number;
-	lockHeld?: boolean;
 }
 
 export type GuardedWriteResult =
@@ -114,6 +113,11 @@ export interface StateWriterOptions {
 	 * `withFileLock` defaults.
 	 */
 	lock?: FileLockOptions;
+	/**
+	 * Caller already holds the workflow state lock for this target path (via
+	 * `withWorkflowStateLock`). Skip re-acquisition to avoid self-deadlock.
+	 */
+	lockHeld?: boolean;
 }
 
 export class StateWriteConflictError extends Error {
@@ -681,63 +685,71 @@ export async function writeWorkflowEnvelopeAtomic(
 	options?: StateWriterOptions,
 ): Promise<string> {
 	const filePath = resolveSkcTarget(targetPath, cwdForOptions(options));
-	const withReceipt = withWorkflowReceipt(value, buildReceipt(options));
-	const stamped = stampWorkflowEnvelopeChecksum(withReceipt, filePath);
-	const parsed = RequiredOnWriteEnvelopeSchema.safeParse(stamped);
-	if (!parsed.success) {
-		throw new Error(
-			`Refusing to write invalid workflow state envelope to ${filePath}: ${parsed.error.issues
-				.map(issue => `${issue.path.join(".") || "<root>"}: ${issue.message}`)
-				.join("; ")}`,
-		);
-	}
-	// #658: internal runtime writers (ralplan/ultragoal/deep-interview/team) persist
-	// envelopes directly, bypassing the `skc state` CLI transition gate (`isValidTransition`,
-	// historically the sole call site in state-runtime.ts). Re-assert that gate on every
-	// sanctioned envelope write so internal writes cannot persist invalid state-machine phase
-	// transitions silently. Forced writes (`skc state ... --force`, reconcile repairs) carry
-	// `audit.forced` and bypass, mirroring the CLI's `use --force to bypass`.
-	//
-	// The gate governs ACTIVE workflow progression only. Deactivation/teardown writes
-	// (`active: false`, e.g. `skc state clear`, which persists the universal `complete`
-	// sentinel that is not a per-skill manifest state) leave the transition graph and are
-	// intentionally exempt.
-	if (options?.audit?.forced !== true && parsed.data.active === true) {
-		const toPhase = parsed.data.current_phase.trim();
-		if (toPhase) {
-			// Lazy import: workflow-manifest dereferences CANONICAL_SKC_WORKFLOW_SKILLS at
-			// module load, and active-state -> state-writer -> workflow-manifest -> active-state
-			// is a load-time cycle. Importing at call time (after init) avoids the TDZ.
-			const { isKnownWorkflowState, isValidTransition } = await import("./workflow-manifest");
-			const skill = parsed.data.skill;
-			// Structural invariant (hard): a `current_phase` absent from the skill's manifest is
-			// never a legitimate internal write, matching the CLI/reconcile unknown-phase gate.
-			if (!isKnownWorkflowState(skill, toPhase)) {
-				throw new Error(
-					`Refusing to write unknown ${skill} phase "${toPhase}" to ${filePath}: not a known ${skill} manifest state (forced writes bypass via audit.forced)`,
-				);
-			}
-			// Transition invariant (#658, diagnostic-only safety net): resolve the prior phase
-			// (caller-supplied `audit.fromPhase`, else the active persisted envelope on disk) and
-			// flag edges the manifest does not define. Intentionally NON-blocking and audit-only
-			// — the CLI path already hard-fails invalid edges before reaching here, and legitimate
-			// internal repairs / ralplan short-mode stage skips move between valid states without a
-			// direct manifest edge. It records an `invalid_transition_detected` audit entry (no
-			// stderr) so such transitions are non-silent without breaking those flows.
-			const fromPhase = (options?.audit?.fromPhase ?? (await readPersistedPhase(filePath)))?.trim();
-			if (
-				fromPhase &&
-				fromPhase !== toPhase &&
-				isKnownWorkflowState(skill, fromPhase) &&
-				!isValidTransition(skill, fromPhase, toPhase)
-			) {
-				await recordInvalidWorkflowTransition({ filePath, skill, fromPhase, toPhase, options });
+	const write = async (): Promise<string> => {
+		const withReceipt = withWorkflowReceipt(value, buildReceipt(options));
+		const stamped = stampWorkflowEnvelopeChecksum(withReceipt, filePath);
+		const parsed = RequiredOnWriteEnvelopeSchema.safeParse(stamped);
+		if (!parsed.success) {
+			throw new Error(
+				`Refusing to write invalid workflow state envelope to ${filePath}: ${parsed.error.issues
+					.map(issue => `${issue.path.join(".") || "<root>"}: ${issue.message}`)
+					.join("; ")}`,
+			);
+		}
+		// #658: internal runtime writers (ralplan/ultragoal/deep-interview/team) persist
+		// envelopes directly, bypassing the `skc state` CLI transition gate (`isValidTransition`,
+		// historically the sole call site in state-runtime.ts). Re-assert that gate on every
+		// sanctioned envelope write so internal writes cannot persist invalid state-machine phase
+		// transitions silently. Forced writes (`skc state ... --force`, reconcile repairs) carry
+		// `audit.forced` and bypass, mirroring the CLI's `use --force to bypass`.
+		//
+		// The gate governs ACTIVE workflow progression only. Deactivation/teardown writes
+		// (`active: false`, e.g. `skc state clear`, which persists the universal `complete`
+		// sentinel that is not a per-skill manifest state) leave the transition graph and are
+		// intentionally exempt.
+		if (options?.audit?.forced !== true && parsed.data.active === true) {
+			const toPhase = parsed.data.current_phase.trim();
+			if (toPhase) {
+				// Lazy import: workflow-manifest dereferences CANONICAL_SKC_WORKFLOW_SKILLS at
+				// module load, and active-state -> state-writer -> workflow-manifest -> active-state
+				// is a load-time cycle. Importing at call time (after init) avoids the TDZ.
+				const { isKnownWorkflowState, isValidTransition } = await import("./workflow-manifest");
+				const skill = parsed.data.skill;
+				// Structural invariant (hard): a `current_phase` absent from the skill's manifest is
+				// never a legitimate internal write, matching the CLI/reconcile unknown-phase gate.
+				if (!isKnownWorkflowState(skill, toPhase)) {
+					throw new Error(
+						`Refusing to write unknown ${skill} phase "${toPhase}" to ${filePath}: not a known ${skill} manifest state (forced writes bypass via audit.forced)`,
+					);
+				}
+				// Transition invariant (#658, diagnostic-only safety net): resolve the prior phase
+				// (caller-supplied `audit.fromPhase`, else the active persisted envelope on disk) and
+				// flag edges the manifest does not define. Intentionally NON-blocking and audit-only
+				// — the CLI path already hard-fails invalid edges before reaching here, and legitimate
+				// internal repairs / ralplan short-mode stage skips move between valid states without a
+				// direct manifest edge. It records an `invalid_transition_detected` audit entry (no
+				// stderr) so such transitions are non-silent without breaking those flows.
+				const fromPhase = (options?.audit?.fromPhase ?? (await readPersistedPhase(filePath)))?.trim();
+				if (
+					fromPhase &&
+					fromPhase !== toPhase &&
+					isKnownWorkflowState(skill, fromPhase) &&
+					!isValidTransition(skill, fromPhase, toPhase)
+				) {
+					await recordInvalidWorkflowTransition({ filePath, skill, fromPhase, toPhase, options });
+				}
 			}
 		}
-	}
-	await atomicWrite(filePath, jsonText(stamped));
-	await maybeAudit(filePath, options);
-	return filePath;
+		await atomicWrite(filePath, jsonText(stamped));
+		await maybeAudit(filePath, options);
+		return filePath;
+	};
+	// Serialize with every other writer of the same state path. Without this, a
+	// revision-preserving envelope write (seed/spec persistence) can interleave
+	// inside a staged apply's check-then-write window and be silently overwritten
+	// (#3387 architect finding 1). Callers already inside `withWorkflowStateLock`
+	// for this path pass `lockHeld: true`.
+	return options?.lockHeld ? write() : lockResolvedWorkflowTarget(filePath, write, options?.lock);
 }
 
 export async function writeTextAtomic(targetPath: string, text: string, options?: StateWriterOptions): Promise<string> {

package/src/skc-runtime/team-launch.ts

@@ -12,6 +12,7 @@ import type {
 	SkcTeamWorkerLifecycle,
 	SkcTeamWorktreeMode,
 } from "./team-runtime";
+import { createInitialSkcTeamWorkerMemoryGuardLedger, workerMemoryGuardLedgerPath } from "./team-worker-memory-guard";
 
 /** Launch-specific option wiring kept separate from runtime dispatch. */
 export function withTeamLaunchTransport(
@@ -34,6 +35,7 @@ export function buildWorkerCommand(
 	config: SkcTeamConfig,
 	worker: SkcTeamWorker,
 	platform: NodeJS.Platform = process.platform,
+	promptOverride?: string,
 ): string {
 	const quote = platform === "win32" ? powershellQuote : shellQuote;
 	const envAssignment = (key: string, value: string): string =>
@@ -41,7 +43,8 @@ export function buildWorkerCommand(
 	const workspace = worker.worktree_path
 		? `Worker worktree: ${worker.worktree_path}.`
 		: `Worker cwd: ${config.leader.cwd}.`;
-	const prompt =
+	const initialPrompt =
+		promptOverride ??
 		[
 			`You are ${worker.id} in skc team ${config.team_name}.`,
 			`Team state root: ${config.state_root}.`,
@@ -50,8 +53,9 @@ export function buildWorkerCommand(
 			"Before implementation, claim your worker-owned task and treat the claimed task record as the source of truth. Do not implement directly from the broad team brief.",
 			`Before claiming work, send startup ACK: skc team api worker-startup-ack --input '{"team_name":"${config.team_name}","worker_id":"${worker.id}","protocol_version":"1"}' --json.`,
 			"Use skc team api update-worker-status to report task-local activity, then claim-task/transition-task-status with this worker id; keep heartbeat current during long work, record completion_evidence (summary plus a passed command or verified inspection/artifact item) before completed, and do not mutate leader-owned goal state.",
-		]
-			.join("\n")
+		].join("\n");
+	const prompt =
+		initialPrompt
 			.replace(/[\uFEFF\u200B]/g, "")
 			.replace(/\r?\n+/g, " ")
 			.trim() || `Worker ${worker.id} ready.`;
@@ -66,6 +70,10 @@ export function buildWorkerCommand(
 		envAssignment("SKC_TEAM_DISPLAY_NAME", config.display_name),
 		envAssignment(SPAWN_PROVENANCE_ENV, config.leader.session_id.trim() || config.team_name),
 		...(worker.worktree_path ? [envAssignment("SKC_TEAM_WORKTREE_PATH", worker.worktree_path)] : []),
+		envAssignment(
+			"SKC_TEAM_WORKER_MEMORY_GUARD_PATH",
+			workerMemoryGuardLedgerPath(path.join(config.state_root, config.team_name), worker.id),
+		),
 	];
 	const joined = envLines.join(" ");
 	const clearInheritedSession = config.skc_session_id
@@ -146,6 +154,7 @@ async function initializeStateDirs(
 	runtime: SkcTeamLaunchRuntime,
 	dir: string,
 	workers: SkcTeamWorker[],
+	platform: NodeJS.Platform,
 ): Promise<void> {
 	await fs.mkdir(path.join(dir, "mailbox"), { recursive: true });
 	for (const worker of workers) {
@@ -167,6 +176,14 @@ async function initializeStateDirs(
 			turn_count: 0,
 			alive: true,
 		});
+		await runtime.writeJson(
+			workerMemoryGuardLedgerPath(dir, worker.id),
+			createInitialSkcTeamWorkerMemoryGuardLedger({
+				workerId: worker.id,
+				platform,
+				now: runtime.now(),
+			}),
+		);
 	}
 	await fs.mkdir(runtime.mailboxDirPath(dir, "leader-fixed"), { recursive: true });
 	await runtime.writeJson(runtime.mailboxPath(dir, "leader-fixed"), { messages: [] });
@@ -217,6 +234,18 @@ export async function startSkcTeamLaunch(
 		await runtime.rollbackCreatedWorktrees(workers);
 		throw error;
 	}
+	const tasksByOwner = new Map<string, string[]>();
+	for (const task of initialTasks) {
+		const owner = task.owner?.trim();
+		if (!owner) continue;
+		const assigned = tasksByOwner.get(owner) ?? [];
+		assigned.push(task.id);
+		tasksByOwner.set(owner, assigned);
+	}
+	const workersWithAssignments = workers.map(worker => ({
+		...worker,
+		assigned_tasks: tasksByOwner.get(worker.id) ?? worker.assigned_tasks,
+	}));
 	const config: SkcTeamConfig = {
 		team_name: teamName,
 		display_name: displayName,
@@ -242,11 +271,11 @@ export async function startSkcTeamLaunch(
 		},
 		leader_cwd: cwd,
 		team_state_root: stateRoot,
-		workers,
+		workers: workersWithAssignments,
 		created_at: createdAt,
 		updated_at: createdAt,
 	};
-	await initializeStateDirs(runtime, dir, config.workers);
+	await initializeStateDirs(runtime, dir, config.workers, platform);
 	await runtime.writeJson(path.join(dir, "config.json"), config);
 	await runtime.writeJson(path.join(dir, "manifest.v2.json"), {
 		version: 2,

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

@@ -455,7 +455,32 @@ export interface WorkerHeartbeatFile {
 	last_turn_at: string;
 	turn_count: number;
 	alive: boolean;
+	/** Linux process start time, so a recycled PID cannot impersonate this worker. */
+	process_start_time?: string;
 }
+/**
+ * Linux process start time (field 22 of /proc/<pid>/stat), used to pin a heartbeat
+ * to one specific process. PIDs are recycled, so without this a reaper can match a
+ * stale record against an unrelated process that later took the same PID.
+ * Returns undefined off Linux or when the process is gone.
+ */
+async function readLinuxProcessStartTime(pid: number): Promise<string | undefined> {
+	if (process.platform !== "linux" || !Number.isSafeInteger(pid) || pid <= 0) return undefined;
+	try {
+		const stat = await Bun.file(`/proc/${pid}/stat`).text();
+		const commandEnd = stat.lastIndexOf(")");
+		if (commandEnd < 0) return undefined;
+		const fields = stat
+			.slice(commandEnd + 2)
+			.trim()
+			.split(/\s+/);
+		const startTime = fields[19];
+		return startTime && /^\d+$/.test(startTime) ? startTime : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
 interface GitResult {
 	ok: boolean;
 	stdout: string;
@@ -491,7 +516,7 @@ interface SkcWorkerIntegrationDedupeState {
 
 export interface SkcWorkerIntegrationAttemptRequestResult {
 	requested: boolean;
-	reason: "requested" | "not_worker" | "missing_worktree" | "no_changes" | "deduped" | "git_error";
+	reason: "requested" | "not_worker" | "missing_worktree" | "no_changes" | "deduped" | "git_error" | "cancelled";
 	worker?: string;
 	team_name?: string;
 	fingerprint?: string;
@@ -499,6 +524,12 @@ export interface SkcWorkerIntegrationAttemptRequestResult {
 	status?: SkcWorkerCheckpointClassification["kind"];
 }
 
+/** Caller-supplied controls for a worker integration attempt. */
+export interface SkcWorkerIntegrationAttemptOptions {
+	/** Abort the attempt between its blocking git probes. */
+	signal?: AbortSignal;
+}
+
 function isSkcTeamTaskStatus(value: string): value is SkcTeamTaskStatus {
 	return ["pending", "blocked", "in_progress", "completed", "failed"].includes(value);
 }
@@ -2973,7 +3004,13 @@ function workerIntegrationFingerprint(head: string | null, classification: SkcWo
 export async function requestSkcWorkerIntegrationAttempt(
 	cwd = process.cwd(),
 	env: NodeJS.ProcessEnv = process.env,
+	options: SkcWorkerIntegrationAttemptOptions = {},
 ): Promise<SkcWorkerIntegrationAttemptRequestResult> {
+	// The probes below shell out to git, which can block for a long time on a large
+	// or network-backed worktree. The caller (session shutdown) needs to stop waiting,
+	// so bail at each boundary instead of running to completion regardless.
+	const cancelled = (): SkcWorkerIntegrationAttemptRequestResult => ({ requested: false, reason: "cancelled" });
+	if (options.signal?.aborted) return cancelled();
 	const teamName = env.SKC_TEAM_NAME?.trim();
 	const worker = env.SKC_TEAM_WORKER_ID?.trim() || env.SKC_TEAM_INTERNAL_WORKER?.split("/").pop()?.trim();
 	if (!teamName || !worker) return { requested: false, reason: "not_worker" };
@@ -2983,7 +3020,9 @@ export async function requestSkcWorkerIntegrationAttempt(
 	const worktreePath = env.SKC_TEAM_WORKTREE_PATH?.trim() || configuredWorker?.worktree_path;
 	if (!worktreePath || !(await pathExists(worktreePath)))
 		return { requested: false, reason: "missing_worktree", worker, team_name: teamName };
+	if (options.signal?.aborted) return cancelled();
 	const classification = classifyWorkerCheckpointStatus(worktreePath);
+	if (options.signal?.aborted) return cancelled();
 	const head = resolveHead(worktreePath);
 	if (classification.kind === "git_error") {
 		return { requested: false, reason: "git_error", worker, team_name: teamName, head, status: classification.kind };
@@ -4346,6 +4385,7 @@ export async function executeSkcTeamApiOperation(
 					last_turn_at: now(),
 					turn_count: Number(input.turn_count ?? 0),
 					alive: Boolean(input.alive ?? true),
+					process_start_time: await readLinuxProcessStartTime(Number(input.pid ?? 0)),
 				},
 				cwd,
 				env,

package/src/skc-runtime/team-store.ts

@@ -126,6 +126,38 @@ export interface SkcTeamApiClaimResult {
 	claim_token?: string;
 	reason?: string;
 }
+export type SkcTeamWorkerClaimSelection =
+	| { kind: "none" }
+	| { kind: "exact"; task: SkcTeamTask; claim: SkcTeamTaskClaim }
+	| { kind: "ambiguous"; tasks: SkcTeamTask[] };
+
+export function selectCurrentClaimedTaskForWorker(
+	tasks: readonly SkcTeamTask[],
+	workerId: string,
+): SkcTeamWorkerClaimSelection {
+	const claimed = tasks.filter(
+		task =>
+			task.status === "in_progress" &&
+			task.assignee === workerId &&
+			task.claim?.owner === workerId &&
+			task.owner === workerId,
+	);
+	if (claimed.length === 0) return { kind: "none" };
+	if (claimed.length === 1) {
+		const task = claimed[0]!;
+		return { kind: "exact", task, claim: task.claim! };
+	}
+	return { kind: "ambiguous", tasks: claimed };
+}
+export function findSkcTeamClaimedTaskForWorker(
+	tasks: readonly SkcTeamTask[],
+	workerId: string,
+): SkcTeamTask | undefined {
+	const active = selectCurrentClaimedTaskForWorker(tasks, workerId);
+	if (active.kind === "exact") return active.task;
+	if (active.kind === "ambiguous") return undefined;
+	return tasks.find(task => task.status === "blocked" && task.assignee === workerId && task.claim?.owner === workerId);
+}
 
 type EventAppender = (event: {
 	type: string;