pi-plans 0.3.2 → 0.3.3

package/src/run-context.ts

@@ -0,0 +1,97 @@
+/**
+ * Session-bound run attribution (I-002).
+ *
+ * The shared `active.json` pointer is repo-wide and races across sessions
+ * and linked worktrees. This module keeps the CURRENT session's run binding
+ * (keyed by the SessionManager identity so it never leaks across session
+ * replacement) and resolves "the run this session is working on" with the
+ * binding first, falling back to the shared pointer for sessions that never
+ * bound a run (legacy behavior).
+ */
+
+import * as path from "node:path";
+import { getRun, readActive, runDirPath, type ActiveInfo } from "./state.ts";
+
+interface RunBinding {
+	runId: string;
+	workdir: string;
+	/** SessionManager identity — stable within one session, replaced on /new, /resume, /fork. */
+	session: unknown;
+}
+
+let binding: RunBinding | null = null;
+
+/** Bind this session to a run. Called on start-run, execution start, and /resume-plans. */
+export function bindRun(session: unknown, workdir: string, runId: string): void {
+	binding = { runId, workdir: path.resolve(workdir), session };
+}
+
+/** Clear the binding (only the session that owns it may clear it). */
+export function clearRunBinding(session: unknown): void {
+	if (binding?.session === session) binding = null;
+}
+
+/** The run id bound to THIS session for THIS workdir, or null. */
+export function boundRunId(session: unknown, workdir: string): string | null {
+	if (binding === null) return null;
+	if (binding.session !== session) return null;
+	if (path.resolve(binding.workdir) !== path.resolve(workdir)) return null;
+	return binding.runId;
+}
+
+/** Test isolation: drop any binding without a session identity check. */
+export function resetRunBindingForTests(): void {
+	binding = null;
+}
+
+/** Resolve full ActiveInfo for an explicit run id; null when the run does not exist. */
+export function activeInfoById(workdir: string, runId: string): ActiveInfo | null {
+	const runDir = runDirPath(workdir, runId);
+	if (runDir === null) return null; // bound run vanished: fall back to the shared pointer
+	const run = getRun(workdir, runId);
+	if (run === null) return null;
+	return { run_id: runId, run_dir: runDir, artifact_dir: run.artifact_dir };
+}
+
+/**
+ * Resolve the run this session should attribute work to. A session-bound
+ * run always wins; sessions without a binding keep the legacy
+ * shared-pointer behavior.
+ */
+export function resolveActiveRun(session: unknown, workdir: string): ActiveInfo | null {
+	if (session !== undefined && session !== null) {
+		const runId = boundRunId(session, workdir);
+		if (runId !== null) {
+			const bound = activeInfoById(workdir, runId);
+			if (bound !== null) return bound;
+		}
+	}
+	return readActive(workdir);
+}
+
+/** Entry shape accepted by {@link restoreRunBindingFromSession}. */
+export interface RunStartEntryLike {
+	type: string;
+	customType?: string;
+	data?: { runId?: unknown };
+}
+
+/**
+ * Restore the session's run binding from `pi-plans-run-start` entries on the
+ * current branch (the same pattern autocomplete restore uses). Only entries
+ * on the current branch count — abandoned branches must not steal
+ * attribution.
+ */
+export function restoreRunBindingFromSession(session: unknown, workdir: string, entries: RunStartEntryLike[]): string | null {
+	let lastRunId: string | null = null;
+	for (const entry of entries) {
+		if (entry.type === "custom" && entry.customType === "pi-plans-run-start") {
+			const runId = entry.data?.runId;
+			if (typeof runId === "string" && runId !== "") lastRunId = runId;
+		}
+	}
+	if (lastRunId === null) return null;
+	if (runDirPath(workdir, lastRunId) === null) return null; // run deleted since
+	bindRun(session, workdir, lastRunId);
+	return lastRunId;
+}

package/src/run-ownership.ts

