pi-goal-x 0.8.2 → 0.10.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-goal-x
 
-> **Fork of [@capyup/pi-goal](https://github.com/capyup/pi-goal)** — this repository extends the upstream with quality-of-life features for the completion auditor, lifecycle reliability improvements, and drafting UX refinements. Upstream changes can be merged from the original repository.
+> **Fork of [@capyup/pi-goal](https://github.com/capyup/pi-goal)** — this repository extends the upstream with quality-of-life features for the completion auditor, lifecycle reliability improvements, mid-flight objective updates, deferred archival, and drafting UX refinements. Upstream changes can be merged from the original repository.
 
 `pi-goal-x` is a long-running goal extension for [pi](https://github.com/earendil-works/pi-coding-agent). It gives the agent a durable objective, a visible lifecycle, and schema-gated tools for drafting, executing, pausing, resuming, and completing work.
 
@@ -10,9 +10,24 @@ The extension is designed around one rule: **the user owns intent; the agent exe
 
 All core features of [@capyup/pi-goal](https://github.com/capyup/pi-goal) are preserved. The following changes are specific to pi-goal-x:
 
+### Mid-flight objective updates
+
+- **`update_goal({updatedObjective})`** — the agent can now sync the goal objective mid-flight when user requirements change, *without* completing the goal. This ensures the completion auditor evaluates against the latest requirements. The combined path (`updatedObjective` + `status: "complete"`) applies the update first, then runs the normal completion+audit flow.
+- **`apply_goal_tweak`** remains available for `/goal-tweak` drafting revisions; the new parameter is the lightest possible touch on the existing `update_goal` tool.
+
+### Deferred archival
+
+- **No more premature archiving**: previously, `update_goal` archived the goal file inline within the tool handler before the agent could see the audit result (or skip notification). Archival is now deferred until `turn_end` — after the agent has received the audit/skip result in the conversation. The goal remains visible in the active pool through the entire completion flow.
+- **Cleaner lifecycle**: completed goals are archived by the `turn_end` lifecycle hook, not by the tool handler. The `accountProgress` guard skips disk reconciliation for completed goals.
+
+### E2e test infrastructure
+
+- **Deterministic fork tests using `--mode json`**: the e2e suite spawns a real `pi --fork --mode json` session, parses structured `tool_execution_start`/`tool_execution_end` JSON events for field-level assertions — no free-text AI output parsing. Uses `--append-system-prompt` + `--tools` to force deterministic tool calls.
+- **Full coverage**: 131 tests total — function-level integration tests (12), mock-pi handler tests (4), file-validity checks (6), and real `pi --fork --mode json` tests (3 scenarios: quick-sync, combined sync+complete, deferred archival).
+
 ### Completion auditor
 
-- **Live progress widget** — when the auditor runs, the TUI shows a spinner, the current tool being executed, and recent output lines. No more wondering if anything is happening.
+- **Live progress widget** — when the auditor runs, the TUI shows a spinner, a progress bar (`[████░░░░] 40%`), step labels (`Inspecting files...`, `Verifying success criteria...`), the current tool being executed, and recent output lines. No more wondering if anything is happening.
 - **Escape to skip** — press Escape during an audit to abort it and complete the goal immediately. The skip is recorded in the ledger as `audit_skipped` with reason `user_aborted` and auditor model metadata.
 - **Disable the auditor entirely** — set `disabled: true` in `.pi/goal-auditor.json` (or toggle it via `/goal-settings` → `disabled`). The agent can still bypass with user confirmation by passing `confirmBypassAuditor: true` to `update_goal`.
 - **Skipped audits are recorded** — every skip (whether disabled or Escape-aborted) is logged to the ledger with the reason, provider, model, and thinking level for full traceability.

package/extensions/goal-auditor.ts

@@ -1,10 +1,13 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import type { Static } from "@earendil-works/pi-ai";
+import { Type } from "@earendil-works/pi-ai";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Model } from "@earendil-works/pi-ai";
 import {
 	createAgentSession,
 	createExtensionRuntime,
+	defineTool,
 	SessionManager,
 	SettingsManager,
 	type ExtensionContext,
@@ -29,9 +32,13 @@ export interface AuditorProgress {
 	/** Recent text output lines from the auditor's assistant messages */
 	recentOutput: string[];
 	/** Phase of the audit */
-	phase: "running" | "tool_executing" | "producing_report" | "done";
+	phase: "running" | "tool_executing" | "producing_report" | "thinking" | "done";
 	/** Elapsed ms since audit started */
 	elapsedMs: number;
+	/** Current step label shown to the user (e.g. "Inspecting files...") */
+	label?: string;
+	/** Completion percentage from 0 to 100 */
+	percentage?: number;
 }
 
 export type AuditorProgressCallback = (progress: AuditorProgress) => void;
@@ -156,9 +163,28 @@ export function buildGoalAuditorPrompt(args: {
 		"2. Inspect artifacts or command output that can prove or disprove those criteria.",
 		"3. Explain missing or weak evidence, especially scaffold-vs-final quality gaps.",
 		"4. End with exactly <approved/> only if the objective is truly complete; otherwise end with exactly <disapproved/>.",
+		"",
+		"Progress reporting:",
+		"You have the report_auditor_progress tool available to report your progress to the user.",
+		"Please use it at natural phase boundaries:",
+		"  - When starting: report_auditor_progress(label='Starting audit...', percentage=0)",
+		"  - When beginning file inspection: report_auditor_progress(label='Inspecting files...', percentage=25)",
+		"  - When verifying success criteria: report_auditor_progress(label='Verifying success criteria...', percentage=50)",
+		"  - When evaluating evidence: report_auditor_progress(label='Evaluating evidence...', percentage=75)",
+		"  - When producing final report: report_auditor_progress(label='Producing report...', percentage=90)",
+		"This is purely for user visibility and does not affect the audit outcome.",
 	].join("\n");
 }
 
+/** Tool name for auditor progress reporting */
+export const REPORT_AUDITOR_PROGRESS_TOOL_NAME = "report_auditor_progress";
+
+/** Parameters for the report_auditor_progress tool */
+export const reportAuditorProgressParams = Type.Object({
+	label: Type.String({ description: "Current step label describing what the auditor is doing (e.g. 'Inspecting files...', 'Verifying success criteria...', 'Producing report...')" }),
+	percentage: Type.Number({ description: "Completion percentage from 0 to 100", minimum: 0, maximum: 100 }),
+});
+
 function makeAuditorResourceLoader(): ResourceLoader {
 	return {
 		getExtensions: () => ({ extensions: [], errors: [], runtime: createExtensionRuntime() }),
@@ -170,9 +196,14 @@ function makeAuditorResourceLoader(): ResourceLoader {
 			"You are a read-only completion auditor running in an isolated pi agent session.",
 			"Inspect the repository and decide whether the claimed goal completion is genuinely satisfied.",
 			"Never modify files. Never approve unless the actual user objective is complete.",
+			"",
+			"You have the report_auditor_progress tool available. Use it to report your audit progress",
+			"to the user at natural phase boundaries (starting, inspecting files, verifying criteria,",
+			"producing report). This helps the user understand what the auditor is doing and how far",
+			"along it is.",
 		].join("\n"),
 		getAppendSystemPrompt: () => [],
-		extendResources: () => {},
+	extendResources: () => {},
 		reload: async () => {},
 	};
 }
@@ -228,16 +259,6 @@ export async function runGoalCompletionAuditor(args: {
 	}
 	try {
 		const createSession = args.createSession ?? createAgentSession;
-		const { session } = await createSession({
-			cwd: args.ctx.cwd,
-			model,
-			thinkingLevel,
-			modelRegistry: args.ctx.modelRegistry,
-			resourceLoader: makeAuditorResourceLoader(),
-			sessionManager: SessionManager.inMemory(args.ctx.cwd),
-			settingsManager: SettingsManager.inMemory({ compaction: { enabled: false } }),
-			tools: ["read", "grep", "find", "ls", "bash"],
-		});
 		const startedAt = Date.now();
 		const progress: AuditorProgress = {
 			recentOutput: [],
@@ -248,6 +269,49 @@ export async function runGoalCompletionAuditor(args: {
 			progress.elapsedMs = Date.now() - startedAt;
 			args.onProgress?.({ ...progress });
 		}
+
+		// Build the report_auditor_progress tool, capturing the progress state
+		const reportProgressTool = defineTool({
+			name: REPORT_AUDITOR_PROGRESS_TOOL_NAME,
+			label: "Report Auditor Progress",
+			description: "Report current progress of the audit to the user. Call this at natural phase boundaries (starting, inspecting files, verifying criteria, producing report) to keep the user informed.",
+			promptSnippet: "Report current audit progress (step label and completion percentage) to the user.",
+			promptGuidelines: [
+				"Use report_auditor_progress at natural phase boundaries during the audit:",
+				"  - When starting the audit: label='Starting audit...' percentage=0",
+				"  - When beginning file inspection: label='Inspecting files...' percentage=25",
+				"  - When verifying success criteria: label='Verifying success criteria...' percentage=50",
+				"  - When evaluating evidence: label='Evaluating evidence...' percentage=75",
+				"  - When producing final report: label='Producing report...' percentage=90",
+				"This is purely for user visibility — it does not affect the audit outcome.",
+				"Do not call this tool more than once every few seconds to avoid flooding.",
+			],
+			parameters: reportAuditorProgressParams,
+			executionMode: "sequential",
+			async execute(_toolCallId, params) {
+				const { label, percentage } = params as Static<typeof reportAuditorProgressParams>;
+				progress.label = label;
+				progress.percentage = percentage;
+				progress.phase = "running";
+				emitProgress();
+				return {
+					content: [{ type: "text", text: `Progress reported: ${label} (${percentage}%)` }],
+					details: {},
+				};
+			},
+		});
+
+		const { session } = await createSession({
+			cwd: args.ctx.cwd,
+			model,
+			thinkingLevel,
+			modelRegistry: args.ctx.modelRegistry,
+			resourceLoader: makeAuditorResourceLoader(),
+			sessionManager: SessionManager.inMemory(args.ctx.cwd),
+			settingsManager: SettingsManager.inMemory({ compaction: { enabled: false } }),
+			tools: ["read", "grep", "find", "ls", "bash", REPORT_AUDITOR_PROGRESS_TOOL_NAME],
+			customTools: [reportProgressTool],
+		});
 		const unsubscribe = session.subscribe((event) => {
 			if (event.type === "tool_execution_start") {
 				progress.currentTool = event.toolName;
@@ -268,6 +332,20 @@ export async function runGoalCompletionAuditor(args: {
 				return;
 			}
 			if (event.type === "message_update") {
+				// Check for thinking events from the assistant stream
+				const streamEvent = (event as any).assistantMessageEvent;
+				if (streamEvent?.type === "thinking_start") {
+					progress.phase = "thinking";
+					if (!progress.label) progress.label = "Analyzing goal...";
+					emitProgress();
+					return;
+				}
+				if (streamEvent?.type === "thinking_end") {
+					progress.phase = "running";
+					emitProgress();
+					return;
+				}
+				// For text content, show producing_report phase
 				progress.phase = "producing_report";
 				const message = event.message as any;
 				if (message?.role === "assistant") {
@@ -300,6 +378,8 @@ export async function runGoalCompletionAuditor(args: {
 		args.signal?.addEventListener("abort", abortSession, { once: true });
 
 		// Emit initial progress
+		progress.label = "Starting audit...";
+		progress.percentage = 0;
 		emitProgress();
 		try {
 			if (args.signal?.aborted) return { approved: false, disapproved: true, output: "", model: modelLabel(model), thinkingLevel, error: "Auditor aborted." };
@@ -307,6 +387,8 @@ export async function runGoalCompletionAuditor(args: {
 		} finally {
 			args.signal?.removeEventListener("abort", abortSession);
 			progress.phase = "done";
+			progress.label = "Audit complete.";
+			progress.percentage = 100;
 			emitProgress();
 			unsubscribe();
 		}

package/extensions/goal-policy.ts

@@ -43,6 +43,14 @@ export function validateGoalCompletion(args: {
 	return { ok: true };
 }
 
+export function validateGoalUpdate(args: {
+	goal: GoalPolicyRecordLike | null;
+}): PolicyValidation {
+	if (!args.goal) return { ok: false, message: "No goal is set; cannot update objective." };
+	if (args.goal.status === "complete") return { ok: false, message: "Goal is already complete; cannot update objective." };
+	return { ok: true };
+}
+
 export function validateGoalAbort(args: {
 	goal: GoalPolicyRecordLike | null;
 	runningGoalId?: string | null;

package/extensions/goal.ts

@@ -106,6 +106,7 @@ import {
 	shouldInjectPostCompactReminder,
 	validateGoalAbort,
 	validateGoalCompletion,
+	validateGoalUpdate,
 	validatePauseGoal,
 	validateResumeGoal,
 } from "./goal-policy.ts";
@@ -1704,16 +1705,70 @@ export default function goalExtension(pi: ExtensionAPI): void {
 			"Do not call update_goal merely because work is stopping, substantial progress was made, or tests passed without covering every requirement.",
 			"Do not use update_goal=complete as an escape hatch when you are blocked. If you are blocked, call pause_goal({reason, suggestedAction?}) instead so the user can intervene.",
 			"For sisyphus goals, do not mark complete until every numbered step has been executed and individually verified against its done criterion.",
+			"If the user gives requirements, feedback, or corrections that differ from the goal objective, the goal is stale. Use update_goal with updatedObjective to sync the objective before continuing work or before marking the goal complete. This ensures the auditor evaluates against the latest requirements.",
 		],
 		parameters: Type.Object({
-			status: StringEnum([COMPLETE_STATUS] as const, { description: "Set to complete only when the objective is achieved." }),
+			status: Type.Optional(StringEnum([COMPLETE_STATUS] as const, { description: "Set to complete only when the objective is achieved." })),
 			completionSummary: Type.Optional(Type.String({ description: "Concise completion claim and evidence summary passed to the independent auditor agent." })),
 			confirmBypassAuditor: Type.Optional(Type.Boolean({ description: "Set to true to confirm bypassing the independent auditor when it is disabled in settings." })),
+			updatedObjective: Type.Optional(Type.String({ description: "Revised goal objective. Use when the user's requirements have changed mid-flight. The goal remains active so the agent can continue working toward the new objective. Can be combined with status=complete to update the objective before the completion audit." })),
 		}),
 		executionMode: "sequential",
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			reconcileFocusedGoalFromDisk(ctx);
-			if (params.status !== COMPLETE_STATUS) throw new Error("update_goal only supports status=complete.");
+
+			// -- Phase 1: Objective update (quick sync) --
+			// Apply updatedObjective before any completion logic so the completion
+			// flow (if status=complete is also set) reads the latest objective.
+			if (params.updatedObjective !== undefined) {
+				const newObjective = params.updatedObjective.trim();
+				if (!newObjective) throw new Error("update_goal requires a non-empty updatedObjective.");
+				const updateGate = validateGoalUpdate({ goal: state.goal });
+				if (!updateGate.ok) {
+					return {
+						content: [{ type: "text", text: updateGate.message }],
+						details: goalDetails(state.goal),
+					};
+				}
+				if (!state.goal) throw new Error("Goal disappeared during objective update.");
+				const next: GoalRecord = {
+					...state.goal,
+					objective: newObjective,
+					updatedAt: nowIso(),
+				};
+				state.goal = writeActiveGoalFile(ctx, next);
+				pi.appendEntry(STATE_ENTRY, goalDetails(state.goal));
+				try {
+					appendGoalEvent(ctx, {
+						type: "goal_tweaked",
+						goalId: state.goal.id,
+						changeSummary: "Objective updated via update_goal",
+						at: state.goal.updatedAt,
+					});
+				} catch {
+					// Ledger append failure should not block update
+				}
+				updateUI(ctx);
+
+				// Quick sync only (no status=complete) — return without terminating
+				if (params.status !== COMPLETE_STATUS) {
+					return {
+						content: [{ type: "text", text: `Goal objective updated.` }],
+						details: goalDetails(state.goal),
+					};
+				}
+				// Fall through: status=complete also set, proceed with completion below
+			}
+
+			// -- Phase 2: Status validation --
+			if (params.status !== COMPLETE_STATUS) {
+				if (params.updatedObjective === undefined) {
+					throw new Error("update_goal requires either status=complete or updatedObjective.");
+				}
+				throw new Error("update_goal requires status=complete when marking a goal complete.");
+			}
+
+			// -- Phase 3: Completion --
 			const completionGate = validateGoalCompletion({ goal: state.goal, runningGoalId });
 			if (!completionGate.ok) {
 				return {
@@ -2009,7 +2064,8 @@ export default function goalExtension(pi: ExtensionAPI): void {
 			};
 		},
 		renderCall(args, theme) {
-			return new Text(theme.fg("toolTitle", "update_goal ") + theme.fg("success", args.status), 0, 0);
+			const label = args?.status ?? args?.updatedObjective ? "sync" : "";
+			return new Text(theme.fg("toolTitle", "update_goal ") + theme.fg("success", label), 0, 0);
 		},
 		renderResult(result, _options, theme) {
 			return renderGoalResult(result, theme);

package/extensions/prompts/goal-prompts.ts

@@ -44,7 +44,9 @@ If you hit a real blocker that you cannot resolve with one more reasonable next
 
 If the user explicitly asks to abandon/cancel this goal, or the objective is obsolete, impossible, or unsafe to continue and should not be marked complete, call abort_goal({reason}) with a non-empty reason and stop.
 
-Do NOT silently invent workarounds, fake completion, or quietly redefine the objective. Do NOT call update_goal=complete to escape a blocker.${sisyphusDisciplineBlock(goal) ? `\n${sisyphusDisciplineBlock(goal)}` : ""}`;
+Do NOT silently invent workarounds, fake completion, or quietly redefine the objective. Do NOT call update_goal=complete to escape a blocker.
+
+Goal evolution: if the user gives requirements, feedback, or corrections that differ from the goal objective, the goal is stale. Propose the updated objective concisely and wait for the user to confirm before continuing. Use update_goal with updatedObjective for narrow focus-area changes, or suggest /goal-tweak for broader revisions (boundaries, constraints, multiple sections). Do NOT mark the goal complete with a stale objective.${sisyphusDisciplineBlock(goal) ? `\n${sisyphusDisciplineBlock(goal)}` : ""}`;
 }
 
 export function continuationPrompt(goal: GoalRecord): string {
@@ -77,6 +79,8 @@ export function continuationPrompt(goal: GoalRecord): string {
 		"Do not call update_goal unless the goal is complete enough to survive independent semantic auditing. Do not mark a goal complete merely because work is stopping.",
 		"Do not ask the user for confirmation unless there is a real blocker.",
 		"",
+		"Goal evolution: if the user gives requirements, feedback, or corrections that differ from the goal objective, the goal is stale. Propose the updated objective concisely and wait for the user to confirm before continuing. Use update_goal with updatedObjective for narrow focus-area changes, or suggest /goal-tweak for broader revisions (boundaries, constraints, multiple sections). Do NOT mark the goal complete with a stale objective.",
+		"",
 		"If you hit a real blocker (missing credentials, contradictory spec, file/permission you cannot access, dangerous operation pending user approval, or an unclear Sisyphus-style ordered plan), call pause_goal({reason, suggestedAction?}) and stop. If the user explicitly asks to abandon/cancel, or the objective is obsolete, impossible, or unsafe to continue, call abort_goal({reason}) and stop. Do not silently invent workarounds. Do not fake completion. pause_goal and abort_goal are structured lifecycle exits; update_goal=complete is not an escape hatch for blockers.",
 		...(goal.sisyphus ? ["", sisyphusDisciplineBlock(goal)] : []),
 	].join("\n");

package/extensions/widgets/goal-widget.ts

@@ -24,8 +24,12 @@ export interface AuditorWidgetProgress {
 	currentToolArgs?: string;
 	currentToolStartedAt?: number;
 	recentOutput: string[];
-	phase: "running" | "tool_executing" | "producing_report" | "done";
+	phase: "running" | "tool_executing" | "producing_report" | "thinking" | "done";
 	elapsedMs: number;
+	/** Current step label shown to the user */
+	label?: string;
+	/** Completion percentage from 0 to 100 */
+	percentage?: number;
 }
 
 export interface GoalWidgetOptions {
@@ -52,6 +56,13 @@ function branchLine(theme: Theme, width: number, isLast: boolean, content: strin
 	return fit(`${theme.fg("dim", prefix)} ${content}`, width);
 }
 
+function progressBar(pct: number, barWidth: number, theme: Theme): string {
+	const safeBar = Math.max(3, barWidth);
+	const filled = Math.min(safeBar, Math.max(0, Math.round((pct / 100) * safeBar)));
+	const empty = safeBar - filled;
+	return `[${theme.fg("accent", "█".repeat(filled))}${theme.fg("dim", "░".repeat(empty))}]`;
+}
+
 function displayIcon(goal: GoalWidgetRecord): { icon: string; color: GoalWidgetColor; label: string } {
 	if (goal.status === "complete") return { icon: "✓", color: "success", label: "complete" };
 	if (goal.status === "paused") {
@@ -81,8 +92,17 @@ function spinnerFrame(): string {
 export function renderAuditorWidgetLines(progress: AuditorWidgetProgress, theme: Theme, width: number): string[] {
 	const safeWidth = Math.max(1, width);
 	const isActive = progress.phase !== "done";
-	const icon = isActive ? theme.fg("accent", spinnerFrame()) : theme.fg("success", "✓");
-	const label = isActive ? "auditing" : "audit complete";
+	const isThinking = progress.phase === "thinking";
+	const icon = isActive
+		? isThinking
+			? theme.fg("muted", "⟡")
+			: theme.fg("accent", spinnerFrame())
+		: theme.fg("success", "✓");
+	const label = isActive
+		? isThinking
+			? "thinking..."
+			: "auditing"
+		: "audit complete";
 	// formatDuration expects seconds, progress.elapsedMs is in milliseconds
 	const duration = formatDuration(Math.floor(progress.elapsedMs / 1000));
 	const lines: string[] = [
@@ -94,7 +114,30 @@ export function renderAuditorWidgetLines(progress: AuditorWidgetProgress, theme:
 		),
 	];
 
-	if (isActive && progress.currentTool) {
+	// Show step label when available
+	if (progress.label) {
+		lines.push(branchLine(
+			theme,
+			safeWidth,
+			false,
+			`${theme.fg("text", truncateText(progress.label, Math.max(8, safeWidth - 6)))}`,
+		));
+	}
+
+	// Show progress bar when percentage is available
+	if (typeof progress.percentage === "number") {
+		const barWidth = Math.max(6, Math.min(safeWidth - 10, 30));
+		const bar = progressBar(progress.percentage, barWidth, theme);
+		const pct = `${theme.fg("muted", `${Math.round(progress.percentage)}%`)}`;
+		lines.push(branchLine(
+			theme,
+			safeWidth,
+			isActive && !progress.currentTool && progress.recentOutput.length === 0 && !isThinking,
+			`${bar} ${pct}`,
+		));
+	}
+
+	if (isActive && !isThinking && progress.currentTool) {
 		const argText = progress.currentToolArgs
 			? truncateText(progress.currentToolArgs, Math.max(10, safeWidth - 24))
 			: "";
@@ -129,7 +172,7 @@ export function renderAuditorWidgetLines(progress: AuditorWidgetProgress, theme:
 	}
 
 	// Show skip hint when audit is actively running
-	if (isActive) {
+	if (isActive && !isThinking) {
 		lines.push(branchLine(
 			theme,
 			safeWidth,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-goal-x",
-  "version": "0.8.2",
+  "version": "0.10.0",
   "description": "Goal mode extension for pi: persistent long-running objectives, /goal-set drafting, Sisyphus prompt style, autoContinue, and an above-editor status overlay. Fork of @capyup/pi-goal.",
   "license": "MIT",
   "author": "pi-goal-x contributors",