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

package/extensions/goal-compaction.ts

@@ -0,0 +1,197 @@
+import {
+  formatDuration,
+  formatTokenValue,
+  statusLabel,
+  truncateText,
+} from "./goal-core.ts";
+import {
+  latestAuditorResultForGoal, latestAuditForGoal,
+  latestEventsForGoal,
+  reconstructGoalLedger,
+  type GoalLedgerEvent,
+  type LedgerStateReadResult,
+} from "./goal-ledger.ts";
+import { type GoalRecord } from "./goal-record.ts";
+import { taskIndex } from "./goal-task-index.ts";
+
+export function buildGoalCompactSummary(
+  goal: GoalRecord,
+  events: GoalLedgerEvent[],
+  auditorOverride?: { verdict: "approved" | "disapproved" | "error"; report: string; at: string },
+): string {
+  const lines: string[] = [];
+  lines.push(`Goal ${goal.id} — ${statusLabel(goal)}`);
+  lines.push(`  Objective: ${truncateText(goal.objective, 200)}`);
+  if (goal.usage.tokensUsed > 0) {
+    lines.push(`  Cumulative goal usage (not context occupancy): ${formatTokenValue(goal.usage.tokensUsed)}`);
+  }
+  if (goal.usage.activeSeconds > 0) {
+    lines.push(`  Time: ${formatDuration(goal.usage.activeSeconds)}`);
+  }
+
+  const recent = latestEventsForGoal(events, goal.id, 5);
+  if (recent.length > 0) {
+    lines.push("  Recent events:");
+    for (const event of recent) {
+      switch (event.type) {
+        case "goal_paused":
+          lines.push(`    - paused: ${event.reason}`);
+          break;
+        case "goal_resumed":
+          lines.push(`    - resumed: ${event.reason}`);
+          break;
+        case "goal_tweaked":
+          lines.push(`    - tweaked: ${event.changeSummary}`);
+          break;
+        case "auditor_toggled":
+          lines.push(`    - auditor toggled ${event.enabled ? "on" : "off"}`);
+          break;
+        case "completion_requested":
+          lines.push(`    - completion requested${event.summary ? `: ${truncateText(event.summary, 80)}` : ""}`);
+          break;
+        case "audit_result":
+          lines.push(`    - auditor ${event.verdict}${event.verdict === "disapproved" ? `: ${truncateText(event.report, 80)}` : ""}`);
+          break;
+        case "goal_completed":
+          lines.push("    - completed");
+          break;
+        case "task_list_set":
+          lines.push(`    - task list set: ${event.taskCount} tasks${event.blockCompletion ? " (blocking)" : ""}`);
+          break;
+        case "task_complete":
+          lines.push(`    - task complete: ${event.taskId}${event.evidence ? ` — ${truncateText(event.evidence, 60)}` : ""}`);
+          break;
+        case "task_skipped":
+          lines.push(`    - task skipped: ${event.taskId} — ${truncateText(event.reason, 60)}`);
+          break;
+        case "task_reopened":
+          lines.push(`    - task reopened: ${event.taskId}`);
+          break;
+        case "goal_aborted":
+          lines.push(`    - aborted: ${event.reason}`);
+          break;
+        default:
+          break;
+      }
+    }
+  }
+
+  const auditor = auditorOverride ?? latestAuditorResultForGoal(events, goal.id);
+  if (latestAuditForGoal(events, goal.id)?.type === "audit_started") lines.push("  Latest audit: no recorded result.");
+  if (auditor && auditor.verdict === "disapproved") {
+    lines.push(`  Auditor rejection (latest): ${truncateText(auditor.report, 120)}`);
+  }
+
+  if (goal.pauseReason) {
+    lines.push(`  Pause reason: ${goal.pauseReason}`);
+  }
+  if (goal.pauseSuggestedAction) {
+    lines.push(`  Suggested action: ${goal.pauseSuggestedAction}`);
+  }
+
+  return lines.join("\n");
+}
+
+export function buildCompactionSummary(args: {
+  goalsById: Map<string, GoalRecord>;
+  focusedGoalId: string | null;
+  ledgerEvents?: GoalLedgerEvent[];
+  /** Checkpoint-fed view: uses reconstructed state + per-goal recent tails instead of a full event list. */
+  ledgerState?: LedgerStateReadResult;
+  capOpenGoals?: number;
+  capEventsPerGoal?: number;
+}): string {
+  const { goalsById, focusedGoalId, ledgerEvents = [], ledgerState, capOpenGoals = 20, capEventsPerGoal = 5 } = args;
+
+  const lines: string[] = [];
+  const openGoals = Array.from(goalsById.values()).filter((g) => g.status !== "complete");
+  const reconstructed = ledgerState?.state ?? reconstructGoalLedger(ledgerEvents);
+  const recentEventsFor = (goalId: string, cap: number): GoalLedgerEvent[] => {
+    if (ledgerState) return (ledgerState.recentEventsByGoal.get(goalId) ?? []).slice(0, cap);
+    return latestEventsForGoal(ledgerEvents, goalId, cap);
+  };
+
+  if (focusedGoalId && goalsById.has(focusedGoalId)) {
+    const focused = goalsById.get(focusedGoalId)!;
+    const auditor = ledgerState
+      ? reconstructed.goals.get(focusedGoalId)?.latestAuditorResult ?? reconstructed.terminalGoals.get(focusedGoalId)?.latestAuditorResult
+      : undefined;
+    lines.push(`[FOCUSED GOAL]`);
+    lines.push(buildGoalCompactSummary(focused, recentEventsFor(focusedGoalId, capEventsPerGoal), auditor));
+    lines.push("");
+  }
+
+  const otherOpen = openGoals.filter((g) => g.id !== focusedGoalId);
+  if (otherOpen.length > 0) {
+    lines.push(`[OTHER OPEN GOALS — ${otherOpen.length} total]`);
+    for (const goal of otherOpen.slice(0, capOpenGoals)) {
+      lines.push(`- ${goal.id} — ${statusLabel(goal)} — ${truncateText(goal.objective, 120)}`);
+    }
+    if (otherOpen.length > capOpenGoals) {
+      lines.push(`... and ${otherOpen.length - capOpenGoals} more`);
+    }
+    lines.push("");
+  }
+
+  if (reconstructed.terminalGoals.size > 0) {
+    lines.push(`[TERMINAL GOALS — ${reconstructed.terminalGoals.size} completed or aborted]`);
+    for (const [goalId, state] of reconstructed.terminalGoals) {
+      const label = state.latestStatus === "complete" ? "completed" : "aborted";
+      lines.push(`- ${goalId} — ${label}${state.completedAt ? ` at ${state.completedAt}` : ""}${state.abortedAt ? ` at ${state.abortedAt}` : ""}`);
+    }
+    lines.push("");
+  }
+
+  if (openGoals.length === 0 && reconstructed.terminalGoals.size === 0) {
+    lines.push("[NO GOALS]");
+    lines.push("No open or terminal goals recorded in this session.");
+  }
+
+  lines.push("[INSTRUCTION]");
+  lines.push("Continue from the focused goal above, or ask the user to run /goal-focus.");
+  lines.push("Do not rely on chat memory for goal state; use the facts above.");
+
+  return lines.join("\n");
+}
+
+/**
+ * PR E §62: post-compaction DELTA for the focused goal. The active system
+ * goal block already contains the objective, full policy, task gate, and
+ * verification contract — this delta adds only what compaction may have
+ * lost: the execution focus, a bounded recent-events tail, the latest
+ * unresolved auditor finding, and the other-open-goals count.
+ */
+export function buildPostCompactionGoalDelta(args: {
+  goal: GoalRecord;
+  ledgerEvents: GoalLedgerEvent[];
+  otherOpenCount: number;
+}): string {
+  const { goal, ledgerEvents, otherOpenCount } = args;
+  const lines: string[] = [];
+  lines.push(`[POST-COMPACTION RESYNC goalId=${goal.id}]`);
+  // Execution focus (with contract) — the one thing memory must not lose.
+  if (goal.currentTaskId && goal.taskList) {
+    const current = taskIndex(goal.taskList.tasks).byId.get(goal.currentTaskId);
+    if (current) {
+      lines.push(`Current task: ${truncateText(current.id, 80)} — ${truncateText(current.title, 180)}${current.verificationContract ? ` (contract: ${truncateText(current.verificationContract, 600)})` : ""}`);
+      if (current.id.length > 80 || current.title.length > 180 || (current.verificationContract?.length ?? 0) > 600) lines.push('Retrieve omitted task requirements with get_goal(section="tasks") before continuing.');
+    }
+  }
+  // Bounded recent-event tail.
+  const recent = latestEventsForGoal(ledgerEvents, goal.id, 5);
+  if (recent.length > 0) {
+    lines.push("Recent events:");
+    for (const event of recent) {
+      lines.push(`  ${event.at.slice(11, 19)} ${event.type}`);
+    }
+  }
+  // Latest unresolved auditor finding.
+  const audit = latestAuditorResultForGoal(ledgerEvents, goal.id);
+  if (latestAuditForGoal(ledgerEvents, goal.id)?.type === "audit_started") lines.push("Latest audit: no recorded result.");
+  if (audit && audit.verdict === "disapproved") {
+    lines.push(`Latest unresolved auditor finding: ${audit.report.slice(0, 300)}`);
+  }
+  lines.push(`Other open goals: ${otherOpenCount}`);
+  lines.push("Continue from authoritative files and goal storage.");
+  return lines.join("\n");
+}

