howtofixcli 0.7.24 → 0.7.26

package/dist/gateway-errors.js

@@ -0,0 +1,107 @@
+/**
+ * What to do about the sentence the gateway just failed with.
+ *
+ * The gateway reports failures in its own words, and the README's
+ * Troubleshooting section already tells a reader what each one means — but only
+ * a reader who has the README open. In the TUI the same sentence arrives as a
+ * feed row titled `failed` and nothing else: the user is left to remember that
+ * `No available channel for model` means "the channel behind that id is down",
+ * not "my token is broken". The other documented sentences have the same gap.
+ *
+ * So the mapping lives here, as a pure string -> string function: no network,
+ * no session, no model runtime. The caller decides where the hint is shown
+ * (under a feed row in the TUI, on stderr in `--print`), which keeps this file
+ * free of UI so it can be exercised directly by a test.
+ *
+ * Every pattern is grounded in a sentence the gateway actually sends — the
+ * README's Troubleshooting list, the `probeModel` measurement (a listed model
+ * answering 500, another answering 401), and the `code 11128` refusal documented
+ * on `repairGatewayModels`. A pattern that matched nothing real would be a hint
+ * that lies, so nothing speculative is matched: unknown sentences return
+ * `undefined` and the caller prints the failure untouched.
+ */
+/**
+ * The one sentence the gateway sends when the channel behind a model id is
+ * down, read as the id it names.
+ *
+ * Shared with `diagnoseGatewayFailure` on purpose: the TUI does not only want
+ * a hint for this failure, it wants the *id* so it can probe the other
+ * candidates for a live one — and two copies of this pattern would drift, so
+ * the caller that opens the model picker would silently stop matching.
+ */
+const NO_LIVE_CHANNEL = /no available channel for model\s+([^\s"',)\]]+)/i;
+/** The model the gateway has no live channel for, or `undefined` for any other sentence. */
+export function deadChannelModel(message) {
+    const text = message ?? "";
+    if (!text.trim())
+        return undefined;
+    return NO_LIVE_CHANNEL.exec(text)?.[1];
+}
+/**
+ * The fix for a known gateway sentence, or `undefined` for anything else.
+ *
+ * Case-insensitive on purpose: the same sentence arrives from the gateway, from
+ * an SDK wrapper (`Upstream API error (HTTP 400)`) and from a probe, with
+ * punctuation that differs. The first pattern that matches wins, ordered from
+ * the most specific sentence to the most generic, so `HTTP 429` inside a rate
+ * limit is read as rate limiting rather than as an upstream error.
+ */
+export function diagnoseGatewayFailure(message) {
+    const text = message ?? "";
+    if (!text.trim())
+        return undefined;
+    // The gateway has no live channel behind that id. Not an account problem:
+    // `/model` lists what answers *now* (README, Troubleshooting). The id is
+    // read by `deadChannelModel` too, which is what lets the TUI go looking for
+    // a channel that *is* alive instead of only saying so.
+    const deadModel = deadChannelModel(text);
+    if (deadModel) {
+        return `the gateway has no live channel for ${deadModel} right now — /model lists the models that answer; pick another.`;
+    }
+    // No credential at all: nothing left the machine, so the message is about
+    // the install rather than about the model or the account balance. Seen on a
+    // fresh install as `401: {"type":"AuthError","message":"Missing API key."}`.
+    if (/\bmissing api key\b|\bauthenticationerror\b|\bauth\s*error\b/i.test(text)) {
+        return "no key for this model yet — /connect signs you in and pulls the model list.";
+    }
+    // `unknown model` means the id is not in models.json at all, which /connect
+    // fixes by pulling the current list (README, Troubleshooting).
+    if (/\bunknown model\b/i.test(text)) {
+        return "/connect pulls the current model list from the gateway.";
+    }
+    // The gateway refused a role the request was sent with (`code 11128`,
+    // "Illegal API invocation") — the compatibility flag on the model entry is
+    // what decides which roles are sent, and /connect re-reads it.
+    if (/\bcode 11128\b|\billegal api invocation\b/i.test(text)) {
+        return "the gateway refused the request shape (code 11128) — /connect re-syncs each model's compatibility flags.";
+    }
+    // 402/insufficient balance: the token is fine, the credit is not.
+    if (/\binsufficient (?:balance|quota|credit)\b|\bexceeded your current quota\b|http\s*402/i.test(text)) {
+        return "the account is out of credit — /usage shows what is left.";
+    }
+    // The gateway's channel failing, not the CLI (README, Troubleshooting).
+    if (/\bserver error\b|http\s*5\d\d/i.test(text)) {
+        return "the gateway's channel is failing, not the CLI — /model lists what your account can reach; pick another.";
+    }
+    // Rate limiting: waiting is the fix, and the run can simply be resent.
+    if (/\brate.?limit|\b429\b/i.test(text)) {
+        return "the gateway is rate-limiting this token — wait a moment, then resend the prompt.";
+    }
+    // Context overflow: the prompt alone is past the model's window. This must be
+    // read before the generic `upstream api error` branch below, because the
+    // gateway wraps the provider's sentence in that prefix.
+    //
+    // The SDK recovers from this by compacting and retrying once; when the user
+    // sees the sentence at all, that recovery has already been spent or refused.
+    // `/compact` is the manual escape, and it is deliberately still allowed while
+    // the auto-compaction breaker is tripped.
+    if (/\bprompt (?:is )?too long\b|\bprompt too long\b|\bexceeds? (?:the )?(?:model'?s )?maximum context length\b|\bmaximum context length is \d+ tokens\b|\bexceeds the context window\b|\bcontext[_ ]length[_ ]exceeded\b|\breduce the length of the messages\b/i.test(text)) {
+        return "the conversation is past this model's context window — /compact summarises it and continues, or /model picks a model with a bigger window.";
+    }
+    // `Upstream API error (HTTP nnn)` — the gateway refused the request; a model
+    // entry written before a gateway change carries stale flags (README).
+    if (/\bupstream api error\b/i.test(text)) {
+        return "the gateway refused the request — run /connect again to re-sync your models.";
+    }
+    return undefined;
+}

package/dist/git.js

@@ -0,0 +1,230 @@
+import { execFile } from "node:child_process";
+import { cp, readdir, stat } from "node:fs/promises";
+import { promisify } from "node:util";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+const execFileAsync = promisify(execFile);
+/**
+ * Run git in the project directory. Never throws; failures come back as text.
+ *
+ * Async on purpose: every caller is a slash command running inside the workbench,
+ * and a synchronous spawn blocks the event loop — on Windows a process spawn costs
+ * far more than on Linux, so `/commit`, `/undo` and `/review` froze the screen for
+ * the duration. Measured on Linux: 6.5 ms for a `status` spawn alone.
+ */
+export async function git(cwd, args) {
+    try {
+        const { stdout } = await execFileAsync("git", args, {
+            cwd,
+            encoding: "utf8",
+            maxBuffer: 8 * 1024 * 1024,
+        });
+        return { ok: true, output: stdout.trim() };
+    }
+    catch (error) {
+        const stderr = error && typeof error === "object" && "stderr" in error && typeof error.stderr === "string" ? error.stderr.trim() : "";
+        const message = error instanceof Error ? error.message : String(error);
+        return { ok: false, output: stderr || message };
+    }
+}
+export async function isGitRepo(cwd) {
+    return (await git(cwd, ["rev-parse", "--is-inside-work-tree"])).output === "true";
+}
+export async function hasChanges(cwd) {
+    return (await git(cwd, ["status", "--porcelain"])).output.length > 0;
+}
+/** Stage everything, commit, and return the one-line summary. */
+export async function commitAll(cwd, message) {
+    const add = await git(cwd, ["add", "-A"]);
+    if (!add.ok)
+        return add;
+    const commit = await git(cwd, ["commit", "-m", message]);
+    if (!commit.ok)
+        return commit;
+    const head = await git(cwd, ["log", "-1", "--oneline"]);
+    return { ok: true, output: head.output || commit.output };
+}
+/** Drop the last commit, keeping its changes staged. The inverse of `/commit`. */
+export async function undoLastCommit(cwd) {
+    const reset = await git(cwd, ["reset", "--soft", "HEAD~1"]);
+    if (!reset.ok)
+        return reset;
+    const head = await git(cwd, ["log", "-1", "--oneline"]);
+    return { ok: true, output: head.output || "reset to the previous commit" };
+}
+export async function diffStat(cwd) {
+    return (await git(cwd, ["diff", "--stat"])).output;
+}
+export async function fullDiff(cwd) {
+    const unstaged = (await git(cwd, ["diff"])).output;
+    const staged = (await git(cwd, ["diff", "--cached"])).output;
+    return [unstaged, staged].filter(Boolean).join("\n");
+}
+/**
+ * Cap a diff for display.
+ *
+ * A transcript is for reading, and a full patch of a large change pushes
+ * everything else off the screen — the note holding it can be hundreds of lines.
+ * The file summary is kept whole (it is what you scan), and the body is cut with
+ * a line saying how much is hidden, so nothing is silently dropped.
+ */
+export function clipDiff(diff, maxLines = 60) {
+    const lines = diff.split("\n");
+    if (lines.length <= maxLines)
+        return diff;
+    const head = lines.slice(0, maxLines);
+    const hidden = lines.length - maxLines;
+    return [...head, `… ${hidden} more line${hidden === 1 ? "" : "s"} not shown — /copy puts the full diff on the clipboard`].join("\n");
+}
+/**
+ * Directories that are (a) expensive to rebuild and (b) always git-ignored.
+ *
+ * Deliberately a fixed list rather than "everything ignored". `git status --ignored`
+ * also reports `.env`, `*.pem`, editor state and local databases — copying those into a
+ * tree that a parallel agent shares widens the blast radius of a mistake for no gain.
+ * A worktree needs what it takes to BUILD; it does not need someone's secrets.
+ */
+const SHARED_IGNORED = ["node_modules", "vendor", "target", ".venv", "venv", "__pycache__", ".pnpm-store", "dist", "build"];
+/**
+ * The weight past which copying is not attempted.
+ *
+ * This runs on the critical path of spawning an agent, so it has a budget. A reflink is
+ * nearly free; a real copy of 200 MB is not, and a worktree that takes four seconds to
+ * appear is one the user will turn off. Past the cap the directory is skipped and named
+ * in the result, so the caller can say why rather than leaving the agent to discover it.
+ */
+const SHARE_BUDGET_BYTES = 1024 * 1024 * 1024;
+async function directorySize(path) {
+    let total = 0;
+    let entries;
+    try {
+        entries = await readdir(path, { withFileTypes: true });
+    }
+    catch {
+        return 0;
+    }
+    for (const entry of entries) {
+        const child = join(path, entry.name);
+        if (entry.isDirectory())
+            total += await directorySize(child);
+        else if (entry.isFile()) {
+            try {
+                total += (await stat(child)).size;
+            }
+            catch {
+                // A file that vanished mid-walk costs nothing to skip.
+            }
+        }
+        // Stop early once the answer is already over budget: the exact figure is not used.
+        if (total > SHARE_BUDGET_BYTES)
+            return total;
+    }
+    return total;
+}
+/**
+ * Give the worktree the ignored directories it needs to build.
+ *
+ * Measured on this host for a 15,585-file / 163 MB `node_modules`:
+ * `git worktree add` 37 ms, a size walk 383 ms, and then the copy. Node's own
+ * recursive `fs.cp` took **13.4 s** — per-file async overhead dominates at this file
+ * count — while spawning `cp -a` took about **1 s**. So the copy is done by `cp` where
+ * it exists, and `fs.cp` is kept only as the fallback for Windows and for a `cp` that
+ * fails. Thirteen seconds is not a slower agent, it is a spawn that looks hung.
+ *
+ * Where the filesystem supports reflinks `cp -a` uses them; where it does not, the copy
+ * is real and the budget below is what bounds it. Returns the directories it could not
+ * share, because silence here would surface later as an agent claiming a pass it never
+ * ran.
+ */
+export async function shareIgnoredDirectories(from, to) {
+    const skipped = [];
+    for (const name of SHARED_IGNORED) {
+        const source = join(from, name);
+        const target = join(to, name);
+        try {
+            if (!(await stat(source)).isDirectory())
+                continue;
+        }
+        catch {
+            continue; // Not present: the common case, and not a problem.
+        }
+        if ((await directorySize(source)) > SHARE_BUDGET_BYTES) {
+            skipped.push(name);
+            continue;
+        }
+        if (await copyDirectory(source, target))
+            continue;
+        skipped.push(name);
+    }
+    return skipped;
+}
+/**
+ * Copy one directory tree, preferring the platform's own `cp`.
+ *
+ * `-a` keeps symlinks as symlinks and preserves mode and timestamps, which matters for
+ * an executable in `node_modules/.bin` and for a build cache that decides what to
+ * rebuild by timestamp.
+ */
+async function copyDirectory(source, target) {
+    if (process.platform !== "win32") {
+        try {
+            await execFileAsync("cp", ["-a", source, target], { maxBuffer: 8 * 1024 * 1024 });
+            return true;
+        }
+        catch {
+            // Fall through to the portable path: a `cp` that is missing or refused is not a
+            // reason to leave the agent without the tree it needs.
+        }
+    }
+    try {
+        await cp(source, target, { recursive: true, force: true, errorOnExist: false, dereference: false });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Give one agent call its own checkout, for `agent({ isolation: "worktree" })`.
+ *
+ * This is what makes parallel writers safe: two agents told to fix different
+ * files in the same tree still race each other's `git add -A`, each other's
+ * builds, and any tool that walks the project. A detached worktree at HEAD gives
+ * each call a private tree, so a sibling's half-finished edit cannot break it.
+ *
+ * Returns `null` when the project is not a git repository (or the worktree could
+ * not be made), because isolation is an optimisation for correctness, not a
+ * reason to fail a run: the caller falls back to the shared tree.
+ *
+ * The worktree is placed under the system temp dir rather than inside the
+ * project, so it never shows up in the project's own `git status` and is not
+ * walked by the agents themselves.
+ *
+ * **The ignored directories are the point of this function.** A worktree is a
+ * checkout of tracked files only, so it arrives without `node_modules/`,
+ * `target/`, `.venv/` — every artifact that is large precisely because it is not
+ * in git. An agent told to fix a bug and verify the fix therefore cannot run the
+ * build or the tests at all: it reports success it never checked, or gives up and
+ * says the tree is broken. Isolation that removes the ability to verify is not
+ * isolation, it is a broken checkout. We copy them in.
+ */
+export async function createAgentWorktree(cwd, label) {
+    if (!(await isGitRepo(cwd)))
+        return null;
+    const safe = label.replace(/[^A-Za-z0-9._-]/g, "-").slice(0, 40) || "agent";
+    const path = join(tmpdir(), `howtofix-wt-${process.pid}-${Date.now()}-${safe}`);
+    const created = await git(cwd, ["worktree", "add", "--detach", path, "HEAD"]);
+    if (!created.ok)
+        return null;
+    const skipped = await shareIgnoredDirectories(cwd, path);
+    return {
+        path,
+        skipped,
+        async remove() {
+            await git(cwd, ["worktree", "remove", "--force", path]);
+            // A crash can leave the directory behind; the worktree registration is
+            // what matters, so prune after removing.
+            await git(cwd, ["worktree", "prune"]);
+        },
+    };
+}

package/dist/goal-extension.js

@@ -0,0 +1,88 @@
+import { readMessageText, writeMessageText } from "./prompt-text.js";
+import { GOAL_CONTINUE, GOAL_ENTRY, continuationPrompt, readGoal, renderGoalBlock, setMirror, shouldContinue } from "./goal.js";
+/** Reseed the HUD mirror. Exported so the workbench can call it on /new and /resume. */
+export function seedGoalMirror(ctx) {
+    setMirror(readGoal(ctx));
+}
+/** The note written when the continuation budget is what stopped the run. */
+function budgetNote(goal) {
+    return `budget exhausted (${goal.budget ?? "default"} continuations)`;
+}
+export function createGoalExtension() {
+    return (hxf) => {
+        hxf.on("session_start", async (_event, ctx) => {
+            seedGoalMirror(ctx);
+        });
+        hxf.on("context_with_system", async (event, ctx) => {
+            const goal = readGoal(ctx);
+            setMirror(goal);
+            if (!goal || goal.status !== "active")
+                return undefined;
+            const head = event.messages[0];
+            if (!head || head.role !== "system")
+                return undefined;
+            const combined = `${readMessageText(head.content)}\n\n${renderGoalBlock(goal)}`;
+            const messages = event.messages.map((message) => (message === head ? { ...head, content: writeMessageText(head.content, combined) } : message));
+            return { messages };
+        });
+        hxf.on("agent_before_settle", async (event, ctx) => {
+            // After a session replacement the SDK still fires settle events for the
+            // session that was replaced, and any read through that ctx is rejected as
+            // stale. There is nothing to do for a session that is no longer on screen,
+            // so a stale ctx ends the handler quietly instead of surfacing an error
+            // the user can do nothing about.
+            try {
+                const goal = readGoal(ctx);
+                setMirror(goal);
+                if (shouldContinue(goal).action === "stop" || !goal)
+                    return undefined;
+                // A run already continuing for another reason (a queued continuation, a
+                // retry) must not be doubled up, and continuing is pointless when the
+                // context cannot accept another request.
+                if (event.continue || !event.context.canContinue)
+                    return undefined;
+                // Persist the spend before continuing: if the process dies mid-run the
+                // count is already on disk, so a resume cannot reset the budget.
+                const spent = { ...goal, used: goal.used + 1 };
+                hxf.appendEntry(GOAL_ENTRY, spent);
+                setMirror(spent);
+                if (shouldContinue(spent).action === "stop") {
+                    // This spend was the last one the budget allowed. Close it here as well
+                    // as on settle, so the state is right even if no settle event follows.
+                    const closed = { ...spent, status: "done", note: budgetNote(spent) };
+                    hxf.appendEntry(GOAL_ENTRY, closed);
+                    setMirror(closed);
+                    return undefined;
+                }
+                return {
+                    entries: [{ type: "custom_message", customType: GOAL_CONTINUE, content: continuationPrompt(spent), display: true }],
+                    continue: true,
+                };
+            }
+            catch {
+                return undefined;
+            }
+        });
+        hxf.on("agent_settled", async (_event, ctx) => {
+            // The run is over. If the budget was the reason, close the goal so the
+            // next prompt does not silently resume a runaway. A ctx left over from a
+            // replaced session throws on read; that session is gone, so there is
+            // nothing to close.
+            try {
+                const goal = readGoal(ctx);
+                const decision = shouldContinue(goal);
+                if (goal && decision.action === "stop" && decision.close) {
+                    const closed = { ...goal, status: "done", note: budgetNote(goal) };
+                    hxf.appendEntry(GOAL_ENTRY, closed);
+                    setMirror(closed);
+                }
+                else {
+                    setMirror(goal);
+                }
+            }
+            catch {
+                return;
+            }
+        });
+    };
+}

package/dist/goal.js

@@ -0,0 +1,222 @@
+/**
+ * A persistent goal for the session, with usage accounting and a continuation
+ * loop.
+ *
+ * Why this exists: opencode's most-reacted session request (#27167) is a native
+ * goal, and its own author states the reason it is not a command template — it
+ * "needs persistence, runtime continuation, usage accounting, and client
+ * sync/status surfaces". A slash command that prints a prompt can do none of
+ * those. What a goal buys over a plain message is that the harness knows what
+ * the run is *for*, so it can:
+ *
+ *   - keep the goal in the prompt every request (a long task survives a
+ *     compaction that drops the original message),
+ *   - continue working when the agent tries to stop with the goal still open,
+ *   - account the cost against it and stop at a budget instead of running away,
+ *   - refuse to let the model declare victory without evidence.
+ *
+ * State lives in the session branch (a `custom` entry), so it survives a resume
+ * and stays correct across a fork — the same reason `todo.ts` keeps its list
+ * there. A module-level mirror exists only so the HUD can paint the goal without
+ * a session handle; it is reseeded from the branch on `session_start`.
+ *
+ * Pure where it matters: {@link applyGoalOp} and {@link shouldContinue} hold the
+ * policy, so both are testable without a session or a model.
+ */
+import { StringEnum } from "@netrodev/hxf-ai";
+import { defineTool } from "@netrodev/hxf-coding-agent";
+import { Type } from "typebox";
+/** Session entry type the goal is persisted under. */
+export const GOAL_ENTRY = "howtofix.goal";
+/** Custom message type used for the automatic continuation. */
+export const GOAL_CONTINUE = "howtofix.goal.continue";
+/** Longest goal text accepted. */
+export const MAX_GOAL = 400;
+/**
+ * Continuations allowed when the goal sets no budget.
+ *
+ * A goal that can continue forever is the failure mode this whole feature is
+ * meant to avoid, so the default is a cap rather than "unlimited": an unattended
+ * run stops and says so, and the user can resume it.
+ */
+export const DEFAULT_BUDGET = 25;
+const MARK = {
+    active: "●",
+    paused: "‖",
+    done: "✓",
+    cleared: "○",
+};
+/** One line for the tool result and the HUD. */
+export function formatGoal(goal) {
+    if (!goal || goal.status === "cleared")
+        return "No goal set.";
+    const cap = goal.budget ?? DEFAULT_BUDGET;
+    const parts = [`${MARK[goal.status]} ${goal.status}`, `${goal.used}/${cap} continuations`];
+    if (goal.note)
+        parts.push(goal.note);
+    return `${parts.join(" · ")}\n${goal.text}`;
+}
+/** The short form painted in the HUD. Empty when there is nothing worth showing. */
+export function goalSegment(goal) {
+    if (!goal || goal.status === "cleared" || goal.status === "done")
+        return "";
+    const cap = goal.budget ?? DEFAULT_BUDGET;
+    const text = goal.text.length > 48 ? `${goal.text.slice(0, 47)}…` : goal.text;
+    return `goal ${MARK[goal.status]} ${goal.used}/${cap} · ${text}`;
+}
+/**
+ * The block injected into the prompt, so the goal survives compaction.
+ *
+ * Deliberately free of anything that changes between turns. This is appended to
+ * the system message, which is the cacheable prefix of every request, so a
+ * counter here would invalidate the prompt cache on every continuation — the
+ * same class of mistake that cost Claude Code 10.2% of fleet-wide cache
+ * creation tokens when a dynamic agent list sat in a tool schema. The spend is
+ * reported where it belongs: in the continuation message and the tool result,
+ * both of which are new content and cannot invalidate a cached prefix.
+ */
+export function renderGoalBlock(goal) {
+    const lines = ["<goal>", goal.text, `Status: ${goal.status}.`];
+    if (goal.status === "active") {
+        lines.push("Work toward this goal until it is genuinely met. When it is, call the `goal` tool with", 'op="complete" and a note naming the evidence; a command you ran or a file you checked.', "If you are blocked and cannot proceed, say so plainly instead of repeating an attempt.");
+    }
+    lines.push("</goal>");
+    return lines.join("\n");
+}
+/** What the agent is told when the harness decides to keep going. */
+export function continuationPrompt(goal) {
+    return [
+        "[goal] The goal is still open and you stopped without closing it:",
+        `  ${goal.text}`,
+        "",
+        "Continue from where you left off. Do not repeat work you already did. If the goal is met,",
+        'call the `goal` tool with op="complete" and a note naming the evidence. Do not call it',
+        "complete to escape a hard problem: if you cannot make progress, state what is blocking you.",
+        `Continuations used: ${goal.used}/${goal.budget ?? DEFAULT_BUDGET}.`,
+    ].join("\n");
+}
+/** A stable in-memory mirror for surfaces with no session handle (the HUD). */
+let mirror;
+export function currentGoal() {
+    return mirror;
+}
+export function setMirror(goal) {
+    mirror = goal;
+}
+export function shouldContinue(goal) {
+    if (!goal)
+        return { action: "stop", reason: "no goal", close: false };
+    if (goal.status === "done")
+        return { action: "stop", reason: "goal complete", close: false };
+    if (goal.status === "cleared")
+        return { action: "stop", reason: "goal cleared", close: false };
+    if (goal.status === "paused")
+        return { action: "stop", reason: "goal paused", close: false };
+    const cap = goal.budget ?? DEFAULT_BUDGET;
+    if (goal.used >= cap)
+        return { action: "stop", reason: `budget exhausted (${cap} continuations)`, close: true };
+    return { action: "continue" };
+}
+/** Apply one op. Pure, so the policy is testable without a session. */
+export function applyGoalOp(goal, op, text, budget, note) {
+    switch (op) {
+        case "view":
+            return { goal };
+        case "set": {
+            if (!text?.trim())
+                return { goal, error: "set needs text" };
+            if (text.length > MAX_GOAL)
+                return { goal, error: `text longer than ${MAX_GOAL} characters` };
+            if (budget !== undefined && (!Number.isInteger(budget) || budget < 1)) {
+                return { goal, error: "budget must be a positive integer" };
+            }
+            // A new goal resets the accounting: the cap belongs to the goal, not to
+            // the session, so a fresh goal gets its full budget.
+            return { goal: { text: text.trim(), status: "active", used: 0, ...(budget === undefined ? {} : { budget }) } };
+        }
+        case "pause":
+        case "resume":
+        case "complete":
+        case "clear": {
+            if (!goal || goal.status === "cleared")
+                return { goal, error: "no goal to change" };
+            if (op === "resume") {
+                if (goal.status === "done")
+                    return { goal, error: "goal is complete; set a new one instead" };
+                return { goal: { ...goal, status: "active", note: undefined } };
+            }
+            if (op === "pause")
+                return { goal: { ...goal, status: "paused" } };
+            if (op === "clear")
+                return { goal: { ...goal, status: "cleared" } };
+            // `complete` requires evidence. The model may only declare victory with a
+            // note naming what it verified; a bare "done" is what lets a wrong answer
+            // ship as a finished task.
+            if (!note?.trim())
+                return { goal, error: "complete needs a note naming the evidence (a command you ran or a file you checked)" };
+            return { goal: { ...goal, status: "done", note: note.trim() } };
+        }
+        default:
+            return { goal, error: `unknown op ${JSON.stringify(op)}` };
+    }
+}
+/**
+ * Rebuild the goal by replaying this branch in order.
+ *
+ * Two sources, because two things write it: the `goal` tool (whose result
+ * `details` are persisted in the transcript, exactly like `todo.ts`) and the
+ * continuation extension, which appends a `custom` entry to record a spend
+ * before it continues. Whichever is later in the branch wins, so a resume sees
+ * the true state and the accounting cannot be reset by a restart.
+ */
+export function readGoal(ctx) {
+    let goal;
+    for (const entry of ctx.sessionManager.getBranch()) {
+        if (entry.type === "custom" && entry.customType === GOAL_ENTRY) {
+            goal = entry.data;
+            continue;
+        }
+        // The slash command persists through `sendCustomMessage`, which writes a
+        // `custom_message` carrying the goal in `details` rather than `data`.
+        if (entry.type === "custom_message" && entry.customType === GOAL_ENTRY) {
+            goal = entry.details ?? goal;
+            continue;
+        }
+        if (entry.type !== "message")
+            continue;
+        const message = entry.message;
+        if (message.role !== "toolResult" || message.toolName !== "goal")
+            continue;
+        const details = message.details;
+        if (details?.goal)
+            goal = details.goal;
+    }
+    return goal;
+}
+export const goalParams = Type.Object({
+    op: StringEnum(["set", "view", "pause", "resume", "complete", "clear"], {
+        description: "set starts a goal; complete closes it with evidence; pause/resume/clear manage it; view reads it",
+    }),
+    text: Type.Optional(Type.String({ description: "The goal, in one sentence, as the user would state it (for set)" })),
+    budget: Type.Optional(Type.Number({ description: "Optional cap on automatic continuations before the run stops" })),
+    note: Type.Optional(Type.String({ description: "Evidence that the goal is met (required for complete)" })),
+});
+export const goalTool = defineTool({
+    name: "goal",
+    label: "goal",
+    description: "Track the goal for this session. The goal is already shown in your context every request, so you rarely need `view`. Call `complete` only when the goal is genuinely met, and pass a note naming the evidence. When a goal is active the harness continues the run if you stop without closing it, so closing it is how you stop.",
+    promptSnippet: "goal: the session's objective, and how to close it",
+    parameters: goalParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+        const before = readGoal(ctx);
+        const { goal, error } = applyGoalOp(before, params.op, params.text, params.budget, params.note);
+        setMirror(goal);
+        const body = formatGoal(goal);
+        const summary = error ? `Error: ${error}\n${body}` : body;
+        return {
+            content: [{ type: "text", text: summary }],
+            details: { op: params.op, goal },
+            ...(error ? { isError: true } : {}),
+        };
+    },
+});