@quantmind-br/pi-goal-x 0.0.0-stage → 0.35.1

package/extensions/storage/goal-lock.ts

@@ -0,0 +1,131 @@
+import { goalStoragePath, ensureGoalStorageDirectory } from "./goal-root.ts";
+/**
+ * Short per-goal filesystem lock (follow-up Stage 4).
+ *
+ * An exclusive lock is acquired through atomic creation of a lock file under
+ * `.pi/goals/.locks/<goalId>.lock` carrying { pid, startedAt } metadata.
+ * Acquisition is bounded: on contention the caller waits briefly and retries,
+ * and stale locks (older than the TTL, or whose pid is no longer alive) are
+ * recovered by removal. The lock serializes cross-process mutations of the
+ * same goal; the optimistic revision check (goal-service.ts) detects stale
+ * writers even when the lock hand-off is fast.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { GoalFileContext } from "./goal-files.ts";
+
+export const GOAL_LOCK_DIR = ".pi/goals/.locks";
+
+export interface GoalLock {
+	release(): void;
+}
+
+// P1-5: strictly bounded acquisition so the main thread never freezes for
+// seconds under cross-process contention. The default window is 8×25ms ≈ 200ms;
+// the persist path passes an even tighter bound (4×25ms ≈ 100ms). A contended
+// write now fails fast with a typed error instead of blocking the TUI for the
+// old 100×25ms ≈ 2.5s worst case; the optimistic revision check (goal-service)
+// is the real guard against concurrent writers.
+//
+// NAF (2026-08-06): the default window drops to 8×1ms ≈ 8ms of sleep (+ the
+// per-attempt staleness check ≈ 8ms) — 10x+ smaller main-thread block under
+// long contention. Brief contention (<10ms) still succeeds; long-held locks
+// fail fast and the caller defers the write (P1-3 turn buffer / persist-skip),
+// so the TUI never freezes on a busy lock.
+const DEFAULT_ACQUIRE_ATTEMPTS = 8;
+const DEFAULT_RETRY_MS = 1;
+const DEFAULT_STALE_TTL_MS = 30_000;
+
+function safeLockName(goalId: string): string {
+	return goalId.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+
+function pidAlive(pid: number): boolean {
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		return (err as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+function readLockPayload(lockPath: string): { pid?: number; startedAt?: string } {
+	try {
+		const raw = JSON.parse(fs.readFileSync(lockPath, "utf8")) as Record<string, unknown>;
+		return {
+			pid: typeof raw.pid === "number" ? raw.pid : undefined,
+			startedAt: typeof raw.startedAt === "string" ? raw.startedAt : undefined,
+		};
+	} catch {
+		// Unparseable payload means a writer crashed mid-create: treat as stale.
+		return {};
+	}
+}
+
+function sleepMs(ms: number): void {
+	// Synchronous bounded wait (Atomics.wait is legal on the main thread and
+	// does not burn CPU like a spin loop).
+	const buffer = new Int32Array(new SharedArrayBuffer(4));
+	Atomics.wait(buffer, 0, 0, ms);
+}
+
+/**
+ * Acquire the exclusive per-goal lock. Throws after the bounded attempt window
+ * if a live writer never releases it. The caller MUST release() the returned
+ * lock (use a finally block).
+ */
+export function acquireGoalLock(
+	ctx: GoalFileContext,
+	goalId: string,
+	opts: { attempts?: number; retryMs?: number; staleTtlMs?: number } = {},
+): GoalLock {
+	const attempts = opts.attempts ?? DEFAULT_ACQUIRE_ATTEMPTS;
+	const retryMs = opts.retryMs ?? DEFAULT_RETRY_MS;
+	const ttlMs = opts.staleTtlMs ?? DEFAULT_STALE_TTL_MS;
+	const lockDir = goalStoragePath(ctx, GOAL_LOCK_DIR);
+	const lockPath = path.join(lockDir, `${safeLockName(goalId)}.lock`);
+	ensureGoalStorageDirectory(ctx, GOAL_LOCK_DIR, false);
+	const payload = JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() });
+
+	for (let attempt = 0; attempt < attempts; attempt++) {
+		try {
+			fs.writeFileSync(lockPath, payload, { flag: "wx" });
+			let released = false;
+			return {
+				release(): void {
+					if (released) return;
+					released = true;
+					try {
+						fs.unlinkSync(lockPath);
+					} catch {
+						// Lock already gone (stale recovery elsewhere); nothing to do.
+					}
+				},
+			};
+		} catch (err) {
+			if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+			// Bounded stale-lock recovery.
+			try {
+				const stat = fs.statSync(lockPath);
+				const payloadInfo = readLockPayload(lockPath);
+				const pid = payloadInfo.pid;
+				const stale = Date.now() - stat.mtimeMs > ttlMs || (pid !== undefined && !pidAlive(pid));
+				if (stale) {
+					try {
+						fs.unlinkSync(lockPath);
+					} catch {
+						// Someone else recovered it first; retry acquisition.
+					}
+					continue;
+				}
+			} catch {
+				// Lock vanished between stat and read (holder released): retry.
+				continue;
+			}
+			sleepMs(retryMs);
+		}
+	}
+	throw new Error(`Timed out acquiring the goal lock for ${goalId} (${attempts} attempts). Another writer may hold it.`);
+}

