pi-goal-x 0.26.2 → 0.26.3

package/README.md

@@ -177,6 +177,12 @@ Show the focused goal:
 /goal-status
 ```
 
+Run read-only storage/runtime health checks:
+
+```text
+/goal-status health
+```
+
 Select an open goal for the current session:
 
 ```text
@@ -341,6 +347,7 @@ Each session can focus on one goal while the project keeps other goals open.
 /goal-list                   List open goals
 /goal-status                 Show the focused goal (unified dashboard)
 /goal-status verbose         Show the focused goal with full diagnostic detail
+/goal-status health          Check goal storage/runtime health (read-only)
 /goal-focus                  Select an open goal
 /goal-unfocus                Remove the session’s focus
 /goal-tweak <change>         Revise the focused goal

package/docs/agent-flow-design.md

@@ -99,7 +99,7 @@ The curated fourteen-command palette:
 | `/goal-direct <objective>` | Direct regular-goal creation without drafting |
 | `/sisyphus-direct <objective>` | Direct Sisyphus creation without drafting |
 | `/goal-list` | List all open goals and the current focus |
-| `/goal-status` | Read-only focused-goal summary plus other-open-goal count |
+| `/goal-status` | Read-only focused-goal summary plus other-open-goal count; append `verbose` for diagnostics or `health` for storage/runtime checks |
 | `/goal-focus` | Choose this session's focused goal |
 | `/goal-unfocus` | Detach the session without modifying the shared goal |
 | `/goal-settings` | Fully operable settings editor for all eight persisted fields |

package/docs/architecture.md

@@ -182,6 +182,7 @@ user confirms.
 - `/sisyphus [seed]` starts a Sisyphus guided draft.
 - `/goal-direct <objective>` and `/sisyphus-direct <objective>` create directly without drafting.
 - `/goal-list` prints all open goals with id, status, mode, usage, objective title, path, and a focus marker.
+- `/goal-status health` performs a read-only coherence check for focus, lifecycle, goal-file presence, malformed ledger entries, task progress, and token-budget pressure; it never acts as a completion verdict.
 - `/goal-focus` uses `ctx.ui.select` when multiple goals are open and updates only session focus.
 - `/goal-unfocus` writes a null session focus entry, clears continuation/runtime state, aborts in-flight work and audits for that session, and leaves the shared active goal file and project-global focus ledger unchanged. Focus revision tokens prevent pending completion and task-list results from mutating a goal after detachment.
 - `/goal-resume` resumes the focused paused goal; when unfocused with multiple open goals, it asks the user to choose. Choosing an already active goal only focuses it.

package/extensions/goal-commands.ts

@@ -1,3 +1,5 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { extractVerificationContract, sisyphusObjectiveSufficient } from "./goal-contract.ts";
 import { detailedSummary, oneLineSummary } from "./goal-format.ts";
