pi-goal-x 0.32.3 → 0.33.0

package/docs/advanced-usage.md

@@ -4,7 +4,13 @@ For installation, goal workflows, commands and the settings overview, see the [R
 
 ## Automatic continuation and optional execution contracts
 
-Active goals continue automatically after successful executions, including reasoning-only responses and final-task verification. No tool call, task update, scheduling declaration, or cooldown is required. Unproductive loops remain possible; optional run limits and token budgets still apply.
+Active goals continue automatically after successful executions, including reasoning-only responses and final-task verification. No tool call, task update, or scheduling declaration is required.
+
+Default continuation is immediate. To slow repeated replies without recognized work, enable **slow repeated idle replies (opt-in)** under Advanced execution in `/goal-settings` (`idleContinuationBackoff: true`). Use the scope switch to choose a global default or a project override. An explicit project `false` overrides global `true`; removing the override restores inheritance.
+
+When enabled, one execution without recognized work continues immediately. Further such executions wait 30, 60, 120, 240, then 300 seconds between attempts. Work observed anywhere in the execution or a change to the objective, requirements or tasks resets the delay. Goal inspection, echo-only calls, accounting and scheduling declarations alone do not reset it. This heuristic may delay reasoning or unfamiliar custom tools, and repeated recognized tool calls can bypass it. It reduces request rate; it does not guarantee progress or finite spending. Use a run allowance or token budget for a hard limit.
+
+The delay survives reloads and shows a relative time, local clock time and resume command. Waiting spends no autonomous runs or active time. Turning the option off cancels a pending delay promptly without renewing spent runs or resuming a paused goal. Turning it on starts observing a subsequent execution, rather than classifying work retroactively. Old saved delay metadata has no effect without opt-in. `/goal-resume` renews the run allowance and continues now; incoming user/producer messages remain ordinary host work outside that allowance. Strict waits and provider-error recovery keep their separate timing.
 
 Enable `strictExecutionContract: true` in `/goal-settings` or your global/project settings to require explicit ready/wait decisions. In that mode, a missing decision permits one repair prompt within the remaining allowance, then pauses. This is a user preference; agents should not enable it merely to continue.
 

package/docs/architecture.md

@@ -249,6 +249,28 @@ token/time intervals per turn; a goal never double-charges the same interval.
 `GoalRuntime` (goal-runtime.ts) owns continuation scheduling, the stale
 checkpoint state, the turn-stop guard, and one-shot steering reminders.
 
+`GoalScheduler` persists dispatch intent and allowance consumption. Default
+continuation is immediate. Explicit `idleContinuationBackoff=true` also records a
+bounded idle streak and earliest next attempt: one immediate continuation, then
+30 seconds doubling to five minutes. Work accumulates over the whole logical run;
+content snapshots exclude usage, revisions and scheduler writes. Disabled pacing
+skips those snapshots. Settings are rechecked at scheduling and admission; opting
+out removes saved delay metadata without renewing consumption. Resume and genuine
+host input reset pacing; strict waits and provider recovery remain independent.
+
+`goal-prompt-profile.ts` detects Pi's native custom-turn startup protocol and
+leaves its structured prompt/tool deltas intact on Pi 1.2 and newer. On older
+affected structured hosts, it projects the current public prompt and resolved
+tools through `context_with_system`, or the full `context` event where necessary.
+That fallback fixes the first request after direct creation, drafting, resume or
+reload without changing history or tool/result pairs. Classic hosts keep their
+native path. Current `agent_settled.aborted` events stop continuation/recovery and
+pause the associated goal, including cancellation before a provider request.
+
+Audit display messages flush only at idle settlement and remain scoped to their
+session. If Pi has invalidated a settlement context, the handler skips it before
+consuming continuation intent or changing the replacement session's queue.
+
 An optional `token_budget` may be set at creation. When accounted usage
 reaches the budget, `accountProgress` transitions the goal to the distinct
 `budget_limited` status exactly once (status leaves `active`, so accounting

package/docs/controls.md

@@ -0,0 +1,140 @@
+# Commands and keys
+
+Open `/goal-settings` and choose **Controls**, or run `/goal-settings controls`.
+The screen has three sections: **Commands**, **Keys** and **Pausing**. Type to
+filter, use the arrow keys and Enter to edit, and Tab to switch sections.
+Page Up/Down moves through long lists; Home/End jumps to the first/last row.
+Ctrl+S switches between **This project** and **All projects**. The selected row shows
+whether its value comes from the project, global settings or the default.
+
+Changes are saved when you choose Save or confirm a recorded key. Escape backs
+out of an edit without saving. **Use inherited value** removes a project
+override; **Remove global override** restores the default. **Use default** pins
+the default in the selected scope. Each section also has a reset action that
+removes only that section's overrides in the selected scope.
+
+## Commands
+
+Each action has a preferred command followed by any aliases. Choose **Edit
+command paths** to replace them, **Add an alias** to keep the current spellings,
+or **Disable** to remove its command invocations. For example, add `/goal edit`
+to **Revise the goal** to use the existing confirmation workflow with that
+spelling. Arguments after the command path are passed through to the action.
+Subcommands appear in argument completion; the longest matching complete path
+wins. A routing-only root lists its available subcommands when called without
+a matching action.
+
+Command changes need a reload. The screen shows when changes are pending;
+Ctrl+R applies them while Pi is idle when controls were opened through a slash
+command. If controls were opened from a shortcut, close them and run `/reload`.
+Keys and pause order take effect immediately.
+
+`/goal-settings` always remains available as a recovery entry. You can give the
+settings action other spellings, but this entry cannot be removed. Pi command
+roots such as `/reload` and `/settings` are reserved. The editor checks conflicts
+with other commands before saving.
+For settings, **Recovery entry only** removes additional aliases while keeping
+`/goal-settings` available.
+
+The settings keys below are stable action IDs, even after renaming an invocation:
+
+| Action ID | Action |
+| --- | --- |
+| `goal` | Guided goal draft |
+| `sisyphus` | Guided Sisyphus draft |
+| `goal-direct` | Immediate goal creation |
+| `sisyphus-direct` | Immediate Sisyphus creation |
+| `goal-tweak` | Confirmed revision |
+| `goal-pause` | Pause goal and stop turn |
+| `goal-resume` | Resume and renew the run allowance |
+| `goal-clear` | Confirmed archival |
+| `goal-list` | List open goals |
+| `goal-status` | Status; also accepts `verbose` or `health` |
+| `goal-refresh` | Read state and settings again |
+| `goal-recovery` | Recovery report; also accepts `repair` |
+| `goal-focus` | Choose a goal |
+| `goal-unfocus` | Detach this session |
+| `goal-settings` | Settings and controls |
+| `goal-cancel` | Cancel a draft |
+
+## Keys
+
+Choose an action under **Keys**, then record a key or edit its Pi key names.
+**Record another key** adds a second binding. **Disable** leaves it unbound.
+Conflicts are checked before saving; errors leave your input available to fix.
+Use a free key or change a conflicting Pi binding in its `keybindings.json`.
+
+Every public goal shortcut is listed: pause, audit interruption, auditor toggle,
+dashboard expansion, compact scrolling, expanded navigation, and goal dialog
+controls. Each command action can also have a shortcut, independently of its
+slash command names. A shortcut for direct creation or revision asks for the
+objective or change before invoking the usual workflow.
+
+Goal dialog controls apply to questionnaires and confirmation dialogs. They
+have their own context, so the same key can confirm a dialog and pause a live
+goal. Text editing and the settings screen use Pi's usual UI controls. The
+settings screen remains usable when you change goal dialog navigation.
+While typing an answer, letters and Pi's editing keys keep editing text. Escape
+leaves the answer editor; free custom keys such as F7 can do the same.
+
+Pi key names include `escape`, `f6`, `ctrl+alt+p`, `pageUp` and `super+k`. Multiple
+keys can be separated with commas. For a comma key combined with other bindings,
+the text editor also accepts a JSON key list, for example `["ctrl+,", "f6"]`.
+Existing comma-key lists reopen in this form so they can be saved unchanged.
+Terminals must report a key before Pi can use it; some modifier combinations
+require the Kitty keyboard protocol. See [Pi's keybinding reference](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/docs/keybindings.md).
+
+## Pausing
+
+The default is still Escape, with **Goal and turn together**. An open dialog
+owns its input; closing the expanded dashboard or interrupting an audit takes
+priority over pausing in that view.
+
+| Pause order | First press | Next press |
+| --- | --- | --- |
+| Goal and turn together | Pause the goal and stop the turn | Pi's normal interrupt |
+| Goal first | Pause the goal; let the current turn finish | Stop the remaining turn |
+| Turn first | Stop the turn and wait for the user, keeping the goal active | Pause the goal |
+
+Goal first finishes the current Pi turn, then stops before another model
+request. A turn-only stop holds automatic continuation, provider recovery and wake-ups.
+It does not spend another run allowance. Resume or send a new user message to
+continue. Reloading an interrupted autonomous run does not replay it.
+
+When you move the pause key away from Pi's interrupt key, Pi's interrupt stops
+the turn and waits for you without pausing the goal. The configured pause key
+uses the selected order. The explicit **Pause the goal** command always stops
+both the goal and its turn, including a turn left running by **Goal first**.
+
+## Settings files
+
+The UI writes the existing sparse settings layers:
+
+- Global: `${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-goal-x-settings.json`.
+- Project: `<project>/.pi/pi-goal-x-settings.json`.
+
+Project leaves override global leaves. Missing leaves inherit; an empty list
+explicitly disables an action. Existing `keybindings.dashboard` settings keep
+their meaning. For example:
+
+```json
+{
+  "commands": {
+    "goal-tweak": ["goal-tweak", "goal edit"],
+    "goal-resume": ["work continue"]
+  },
+  "pauseOrder": "turn-first",
+  "keybindings": {
+    "pause": ["f6", "ctrl+alt+p"],
+    "toggleAuditor": "ctrl+alt+a",
+    "interruptAudit": "escape",
+    "dashboard": { "toggleExpand": "ctrl+alt+t" },
+    "dialog": { "confirm": "enter", "cancel": "escape" },
+    "commands": { "goal-settings": "f10", "goal-status": [] }
+  }
+}
+```
+
+Use `/goal-refresh` after external key or pause-order edits, and `/reload` after
+external command edits. Verbose goal status reports the effective controls and
+their sources. Developer-only `PI_GOAL_DEBUG` shortcuts are unchanged.

package/docs/prompt-caching.md

@@ -14,7 +14,9 @@ For Anthropic-style explicit caching, the extension moves Pi's existing cache_co
 
 Execution tools already use an idempotent profile: goal progress, focus, and lifecycle changes do not change schemas. Explicit switches into/out of drafting and changes to disableTasks can change tools and legitimately rebuild the cache. Drafting messages are appended to conversation history. Isolated auditor and Oracle sessions already use fixed instructions/tool profiles and place goal-specific evidence in their user messages; their tool loops retain history. They have separate sessions and use Pi's cache defaults. Opting these sessions into project resources also opts into any behavior from those resources.
 
-Cache reuse can still be interrupted by Pi compaction, branch/session changes, model/provider switches, other extensions changing earlier content, changed tool schemas, provider expiry, minimum-length or breakpoint-lookback limits, or routing. The extension cannot guarantee a hit rate or a particular cost reduction. The supported Pi range is 0.83 through 0.87. Validation covers each supported minor; development dependencies pin 0.87.0.
+Cache reuse can still be interrupted by Pi compaction, branch/session changes, model/provider switches, other extensions changing earlier content, changed tool schemas, provider expiry, minimum-length or breakpoint-lookback limits, or routing. The extension cannot guarantee a hit rate or a particular cost reduction. The declared host range is in `package.json`; development dependencies pin Pi 1.4.0, which requires Node 22.19 or newer. Older supported hosts retain the extension's Node 22.15 floor.
+
+Pi 1.2 and newer prepare custom-triggered turns through the same public startup protocol as user prompts. The extension leaves their structured prompt and tool deltas intact, including additional sections supplied by other extensions. On older affected structured hosts, goal requests use the public full-context boundary to project the current prompt and resolved tools from the first request after drafting, direct creation, resume or reload. That fallback leaves persisted history and conversation messages intact; earlier structured hosts expose the boundary through `context`, and classic hosts retain their native path. Explicit tool-profile changes can still rebuild the prefix.
 
 Validation includes consecutive request-prefix regressions; actual Anthropic, Anthropic-compatible Chat Completions, OpenAI Chat Completions and Responses serialization with short/long/disabled retention; Bedrock payload-shape checks; lifecycle/tool-pair safety tests; and full SDK parent/auditor/Oracle payload captures. These tests stop before HTTP dispatch. They verify request construction, not live provider hit rates.
 

package/extensions/auditor-selector.ts

@@ -5,9 +5,11 @@
  * current-session/default choice (which clears the explicit provider/model),
  * authenticated models from the model registry (with a ✓ marker on the exact
  * current selection), and an advanced manual `provider/model` entry. The
- * thinking-level row offers the six levels or `(default)`.
+ * thinking-level row offers Pi's seven levels or `(default)`.
  */
 
+import { GOAL_THINKING_LEVELS } from "./goal-settings.ts";
+
 export type AuditorModelSummary = { provider: string; id: string; name?: string };
 
 export type AuditorChoice =
@@ -15,7 +17,7 @@ export type AuditorChoice =
 	| { kind: "model"; provider: string; model: string; label: string }
 	| { kind: "manual"; label: string };
 
-export const AUDITOR_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
+export const AUDITOR_THINKING_LEVELS = GOAL_THINKING_LEVELS;
 
 export function auditorModelLabel(model: AuditorModelSummary): string {
 	return `${model.provider}/${model.id}${model.name && model.name !== model.id ? ` — ${model.name}` : ""}`;

package/extensions/goal-auditor.ts

@@ -14,7 +14,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import type { GoalRecord, GoalTask, GoalTaskList } from "./goal-record.ts";
 import { countTaskSubtree } from "./goal-task-count.ts";
-import { loadGoalSettings, type GoalSettings, type ThinkingLevel } from "./goal-settings.ts";
+import { GOAL_THINKING_LEVELS, loadGoalSettings, type GoalSettings, type ThinkingLevel } from "./goal-settings.ts";
 import { statusLabel } from "./goal-core.ts";
 
 export interface AuditorProgress {
@@ -47,7 +47,7 @@ export interface GoalAuditorResult {
 	error?: string;
 }
 
-const THINKING_LEVELS = new Set(["off", "minimal", "low", "medium", "high", "xhigh"]);
+const THINKING_LEVELS = new Set<string>(GOAL_THINKING_LEVELS);
 
 function asNonEmptyString(value: unknown): string | undefined {
 	return typeof value === "string" && value.trim() ? value.trim() : undefined;

package/extensions/goal-commands.ts

@@ -1,3 +1,5 @@
+import { GOAL_COMMANDS, commandHint, commandPaths, commandProblems, commandRoutes, matchCommandRoute, type GoalCommandId } from "./goal-controls.ts";
+import { showGoalControls } from "./widgets/goal-controls-dialog.ts";
 import { goalStoragePath, goalStorageRoot } from "./storage/goal-root.ts";
 import { existsSync } from "node:fs";
 import path from "node:path";
@@ -75,12 +77,15 @@ import {
 import type { GoalCore } from "./goal-state.ts";
 
 /**
- * The curated twelve-command palette. /goal and /sisyphus begin guided
- * drafting; -direct commands are the explicit bypass. Every frequent lifecycle action is independently
- * registered so it appears in slash-command tab completion. No aliases.
+ * Stable command actions retain their lifecycle checks. Configured invocation
+ * paths are registered at load time; aliases and subcommands share the same
+ * handler and argument completion. /goal-settings remains the recovery entry.
  */
 export function registerGoalCommands(core: GoalCore): void {
 	const { pi } = core;
+	type Definition = { description: string; handler: (args: string, ctx: ExtensionContext) => Promise<void> };
+	const actions = new Map<GoalCommandId, Definition>();
+	const define = (id: GoalCommandId, definition: Definition): void => { actions.set(id, definition); };
 
 	async function chooseOpenGoal(ctx: ExtensionContext, title: string): Promise<GoalRecord | null> {
 		core.reconcileFocusedGoalFromDisk(ctx);
@@ -117,7 +122,7 @@ export function registerGoalCommands(core: GoalCore): void {
 	async function focusGoalCommand(ctx: ExtensionContext): Promise<void> {
 		const open = core.openGoals();
 		if (open.length === 0) {
-			ctx.ui.notify("No open goals. Use /goal to draft one, or /goal-direct <objective> to start immediately.", "warning");
+			ctx.ui.notify(`No open goals. Use ${commandHint("goal", core.loadedCommands)} to draft one, or ${commandHint("goal-direct", core.loadedCommands)} <objective> to start immediately.`, "warning");
 			return;
 		}
 		if (open.length === 1) {
@@ -172,7 +177,7 @@ export function registerGoalCommands(core: GoalCore): void {
 		}
 		if (!current) {
 			const openCount = otherOpenGoalCount(core.goalsById, null);
-			ctx.ui.notify(openCount > 0 ? buildUnfocusedOpenGoalsSummary(openCount) : detailedSummary(null), "info");
+			ctx.ui.notify(openCount > 0 ? buildUnfocusedOpenGoalsSummary(openCount) : detailedSummary(null, core.loadedCommands), "info");
 			return;
 		}
 		ctx.ui.notify(`Goal unfocused for this session. It remains open in .pi/goals: ${current.id}`, "info");
@@ -181,12 +186,12 @@ export function registerGoalCommands(core: GoalCore): void {
 	function handleDirectGoalSet(rawObjective: string, ctx: ExtensionContext, mode: GoalMode): void {
 		const raw = rawObjective.trim();
 		if (!raw) {
-			const command = mode === "sisyphus" ? "/sisyphus <objective>" : "/goal <objective>";
+			const command = `${commandHint(mode === "sisyphus" ? "sisyphus-direct" : "goal-direct", core.loadedCommands)} <objective>`;
 			ctx.ui.notify(`No objective provided. Use ${command}.`, "warning");
 			return;
 		}
 		if (mode === "sisyphus" && !sisyphusObjectiveSufficient(raw)) {
-			ctx.ui.notify("A Sisyphus objective needs ordered steps with per-step done criteria. Use /sisyphus for guided drafting, or provide numbered steps (1) ..., 2) ...) in the objective.", "warning");
+			ctx.ui.notify(`A Sisyphus objective needs ordered steps with per-step done criteria. Use ${commandHint("sisyphus", core.loadedCommands)} for guided drafting, or provide numbered steps (1) ..., 2) ...) in the objective.`, "warning");
 			return;
 		}
 		const settings = loadGoalSettings(ctx.cwd);
@@ -222,7 +227,7 @@ export function registerGoalCommands(core: GoalCore): void {
 			? `\n\n${formatCheckpointHealthReport(checkpointHealth, sessionFile)}`
 			: "";
 		ctx.ui.notify(
-			formatRecoveryReport(report) + checkpointSection,
+			formatRecoveryReport(report, core.loadedCommands) + checkpointSection,
 			report.healthy && (checkpointHealth?.legacyFull ?? 0) === 0 ? "info" : "warning",
 		);
 	}
@@ -262,6 +267,7 @@ export function registerGoalCommands(core: GoalCore): void {
 			? `goal-refresh: re-read caches from disk — ${changes.length} change(s):\n${changes.map((c) => `  - ${c}`).join("\n")}`
 			: "goal-refresh: no changes detected — caches were already current.";
 		ctx.ui.notify(text, "info");
+		core.scheduler.refreshSettings(ctx);
 		core.updateUI(ctx);
 	}
 
@@ -279,7 +285,10 @@ export function registerGoalCommands(core: GoalCore): void {
 		const health = /^\s*health\b/i.test(rawArgs);
 		const ledger = readGoalLedger(ctx);
 		const text = buildGoalStatusText({
+			commands: core.loadedCommands,
+			keybindings: loadGoalSettings(ctx.cwd).keybindings,
 			maxAutonomousRuns: loadGoalSettings(ctx.cwd).maxAutonomousRuns,
+			idleContinuationBackoff: loadGoalSettings(ctx.cwd).idleContinuationBackoff,
 			goal: view,
 			focused: view !== null && core.focusedGoalId === view.id,
 			otherOpenGoals: otherCount,
@@ -323,10 +332,14 @@ export function registerGoalCommands(core: GoalCore): void {
 			return;
 		}
 		if (currentGoal.status === "paused") {
-			ctx.ui.notify("Goal is already paused. Use /goal-resume to continue.", "info");
+			ctx.ui.notify(`Goal is already paused. Use ${commandHint("goal-resume", core.loadedCommands)} to continue.`, "info");
+			if (!ctx.isIdle()) ctx.abort?.();
 			return;
 		}
+		core.interruption.reset();
+		ctx.ui.setStatus("goal-interrupt", undefined);
 		core.pauseActiveGoal(ctx);
+		ctx.abort?.();
 	}
 
 	async function handleGoalResume(ctx: ExtensionContext): Promise<void> {
@@ -361,10 +374,11 @@ export function registerGoalCommands(core: GoalCore): void {
 	type SettingRow = {
 		key: keyof GoalSettings | string;
 		label: string;
-		section: "Goal behavior" | "Task tracking" | "Completion auditor" | "Blocker Oracle";
+		section: "Goal behavior" | "Task tracking" | "Completion auditor" | "Blocker Oracle" | "Advanced execution";
 		kind: "boolean" | "modelSelector" | "thinking" | "positiveInteger";
 		/** Settings path for the mutation (defaults to [key]). */
 		path?: string[];
+		help?: string;
 	};
 
 	const SETTING_ROWS: readonly SettingRow[] = [
@@ -377,6 +391,8 @@ export function registerGoalCommands(core: GoalCore): void {
 		{ key: "showAutonomousRuns", label: "show autonomous runs line", section: "Goal behavior", kind: "boolean" },
 		{ key: "stallTimeoutMinutes", label: "stall timeout (minutes)", section: "Goal behavior", kind: "positiveInteger" },
 		{ key: "objectiveMaxChars", label: "max objective length (0 = none)", section: "Goal behavior", kind: "positiveInteger" },
+		{ key: "idleContinuationBackoff", label: "slow repeated idle replies (opt-in)", section: "Advanced execution", kind: "boolean",
+			help: "Slows repeated replies without recognized work. May delay reasoning or custom tools. For a hard stop, set an autonomous run allowance." },
 		{ key: "disableTasks", label: "disableTasks", section: "Task tracking", kind: "boolean" },
 		{ key: "subtaskDepth", label: "subtaskDepth", section: "Task tracking", kind: "positiveInteger" },
 		{ key: "disabled", label: "auditor disabled", section: "Completion auditor", kind: "boolean" },
@@ -393,7 +409,7 @@ export function registerGoalCommands(core: GoalCore): void {
 	];
 
 	function settingsValue(config: GoalSettings, key: keyof GoalSettings | string): string {
-		if (key === "strictExecutionContract" || key === "disabled" || key === "disableTasks" || key === "disableContracts" || key === "autoSelectSingleGoal" || key === "auditorProjectResources" || key === "hideUnfocusedBanner" || key === "hideUnfocusedPrompt" || key === "showAutonomousRuns") {
+		if (key === "idleContinuationBackoff" || key === "strictExecutionContract" || key === "disabled" || key === "disableTasks" || key === "disableContracts" || key === "autoSelectSingleGoal" || key === "auditorProjectResources" || key === "hideUnfocusedBanner" || key === "hideUnfocusedPrompt" || key === "showAutonomousRuns") {
 			return config[key] === true ? "true" : "false";
 		}
 		if (key === "subtaskDepth") return config.subtaskDepth !== undefined ? String(config.subtaskDepth) : "1";
@@ -439,6 +455,7 @@ export function registerGoalCommands(core: GoalCore): void {
 			try {
 				mutateSettingsLayer({ scope, cwd: ctx.cwd, mutation });
 				applyEffectiveSettings();
+				if (mutation.path[0] === "idleContinuationBackoff") core.scheduler.refreshSettings(ctx);
 				return true;
 			} catch (err) {
 				ctx.ui.notify(`Settings change failed: ${err instanceof Error ? err.message : String(err)}`, "warning");
@@ -457,6 +474,8 @@ export function registerGoalCommands(core: GoalCore): void {
 				const localLayer = snapshot[scope].layer as Record<string, unknown>;
 				const options: string[] = [];
 				options.push(`─── Editing: ${scope} (${scopePath(scope)}) ───`);
+				options.push(`Scope: ${scope} (select to switch)`);
+				options.push("Controls: commands, keys and pause order…");
 				let lastSection: string | null = null;
 				const pathOf = (row: SettingRow): string[] => row.path ?? [String(row.key)];
 				const valueAtPath = (obj: unknown, path: string[]): unknown => {
@@ -494,6 +513,7 @@ export function registerGoalCommands(core: GoalCore): void {
 				options.push("Done");
 				const selected = await ctx.ui.select("Goal settings", options);
 				if (!selected || selected === "Done") break;
+				if (selected.startsWith("Controls:")) { if (await showGoalControls(core, ctx, scope)) return; continue; }
 				if (selected.startsWith("───")) continue; // headers are not rows
 				const trimmed = selected.trim();
 				if (trimmed.startsWith("Scope:")) {
@@ -534,7 +554,7 @@ export function registerGoalCommands(core: GoalCore): void {
 					];
 					if (hasLocalOverride) actions.push(inheritLabel);
 					actions.push("Cancel");
-					const action = await ctx.ui.select(`${row.label} (${scope})`, actions);
+					const action = await ctx.ui.select(`${row.label} (${scope})${row.help ? `\n${row.help}` : ""}`, actions);
 					if (!action || action === "Cancel") continue;
 					if (action === inheritLabel) {
 						applyMutation(scope, { op: "unset", path: rowPath });
@@ -552,7 +572,7 @@ export function registerGoalCommands(core: GoalCore): void {
 					const actions = [`Set ${scope} override...`];
 					if (hasLocalOverride) actions.push(inheritLabel);
 					actions.push("Cancel");
-					const action = await ctx.ui.select(`${row.label} (${scope})`, actions);
+					const action = await ctx.ui.select(`${row.label} (${scope})${row.help ? `\n${row.help}` : ""}`, actions);
 					if (!action || action === "Cancel") continue;
 					if (action === inheritLabel) {
 						applyMutation(scope, { op: "unset", path: rowPath });
@@ -658,7 +678,7 @@ export function registerGoalCommands(core: GoalCore): void {
 		// Headless behavior is explicit: guidance without mutation. Clearing
 		// requires an interactive confirmation (follow-up Stage 2).
 		if (!ctx.hasUI) {
-			ctx.ui.notify(`Run /goal-clear in an interactive session to confirm clearing: ${oneLineSummary(target)}`, "warning");
+			ctx.ui.notify(`Run ${commandHint("goal-clear", core.loadedCommands)} in an interactive session to confirm clearing: ${oneLineSummary(target)}`, "warning");
 			return;
 		}
 		const confirmed = await ctx.ui.confirm("Clear goal?", oneLineSummary(target));
@@ -688,19 +708,19 @@ export function registerGoalCommands(core: GoalCore): void {
 				const selected = await chooseOpenGoal(ctx, "Tweak which open goal?");
 				if (!selected) return;
 			} else {
-				ctx.ui.notify("No goal is set. Use /goal to draft one, or /goal-direct <objective> to create one immediately.", "warning");
+				ctx.ui.notify(`No goal is set. Use ${commandHint("goal", core.loadedCommands)} to draft one, or ${commandHint("goal-direct", core.loadedCommands)} <objective> to create one immediately.`, "warning");
 				return;
 			}
 		}
 		const currentGoal = core.state.goal;
 		if (!currentGoal) return;
 		if (currentGoal.status === "complete") {
-			ctx.ui.notify("Goal is complete. Use /goal to draft a new one, or /goal-direct <objective> to create one immediately.", "warning");
+			ctx.ui.notify(`Goal is complete. Use ${commandHint("goal", core.loadedCommands)} to draft a new one, or ${commandHint("goal-direct", core.loadedCommands)} <objective> to create one immediately.`, "warning");
 			return;
 		}
 		const trimmed = replacement.trim();
 		if (!trimmed) {
-			ctx.ui.notify("Describe the requested change: /goal-tweak <change>, for example remove the token budget", "info");
+			ctx.ui.notify(`Describe the requested change: ${commandHint("goal-tweak", core.loadedCommands)} <change>, for example remove the token budget`, "info");
 			return;
 		}
 		const max = loadGoalSettings(ctx.cwd).objectiveMaxChars;
@@ -714,19 +734,19 @@ export function registerGoalCommands(core: GoalCore): void {
 	}
 
 	// /goal and /sisyphus are the guided default. -direct commands are the explicit bypass.
-	pi.registerCommand("goal", {
+	define("goal", {
 		description: "Draft a regular goal with clarification, task planning, and confirmation.",
 		handler: async (rawArgs, ctx) => {
 			await startGoalDrafting(core, ctx, "goal", rawArgs);
 		},
 	});
-	pi.registerCommand("sisyphus", {
+	define("sisyphus", {
 		description: "Draft a Sisyphus goal with clarification, task planning, and confirmation.",
 		handler: async (rawArgs, ctx) => {
 			await startGoalDrafting(core, ctx, "sisyphus", rawArgs);
 		},
 	});
-	pi.registerCommand("goal-cancel", {
+	define("goal-cancel", {
 		description: "Cancel the in-progress guided draft without creating or modifying a goal.",
 		handler: async (_rawArgs, ctx) => {
 			if (!hasActiveDraft(core)) {
@@ -738,15 +758,15 @@ export function registerGoalCommands(core: GoalCore): void {
 			ctx.ui.notify("Draft cancelled; no goal was created. The execution profile is restored.", "info");
 		},
 	});
-	pi.registerCommand("goal-direct", {
+	define("goal-direct", {
 		description: "Create and start a regular goal immediately, without drafting.",
 		handler: async (rawArgs, ctx) => { handleDirectGoalSet(rawArgs, ctx, "goal"); },
 	});
-	pi.registerCommand("sisyphus-direct", {
+	define("sisyphus-direct", {
 		description: "Create and start a Sisyphus goal immediately, without drafting.",
 		handler: async (rawArgs, ctx) => { handleDirectGoalSet(rawArgs, ctx, "sisyphus"); },
 	});
-	pi.registerCommand("goal-list", {
+	define("goal-list", {
 		description: "List all open goals and the current focus.",
 		handler: async (_rawArgs, ctx) => {
 			core.reconcileFocusedGoalFromDisk(ctx);
@@ -754,64 +774,92 @@ export function registerGoalCommands(core: GoalCore): void {
 			core.updateUI(ctx);
 		},
 	});
-	pi.registerCommand("goal-status", {
+	define("goal-status", {
 		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);
 		},
 	});
-	pi.registerCommand("goal-refresh", {
+	define("goal-refresh", {
 		description: "Re-read goal storage caches (pool, ledger, settings) from disk and report what changed. Picks up external edits to .pi files — no file watchers needed.",
 		handler: async (_rawArgs, ctx) => {
 			await runGoalRefresh(ctx);
 		},
 	});
-	pi.registerCommand("goal-recovery", {
+	define("goal-recovery", {
 		description: "Read-only storage/recovery report (malformed goal files, malformed ledger lines, stale locks, orphaned snapshot data). Append \"repair\" to remove stale locks and refresh the pool snapshot after confirmation (with backup).",
 		handler: async (rawArgs, ctx) => {
 			await runGoalRecovery((rawArgs ?? "").trim(), ctx);
 		},
 	});
-	pi.registerCommand("goal-focus", {
+	define("goal-focus", {
 		description: "Choose which open goal this session focuses on.",
 		handler: async (_rawArgs, ctx) => {
 			await focusGoalCommand(ctx);
 		},
 	});
-	pi.registerCommand("goal-unfocus", {
+	define("goal-unfocus", {
 		description: "Stop focusing the current goal (session only; goal stays open).",
 		handler: async (_rawArgs, ctx) => {
 			unfocusGoalCommand(ctx);
 		},
 	});
-	pi.registerCommand("goal-settings", {
-		description: "Open pi-goal settings (auditor provider/model/thinking level).",
-		handler: async (_rawArgs, ctx) => {
-			await handleSettingsMenu(ctx);
+	define("goal-settings", {
+		description: "Goal settings and controls; accepts controls for commands, keys and pause order.",
+		handler: async (rawArgs, ctx) => {
+			if (rawArgs.trim() === "controls") await showGoalControls(core, ctx);
+			else await handleSettingsMenu(ctx);
 		},
 	});
-	pi.registerCommand("goal-tweak", {
+	define("goal-tweak", {
 		description: "Revise the current goal or its token budget with confirmation.",
 		handler: async (rawArgs, ctx) => {
 			await runGoalTweak(rawArgs, ctx);
 		},
 	});
-	pi.registerCommand("goal-clear", {
+	define("goal-clear", {
 		description: "Archive the current goal after confirmation (user-owned abandonment).",
 		handler: async (_rawArgs, ctx) => {
 			await handleGoalClear(ctx);
 		},
 	});
-	pi.registerCommand("goal-pause", {
-		description: "Pause the currently running goal. Esc also pauses while running.",
+	define("goal-pause", {
+		description: "Pause the currently running goal and stop its turn.",
 		handler: async (_rawArgs, ctx) => {
 			await handleGoalPause(ctx);
 		},
 	});
-	pi.registerCommand("goal-resume", {
+	define("goal-resume", {
 		description: "Continue now and renew the configured autonomous-run allowance.",
 		handler: async (_rawArgs, ctx) => {
 			await handleGoalResume(ctx);
 		},
 	});
+	const configured = loadGoalSettings(process.cwd()).commands;
+	const problems = commandProblems(configured);
+	core.loadedCommands = problems.length ? undefined : configured;
+	core.controlWarnings = problems;
+	const routes = commandRoutes(core.loadedCommands);
+	core.invokeGoalCommand = async (id, args, ctx) => {
+		const action = actions.get(id);
+		if (!action) return;
+		core.enterGoalModal();
+		try { await action.handler(args, ctx); }
+		finally { core.exitGoalModal(); }
+	};
+	const roots = [...actions.keys()].flatMap(id => commandPaths(core.loadedCommands, id).map(route => route.split(" ")[0]!));
+	for (const root of new Set([...roots, "goal-settings"])) {
+		const rootRoutes = routes.filter(route => route.path.split(" ")[0] === root);
+		const direct = rootRoutes.find(route => route.path === root);
+		pi.registerCommand(root, {
+			description: direct ? actions.get(direct.id)!.description : `Goal actions: ${rootRoutes.map(route => route.path.slice(root.length + 1)).join(", ")}`,
+			getArgumentCompletions: prefix => rootRoutes.filter(route => route.path !== root && route.path.slice(root.length + 1).startsWith(prefix)).map(route => ({ value: route.path.slice(root.length + 1), label: route.path.slice(root.length + 1), description: GOAL_COMMANDS.find(([id]) => id === route.id)![1] })),
+			handler: async (args, ctx) => {
+				const match = matchCommandRoute(routes, root, args);
+				if (match) await core.invokeGoalCommand!(match.id, match.args, ctx);
+				else ctx.ui.notify(`Choose a goal command: ${rootRoutes.map(route => `/${route.path}`).join(", ")}`, "info");
+			},
+		});
+	}
+
 }