package/extensions/storage/goal-root.ts

@@ -0,0 +1,95 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { loadSettingsSnapshot } from "../goal-settings.ts";
+
+export interface GoalStorageContext {
+	cwd: string;
+	/** Plain snapshot for deferred readers; never capture an ExtensionContext. */
+	goalStorageRoot?: string;
+	sessionManager?: { getSessionId(): string | undefined };
+}
+
+// Host contexts change between hooks; the session manager owns their lifetime.
+const roots = new WeakMap<object, { id: string | undefined; cwd: string; root: string }>();
+
+export function goalStorageRoot(ctx: GoalStorageContext): string {
+	if (ctx.goalStorageRoot !== undefined) return ctx.goalStorageRoot;
+	// Low-level cwd-only callers retain the original zero-settings-I/O contract.
+	// Host sessions resolve configuration once; detached readers take a snapshot.
+	return ctx.sessionManager ? configuredGoalRoot(ctx) : path.resolve(ctx.cwd, ".pi/goals");
+}
+
+function configuredGoalRoot(ctx: GoalStorageContext): string {
+	if (ctx.goalStorageRoot !== undefined) return ctx.goalStorageRoot;
+	const manager = ctx.sessionManager;
+	const id = manager?.getSessionId();
+	const key = manager ?? ctx;
+	const pinned = roots.get(key);
+	if (pinned && pinned.id === id && pinned.cwd === ctx.cwd) return pinned.root;
+	const settings = loadSettingsSnapshot(ctx.cwd);
+	const source = settings.provenance.get("goalsRoot")?.source;
+	const invalid = settings.diagnostics.find(d => d.settingPath === "goalsRoot" && source !== "environment" && (d.scope === "project" || source !== "project"));
+	if (invalid) throw new Error(`Invalid goalsRoot: ${invalid.message}`);
+	const configured = settings.value.goalsRoot;
+	let root = path.resolve(ctx.cwd, ".pi/goals");
+	if (configured !== undefined) {
+		const expanded = configured === "~" ? os.homedir() : configured.startsWith("~/") ? path.join(os.homedir(), configured.slice(2)) : configured;
+		if (!path.isAbsolute(expanded) || expanded.includes("\0")) throw new Error("goalsRoot / PI_GOAL_ROOT must be an absolute path or ~/path; reload after correcting it.");
+		root = path.normalize(expanded);
+		fs.mkdirSync(root, { recursive: true });
+		if (fs.lstatSync(root).isSymbolicLink()) throw new Error(`Goal root is a symlink: ${root}`);
+		root = fs.realpathSync(root);
+		// Metadata lives inside an override without perturbing the pool's mtime.
+		const metadata = path.join(root, ".metadata");
+		fs.mkdirSync(metadata, { recursive: true });
+		if (fs.lstatSync(metadata).isSymbolicLink()) throw new Error(`Goal metadata directory is a symlink: ${metadata}`);
+	}
+	roots.set(key, { id, cwd: ctx.cwd, root });
+	return root;
+}
+
+export function goalStorageContext(ctx: GoalStorageContext): GoalStorageContext {
+	return { cwd: ctx.cwd, goalStorageRoot: configuredGoalRoot(ctx) };
+}
+
+/** Logical paths stay compatible in saved goal files, independent of pool location. */
+export function goalStoragePath(ctx: GoalStorageContext, logical: string): string {
+	const relative = logical.replace(/\\/g, "/");
+	if (relative !== ".pi/goals" && !relative.startsWith(".pi/goals/")) throw new Error(`Invalid goal storage path: ${logical}`);
+	const root = goalStorageRoot(ctx);
+	const result = path.resolve(root, relative.slice(".pi/goals".length + 1));
+	const inside = path.relative(root, result);
+	if (inside === ".." || inside.startsWith(`..${path.sep}`) || path.isAbsolute(inside)) throw new Error(`Goal path escapes root: ${logical}`);
+	return result;
+}
+
+export function isExternalGoalStorage(ctx: GoalStorageContext): boolean {
+	return goalStorageRoot(ctx) !== path.resolve(ctx.cwd, ".pi/goals");
+}
+
+export function goalPoolSnapshotPath(ctx: GoalStorageContext): string {
+	const root = goalStorageRoot(ctx);
+	return root === path.resolve(ctx.cwd, ".pi/goals")
+		? path.join(path.dirname(root), ".goals-pool-snapshot.json")
+		: path.join(root, ".metadata", ".goals-pool-snapshot.json");
+}
+
+/** Validate managed ancestors on writes, without adding I/O to steady-state reads. */
+export function ensureGoalStorageDirectory(ctx: GoalStorageContext, logical: string, verifyDefault = true): void {
+	const root = goalStorageRoot(ctx);
+	const target = goalStoragePath(ctx, logical);
+	if (root === path.resolve(ctx.cwd, ".pi/goals")) {
+		fs.mkdirSync(target, { recursive: true });
+		if (verifyDefault && fs.lstatSync(target).isSymbolicLink()) throw new Error(`Goal directory is a symlink: ${target}`);
+		return;
+	}
+	// An external pool removed during a session must not silently reappear.
+	if (fs.lstatSync(root).isSymbolicLink()) throw new Error(`Goal root is a symlink: ${root}`);
+	let dir = root;
+	for (const part of path.relative(root, target).split(path.sep).filter(Boolean)) {
+		dir = path.join(dir, part);
+		try { fs.mkdirSync(dir); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
+		if (fs.lstatSync(dir).isSymbolicLink()) throw new Error(`Goal directory is a symlink: ${dir}`);
+	}
+}

package/extensions/widgets/auditor-dashboard-model.ts

@@ -0,0 +1,174 @@
+/**
+ * Structured audit dashboard model (plan §15).
+ *
+ * Pure derivation from the low-level auditor progress stream: five check
+ * stages (objective, verification, tasks, workspace, decision) with explicit
+ * pending/running/passed/failed states, plus the approval/rejection result
+ * card model. No TUI imports; the renderer and /goal-status share this model.
+ */
+
+import type { AuditorProgress } from "../goal-auditor.ts";
+import { formatDashboardDuration } from "./goal-dashboard-model.ts";
+
+export type AuditCheckState = "pending" | "running" | "passed" | "failed";
+
+export type AuditCheckId = "objective" | "verification" | "tasks" | "workspace" | "decision";
+
+export interface AuditCheck {
+	id: AuditCheckId;
+	label: string;
+	state: AuditCheckState;
+	detail?: string;
+}
+
+export type AuditVerdict = "approved" | "disapproved" | "error";
+
+export interface AuditorDashboardModel {
+	auditorLabel: string;
+	elapsedMs: number;
+	percentage?: number;
+	checks: AuditCheck[];
+	currentTool?: string;
+	currentToolArgs?: string;
+	recentOutput: string[];
+	/** Result verdict when the audit finished (drives the result card). */
+	verdict?: AuditVerdict | null;
+	/** Whether the audit session is still running (false when phase === done). */
+	active: boolean;
+}
+
+export interface AuditResultCard {
+	verdict: AuditVerdict;
+	label: string;
+	lines: string[];
+}
+
+const CHECK_LABELS: Array<{ id: AuditCheckId; label: string }> = [
+	{ id: "objective", label: "Objective and success criteria" },
+	{ id: "verification", label: "Verification contracts" },
+	{ id: "tasks", label: "Tasks and recorded evidence" },
+	{ id: "workspace", label: "Workspace inspection" },
+	{ id: "decision", label: "Final decision" },
+];
+
+export interface DeriveAuditorDashboardOptions {
+	auditorLabel?: string;
+	/** Result verdict when known (set after the audit session finishes). */
+	verdict?: AuditVerdict | null;
+}
+
+/**
+ * Derive the structured audit dashboard from the raw progress stream (§15.2).
+ *
+ * Active audit: checks advance through percentage bands (objective ≥20%,
+ * verification ≥40%, tasks ≥60%, workspace ≥80%, decision ≥80%) so the five
+ * stages light up in order. Finished audit: all checks pass except decision,
+ * which follows the verdict (approved → passed; disapproved/error → failed).
+ */
+export function deriveAuditorDashboardModel(
+	progress: AuditorProgress,
+	options: DeriveAuditorDashboardOptions = {},
+): AuditorDashboardModel {
+	const pct = clampPercentage(progress.percentage);
+	const done = progress.phase === "done";
+	const verdict = options.verdict !== undefined ? options.verdict : null;
+
+	const checks: AuditCheck[] = CHECK_LABELS.map(({ id, label }) => {
+		if (!done) {
+			const state = checkStateActive(id, pct);
+			return { id, label, state };
+		}
+		if (id === "decision") {
+			const state: AuditCheckState = verdict === "approved" ? "passed" : verdict === "disapproved" || verdict === "error" ? "failed" : "passed";
+			return { id, label, state };
+		}
+		return { id, label, state: "passed" };
+	});
+
+	return {
+		auditorLabel: options.auditorLabel ?? progress.label ?? "Independent completion audit",
+		elapsedMs: progress.elapsedMs,
+		...(progress.percentage !== undefined ? { percentage: pct } : {}),
+		checks,
+		currentTool: progress.currentTool,
+		currentToolArgs: progress.currentToolArgs,
+		recentOutput: progress.recentOutput,
+		...(verdict ? { verdict } : {}),
+		active: !done,
+	};
+}
+
+function checkStateActive(id: AuditCheckId, pct: number): AuditCheckState {
+	switch (id) {
+		case "objective":
+			return pct >= 20 ? "passed" : "running";
+		case "verification":
+			return pct >= 40 ? "passed" : pct >= 20 ? "running" : "pending";
+		case "tasks":
+			return pct >= 60 ? "passed" : pct >= 40 ? "running" : "pending";
+		case "workspace":
+			return pct >= 80 ? "passed" : pct >= 60 ? "running" : "pending";
+		case "decision":
+			return pct >= 80 ? "running" : "pending";
+	}
+}
+
+function clampPercentage(value: number | undefined): number {
+	if (value === undefined) return 0;
+	return Math.min(100, Math.max(0, Math.round(value)));
+}
+
+/** Human duration label for the audit header (reused formatter). */
+export function formatAuditElapsed(elapsedMs: number): string {
+	return formatDashboardDuration(Math.floor(elapsedMs / 1000));
+}
+
+/**
+ * Build the result card (§15.4). Approval shows the fixed acceptance lines;
+ * rejection extracts concise findings from the auditor report (bullet-style or
+ * the leading non-marker lines, capped at three); errors state the failure.
+ */
+export function deriveAuditResultCard(verdict: AuditVerdict, report: string): AuditResultCard {
+	if (verdict === "approved") {
+		return {
+			verdict,
+			label: "APPROVED",
+			lines: ["Objective satisfied.", "Verification requirements satisfied.", "Required tasks and evidence accepted."],
+		};
+	}
+	if (verdict === "error") {
+		return {
+			verdict,
+			label: "ERROR",
+			lines: [report.trim() ? oneLine(report) : "The auditor could not finish the review."],
+		};
+	}
+	const findings = extractFindings(report);
+	return {
+		verdict,
+		label: "CHANGES REQUIRED",
+		lines: findings.length > 0 ? findings : [oneLine(report) || "The auditor requested changes — review the report."],
+	};
+}
+
+function extractFindings(report: string): string[] {
+	const lines = report.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+	const findings: string[] = [];
+	for (const line of lines) {
+		if (/^<(approved|disapproved)\s*\/>/.test(line)) continue;
+		const cleaned = line.replace(/^[-*•✗✓]\s*/, "").replace(/^(\d+[.)])\s*/, "").trim();
+		if (!cleaned) continue;
+		// Skip section headers ("Audit report:", "Findings:") and generic
+		// "Auditor: ..." attribution lines — they are not findings.
+		if (/^auditor\s*:/i.test(cleaned)) continue;
+		if (/^[a-z][a-z ]{0,24}:$/i.test(cleaned)) continue;
+		if (cleaned.length > 200) findings.push(`${cleaned.slice(0, 197)}...`);
+		else findings.push(cleaned);
+		if (findings.length >= 3) break;
+	}
+	return findings;
+}
+
+function oneLine(value: string): string {
+	return value.replace(/\s+/g, " ").trim();
+}

package/extensions/widgets/dialog-scaffold.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared bordered-dialog scaffold (P1-11): the line/horiz/inner-width helpers
+ * were copy-pasted across the escape dialog, the task-list confirmation
+ * dialog, and the task-list overlay. Collapsed here with byte-identical
+ * output; the renderers above these helpers keep their own headers, options,
+ * and footers.
+ */
+
+import { visibleWidth } from "@earendil-works/pi-tui";
+
+/** Inner content width between the ││ borders for a dialog at termWidth. */
+export function dialogInnerWidth(termWidth: number, maxInner = 64): number {
+	return Math.min(termWidth, maxInner) - 2;
+}
+
+/** One bordered line: exactly innerWidth visible chars between ││. */
+export function borderedLine(accent: (s: string) => string, innerWidth: number, content: string): string {
+	const vis = visibleWidth(content);
+	const fill = innerWidth - vis;
+	return accent("│") + content + (fill > 0 ? " ".repeat(fill) : "") + accent("│");
+}
+
+/** The ── run used by ┌/├/└ borders. */
+export function horizontalRule(innerWidth: number): string {
+	return "─".repeat(innerWidth);
+}