@@ -161,12 +163,19 @@ export function registerGoalCommands(core: GoalCore): void {
 		const view = core.goalForDisplay() ?? core.state.goal;
 		const otherCount = otherOpenGoalCount(core.goalsById, core.focusedGoalId);
 		const verbose = /^\s*verbose\b/i.test(rawArgs);
+		const health = /^\s*health\b/i.test(rawArgs);
+		const ledger = readGoalLedger(ctx);
 		const text = buildGoalStatusText({
 			goal: view,
 			focused: view !== null && core.focusedGoalId === view.id,
 			otherOpenGoals: otherCount,
-			ledgerEvents: readGoalLedger(ctx).events,
+			ledgerEvents: ledger.events,
+			ledgerMalformed: ledger.malformed,
 			verbose,
+			health,
+			activeFilePresent: health && view?.activePath
+				? existsSync(path.resolve(ctx.cwd, view.activePath))
+				: undefined,
 			// §13.2: effective settings with provenance appear only in verbose mode;
 			// the standard mode stays free of settings noise (§13.1).
 			settingsReport: verbose ? effectiveSettingsReport(ctx.cwd) : [],
@@ -481,8 +490,8 @@ export function registerGoalCommands(core: GoalCore): void {
 			ctx.ui.notify("Provide the replacement objective: /goal-tweak <new objective>", "info");
 			return;
 		}
-		if (trimmed.length > (loadGoalSettings(ctx.cwd).objectiveMaxChars ?? 0)) {
-			const max = loadGoalSettings(ctx.cwd).objectiveMaxChars;
+		const max = loadGoalSettings(ctx.cwd).objectiveMaxChars;
+		if (trimmed.length > (max ?? 0)) {
 			if (max !== undefined && max > 0) {
 				ctx.ui.notify(`Replacement objective exceeds ${max} characters (${trimmed.length}).`, "warning");
 				return;
@@ -533,7 +542,7 @@ export function registerGoalCommands(core: GoalCore): void {
 		},
 	});
 	pi.registerCommand("goal-status", {
-		description: "Show the unified goal dashboard for the focused goal (read-only). Append \"verbose\" for full diagnostic detail (goal id, revision, objective, task tree with evidence and contracts, ledger history, budget, pause/blocker, paths, audit report, effective settings).",
+		description: "Show the unified goal dashboard (read-only). Append \"verbose\" for full detail or \"health\" for storage/runtime checks.",
 		handler: async (rawArgs, ctx) => {
 			await showGoalStatus(rawArgs ?? "", ctx);
 		},

package/extensions/goal-events.ts

@@ -300,6 +300,11 @@ export function registerGoalEvents(core: GoalCore): void {
 		core.advanceTurnSeq();
 		const currentSystemPrompt = () => ctx.getSystemPrompt?.() || event.systemPrompt;
 		const incomingGoalId = extractGoalIdFromInjectedMessage(event.prompt ?? "");
+		// Several prompt enrichments may need the same ledger snapshot. Keep one
+		// local read for this hook instead of repeatedly traversing the cached
+		// ledger when rejection and post-compaction steering overlap.
+		let promptLedger: ReturnType<typeof readGoalLedger> | undefined;
+		const getPromptLedger = () => promptLedger ??= readGoalLedger(ctx);
 
 		// If this turn was triggered by a hidden goal checkpoint that no longer
 		// matches the active goal, abort the whole turn instead of letting the
@@ -353,10 +358,10 @@ export function registerGoalEvents(core: GoalCore): void {
 				pauseExtras.push(`Pause reason: ${current.pauseReason ?? "(unknown)"}`);
 				if (current.pauseSuggestedAction) pauseExtras.push(`Suggested action: ${current.pauseSuggestedAction}`);
 			}
-			// Inject durable auditor feedback if available
-			let auditorExtra = "";
-			try {
-				const ledger = readGoalLedger(ctx);
+				// Inject durable auditor feedback if available
+				let auditorExtra = "";
+				try {
+					const ledger = getPromptLedger();
 				const auditorResult = latestAuditorResultForGoal(ledger.events, current.id);
 				if (auditorResult && auditorResult.verdict === "disapproved") {
 					auditorExtra = `\n\n[AUDITOR REJECTION] An independent auditor previously rejected a completion request for this goal. Reason: ${auditorResult.report.slice(0, 300)}\nAddress the auditor's objections before requesting completion again.`;
@@ -395,7 +400,7 @@ export function registerGoalEvents(core: GoalCore): void {
 		if (stalledNote) prompt += stalledNote;
 		// Inject durable auditor feedback if the latest result was a rejection
 		try {
-			const ledger = readGoalLedger(ctx);
+			const ledger = getPromptLedger();
 			const auditorResult = latestAuditorResultForGoal(ledger.events, activeGoal.id);
 			if (auditorResult && auditorResult.verdict === "disapproved" && ledger.events.some((e) => e.type === "completion_requested" && e.goalId === activeGoal.id)) {
 				prompt = `${prompt}\n\n[AUDITOR REJECTION goalId=${activeGoal.id}]\nAn independent auditor previously rejected a completion request for this goal. Reason: ${auditorResult.report.slice(0, 300)}\nAddress the auditor's objections before requesting completion again.`;
@@ -405,9 +410,9 @@ export function registerGoalEvents(core: GoalCore): void {
 		}
 		if (core.runtime.isPostCompactReminderPending() && shouldInjectPostCompactReminder({ pending: true, goal: activeGoal })) {
 			core.runtime.clearPostCompactReminder();
-			// Use deterministic compaction summary instead of generic reminder
-			try {
-				const ledger = readGoalLedger(ctx);
+				// Use deterministic compaction summary instead of generic reminder
+				try {
+					const ledger = getPromptLedger();
 				const compaction = buildCompactionSummary({ goalsById: core.goalsById, focusedGoalId: core.focusedGoalId, ledgerEvents: ledger.events });
 				prompt = `${prompt}\n\n[POST-COMPACTION RESYNC goalId=${activeGoal.id}]\n${compaction}`;
 			} catch {
@@ -473,4 +478,3 @@ export function registerGoalEvents(core: GoalCore): void {
 		if (core.state.goal) core.persist(ctx);
 	});
 }
-

package/extensions/goal-service.ts

@@ -1,5 +1,5 @@
 import { cloneGoal, nowIso, type GoalFocusReason, type GoalRecord, type GoalTask, type GoalUsage } from "./goal-record.ts";
-import { appendGoalEvent, type GoalLedgerEvent , appendGoalEvents } from "./goal-ledger.ts";
+import { appendGoalEvent, appendGoalEvents, type GoalLedgerEvent } from "./goal-ledger.ts";
 import { findTaskInTree, updateTaskInTree } from "./goal-policy.ts";
 import {
 	GOALS_DIR,
@@ -175,7 +175,12 @@ export class GoalService {
 
 	/** Open (or reopen) the per-turn transaction for the focused goal. */
 	beginTurn(ctx: GoalServiceContext, goalId: string | null): void {
-		if (this.turn.active) this.flushTurn(ctx);
+		if (this.turn.active) {
+			this.flushTurn(ctx);
+			// Lock contention must not discard the previous transaction. Keep it
+			// open so the next turn boundary retries the same buffered write.
+			if (this.turn.active) return;
+		}
 		this.turn = { active: true, goalId, goal: null, archive: false, ledger: [] };
 	}
 
@@ -186,16 +191,20 @@ export class GoalService {
 	 */
 	flushTurn(ctx: GoalServiceContext): GoalRecord | null {
 		if (!this.turn.active) return null;
-		this.turn.active = false;
 		const goal = this.turn.goal;
-		if (!goal) return null;
+		if (!goal) {
+			this.turn.active = false;
+			return null;
+		}
 		let lock: GoalLock;
 		try {
 			lock = acquireGoalLock(ctx, goal.id);
 		} catch {
-			// Another writer holds the lock; skip this flush (same policy as persist).
+			// Another writer holds the lock; preserve the buffer so a later turn
+			// boundary can retry it instead of silently losing the mutation.
 			return null;
 		}
+		this.turn.active = false;
 		try {
 			const freshDisk = this.readFreshDiskGoal(ctx, goal);
 			const base = freshDisk ?? goal;
@@ -203,25 +212,7 @@ export class GoalService {
 			const written = this.turn.archive || next.status === "complete"
 				? archiveGoalFile(ctx, next)
 				: writeActiveGoalFile(ctx, next);
-			if (this.turn.ledger.length > 0) {
-				const batch = appendGoalEvents(ctx, this.turn.ledger);
-				if (!batch.ok) {
-					// Fall back to per-event appends so each failure still surfaces
-					// through the diagnostic hook with its original granularity.
-					for (const event of this.turn.ledger) {
-						const append = appendGoalEvent(ctx, event);
-						if (!append.ok) {
-							this.ref.onDiagnostic({
-								severity: "warning",
-								source: "ledger",
-								goalId: "goalId" in event ? event.goalId : undefined,
-								eventType: event.type,
-								message: `Ledger append failed for ${event.type}${("goalId" in event) ? ` (goal ${event.goalId})` : ""}: ${String(append.error)}`,
-							});
-						}
-					}
-				}
-			}
+			this.appendLedgerEventsBestEffort(ctx, this.turn.ledger);
 			this.trackBaseline(written.id, written.usage);
 			this.ref.setFocused(written);
 			return written;
@@ -264,6 +255,28 @@ export class GoalService {
 		};
 	}
 
+	/**
+	 * Append ledger events without making them part of the authoritative state
+	 * transaction. A batch is the common path; individual retries preserve the
+	 * existing best-effort behavior and keep failures observable per event.
+	 */
+	private appendLedgerEventsBestEffort(ctx: GoalServiceContext, events: GoalLedgerEvent[]): void {
+		if (events.length === 0) return;
+		if (events.length > 1 && appendGoalEvents(ctx, events).ok) return;
+		for (const event of events) {
+			const append = appendGoalEvent(ctx, event);
+			if (!append.ok) {
+				this.ref.onDiagnostic({
+					severity: "warning",
+					source: "ledger",
+					goalId: "goalId" in event ? event.goalId : undefined,
+					eventType: event.type,
+					message: `Ledger append failed for ${event.type}${"goalId" in event ? ` (goal ${event.goalId})` : ""}: ${String(append.error)}`,
+				});
+			}
+		}
+	}
+
 	/** Safe focused record reconciliation from disk. */
 	reconcileFocused(ctx: GoalServiceContext, opts: { preserveMemoryUsage?: boolean } = {}): boolean {
 		const current = this.ref.getFocused();
@@ -426,20 +439,7 @@ export class GoalService {
 				} catch {
 					events = [];
 				}
-				for (const event of events) {
-					const append = appendGoalEvent(ctx, event);
-					if (!append.ok) {
-						// Ledger append failure after the authoritative write keeps the
-						// successful state transition; surface an observable diagnostic.
-						this.ref.onDiagnostic({
-							severity: "warning",
-							source: "ledger",
-							goalId: "goalId" in event ? event.goalId : undefined,
-							eventType: event.type,
-							message: `Ledger append failed for ${event.type}${("goalId" in event) ? ` (goal ${event.goalId})` : ""}: ${String(append.error)}`,
-						});
-					}
-				}
+				this.appendLedgerEventsBestEffort(ctx, events);
 			}
 
 			// 6. in-memory pool/focus commit.
@@ -594,18 +594,7 @@ export class GoalService {
 			const written = writeActiveGoalFile(ctx, mutated);
 			if (spec.ledger) {
 				try {
-					for (const event of spec.ledger(written, updatedTask)) {
-						const append = appendGoalEvent(ctx, event);
-						if (!append.ok) {
-							this.ref.onDiagnostic({
-								severity: "warning",
-								source: "ledger",
-								goalId: "goalId" in event ? event.goalId : undefined,
-								eventType: event.type,
-								message: `Ledger append failed for ${event.type}${("goalId" in event) ? ` (goal ${event.goalId})` : ""}: ${String(append.error)}`,
-							});
-						}
-					}
+					this.appendLedgerEventsBestEffort(ctx, spec.ledger(written, updatedTask));
 				} catch (err) {
 					// Unexpected ledger-spec error after the authoritative write keeps
 					// the successful state transition.
@@ -689,25 +678,7 @@ export class GoalService {
 		const previousGoalId = this.ref.getFocused()?.id ?? null;
 		const written = writeActiveGoalFile(ctx, sanitizeGoalPaths(ctx, spec.goal));
 		if (spec.ledger && spec.ledger.length > 0) {
-			// Batch append (P1-8): one write+append for the whole event block.
-			const batch = appendGoalEvents(ctx, spec.ledger);
-			if (!batch.ok) {
-				// Fall back to per-event appends so each failure still surfaces
-				// through the diagnostic hook with its original granularity.
-				for (const event of spec.ledger) {
-					const append = appendGoalEvent(ctx, event);
-					if (!append.ok) {
-						// Best-effort ledger; creation still succeeds.
-						this.ref.onDiagnostic({
-							severity: "warning",
-							source: "ledger",
-							goalId: "goalId" in event ? event.goalId : undefined,
-							eventType: event.type,
-							message: `Ledger append failed for ${event.type}${"goalId" in event ? ` (goal ${event.goalId})` : ""}: ${String(append.error)}`,
-						});
-					}
-				}
-			}
+			this.appendLedgerEventsBestEffort(ctx, spec.ledger);
 		}
 		this.ref.setFocused(written);
 		this.trackBaseline(written.id, written.usage);
@@ -723,25 +694,7 @@ export class GoalService {
 			this.turn.ledger.push(...events);
 			return;
 		}
-		if (events.length > 1) {
-			// Batch append (P1-8): one write+append for the whole event block.
-			const batch = appendGoalEvents(ctx, events);
-			if (batch.ok) return;
-		}
-		for (const event of events) {
-			const append = appendGoalEvent(ctx, event);
-			if (!append.ok) {
-				// Ledger append failure must not crash the surrounding flow, but it
-				// stays observable through the diagnostic hook.
-				this.ref.onDiagnostic({
-					severity: "warning",
-					source: "ledger",
-					goalId: "goalId" in event ? event.goalId : undefined,
-					eventType: event.type,
-					message: `Ledger append failed for ${event.type}${"goalId" in event ? ` (goal ${event.goalId})` : ""}: ${String(append.error)}`,
-				});
-			}
-		}
+		this.appendLedgerEventsBestEffort(ctx, events);
 	}
 
 	/** Diagnostic write for the debug widget toggle (separate debug dir; not a goal mutation). */

package/extensions/goal-state.ts

@@ -508,7 +508,6 @@ export function createGoalCore(
 		// goal budget_limited exactly once (status no longer active, so accounting
 		// stops and the transition cannot re-fire), emit the ledger event, arm the
 		// one-time wrap-up steering, and cancel pending continuations.
-		const budgetGoal2 = state.goal;
 		if (budgetGoal && budgetGoal.status === "active" && typeof budgetGoal.tokenBudget === "number" && budgetReached(budgetGoal)) {
 			const transition = goalService.apply(ctx, {
 				reconcile: false,

package/extensions/goal-status.ts

@@ -34,7 +34,11 @@ export interface GoalStatusTextOptions {
 	focused: boolean;
 	otherOpenGoals: number;
 	ledgerEvents?: GoalLedgerEvent[];
+	ledgerMalformed?: number;
 	verbose?: boolean;
+	health?: boolean;
+	/** Supplied by the command layer only for the explicit health check. */
+	activeFilePresent?: boolean;
 	/** Effective settings lines with provenance (verbose only). */
 	settingsReport?: string[];
 	width?: number;
@@ -55,6 +59,7 @@ export interface GoalStatusTextOptions {
  */
 export function buildGoalStatusText(options: GoalStatusTextOptions): string {
 	const width = options.width ?? GOAL_STATUS_WIDTH;
+	if (options.health) return buildHealthStatus(options, width);
 	if (!options.goal) {
 		return options.otherOpenGoals > 0
 			? renderUnfocusedDashboard(options.otherOpenGoals, PLAIN_THEME, width).join("\n")
@@ -87,6 +92,101 @@ export function buildGoalStatusText(options: GoalStatusTextOptions): string {
 	return parts.join("\n\n");
 }
 
+interface HealthCheck {
+	label: string;
+	value: string;
+	severity: "ok" | "warn" | "error";
+}
+
+/**
+ * Render a concise, read-only integrity report. This deliberately checks
+ * storage/runtime coherence only; it does not infer that the work itself is
+ * complete from task counts or contracts.
+ */
+function buildHealthStatus(options: GoalStatusTextOptions, width: number): string {
+	const goal = options.goal;
+	if (!goal) {
+		const focus = options.otherOpenGoals > 0
+			? `WARN — no goal is focused; ${options.otherOpenGoals} open goal${options.otherOpenGoals === 1 ? "" : "s"} remain.`
+			: "OK — no goal is focused and there are no open goals.";
+		return ["Goal health: " + (options.otherOpenGoals > 0 ? "WARN" : "OK"), `Focus: ${focus}`, "Run /goal-status for the normal dashboard."].join("\n");
+	}
+
+	const checks: HealthCheck[] = [];
+	checks.push({
+		label: "Focus",
+		value: options.focused ? "focused" : "not focused",
+		severity: options.focused ? "ok" : "warn",
+	});
+	checks.push({
+		label: "Lifecycle",
+		value: `${statusLabelForHealth(goal)}${goal.autoContinue ? " · auto-continue on" : " · auto-continue off"}`,
+		severity: goal.status === "active" || goal.status === "paused" || goal.status === "blocked" || goal.status === "budget_limited" || goal.status === "complete" ? "ok" : "error",
+	});
+
+	if (goal.status !== "complete") {
+		const fileSeverity = options.activeFilePresent === false ? "error" : options.activeFilePresent === true ? "ok" : "warn";
+		checks.push({
+			label: "Goal file",
+			value: goal.activePath ? (options.activeFilePresent === false ? `missing · ${goal.activePath}` : goal.activePath) : "missing active path",
+			severity: fileSeverity,
+		});
+	}
+
+	const malformed = options.ledgerMalformed ?? 0;
+	checks.push({
+		label: "Ledger",
+		value: malformed > 0 ? `${malformed} malformed entr${malformed === 1 ? "y" : "ies"}` : "valid",
+		severity: malformed > 0 ? "warn" : "ok",
+	});
+
+	if (goal.taskList) {
+		const tasks = flattenHealthTasks(goal.taskList.tasks);
+		const completed = tasks.filter((task) => task.status === "complete" || task.status === "skipped").length;
+		const pending = tasks.length - completed;
+		const contractedPending = tasks.filter((task) => task.status === "pending" && Boolean(task.verificationContract?.trim())).length;
+		checks.push({
+			label: "Tasks",
+			value: `${completed}/${tasks.length} terminal · ${pending} pending${contractedPending > 0 ? ` · ${contractedPending} contracted` : ""}`,
+			severity: goal.taskList.blockCompletion && pending > 0 ? "warn" : "ok",
+		});
+	}
+
+	if (typeof goal.tokenBudget === "number" && goal.tokenBudget > 0) {
+		const percentage = Math.round((goal.usage.tokensUsed / goal.tokenBudget) * 100);
+		checks.push({
+			label: "Budget",
+			value: `${formatCompactTokensForHealth(goal.usage.tokensUsed)} / ${formatCompactTokensForHealth(goal.tokenBudget)} (${Math.max(0, percentage)}%)`,
+			severity: goal.status === "budget_limited" || percentage >= 100 ? "warn" : percentage >= 90 ? "warn" : "ok",
+		});
+	}
+
+	const overall = checks.some((check) => check.severity === "error") ? "ERROR" : checks.some((check) => check.severity === "warn") ? "WARN" : "OK";
+	const lines = [`Goal health: ${overall}`, `Goal: ${truncateText(goal.objective, Math.max(20, width - 12))}`];
+	for (const check of checks) lines.push(`${check.severity === "error" ? "ERROR" : check.severity === "warn" ? "WARN" : "OK"} ${check.label}: ${check.value}`);
+	lines.push("", "This is a storage/runtime health check, not a completion verdict.");
+	return lines.join("\n");
+}
+
+function flattenHealthTasks(tasks: GoalTask[]): GoalTask[] {
+	const result: GoalTask[] = [];
+	for (const task of tasks) {
+		result.push(task);
+		if (task.subtasks) result.push(...flattenHealthTasks(task.subtasks));
+	}
+	return result;
+}
+
+function statusLabelForHealth(goal: GoalRecord): string {
+	return goal.status === "budget_limited" ? "budget limited" : goal.status;
+}
+
+function formatCompactTokensForHealth(value: number): string {
+	if (value >= 1_000_000) return `${(value / 1_000_000).toFixed(1).replace(/\.0$/, "")}M`;
+	if (value >= 1_000) return `${(value / 1_000).toFixed(1).replace(/\.0$/, "")}K`;
+	return String(Math.max(0, Math.floor(value)));
+}
+
 function lastAuditBlock(
 	audit: { verdict: "approved" | "disapproved" | "error"; report: string; at: string },
 	width: number,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-goal-x",
-  "version": "0.26.2",
+  "version": "0.26.3",
   "description": "Goal mode extension for pi: durable long-running objectives, five model tools, structured tasks, independent completion audit, Sisyphus mode, auto-continue, and a status overlay.",
   "license": "MIT",
   "author": "pi-goal-x contributors",