package/extensions/goal-completion.ts

@@ -0,0 +1,173 @@
+import {randomUUID} from "node:crypto";
+import {type AgentToolResult, type ExtensionContext} from "@earendil-works/pi-coding-agent";
+import {GOAL_AUDIT_ENTRY, detailedSummary, goalDetails} from "./goal-format.ts";
+import {buildCompletionReport, buildTaskSummary, taskCompletionBlockWarning, validateGoalCompletion} from "./goal-policy.ts";
+import {loadGoalSettings, loadGoalSettingsFileConfig} from "./goal-settings.ts";
+import {runGoalCompletionAuditor, type GoalAuditorResult} from "./goal-auditor.ts";
+import {nowIso, type GoalRecord} from "./goal-record.ts";
+import {latestEventsForGoal, latestSettledAuditorResultForGoal, goalRuntimeEvents, type GoalLedgerEvent} from "./goal-ledger.ts";
+import {mergeGoalPromptFromDisk} from "./storage/goal-files.ts";
+import {isStaleExtensionContextError} from "./goal-session-safety.ts";
+import {goalStorageContext} from "./storage/goal-root.ts";
+import {showEscapeDialog} from "./widgets/goal-escape-dialog.ts";
+import type {GoalCore, ActiveGoalAudit} from "./goal-state.ts";
+
+type CompletionOptions = {
+ goal: GoalRecord;
+ focus: {goalId: string; revision: number};
+ auditorReport?: string;
+ skipped?: string;
+ userBypass?: boolean;
+};
+
+/** One completion transaction, using current usage and the audited disk revision. */
+function commitCompletion(core: GoalCore, ctx: ExtensionContext, opts: CompletionOptions): AgentToolResult<unknown> {
+ if (!core.isFocusedOperationCurrent(opts.focus)) return core.focusedOperationCancelledResult("Goal completion", opts.focus);
+ core.reconcileFocusedGoalFromDisk(ctx);
+ if (core.state.goal?.revision !== opts.goal.revision) return {
+  content: [{type: "text", text: "Goal completion failed: the goal changed during the audit. Recheck the current requirements and retry."}],
+  details: goalDetails(core.state.goal), terminate: false,
+ };
+ core.accountProgress(ctx);
+ let result;
+ try {
+  result = core.goalService.apply(ctx, {
+   reconcile: false, focusToken: opts.focus,
+   mutate: current => ({...current, status: "complete", stopReason: "agent", updatedAt: nowIso()}),
+  });
+ } catch (error) {result = {ok: false as const, message: error instanceof Error ? error.message : String(error)};}
+ if (!result.ok) return {
+  content: [{type: "text", text: `Goal completion failed: ${result.message}. The goal was not completed.`}],
+  details: goalDetails(core.state.goal), terminate: false,
+ };
+ core.runtime.markTurnStopped(result.goal.id);
+ core.updateUI(ctx);
+ const report = buildCompletionReport({detailedSummary: detailedSummary(core.state.goal), auditorReport: opts.auditorReport, auditSkippedReason: opts.skipped, taskSummary: core.state.goal?.taskList ? buildTaskSummary(core.state.goal.taskList) : null});
+ return {content: [{type: "text", text: report + (opts.userBypass ? "\n\nThe goal is complete. Provide a final summary of what was accomplished." : "")}], details: goalDetails(core.state.goal), ...(opts.userBypass ? {} : {terminate: true})};
+}
+
+/** Capture one audit owner; every outcome and callback belongs to that owner. */
+export async function runGoalCompletionFlow(core: GoalCore, ctx: ExtensionContext, completionSummary?: string): Promise<AgentToolResult<unknown>> {
+ const flushError = core.goalService.flushForAudit(ctx);
+ if (flushError) return {content: [{type: "text", text: flushError}], details: goalDetails(core.state.goal)};
+ core.reconcileFocusedGoalFromDisk(ctx);
+ const gate = validateGoalCompletion({goal: core.state.goal, runningGoalId: core.runningGoalId});
+ if (!gate.ok) return {content: [{type: "text", text: gate.message}], details: goalDetails(core.state.goal)};
+ if (!core.state.goal) throw new Error("Goal disappeared during completion validation.");
+ const settings = loadGoalSettings(ctx.cwd);
+ const warning = !settings.disableTasks && core.state.goal.taskList ? taskCompletionBlockWarning(core.state.goal.taskList) : null;
+ if (warning) return {content: [{type: "text", text: warning}], details: goalDetails(core.state.goal)};
+
+ const target = mergeGoalPromptFromDisk(ctx, core.state.goal);
+ const focus = core.focusedOperationToken(target.id);
+ const storage = goalStorageContext(ctx);
+ const config = loadGoalSettingsFileConfig(ctx.cwd);
+ const label = config.provider || config.model || config.thinkingLevel
+  ? `${config.provider ?? "default"}/${config.model ?? "default"}${config.thinkingLevel ? `:${config.thinkingLevel}` : ""}` : "default";
+ const auditId = randomUUID();
+ const append = (event: GoalLedgerEvent) => core.goalService.appendEvents(storage, [event], {immediate: true});
+ const message = (phase: string, text: string, auditor = label) => core.auditMessages.enqueue(ctx, {customType: GOAL_AUDIT_ENTRY, content: text, display: true, details: {phase, goalId: target.id, auditor}});
+ const cancelled = () => core.focusedOperationCancelledResult("Goal completion", focus);
+ const persistenceError = (): AgentToolResult<unknown> => ({isError: true, content: [{type: "text", text: "The audit outcome could not be persisted. The goal remains open; inspect the storage diagnostic and retry."}], details: goalDetails(core.state.goal), terminate: false});
+ append({type: "completion_requested", goalId: target.id, at: nowIso()});
+ core.activeAudit?.cancel("A newer completion attempt replaced this audit.");
+
+ const skipReason = target.skipAuditor ? "per-goal auditor disabled" : config.disabled ? "auditor disabled in settings" : undefined;
+ if (skipReason) {
+  if (!append({type: "audit_skipped", auditId, goalId: target.id, reason: "disabled", provider: config.provider, model: config.model, thinkingLevel: config.thinkingLevel, at: nowIso()})) return persistenceError();
+  message("skipped", `Goal completed — ${skipReason}.`);
+  return commitCompletion(core, ctx, {goal: target, focus, skipped: skipReason});
+ }
+
+ const run: ActiveGoalAudit = {
+  controller: new AbortController(), phase: "running",
+  cancel: reason => {
+   if (run.phase === "settling" || run.phase === "settled") return;
+   run.controller.abort();
+   settle({type: "audit_result", auditId, goalId: target.id, verdict: "error", report: reason, at: nowIso()});
+  },
+ };
+ const current = () => core.activeAudit === run && core.isFocusedOperationCurrent(focus) && run.phase !== "settled";
+ function settle(event: GoalLedgerEvent): boolean {
+  if (run.phase === "settling" || run.phase === "settled") return false;
+  run.phase = "settling";
+  try {return append(event);}
+  finally {
+   run.phase = "settled";
+   if (core.activeAudit === run) {
+    core.activeAudit = null;
+    core.stopAuditAnimation();
+    core.auditProgress = null;
+    core.goalWidgetComponentRef.current?.invalidate();
+   }
+  }
+ }
+ core.activeAudit = run;
+ try {
+  if (!append({type: "audit_started", auditId, goalId: target.id, provider: config.provider, model: config.model, thinkingLevel: config.thinkingLevel, at: nowIso()})) {
+   run.cancel("Audit could not start because its ledger entry failed.");
+   return persistenceError();
+  }
+  message("started", `Auditor: I am starting the independent completion audit.\nGoal id: ${target.id}\nAuditor model: ${label}`);
+  const startedAt = Date.now();
+  core.clearAuditResult();
+  core.auditProgress = {recentOutput: [], phase: "running", elapsedMs: 0, auditorLabel: label};
+  core.stopAuditAnimation();
+  core.auditAnimationTimer = setInterval(() => {
+   if (!current() || !core.auditProgress) return;
+   core.auditProgress.elapsedMs = Date.now() - startedAt;
+   core.goalWidgetComponentRef.current?.invalidate();
+  }, 80);
+  core.auditAnimationTimer.unref?.();
+  const ledger = goalRuntimeEvents(storage, target.id);
+  const tail = latestEventsForGoal(ledger, target.id, 8);
+  const previous = latestSettledAuditorResultForGoal(ledger, target.id);
+  let warmContext = tail.length ? `Recent goal events (from the shared ledger):\n${tail.map(e => `- ${e.at} ${e.type}${"taskId" in e ? ` (task ${e.taskId})` : ""}${"evidence" in e && e.evidence ? ` evidence: ${e.evidence}` : ""}`).join("\n")}` : null;
+  if (previous?.verdict === "disapproved") warmContext = `${warmContext ?? ""}\nPrevious rejection (verify whether resolved): ${previous.report.slice(0, 600)}`;
+  let auditor: GoalAuditorResult;
+  try {
+   auditor = await (core.dependencies.runCompletionAuditor ?? runGoalCompletionAuditor)({ctx, goal: target, detailedSummary: detailedSummary(target), completionSummary: completionSummary?.trim() || undefined, settings, warmContext, signal: run.controller.signal, onProgress: progress => {
+    if (!current() || run.phase !== "running") return;
+    core.auditProgress = {...progress, elapsedMs: Date.now() - startedAt};
+    core.goalWidgetComponentRef.current?.invalidate();
+   }});
+  } catch (error) {auditor = {approved: false, disapproved: false, output: "", error: error instanceof Error ? error.message : String(error)};}
+  if (!current()) return cancelled();
+  core.stopAuditAnimation();
+  core.auditProgress = null;
+
+  if (run.controller.signal.aborted || auditor.error === "Auditor aborted.") {
+   run.phase = "awaiting-choice";
+   core.updateUI(ctx);
+   core.enterGoalModal();
+   let choice;
+   try {choice = await showEscapeDialog(ctx, target.objective);}
+   finally {if (current()) core.exitGoalModal();}
+   if (!current()) return cancelled();
+   if (choice === "complete_without_audit") {
+    if (!settle({type: "audit_skipped", auditId, goalId: target.id, reason: "user_aborted", provider: config.provider, model: config.model, thinkingLevel: config.thinkingLevel, at: nowIso()})) return persistenceError();
+    message("skipped", "Goal completed — user bypassed audit via Escape.");
+    return commitCompletion(core, ctx, {goal: target, focus, skipped: "auditor bypassed (user pressed Escape during audit)", userBypass: true});
+   }
+   if (!settle({type: "audit_result", auditId, goalId: target.id, verdict: "error", report: "Audit aborted — the goal remains active and work continues.", at: nowIso()})) return persistenceError();
+   core.updateUI(ctx);
+   return {content: [{type: "text", text: "Audit aborted — the goal remains active and work continues."}], details: goalDetails(core.state.goal)};
+  }
+  const verdict = auditor.approved ? "approved" : auditor.error ? "error" : "disapproved";
+  if (!settle({type: "audit_result", auditId, goalId: target.id, verdict, report: auditor.output || auditor.error || "Auditor produced no output.", at: nowIso()})) return persistenceError();
+  core.setAuditResult(verdict, auditor.output || auditor.error || "Auditor produced no output.");
+  if (!auditor.approved) {
+   const text = ["Goal audit rejected.", "", "Goal completion rejected by independent auditor.", auditor.model ? `Auditor model: ${auditor.model}${auditor.thinkingLevel ? `:${auditor.thinkingLevel}` : ""}` : undefined, auditor.error ? `Auditor error: ${auditor.error}` : undefined, "", auditor.output || "Auditor produced no approval marker."].filter(line => line !== undefined).join("\n");
+   message("rejected", text, auditor.model);
+   return {content: [{type: "text", text}], details: goalDetails(core.state.goal)};
+  }
+  message("approved", ["Auditor: I approve this completion claim.", auditor.model ? `Auditor model: ${auditor.model}${auditor.thinkingLevel ? `:${auditor.thinkingLevel}` : ""}` : undefined, "", auditor.output || "Auditor approved completion."].filter(line => line !== undefined).join("\n"), auditor.model);
+  return commitCompletion(core, ctx, {goal: target, focus, auditorReport: auditor.output});
+ } catch (error) {
+  if (isStaleExtensionContextError(error)) return cancelled();
+  throw error;
+ } finally {
+  // Covers a dialog/host exception as well as late cancellation; settlement is claimed once.
+  if (run.phase !== "settled") run.cancel("Completion audit ended without a terminal result.");
+ }
+}