@@ -0,0 +1,310 @@
+/**
+ * Run activity ownership (I-002).
+ *
+ * At most one live owner per run. An owner record carries host, pid, the
+ * process start time (PID-reuse guard), the Pi session id, a random process
+ * token, and a generation counter. Acquisition is atomic (O_EXCL create);
+ * takeovers require proof the previous owner is dead — process gone, or the
+ * pid alive but with a different start time (reused pid). Unknown hosts,
+ * corrupt records, and unverifiable liveness are conservatively refused.
+ */
+
+import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import {
+	closeSync,
+	existsSync,
+	mkdirSync,
+	openSync,
+	readFileSync,
+	renameSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { StateError, runDirPath, utcNow } from "./state.ts";
+
+export const OWNER_SCHEMA = 1;
+
+export interface OwnerRecord {
+	schema: number;
+	host: string;
+	pid: number;
+	/** `ps -o lstart=` output; null when unresolvable. Mismatch vs a live pid means reuse. */
+	pidStart: string | null;
+	sessionId: string | null;
+	processToken: string;
+	generation: number;
+	acquiredAt: string;
+}
+
+export class OwnershipError extends StateError {}
+
+/** Records this process currently holds: runKey → owner. */
+const held = new Map<string, OwnerRecord>();
+
+function runKey(workdir: string, runId: string): string {
+	return `${path.resolve(workdir)}::${runId}`;
+}
+
+function ownerFilePath(workdir: string, runId: string): string | null {
+	const runDir = runDirPath(workdir, runId);
+	return runDir === null ? null : path.join(runDir, "owner.json");
+}
+
+function validateOwnerRecord(data: unknown, label: string): OwnerRecord {
+	if (data === null || typeof data !== "object" || Array.isArray(data)) {
+		throw new OwnershipError(`${label}: expected an object`);
+	}
+	const record = data as Record<string, unknown>;
+	const allowed = new Set(["schema", "host", "pid", "pidStart", "sessionId", "processToken", "generation", "acquiredAt"]);
+	for (const key of Object.keys(record)) {
+		if (!allowed.has(key)) throw new OwnershipError(`${label}: unexpected key "${key}"`);
+	}
+	if (record.schema !== OWNER_SCHEMA) {
+		throw new OwnershipError(`${label}.schema: unsupported version ${String(record.schema)}`);
+	}
+	if (typeof record.host !== "string" || record.host === "") throw new OwnershipError(`${label}.host: expected a non-empty string`);
+	if (typeof record.pid !== "number" || !Number.isSafeInteger(record.pid) || record.pid < 1) {
+		throw new OwnershipError(`${label}.pid: expected a positive integer`);
+	}
+	if (record.pidStart !== null && typeof record.pidStart !== "string") {
+		throw new OwnershipError(`${label}.pidStart: expected a string or null`);
+	}
+	if (typeof record.processToken !== "string" || record.processToken === "") {
+		throw new OwnershipError(`${label}.processToken: expected a non-empty string`);
+	}
+	if (typeof record.generation !== "number" || !Number.isSafeInteger(record.generation) || record.generation < 1) {
+		throw new OwnershipError(`${label}.generation: expected a positive integer`);
+	}
+	if (typeof record.acquiredAt !== "string") throw new OwnershipError(`${label}.acquiredAt: expected a string`);
+	return {
+		schema: OWNER_SCHEMA,
+		host: record.host,
+		pid: record.pid,
+		pidStart: (record.pidStart as string | null) ?? null,
+		sessionId: (record.sessionId as string | null) ?? null,
+		processToken: record.processToken,
+		generation: record.generation,
+		acquiredAt: record.acquiredAt,
+	};
+}
+
+function readOwnerFile(filePath: string): OwnerRecord {
+	let data: unknown;
+	try {
+		data = JSON.parse(readFileSync(filePath, "utf8"));
+	} catch (error) {
+		throw new OwnershipError(`owner record ${filePath} is corrupt (${(error as Error).message}); repair or remove it explicitly`);
+	}
+	return validateOwnerRecord(data, "owner record");
+}
+
+function writeOwnerFile(filePath: string, record: OwnerRecord): void {
+	mkdirSync(path.dirname(filePath), { recursive: true });
+	const tmp = `${filePath}.tmp`;
+	writeFileSync(tmp, `${JSON.stringify(record, null, "\t")}\n`, "utf8");
+	renameSync(tmp, filePath);
+}
+
+/** Process start time via `ps -o lstart=`; null when unresolvable. */
+export function processStartOf(pid: number): string | null {
+	try {
+		const result = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8", timeout: 5000 });
+		if (result.error || result.status !== 0) return null;
+		const start = (result.stdout ?? "").trim();
+		return start === "" ? null : start;
+	} catch {
+		return null;
+	}
+}
+
+function processAlive(pid: number, pidStart: string | null): boolean {
+	try {
+		process.kill(pid, 0);
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (code === "ESRCH") return false;
+		return true; // EPERM etc.: exists but not ours
+	}
+	if (pidStart === null) return true; // alive, start unverifiable
+	// F-006 (implementation review): a live pid whose CURRENT start time cannot
+	// be resolved (ps missing/failing) is conservatively ALIVE — never steal.
+	const currentStart = processStartOf(pid);
+	if (currentStart === null) return true;
+	return currentStart === pidStart; // mismatch = reused pid = dead owner
+}
+
+export interface AcquireOptions {
+	sessionId?: string | null;
+}
+
+/**
+ * Acquire (or keep) ownership of a run for this process. Re-acquiring a run
+ * this process already holds returns the existing record. A live foreign
+ * owner, a foreign host, or a corrupt record is refused.
+ */
+export function acquireOwnership(workdir: string, runId: string, options: AcquireOptions = {}): OwnerRecord {
+	const key = runKey(workdir, runId);
+	const alreadyHeld = held.get(key);
+	if (alreadyHeld) {
+		// Keep the token; refresh nothing — liveness is checked on demand.
+		return alreadyHeld;
+	}
+	const filePath = ownerFilePath(workdir, runId);
+	if (filePath === null) throw new OwnershipError(`run does not exist: ${runId}`);
+	mkdirSync(path.dirname(filePath), { recursive: true });
+	const candidate: OwnerRecord = {
+		schema: OWNER_SCHEMA,
+		host: os.hostname(),
+		pid: process.pid,
+		pidStart: processStartOf(process.pid),
+		sessionId: options.sessionId ?? null,
+		processToken: randomUUID().replace(/-/g, ""),
+		generation: 1,
+		acquiredAt: utcNow(),
+	};
+	// Fast path: exclusive create when no owner exists yet.
+	try {
+		const fd = openSync(filePath, "wx");
+		writeFileSync(fd, `${JSON.stringify(candidate, null, "\t")}\n`, "utf8");
+		closeSync(fd);
+		held.set(key, candidate);
+		return candidate;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+	}
+	// Someone owns it. Same live process re-entering (e.g. extension reload
+	// dropped the in-memory map): adopt the existing record when pid+start
+	// match, keeping generation continuity.
+	const existing = readOwnerFile(filePath);
+	if (existing.host === candidate.host && existing.pid === candidate.pid && existing.pidStart === candidate.pidStart) {
+		held.set(key, existing);
+		return existing;
+	}
+	if (existing.host !== candidate.host) {
+		throw new OwnershipError(
+			`run ${runId} is owned by host "${existing.host}"; cross-host liveness cannot be verified — refusing`,
+		);
+	}
+	if (processAlive(existing.pid, existing.pidStart)) {
+		throw new OwnershipError(
+			`run ${runId} is actively owned by pid ${existing.pid} (generation ${existing.generation}); refusing to steal`,
+		);
+	}
+	// Provably dead previous owner: guarded takeover.
+	takeoverWithLock(filePath, workdir, runId, existing, candidate, options);
+	const next = readOwnerFile(filePath);
+	held.set(key, next);
+	return next;
+}
+
+function takeoverWithLock(
+	filePath: string,
+	workdir: string,
+	runId: string,
+	expected: OwnerRecord,
+	candidate: OwnerRecord,
+	options: AcquireOptions,
+): void {
+	const lockPath = `${filePath}.lock`;
+	for (let attempt = 0; attempt < 3; attempt++) {
+		try {
+			const fd = openSync(lockPath, "wx");
+			closeSync(fd);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+			// Stale-lock sweep: a lock whose creator is gone cannot deadlock us.
+			try {
+				const lock = JSON.parse(readFileSync(lockPath, "utf8")) as { pid?: number };
+				if (typeof lock.pid === "number" && !processAlive(lock.pid, null)) unlinkSync(lockPath);
+			} catch {
+				/* unreadable lock: wait and retry */
+			}
+			const snooze = spawnSync("sleep", ["0.05"], { encoding: "utf8" });
+			if (snooze.error) break;
+			continue;
+		}
+		try {
+			// Re-validate under the lock: the world may have moved.
+			const current = readOwnerFile(filePath);
+			if (current.processToken !== expected.processToken) {
+				throw new OwnershipError(`run ${runId} changed owners during takeover; retry acquire`);
+			}
+			if (processAlive(current.pid, current.pidStart)) {
+				throw new OwnershipError(`run ${runId} owner pid ${current.pid} is alive again; refusing to steal`);
+			}
+			const next: OwnerRecord = {
+				...candidate,
+				sessionId: options.sessionId ?? null,
+				generation: current.generation + 1,
+			};
+			writeOwnerFile(filePath, next);
+			writeFileSync(lockPath, `${JSON.stringify({ pid: process.pid, takenAt: utcNow() })}\n`, "utf8");
+		} finally {
+			try {
+				unlinkSync(lockPath);
+			} catch {
+				/* best-effort */
+			}
+		}
+		return;
+	}
+	throw new OwnershipError(`run ${runId}: could not acquire the takeover lock; another takeover is in flight`);
+}
+
+/** Current owner record without acquiring; null when unowned. Corrupt records throw. */
+export function ownershipRecord(workdir: string, runId: string): OwnerRecord | null {
+	const filePath = ownerFilePath(workdir, runId);
+	if (filePath === null || !existsSync(filePath)) return null;
+	return readOwnerFile(filePath);
+}
+
+/** True when a live owner holds the run right now. */
+export function ownershipHeld(workdir: string, runId: string): boolean {
+	const record = ownershipRecord(workdir, runId);
+	if (record === null) return false;
+	return processAlive(record.pid, record.pidStart);
+}
+
+/** Fail when this session no longer owns the run (takeover or release happened). */
+export function assertOwnership(workdir: string, runId: string, expected: { processToken: string; generation: number }): void {
+	const filePath = ownerFilePath(workdir, runId);
+	if (filePath === null || !existsSync(filePath)) {
+		throw new OwnershipError(`run ${runId} has no owner record; ownership was released`);
+	}
+	const record = readOwnerFile(filePath);
+	if (record.processToken !== expected.processToken || record.generation !== expected.generation) {
+		throw new OwnershipError(
+			`ownership of ${runId} moved (generation ${expected.generation} → ${record.generation}); this session no longer owns the run`,
+		);
+	}
+}
+
+/** Release ownership; only the matching token may remove the record. */
+export function releaseOwnership(workdir: string, runId: string, processToken: string): boolean {
+	const key = runKey(workdir, runId);
+	const filePath = ownerFilePath(workdir, runId);
+	if (filePath === null) return false;
+	held.delete(key);
+	if (!existsSync(filePath)) return false;
+	const record = readOwnerFile(filePath);
+	if (record.processToken !== processToken) return false;
+	try {
+		unlinkSync(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** Records held by this process (test/inspection helper). */
+export function heldOwnershipKeys(): string[] {
+	return [...held.keys()];
+}
+
+/** The owner record this process currently holds for a run, if any (F-005). */
+export function heldOwnershipRecord(workdir: string, runId: string): OwnerRecord | null {
+	return held.get(runKey(workdir, runId)) ?? null;
+}

package/src/state.ts

@@ -130,6 +130,8 @@ export interface DecisionEntry {
 	answer: string;
 	answer_source: "user" | "auto-complete";
 	artifact?: string;
+	/** Stable question id when the ask_choice call carried one (F-005 reconcile). */
+	questionId?: string;
 	recorded_at: string;
 }
 
@@ -247,7 +249,7 @@ export function resolveStateRootOrNull(workdir: string): string | null {
 // Config helpers
 // ---------------------------------------------------------------------------
 
-function atomicWriteJson(filePath: string, data: unknown): void {
+export function atomicWriteJson(filePath: string, data: unknown): void {
 	fs.mkdirSync(path.dirname(filePath), { recursive: true });
 	const tmp = `${filePath}.tmp`;
 	writeFileSync(tmp, `${JSON.stringify(data, null, "\t")}\n`, "utf8");
@@ -500,6 +502,14 @@ function requireRunDir(workdir: string, runId: string): string {
 	return runDir;
 }
 
+/** Read-only run directory resolution; returns null when the run does not exist. */
+export function runDirPath(workdir: string, runId: string): string | null {
+	const stateRoot = resolveStateRootOrNull(workdir);
+	if (stateRoot === null) return null;
+	const runDir = path.join(stateRoot, "runs", runId);
+	return existsSync(runDir) ? runDir : null;
+}
+
 export function recordDecision(workdir: string, runId: string, entry: Omit<DecisionEntry, "recorded_at">): DecisionEntry {
 	const runDir = requireRunDir(workdir, runId);
 	const full: DecisionEntry = { ...entry, recorded_at: utcNow() };
@@ -521,6 +531,19 @@ export function recordSubagent(workdir: string, runId: string, entry: Omit<Subag
 	return full;
 }
 
+/** Update a run's recorded workdir (cross-worktree migration, D-007). */
+export function updateRunWorkdir(workdir: string, runId: string, newWorkdir: string): RunInfo {
+	const stateRoot = resolveStateRootOrNull(workdir);
+	if (stateRoot === null) throw new StateError("no pi-plans state found; run init first");
+	const runPath = path.join(stateRoot, "runs", runId, "run.json");
+	if (!existsSync(runPath)) throw new StateError(`run does not exist: ${runId}`);
+	const run = JSON.parse(readFileSync(runPath, "utf8")) as RunInfo;
+	run.workdir = path.resolve(newWorkdir);
+	run.updated_at = utcNow();
+	atomicWriteJson(runPath, run);
+	return run;
+}
+
 export function setRunStatus(workdir: string, runId: string, status: string): RunInfo {
 	if (!VALID_RUN_STATUSES.has(status)) {
 		throw new StateError(`status must be one of ${[...VALID_RUN_STATUSES].join(", ")}`);

package/src/termination-prompt.ts

@@ -20,3 +20,11 @@ export const TERMINATION_OPTIONS = [
 export function renderTerminationOptions(): string {
 	return TERMINATION_OPTIONS.map((option, index) => `${index + 1}. ${option}`).join("  ");
 }
+
+/** Stable question id for the termination question so cross-session resume
+ * can deduplicate it and link the answer to the checkpoint (I-004). */
+export const TERMINATION_QUESTION_ID = "termination-condition";
+
+/** Instruction appended wherever the termination question is requested. */
+export const TERMINATION_RECORDING_INSTRUCTIONS =
+	'Ask it with ask_choice using questionId: "termination-condition" (autoComplete: false). After the user answers, persist the loop configuration: plans record-checkpoint (checkpoint: { transition: "implementation-review-configured", terminationCondition: "<the chosen option>" }).';