@koltmcbride/pi-goal 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kolt McBride
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# pi-goal
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+[![pi package](https://img.shields.io/badge/pi-extension-5b54d6.svg)](https://github.com/earendil-works/pi-coding-agent)
+
+> Goal-directed autonomous work loops for [pi](https://github.com/earendil-works/pi-coding-agent).
+
+Set a goal as a single completion condition. After every turn, a lightweight
+evaluator checks whether the condition is met. If it isn't, the agent is
+automatically prompted to keep working — turn after turn — until the goal is
+satisfied or you stop it. It's the autonomous counterpart to a plain prompt:
+you describe the *end state*, not each step.
+
+```
+/goal all tests in test/auth pass and the lint step is clean
+```
+
+---
+
+## Features
+
+- **Single-condition goals** — describe a verifiable end state; the agent drives toward it.
+- **Self-evaluating loop** — after each turn the configured model judges progress with a cheap yes/no call.
+- **Live status** — a footer timer shows elapsed time and turn count while a goal runs.
+- **Resumes across sessions** — an in-progress goal is restored automatically when you reopen the session.
+- **Bounded** — a hard turn cap prevents a goal that never resolves from looping forever.
+
+## Requirements
+
+- [pi](https://github.com/earendil-works/pi-coding-agent) (`@earendil-works/pi-coding-agent`).
+- A configured model — the same model that powers your session is reused for evaluation.
+
+## Installation
+
+From npm:
+
+```bash
+pi install npm:@koltmcbride/pi-goal
+```
+
+From git:
+
+```bash
+pi install git:github.com/kolt-mcb/pi-goal@v0.1.0
+```
+
+> ⚠️ Pi packages run with full system access. Review the source before installing.
+
+## Usage
+
+```
+/goal <condition>    Set a goal and start working immediately
+/goal                Show the active goal's status
+/goal status         Alias for /goal
+/goal clear          Clear the active goal
+```
+
+`clear` also accepts the aliases `stop`, `off`, `reset`, `none`, and `cancel`.
+The subcommands are offered as autocompletions when you type `/goal ` and press
+Tab.
+
+Re-issuing `/goal <condition>` while a goal is active replaces the condition
+and restarts the loop with it.
+
+### Writing effective conditions
+
+A good condition has **one measurable end state** and **a clear way for the
+agent to demonstrate it** in its output:
+
+```
+/goal all tests in test/auth pass and the lint step is clean
+/goal refactor src/database to use connection pooling, verified by tests in test/db.test.ts
+/goal every exported symbol in src/api has a docstring
+```
+
+Goals work best for substantial, verifiable work — migrating a module until
+every call site compiles, implementing a design doc until its acceptance
+criteria hold, or working through a backlog until the queue is empty.
+
+### Status display
+
+While a goal is active, the footer shows a live timer:
+
+```
+⏱ 3t · 2m 15s
+```
+
+`/goal` (or `/goal status`) prints the full state:
+
+```
+Condition: all tests in test/auth pass and the lint step is clean
+Running:   2m 15s
+Turns:     3
+Last reason: one failing test remains in test/auth/login.test.ts
+```
+
+On completion the footer reports `✓ Goal achieved in 3 turns`.
+
+## How it works
+
+1. **Set** — `/goal <condition>` records the condition and sends it as the
+   first prompt, kicking off work immediately.
+2. **Evaluate** — at the end of each turn, the agent's text and tool results are
+   summarized and passed to a minimal evaluator call on the same configured
+   model: *has the condition been met?*
+3. **Continue or stop** — if not met, a hidden continuation message is queued as
+   the next turn with the latest evaluation reason, and the agent keeps working.
+   When the evaluator returns *yes*, the loop stops and the result is reported.
+
+A goal stops automatically when the condition is met, when you run `/goal clear`,
+or after a safety cap of **120 turns** without success. State is persisted as
+custom session entries, so a goal that was still running when a session ended is
+restored on resume.
+
+## Relationship to Claude Code's `/goal`
+
+pi-goal mirrors the `/goal` interface from Claude Code, with a few differences:
+
+| | Claude Code | pi-goal |
+|---|:---:|:---:|
+| Slash interface | ✓ | ✓ |
+| Session persistence | ✓ | ✓ |
+| Footer timer | ✓ | ✓ |
+| Evaluation model | separate small model | your configured model (minimal reasoning) |
+
+## Development
+
+```bash
+npm install        # install dev + peer dependencies
+npm run typecheck  # tsc --noEmit
+npm test           # run the smoke test
+```
+
+The extension is plain TypeScript; pi loads the source directly via the `pi`
+manifest in [`package.json`](./package.json), so there is no build step.
+
+## License
+
+[MIT](./LICENSE) © Kolt McBride

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@koltmcbride/pi-goal",
+  "version": "0.1.0",
+  "description": "Pi extension for goal-directed autonomous work loops",
+  "license": "MIT",
+  "author": "Kolt McBride",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "goal",
+    "automation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kolt-mcb/pi-goal.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kolt-mcb/pi-goal/issues"
+  },
+  "homepage": "https://github.com/kolt-mcb/pi-goal#readme",
+  "files": [
+    "src/**/*.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/extension/index.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "tsx test/smoke.test.ts"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-agent-core": {
+      "optional": true
+    },
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "^0.74.0",
+    "@earendil-works/pi-ai": "^0.74.0",
+    "@earendil-works/pi-coding-agent": "^0.74.0",
+    "@types/node": "^25.9.1",
+    "tsx": "^4.22.3",
+    "typescript": "^6.0.3"
+  }
+}

package/src/extension/evaluator.ts

@@ -0,0 +1,131 @@
+/**
+ * Lightweight goal evaluator.
+ *
+ * Calls the same configured model with a minimal prompt to determine
+ * whether the goal completion condition has been satisfied based on
+ * the agent's most recent turn output.
+ */
+
+import { completeSimple } from "@earendil-works/pi-ai";
+import type { Model } from "@earendil-works/pi-ai";
+import type { GoalState } from "./persistence";
+
+interface EvalResult {
+	met: boolean;
+	reason: string;
+	usage?: { input: number; output: number };
+}
+
+/**
+ * Build the evaluator prompt from the goal condition and turn evidence.
+ */
+function buildEvalPrompt(condition: string, turnText: string, turnCount: number): string {
+	return [
+		`CONDITION: ${condition}`,
+		`TURN: ${turnCount}`,
+		`AGENT OUTPUT SUMMARY (text + tool results from last turn):`,
+		"---",
+		truncate(turnText, 6000),
+		"---",
+		"",
+		"Has the condition been met? Reply with exactly one of:",
+		'  YES  — if the agent output demonstrates the condition is satisfied.',
+		'  NO: <brief reason>  — if not, what is still needed.',
+	].join("\n");
+}
+
+/**
+ * Evaluate whether the goal condition is met.
+ */
+export async function evaluateGoal(
+	model: Model<any>,
+	state: GoalState,
+	turnText: string,
+): Promise<EvalResult> {
+	const prompt = buildEvalPrompt(state.condition, turnText, state.turnCount + 1);
+
+	try {
+		const result = await completeSimple(model, {
+			messages: [{ role: "user", content: prompt, timestamp: Date.now() }],
+			tools: [],
+		}, {
+			// Keep the evaluator cheap: a yes/no judgement needs no deep reasoning.
+			reasoning: "minimal",
+		});
+
+		const text = (result.content ?? [])
+			.filter((c: any) => c.type === "text")
+			.map((c: any) => c.text ?? "")
+			.join(" ")
+			.trim();
+
+		if (/^YES$/i.test(text)) {
+			return { met: true, reason: "Condition satisfied" };
+		}
+
+		const match = /^NO:\s*(.*)/i.exec(text);
+		return {
+			met: false,
+			reason: match?.[1]?.trim() ?? "Evaluator did not reach a conclusion",
+		};
+	} catch (err: unknown) {
+		const msg = err instanceof Error ? err.message : String(err);
+		return {
+			met: false,
+			reason: `Evaluator error: ${msg.slice(0, 120)}`,
+		};
+	}
+}
+
+/**
+ * Evaluate with explicit turn text and context messages.
+ * The turnText should contain the assistant's text + tool result evidence
+ * from the most recent turn.
+ */
+export function buildTurnEvidence(
+	event: { message?: unknown; toolResults?: unknown[] },
+): string {
+	const parts: string[] = [];
+
+	// Assistant message text
+	const msg = event.message as { role?: string; content?: unknown[] } | undefined;
+	if (msg?.content && Array.isArray(msg.content)) {
+		for (const block of msg.content) {
+			const b = block as { type?: string; text?: string; name?: string; arguments?: unknown };
+			if (b.type === "text" && b.text) {
+				parts.push(`--- text output ---\n${b.text}`);
+			} else if (b.type === "toolCall" || b.type === "tool_use") {
+				const toolName = b.name ?? "unknown";
+				const args = typeof b.arguments === "string" ? b.arguments : JSON.stringify(b.arguments ?? "");
+				parts.push(`--- tool use: ${toolName} ---\n${args}`);
+			}
+		}
+	}
+
+	// Tool results
+	const toolResults = event.toolResults as Array<{
+		toolName?: string;
+		content?: Array<{ type?: string; text?: string }>;
+		isError?: boolean;
+	}> | undefined;
+	if (toolResults?.length) {
+		for (const tr of toolResults) {
+			const name = tr.toolName ?? "unknown";
+			const isError = tr.isError ? " [error]" : "";
+			const text = (tr.content ?? [])
+				.filter((c: { type?: string; text?: string }) => c.type === "text")
+				.map((c: { type?: string; text?: string }) => c.text ?? "")
+				.join("\n");
+			if (text) {
+				parts.push(`--- tool result: ${name}${isError} ---\n${text}`);
+			}
+		}
+	}
+
+	return parts.join("\n\n");
+}
+
+function truncate(s: string, max: number): string {
+	if (s.length <= max) return s;
+	return s.slice(0, max) + "\n...(truncated)";
+}

package/src/extension/index.ts

@@ -0,0 +1,169 @@
+/**
+ * pi-goal — Goal-directed autonomous work loops
+ *
+ * Mirrors Claude Code's /goal interface:
+ *   /goal <condition>  — set a goal, starts working immediately
+ *   /goal              — show goal status
+ *   /goal clear        — clear the active goal
+ *
+ * After each turn, a lightweight evaluator call checks whether the condition
+ * is met. If not, a nextTurn message kicks off the next turn automatically,
+ * so the agent keeps working until the goal is satisfied or cleared.
+ */
+
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	TurnEndEvent,
+	SessionStartEvent,
+	SessionShutdownEvent,
+} from "@earendil-works/pi-coding-agent";
+import type { GoalState } from "./persistence";
+import { GOAL_STATE_TYPE, saveState, loadState, saveAchieved } from "./persistence";
+import { evaluateGoal, buildTurnEvidence } from "./evaluator";
+import { registerSlashCommands } from "./slash";
+
+// ── Constants ────────────────────────────────────────────────────────────
+const STATUS_KEY = "goal-status";
+// Hard cap on continuation turns, so a goal that never resolves can't loop forever.
+const MAX_TURNS = 120;
+
+// ── Module-level state ───────────────────────────────────────────────────
+let activeGoal: GoalState | null = null;
+let statusTimer: ReturnType<typeof setInterval> | null = null;
+let lastUiCtx: ExtensionContext | null = null;
+let extensionApi: ExtensionAPI | null = null;
+
+// ── Status display ───────────────────────────────────────────────────────
+function statusText(goal: GoalState): string {
+	const totalSec = Math.floor((Date.now() - goal.startedAt) / 1000);
+	const hrs = Math.floor(totalSec / 3600);
+	const mins = Math.floor((totalSec % 3600) / 60);
+	const secs = totalSec % 60;
+	const t = hrs > 0
+		? `${String(hrs).padStart(2, "0")}:${String(mins).padStart(2, "0")}:${String(secs).padStart(2, "0")}`
+		: `${mins}m ${secs}s`;
+	return `⏱ ${goal.turnCount}t · ${t}`;
+}
+
+function updateStatus(ctx: ExtensionContext): void {
+	ctx.ui.setStatus(STATUS_KEY, activeGoal ? statusText(activeGoal) : undefined);
+}
+
+function startStatusTick(ctx: ExtensionContext): void {
+	stopStatusTick();
+	if (!activeGoal) return;
+	updateStatus(ctx);
+	statusTimer = setInterval(() => {
+		try { updateStatus(ctx); } catch { stopStatusTick(); }
+	}, 1000);
+}
+
+function stopStatusTick(): void {
+	if (statusTimer) { clearInterval(statusTimer); statusTimer = null; }
+}
+
+// ── turn_end handler ─────────────────────────────────────────────────────
+async function handleTurnEnd(event: TurnEndEvent, ctx: ExtensionContext): Promise<void> {
+	if (!activeGoal || !extensionApi) return;
+	if (!ctx.model) {
+		// No model available — can't evaluate, so stop the goal cleanly.
+		stopStatusTick();
+		ctx.ui.setStatus(STATUS_KEY, "⚠ No model for evaluation");
+		activeGoal = null;
+		return;
+	}
+
+	// Build evidence from this turn and ask the evaluator if the goal is met.
+	const evidence = buildTurnEvidence(event);
+	activeGoal.elapsedMs = Date.now() - activeGoal.startedAt;
+	const evalResult = await evaluateGoal(ctx.model, activeGoal, evidence);
+	activeGoal.lastReason = evalResult.reason;
+
+	if (evalResult.met) {
+		// ✓ Goal achieved
+		saveAchieved(extensionApi, activeGoal);
+		const turns = activeGoal.turnCount;
+		stopStatusTick();
+		ctx.ui.setStatus(STATUS_KEY, `✓ Goal achieved in ${turns} turns`);
+		ctx.ui.notify(`Goal achieved in ${turns} turns`, "info");
+		activeGoal = null;
+		return;
+	}
+
+	// Goal not met — record progress and continue the loop.
+	activeGoal.turnCount++;
+	saveState(extensionApi, activeGoal);
+	updateStatus(ctx);
+
+	if (activeGoal.turnCount > MAX_TURNS) {
+		stopStatusTick();
+		ctx.ui.setStatus(STATUS_KEY, `⚠ Goal stopped: turn limit (${MAX_TURNS})`);
+		ctx.ui.notify(`Goal stopped after ${MAX_TURNS} turns without meeting the condition.`, "warning");
+		activeGoal = null;
+		return;
+	}
+
+	// Inject a continuation message to keep the agent focused on the goal.
+	const reminder = [
+		`[GOAL: turn ${activeGoal.turnCount}]`,
+		``,
+		`The completion condition has not been met yet.`,
+		`Last evaluation: ${evalResult.reason}`,
+		``,
+		`Goal condition: ${activeGoal.condition}`,
+		`Continue working toward it.`,
+	].join("\n");
+
+	extensionApi.sendMessage({
+		customType: GOAL_STATE_TYPE,
+		content: reminder,
+		// Hidden from the TUI (the footer timer shows progress); still steers the model.
+		display: false,
+		details: activeGoal,
+	}, {
+		deliverAs: "nextTurn",
+		triggerTurn: true,
+	});
+}
+
+// ── session lifecycle ────────────────────────────────────────────────────
+function handleSessionStart(_event: SessionStartEvent, ctx: ExtensionContext): void {
+	lastUiCtx = ctx;
+
+	// Restore an in-progress goal from a previous session, if any.
+	const saved = loadState(ctx.sessionManager);
+	if (saved) {
+		activeGoal = saved;
+		startStatusTick(ctx);
+		const label = saved.condition.length > 60 ? `${saved.condition.slice(0, 60)}…` : saved.condition;
+		ctx.ui.notify(`Restored goal: "${label}" (${saved.turnCount} turns so far)`, "info");
+	}
+}
+
+function handleSessionShutdown(_event: SessionShutdownEvent): void {
+	stopStatusTick();
+	activeGoal = null;
+}
+
+// ── Extension entry point ────────────────────────────────────────────────
+export default function registerGoalExtension(pi: ExtensionAPI): void {
+	extensionApi = pi;
+
+	registerSlashCommands(pi, {
+		get: () => activeGoal,
+		set: (state) => {
+			activeGoal = state;
+			if (lastUiCtx) startStatusTick(lastUiCtx);
+		},
+		clear: () => {
+			stopStatusTick();
+			activeGoal = null;
+			if (lastUiCtx) lastUiCtx.ui.setStatus(STATUS_KEY, undefined);
+		},
+	});
+
+	pi.on("turn_end", handleTurnEnd);
+	pi.on("session_start", handleSessionStart);
+	pi.on("session_shutdown", handleSessionShutdown);
+}

package/src/extension/persistence.ts

@@ -0,0 +1,74 @@
+/**
+ * Goal state persistence via session entries.
+ *
+ * Goal metadata is stored as custom session entries so an in-progress goal
+ * survives session resume. Writes go through `pi.appendEntry` (ExtensionAPI);
+ * reads walk the entries exposed by the read-only session manager.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+// ReadonlySessionManager isn't exported from the package root; derive it from
+// the context shape so loadState accepts exactly what event handlers receive.
+type ReadonlySessionManager = ExtensionContext["sessionManager"];
+
+/** customType for an active-goal snapshot entry. */
+const STATE_TYPE = "pi-goal-state";
+/** customType for a marker written when a goal is achieved. */
+const ACHIEVED_TYPE = "pi-goal-achieved";
+
+export interface GoalState {
+	condition: string;
+	startedAt: number;
+	turnCount: number;
+	elapsedMs: number;
+	lastReason: string;
+}
+
+// Re-exported so the extension can tag continuation messages consistently.
+export { STATE_TYPE as GOAL_STATE_TYPE };
+
+/**
+ * Save the current goal state as a custom session entry.
+ * The latest such entry wins on resume (see loadState).
+ */
+export function saveState(pi: ExtensionAPI, state: GoalState): void {
+	pi.appendEntry(STATE_TYPE, { timestamp: Date.now(), ...state });
+}
+
+/**
+ * Load the most recent goal state from the session.
+ *
+ * Walks entries newest-first. `pi.appendEntry` stores a CustomEntry whose
+ * `type` is always "custom" and whose `customType` carries our tag, so we
+ * match on `customType` — not `type`. A more recent "achieved" marker means
+ * the last goal finished, so there is no active goal to restore.
+ */
+export function loadState(
+	sessionManager: ReadonlySessionManager,
+): GoalState | null {
+	const entries = sessionManager.getEntries() ?? [];
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i] as {
+			type?: string;
+			customType?: string;
+			data?: unknown;
+		};
+		if (entry.type !== "custom") continue;
+		if (entry.customType === STATE_TYPE && entry.data) {
+			return entry.data as GoalState;
+		}
+		if (entry.customType === ACHIEVED_TYPE) {
+			return null; // most recent goal was completed — nothing active
+		}
+	}
+	return null;
+}
+
+/**
+ * Mark a goal as achieved. Appends a marker entry so loadState knows the
+ * goal was completed rather than still active.
+ */
+export function saveAchieved(pi: ExtensionAPI, state: GoalState): void {
+	pi.appendEntry(ACHIEVED_TYPE, { timestamp: Date.now(), ...state });
+}