package/extensions/goal-context.ts

@@ -0,0 +1,12 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+/** Filter after Pi restores system and tool state, including on the first request. */
+export function registerGoalContext(
+	pi: ExtensionAPI,
+	transform: (messages: unknown[], ctx: ExtensionContext) => unknown[] | null,
+): void {
+	pi.on("context_with_system", (event, ctx) => {
+		const messages = transform(event.messages, ctx);
+		return messages === null ? undefined : { messages: messages as typeof event.messages };
+	});
+}

package/extensions/goal-contract.ts

@@ -0,0 +1,58 @@
+/**
+ * Small record/input parser (Stage 5 of the hardening plan): verification
+ * contract extraction and objective prompt-safety live here, outside the
+ * (the historical goal-draft module was removed).
+ */
+
+const VERIFICATION_CONTRACT_RE = /^Verification contract:\s*(.+)$/im;
+
+/**
+ * Extract a `Verification contract:` section from a goal objective and return
+ * the cleaned objective (without the contract section) and the contract text.
+ *
+ * The contract section is a single line matching:
+ *   Verification contract: <text>
+ *
+ * It can appear anywhere in the objective, but by convention it goes after
+ * the other sections (like Success criteria, Boundaries, Constraints).
+ *
+ * If no contract section is found, `verificationContract` is undefined.
+ */
+export function extractVerificationContract(objective: string): { objective: string; verificationContract?: string } {
+	const lines = objective.replace(/\r/g, "").split("\n");
+	let contract: string | undefined;
+	const filtered: string[] = [];
+
+	for (const line of lines) {
+		const trimmed = line.trim();
+		const m = VERIFICATION_CONTRACT_RE.exec(trimmed);
+		if (m) {
+			contract = m[1]!.trim();
+			// Skip this line — don't add it to the cleaned objective
+		} else {
+			filtered.push(line);
+		}
+	}
+
+	return {
+		objective: filtered.join("\n"),
+		verificationContract: contract || undefined,
+	};
+}
+
+/** Escape untrusted-objective tags so injected objectives cannot break prompts. */
+export function promptSafeObjective(objective: string): string {
+	return objective.replace(/<\/?untrusted_objective>/gi, (tag) => tag.replace(/</g, "&lt;").replace(/>/g, "&gt;"));
+}
+
+/**
+ * A Sisyphus objective must express ordered work: numbered items in the body
+ * ("1)", "1.", "1:") or explicit "Step N" markers. Without any such marker the
+ * objective cannot be executed in patient ordered fashion, so the guided
+ * /sisyphus flow (or a corrected /sisyphus-direct argument) is required.
+ */
+export function sisyphusObjectiveSufficient(objective: string): boolean {
+	// Ordered work can be written inline ("Refactor: 1) extract. 2) wire.")
+	// or as a numbered block; any explicit item marker counts as sufficient.
+	return /\b\d{1,2}\s*[).:]|\bstep\s*\d+/i.test(objective.trim());
+}