package/src/extension/slash.ts

@@ -0,0 +1,140 @@
+/**
+ * Slash commands for /goal.
+ *
+ *   /goal <condition>  — set (or replace) a goal, start working
+ *   /goal              — show goal status when active; usage info when no goal
+ *   /goal clear        — clear the active goal
+ *   /goal status       — same as /goal
+ *
+ * Mirroring Claude Code's /goal, the clear action accepts several aliases:
+ * clear, stop, off, reset, none, cancel.
+ *
+ * The command owns no state of its own: index.ts passes accessor callbacks so
+ * the command and the extension's turn-end loop share a single source of truth.
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { GoalState } from "./persistence";
+
+/** Accessors into the extension's active-goal state, supplied by index.ts. */
+export interface GoalSlashAPI {
+	get: () => GoalState | null;
+	set: (state: GoalState) => void;
+	clear: () => void;
+}
+
+/** Words that clear an active goal. Mirrors Claude Code's /goal aliases. */
+const CLEAR_ALIASES = ["clear", "stop", "off", "reset", "none", "cancel"];
+
+/** Subcommands surfaced in the `/goal <Tab>` argument autocomplete. */
+const SUBCOMMAND_COMPLETIONS = [
+	{ value: "status", label: "status", description: "Show the active goal's status" },
+	{ value: "clear", label: "clear", description: "Clear the active goal" },
+	...CLEAR_ALIASES.filter((a) => a !== "clear").map((a) => ({
+		value: a,
+		label: a,
+		description: "Clear the active goal (alias for clear)",
+	})),
+];
+
+/** True when the argument is one of the clear/stop/off/… reserved words. */
+function isClearCommand(arg: string): boolean {
+	return CLEAR_ALIASES.includes(arg.toLowerCase());
+}
+
+export function registerSlashCommands(pi: ExtensionAPI, api: GoalSlashAPI): void {
+	pi.registerCommand("goal", {
+		description: "Goal-directed autonomous work loop",
+		getArgumentCompletions: (prefix: string) => {
+			const p = prefix.trim().toLowerCase();
+			const matches = SUBCOMMAND_COMPLETIONS.filter((c) => c.value.startsWith(p));
+			return matches.length > 0 ? matches : null;
+		},
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			const trimmed = args.trim();
+			const goal = api.get();
+
+			if (goal) {
+				// ── Goal is active ──────────────────────────────────
+				if (isClearCommand(trimmed)) {
+					api.clear();
+					ctx.ui.notify("Goal cleared.", "info");
+					return;
+				}
+				if (trimmed === "status" || !trimmed) {
+					showStatus(goal, ctx);
+					return;
+				}
+				// Additional args on an active goal → replace the condition
+				doSetGoal(pi, api, trimmed, ctx);
+				return;
+			}
+
+			// ── No active goal ──────────────────────────────────────
+			if (!trimmed || trimmed === "status") {
+				noActiveGoal(ctx);
+				return;
+			}
+			if (isClearCommand(trimmed)) {
+				ctx.ui.notify("No active goal to clear.", "warning");
+				return;
+			}
+
+			// New goal
+			doSetGoal(pi, api, trimmed, ctx);
+		},
+	});
+}
+
+/** Set a fresh goal and start the first turn with the condition as the prompt. */
+function doSetGoal(
+	pi: ExtensionAPI,
+	api: GoalSlashAPI,
+	condition: string,
+	ctx: ExtensionCommandContext,
+): void {
+	api.set({
+		condition,
+		startedAt: Date.now(),
+		turnCount: 0,
+		elapsedMs: 0,
+		lastReason: "",
+	});
+	ctx.ui.notify(
+		`Goal set: "${truncate(condition, 60)}"`,
+		"info",
+	);
+
+	// Kick off the first turn. Send raw (executeSlashCommands defaults to false)
+	// so a condition that happens to start with "/" is treated as plain text.
+	pi.sendUserMessage(condition);
+}
+
+function showStatus(goal: GoalState, ctx: ExtensionCommandContext): void {
+	const lines = [
+		`Condition: ${goal.condition}`,
+		`Running:   ${formatDuration(Date.now() - goal.startedAt)}`,
+		`Turns:     ${goal.turnCount}`,
+	];
+	if (goal.lastReason) {
+		lines.push(`Last reason: ${goal.lastReason}`);
+	}
+	ctx.ui.notify(lines.join("\n"), "info");
+}
+
+function noActiveGoal(ctx: ExtensionCommandContext): void {
+	ctx.ui.notify("No active goal. Use `/goal <condition>` to set one.", "info");
+}
+
+function formatDuration(ms: number): string {
+	const totalSec = Math.floor(ms / 1000);
+	const hrs = Math.floor(totalSec / 3600);
+	const mins = Math.floor((totalSec % 3600) / 60);
+	const secs = totalSec % 60;
+	if (hrs > 0) return `${hrs}h ${mins}m ${secs}s`;
+	return `${mins}m ${secs}s`;
+}
+
+function truncate(s: string, max: number): string {
+	return s.length > max ? `${s.slice(0, max)}…` : s;
+}