package/extensions/goal-controls.ts

@@ -0,0 +1,202 @@
+import type { KeyId } from "@earendil-works/pi-tui";
+
+/** Stable action IDs; invocation names are preferences, not lifecycle logic. */
+export const GOAL_COMMANDS = [
+	["goal", "Draft a goal", "Start a guided goal with confirmation."],
+	["sisyphus", "Draft a Sisyphus goal", "Draft an ordered, persistent goal."],
+	["goal-direct", "Start a goal directly", "Create a goal immediately from the supplied objective."],
+	["sisyphus-direct", "Start Sisyphus directly", "Create an ordered goal immediately."],
+	["goal-tweak", "Revise the goal", "Revise the objective or budget, with confirmation."],
+	["goal-pause", "Pause the goal", "Pause the goal and stop the current turn."],
+	["goal-resume", "Resume the goal", "Continue and renew the autonomous run allowance."],
+	["goal-clear", "Clear the goal", "Archive the goal after confirmation."],
+	["goal-list", "List goals", "Show the open goals in this project."],
+	["goal-status", "Show goal status", "Show progress; accepts verbose and health."],
+	["goal-refresh", "Refresh goal state", "Read goal files and settings again."],
+	["goal-recovery", "Recover goal files", "Inspect recovery information; repair requires confirmation."],
+	["goal-focus", "Focus a goal", "Choose the goal this session works on."],
+	["goal-unfocus", "Unfocus the goal", "Detach this session, leaving the shared goal open."],
+	["goal-settings", "Goal settings", "Open settings. /goal-settings always remains available."],
+	["goal-cancel", "Cancel a draft", "Cancel the guided draft without creating a goal."],
+] as const;
+export type GoalCommandId = typeof GOAL_COMMANDS[number][0];
+export type GoalCommands = Partial<Record<GoalCommandId, string[]>>;
+export const GOAL_COMMAND_INPUTS: Partial<Record<GoalCommandId, string>> = {
+	"goal-direct": "Goal objective", "sisyphus-direct": "Sisyphus objective and ordered steps", "goal-tweak": "Change to the goal",
+};
+export type GoalKeybinding = KeyId | KeyId[];
+export type PauseOrder = "together" | "goal-first" | "turn-first";
+
+export const PAUSE_ORDERS: ReadonlyArray<{ id: PauseOrder; label: string; help: string }> = [
+	{ id: "together", label: "Goal and turn together", help: "One press pauses the goal and stops the current turn." },
+	{ id: "goal-first", label: "Goal first", help: "First: pause the goal; the turn finishes. Next: stop the turn." },
+	{ id: "turn-first", label: "Turn first", help: "First: stop the turn and wait. Next: pause the goal. Resume or a message continues." },
+];
+
+export type GoalKeyContext = "global" | "compact" | "expanded" | "audit" | "dialog";
+export const GOAL_DIALOG_KEYS = {
+	confirm: "enter", cancel: "escape", up: "up", down: "down", next: ["tab", "right"], previous: ["shift+tab", "left"],
+	pageUp: "pageUp", pageDown: "pageDown", scrollUp: "ctrl+up", scrollDown: "ctrl+down", toggleAuditor: "a",
+} satisfies Record<string, GoalKeybinding>;
+export type GoalDialogAction = keyof typeof GOAL_DIALOG_KEYS;
+export interface GoalKeyAction {
+	path: string[];
+	label: string;
+	help: string;
+	context: GoalKeyContext;
+	defaults: GoalKeybinding;
+}
+const dashboard = (name: string, label: string, defaults: GoalKeybinding, context: GoalKeyContext, help: string): GoalKeyAction =>
+	({ path: ["keybindings", "dashboard", name], label, defaults, context, help });
+export const GOAL_KEY_ACTIONS: readonly GoalKeyAction[] = [
+	{ path: ["keybindings", "pause"], label: "Pause / interrupt", defaults: "escape", context: "global", help: "Uses the chosen pause order. Dialogs, audit and expanded view take priority." },
+	{ path: ["keybindings", "toggleAuditor"], label: "Toggle completion auditor", defaults: "ctrl+shift+a", context: "global", help: "Enable or disable the independent auditor for the focused goal." },
+	dashboard("toggleExpand", "Expand / collapse dashboard", "ctrl+shift+t", "global", "Switch between the compact and expanded task list."),
+	dashboard("scrollUp", "Compact: scroll up", "ctrl+shift+up", "compact", "Scroll only when the compact task list overflows."),
+	dashboard("scrollDown", "Compact: scroll down", "ctrl+shift+down", "compact", "Scroll only when the compact task list overflows."),
+	dashboard("scrollPageUp", "Compact: page up", "ctrl+shift+pageUp", "compact", "Scroll the compact list by one page."),
+	dashboard("scrollPageDown", "Compact: page down", "ctrl+shift+pageDown", "compact", "Scroll the compact list by one page."),
+	dashboard("scrollFirst", "Compact: first task", "ctrl+shift+home", "compact", "Go to the start of the compact task list."),
+	dashboard("scrollLast", "Compact: last task", "ctrl+shift+end", "compact", "Go to the end of the compact task list."),
+	dashboard("collapse", "Expanded: close dashboard", "escape", "expanded", "Close the expanded view without pausing work."),
+	dashboard("up", "Expanded: scroll up", "up", "expanded", "Move up in the expanded task list."),
+	dashboard("down", "Expanded: scroll down", "down", "expanded", "Move down in the expanded task list."),
+	dashboard("pageUp", "Expanded: page up", "pageUp", "expanded", "Move one page up."),
+	dashboard("pageDown", "Expanded: page down", "pageDown", "expanded", "Move one page down."),
+	dashboard("first", "Expanded: first task", "home", "expanded", "Go to the start of the expanded task list."),
+	dashboard("last", "Expanded: last task", "end", "expanded", "Go to the end of the expanded task list."),
+	{ path: ["keybindings", "interruptAudit"], label: "Interrupt the audit", defaults: "escape", context: "audit", help: "Stop the audit and show the existing completion choices." },
+	...Object.entries(GOAL_DIALOG_KEYS).map(([name, defaults]): GoalKeyAction => ({
+		path: ["keybindings", "dialog", name], label: `Dialog: ${{ confirm: "confirm selection", cancel: "cancel / go back", up: "previous option", down: "next option", next: "next question", previous: "previous question", pageUp: "page up", pageDown: "page down", scrollUp: "scroll up", scrollDown: "scroll down", toggleAuditor: "toggle auditor" }[name]}`,
+		defaults, context: "dialog", help: "Applies to goal questionnaires and confirmations. Settings navigation and text editing keep Pi's controls.",
+	})),
+	...GOAL_COMMANDS.map(([id, label, help]): GoalKeyAction => ({ path: ["keybindings", "commands", id], label, help, context: "global", defaults: [] })),
+];
+
+export function valueAtPath(value: unknown, path: readonly string[]): unknown {
+	let cursor = value;
+	for (const part of path) {
+		if (!cursor || typeof cursor !== "object") return undefined;
+		cursor = (cursor as Record<string, unknown>)[part];
+	}
+	return cursor;
+}
+export function bindingKeys(binding: GoalKeybinding | undefined): KeyId[] {
+	return binding === undefined ? [] : Array.isArray(binding) ? binding : [binding];
+}
+export function keyActionBinding(settings: unknown, action: GoalKeyAction): GoalKeybinding {
+	return (valueAtPath(settings, action.path) as GoalKeybinding | undefined) ?? action.defaults;
+}
+
+/** Used only while editing, so validation can consider both scopes before a write. */
+export function resolveGoalControls(global: unknown, project?: unknown): { commands: GoalCommands; keybindings: Record<string, unknown> } {
+	const value = { commands: {} as GoalCommands, keybindings: {} as Record<string, unknown> };
+	for (const [id] of GOAL_COMMANDS) value.commands[id] = (valueAtPath(project, ["commands", id]) ?? valueAtPath(global, ["commands", id]) ?? [id]) as string[];
+	for (const action of GOAL_KEY_ACTIONS) {
+		let target: Record<string, unknown> = value;
+		for (const part of action.path.slice(0, -1)) target = (target[part] ??= {}) as Record<string, unknown>;
+		target[action.path.at(-1)!] = valueAtPath(project, action.path) ?? valueAtPath(global, action.path) ?? action.defaults;
+	}
+	return value;
+}
+
+const specialKeys = new Map("escape enter tab space backspace delete insert clear home end pageUp pageDown up down left right f1 f2 f3 f4 f5 f6 f7 f8 f9 f10 f11 f12".split(" ").map(key => [key.toLowerCase(), key]));
+/** Accept the public Pi key grammar, canonicalizing aliases and modifier order. */
+export function normalizeGoalKey(value: unknown): KeyId | undefined {
+	if (typeof value !== "string" || !value.trim()) return undefined;
+	let text = value.trim().toLowerCase();
+	if (text === "esc") text = "escape";
+	if (text === "return") text = "enter";
+	const modifiers: string[] = [];
+	while (/^(ctrl|shift|alt|super)\+/.test(text)) {
+		const i = text.indexOf("+");
+		const modifier = text.slice(0, i);
+		if (modifiers.includes(modifier)) return undefined;
+		modifiers.push(modifier); text = text.slice(i + 1);
+	}
+	text = text === "esc" ? "escape" : text === "return" ? "enter" : text;
+	const key = specialKeys.get(text) ?? (/^[a-z0-9`\-=[\]\\;'",./!@#$%^&*()_+|~{}:<>?]$/.test(text) ? text : undefined);
+	if (!key) return undefined;
+	return [...["ctrl", "alt", "shift", "super"].filter(m => modifiers.includes(m)), key].join("+") as KeyId;
+}
+export function parseGoalKeybinding(value: unknown): GoalKeybinding | undefined {
+	if (typeof value === "string") return normalizeGoalKey(value);
+	if (!Array.isArray(value) || value.length > 16) return undefined;
+	const keys = value.map(normalizeGoalKey);
+	return keys.every((key): key is KeyId => key !== undefined) ? [...new Set(keys)] : undefined;
+}
+
+export function sameGoalKey(a: string, b: string, kitty = false): boolean {
+	const physical = (key: string) => kitty ? key : ({ "ctrl+[": "escape", "ctrl+m": "enter", "ctrl+i": "tab", "ctrl+h": "backspace", "ctrl+?": "backspace", "ctrl+@": "ctrl+space" }[key] ?? key);
+	return physical(normalizeGoalKey(a) ?? a) === physical(normalizeGoalKey(b) ?? b);
+}
+
+const PI_COMMAND_ROOTS = new Set("settings model tree thinking scoped-models export import share bug copy name session changelog hotkeys fork clone trust login logout new compact resume reload quit".split(" "));
+export function normalizeCommandPath(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const route = value.trim().replace(/^\//, "").replace(/\s+/g, " ");
+	return route.length <= 96 && /^[a-z][a-z0-9_-]*(?: [a-z][a-z0-9_-]*)*$/.test(route) ? route : undefined;
+}
+export function parseCommandPaths(value: unknown): string[] | undefined {
+	if (!Array.isArray(value) || value.length > 16) return undefined;
+	const paths = value.map(normalizeCommandPath);
+	return paths.every((route): route is string => route !== undefined) ? [...new Set(paths)] : undefined;
+}
+export function commandPaths(commands: GoalCommands | undefined, id: GoalCommandId): string[] {
+	return commands?.[id] ?? [id];
+}
+export function commandHint(id: GoalCommandId, commands?: GoalCommands): string {
+	const first = commandPaths(commands, id)[0];
+	if (!first && id === "goal-settings") return "/goal-settings";
+	return first ? `/${first}` : `/goal-settings controls to enable ${GOAL_COMMANDS.find(([action]) => action === id)![1].toLowerCase()}`;
+}
+const commandReference = new RegExp(`/(${GOAL_COMMANDS.map(([id]) => id).sort((a, b) => b.length - a.length).join("|")})(?![a-z0-9_-])`, "g");
+/** For standing instructions only: objectives and other user text stay verbatim. */
+export function commandInstructions(text: string, commands?: GoalCommands): string {
+	return commands ? text.replace(commandReference, (_match, id: GoalCommandId) => commandHint(id, commands)) : text;
+}
+export interface GoalCommandRoute { path: string; id: GoalCommandId }
+export function commandRoutes(commands: GoalCommands | undefined): GoalCommandRoute[] {
+	const routes = GOAL_COMMANDS.flatMap(([id]) => commandPaths(commands, id).map(path => ({ path, id })));
+	if (!routes.some(route => route.path === "goal-settings")) routes.push({ path: "goal-settings", id: "goal-settings" });
+	return routes.sort((a, b) => b.path.length - a.path.length);
+}
+export function commandProblems(commands: GoalCommands | undefined, occupiedRoots: readonly string[] = []): string[] {
+	const problems: string[] = [];
+	const owners = new Map<string, GoalCommandId>();
+	for (const [id] of GOAL_COMMANDS) for (const route of commandPaths(commands, id)) {
+		const root = route.split(" ")[0]!;
+		if (PI_COMMAND_ROOTS.has(root) || occupiedRoots.includes(root)) problems.push(`/${root} belongs to Pi or another command.`);
+		if (root === "goal-settings" && id !== "goal-settings") problems.push("/goal-settings is reserved for settings recovery.");
+		const owner = owners.get(route);
+		if (owner && owner !== id) problems.push(`/${route} is already assigned to ${owner}.`);
+		owners.set(route, id);
+	}
+	return [...new Set(problems)];
+}
+export function matchCommandRoute(routes: readonly GoalCommandRoute[], root: string, args: string): { id: GoalCommandId; args: string } | undefined {
+	const input = root + (args ? ` ${args}` : "");
+	for (const route of routes) {
+		const matched = new RegExp(`^${route.path.split(" ").join("\\s+")}(?=$|\\s)`).exec(input);
+		if (matched) return { id: route.id, args: input.slice(matched[0].length).trimStart() };
+	}
+	return undefined;
+}
+
+/** Global keys overlap both dashboard modes; view-specific handlers own Escape first. */
+export function keybindingProblems(settings: unknown, edited?: GoalKeyAction, kitty = false): string[] {
+	const problems: string[] = [];
+	for (let i = 0; i < GOAL_KEY_ACTIONS.length; i++) {
+		const a = GOAL_KEY_ACTIONS[i]!;
+		for (const b of GOAL_KEY_ACTIONS.slice(i + 1)) {
+			if (edited && a !== edited && b !== edited) continue;
+			if ((a.context === "dialog") !== (b.context === "dialog")) continue;
+			if (a.context !== b.context && a.context !== "global" && b.context !== "global") continue;
+			// These view-specific actions deliberately take priority over pause.
+			if ((a.path[1] === "pause" || b.path[1] === "pause") && [a, b].some(x => x.path[1] === "interruptAudit" || x.path[2] === "collapse")) continue;
+			const overlap = bindingKeys(keyActionBinding(settings, a)).filter(key => bindingKeys(keyActionBinding(settings, b)).some(bound => sameGoalKey(key, bound, kitty)));
+			if (overlap.length) problems.push(`${overlap.join(", ")} is also assigned to ${edited === b ? a.label : b.label}.`);
+		}
+	}
+	return [...new Set(problems)];
+}