@kinqs/brainrouter-cli 0.3.4

package/dist/state/cliState.d.ts

@@ -0,0 +1,59 @@
+export declare function isPathInside(parent: string, candidate: string): boolean;
+/**
+ * User-global brainrouter home. Defaults to `~/.brainrouter`. Override with
+ * the `BRAINROUTER_HOME` env var — tests set this to keep their state out of
+ * the real user home.
+ */
+export declare function getBrainrouterHome(): string;
+/**
+ * Per-workspace state root inside the global home. Encodes the absolute
+ * workspace path with a readable prefix + short hash so two workspaces with
+ * the same basename never collide.
+ *
+ *   ~/.brainrouter/workspaces/BrainRouter-3a7f9c12/
+ */
+export declare function getWorkspaceStateRoot(workspaceRoot: string): string;
+/**
+ * CLI state directory for a workspace. Defaults to
+ *   ~/.brainrouter/workspaces/<encoded>/cli
+ * Older builds wrote to <workspaceRoot>/.brainrouter/cli — `getWorkspaceStateRoot`
+ * handles the one-time migration so transcripts/goals/plans/hooks/memories
+ * follow the user instead of cluttering the project.
+ */
+export declare function getCliStateDir(workspaceRoot: string): string;
+/**
+ * Workspace-local state directory, e.g. `<workspace>/.brainrouter/`. Reserved
+ * for artifacts that are *meant* to be committed alongside the code — durable
+ * workflow specs, task breakdowns, walkthrough notes. Everything else
+ * (sessions, hooks, hookify rules, memories, preferences, transcripts) lives
+ * under `getWorkspaceStateRoot` in the user-global home so the project tree
+ * stays clean.
+ */
+export declare function getWorkspaceLocalDir(workspaceRoot: string): string;
+export declare function getCliStateFile(workspaceRoot: string, fileName: string): string;
+/**
+ * Encode a sessionKey to a safe directory name. Base64url keeps it short and
+ * round-trippable so listSessions can recover the original key. The 180-char
+ * cap matches the previous transcript filename limit.
+ */
+export declare function encodeSessionKey(sessionKey: string): string;
+export declare function decodeSessionKey(encoded: string): string;
+/**
+ * Per-session state bucket at `<workspace>/.brainrouter/cli/sessions/<encoded>/`.
+ * Goal, plan, transcript, and any future per-session artifacts live together
+ * here so users can browse one folder per chat session instead of hunting
+ * across siblings.
+ */
+export declare function getSessionStateDir(workspaceRoot: string, sessionKey: string): string;
+export declare function getSessionStateFile(workspaceRoot: string, sessionKey: string, fileName: string): string;
+/**
+ * List every persisted session bucket: returns `{ sessionKey, dir, modifiedAt }`
+ * newest first. Used by `/sessions` to render a picker.
+ */
+export declare function listSessionDirs(workspaceRoot: string): Array<{
+    sessionKey: string;
+    dir: string;
+    modifiedAt: string;
+}>;
+export declare function readJsonFile<T>(filePath: string, fallback: T): T;
+export declare function writeJsonFile(filePath: string, value: unknown): void;

package/dist/state/cliState.js

@@ -0,0 +1,311 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+export function isPathInside(parent, candidate) {
+    const relative = path.relative(parent, candidate);
+    return relative === '' || (!!relative && !relative.startsWith('..') && !path.isAbsolute(relative));
+}
+/**
+ * User-global brainrouter home. Defaults to `~/.brainrouter`. Override with
+ * the `BRAINROUTER_HOME` env var — tests set this to keep their state out of
+ * the real user home.
+ */
+export function getBrainrouterHome() {
+    const override = process.env.BRAINROUTER_HOME?.trim();
+    const target = override ?? path.join(os.homedir(), '.brainrouter');
+    fs.mkdirSync(target, { recursive: true });
+    // Resolve symlinks (eg. macOS /tmp → /private/tmp) so callers comparing
+    // against `realpathSync(workspaceRoot)` see the same root.
+    try {
+        return fs.realpathSync(target);
+    }
+    catch {
+        return target;
+    }
+}
+/**
+ * Per-workspace state root inside the global home. Encodes the absolute
+ * workspace path with a readable prefix + short hash so two workspaces with
+ * the same basename never collide.
+ *
+ *   ~/.brainrouter/workspaces/BrainRouter-3a7f9c12/
+ */
+export function getWorkspaceStateRoot(workspaceRoot) {
+    const abs = fs.realpathSync(workspaceRoot);
+    const home = getBrainrouterHome();
+    const encoded = encodeWorkspacePath(abs);
+    const dir = path.join(home, 'workspaces', encoded);
+    fs.mkdirSync(dir, { recursive: true });
+    // Migration check fires here (idempotent) so hooks/ and memories/ get
+    // moved over even if the caller never goes through getCliStateDir.
+    migrateLegacyWorkspaceState(workspaceRoot, dir);
+    return dir;
+}
+function encodeWorkspacePath(absWorkspaceRoot) {
+    const base = path.basename(absWorkspaceRoot).replace(/[^A-Za-z0-9._-]+/g, '_') || 'root';
+    const hash = crypto.createHash('sha1').update(absWorkspaceRoot).digest('hex').slice(0, 8);
+    return `${base.slice(0, 60)}-${hash}`;
+}
+/**
+ * CLI state directory for a workspace. Defaults to
+ *   ~/.brainrouter/workspaces/<encoded>/cli
+ * Older builds wrote to <workspaceRoot>/.brainrouter/cli — `getWorkspaceStateRoot`
+ * handles the one-time migration so transcripts/goals/plans/hooks/memories
+ * follow the user instead of cluttering the project.
+ */
+export function getCliStateDir(workspaceRoot) {
+    const wsRoot = getWorkspaceStateRoot(workspaceRoot);
+    const stateDir = path.join(wsRoot, 'cli');
+    if (!isPathInside(wsRoot, stateDir)) {
+        throw new Error('CLI state directory escapes workspace state root.');
+    }
+    fs.mkdirSync(stateDir, { recursive: true });
+    return stateDir;
+}
+let migrationAttempted = new Set();
+function migrateLegacyWorkspaceState(workspaceRoot, newRoot) {
+    if (migrationAttempted.has(workspaceRoot))
+        return;
+    migrationAttempted.add(workspaceRoot);
+    try {
+        const abs = fs.realpathSync(workspaceRoot);
+        const legacyRoot = path.join(abs, '.brainrouter');
+        if (!fs.existsSync(legacyRoot))
+            return;
+        // If the legacy tree IS the new tree (because BRAINROUTER_HOME points at the
+        // workspace), do nothing.
+        if (path.resolve(legacyRoot) === path.resolve(newRoot))
+            return;
+        // The workspace-local "workflows/" tree is intentionally part of the
+        // workspace and must NOT be migrated away — that's the documented
+        // place to keep spec.md / tasks.md / walkthrough.md so the team can
+        // commit them. We only rescue cli/, hooks/, and memories/.
+        const markerFile = path.join(newRoot, '.migrated-from-workspace');
+        if (!fs.existsSync(markerFile)) {
+            for (const sub of ['cli', 'hooks', 'memories']) {
+                const src = path.join(legacyRoot, sub);
+                if (fs.existsSync(src)) {
+                    copyDirRecursive(src, path.join(newRoot, sub));
+                }
+            }
+            fs.writeFileSync(markerFile, `Migrated from ${legacyRoot} at ${new Date().toISOString()}\n`, 'utf8');
+            process.stderr.write(`brainrouter: migrated legacy state from ${legacyRoot} to ${newRoot}\n`);
+        }
+        // Now neutralize the legacy directory so the agent's list_dir / read_file
+        // don't see stale state in the workspace tree. Anything that ISN'T a
+        // workflows/ folder is moved to .brainrouter.migrated/. If only
+        // workflows/ remains, the workspace-local .brainrouter/ stays as the
+        // canonical home for committable artifacts.
+        const archiveRoot = path.join(abs, '.brainrouter.migrated');
+        const entries = fs.readdirSync(legacyRoot, { withFileTypes: true });
+        let archivedAny = false;
+        for (const entry of entries) {
+            if (entry.name === 'workflows')
+                continue;
+            const from = path.join(legacyRoot, entry.name);
+            const to = path.join(archiveRoot, entry.name);
+            try {
+                fs.mkdirSync(archiveRoot, { recursive: true });
+                if (!fs.existsSync(to)) {
+                    fs.renameSync(from, to);
+                    archivedAny = true;
+                }
+                else {
+                    // Already archived from a prior run — just remove the stale copy.
+                    fs.rmSync(from, { recursive: true, force: true });
+                }
+            }
+            catch {
+                // best-effort: skip files we can't rename
+            }
+        }
+        if (archivedAny) {
+            process.stderr.write(`brainrouter: archived legacy in-workspace state to ${archiveRoot} (safe to delete after verifying)\n`);
+        }
+        // If the workspace-local `.brainrouter/` is now completely empty (no
+        // `workflows/` to preserve), remove the empty shell so the user
+        // doesn't see a stray folder reappear every session. We only delete
+        // it when empty — never when it still has committable workflow
+        // artifacts inside.
+        try {
+            const remaining = fs.readdirSync(legacyRoot);
+            if (remaining.length === 0) {
+                fs.rmdirSync(legacyRoot);
+            }
+        }
+        catch {
+            // best-effort cleanup
+        }
+    }
+    catch (err) {
+        // Migration is best-effort. If it fails (permissions etc.), the CLI still
+        // runs against the new location and the user can copy manually.
+        process.stderr.write(`brainrouter: legacy-state migration skipped (${err.message ?? err})\n`);
+    }
+}
+/**
+ * Workspace-local state directory, e.g. `<workspace>/.brainrouter/`. Reserved
+ * for artifacts that are *meant* to be committed alongside the code — durable
+ * workflow specs, task breakdowns, walkthrough notes. Everything else
+ * (sessions, hooks, hookify rules, memories, preferences, transcripts) lives
+ * under `getWorkspaceStateRoot` in the user-global home so the project tree
+ * stays clean.
+ */
+export function getWorkspaceLocalDir(workspaceRoot) {
+    const root = fs.realpathSync(workspaceRoot);
+    const dir = path.join(root, '.brainrouter');
+    if (!isPathInside(root, dir)) {
+        throw new Error('Workspace-local brainrouter directory escapes workspace root.');
+    }
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+}
+function copyDirRecursive(src, dst) {
+    if (!fs.existsSync(src))
+        return;
+    fs.mkdirSync(dst, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        const srcPath = path.join(src, entry.name);
+        const dstPath = path.join(dst, entry.name);
+        if (entry.isDirectory()) {
+            copyDirRecursive(srcPath, dstPath);
+        }
+        else if (entry.isFile()) {
+            if (fs.existsSync(dstPath))
+                continue; // don't clobber existing state
+            fs.copyFileSync(srcPath, dstPath);
+        }
+    }
+}
+export function getCliStateFile(workspaceRoot, fileName) {
+    if (!/^[a-zA-Z0-9._-]+$/.test(fileName)) {
+        throw new Error(`Invalid CLI state file name: ${fileName}`);
+    }
+    const stateDir = getCliStateDir(workspaceRoot);
+    const filePath = path.join(stateDir, fileName);
+    if (!isPathInside(stateDir, filePath)) {
+        throw new Error(`CLI state file escapes state directory: ${fileName}`);
+    }
+    return filePath;
+}
+/**
+ * Encode a sessionKey to a safe directory name. Base64url keeps it short and
+ * round-trippable so listSessions can recover the original key. The 180-char
+ * cap matches the previous transcript filename limit.
+ */
+export function encodeSessionKey(sessionKey) {
+    return Buffer.from(sessionKey, 'utf8').toString('base64url').slice(0, 180);
+}
+export function decodeSessionKey(encoded) {
+    try {
+        return Buffer.from(encoded, 'base64url').toString('utf8');
+    }
+    catch {
+        return encoded;
+    }
+}
+/**
+ * Per-session state bucket at `<workspace>/.brainrouter/cli/sessions/<encoded>/`.
+ * Goal, plan, transcript, and any future per-session artifacts live together
+ * here so users can browse one folder per chat session instead of hunting
+ * across siblings.
+ */
+export function getSessionStateDir(workspaceRoot, sessionKey) {
+    const stateDir = getCliStateDir(workspaceRoot);
+    const sessionsDir = path.join(stateDir, 'sessions');
+    fs.mkdirSync(sessionsDir, { recursive: true });
+    const sessionDir = path.join(sessionsDir, encodeSessionKey(sessionKey));
+    if (!isPathInside(sessionsDir, sessionDir)) {
+        throw new Error('Session state directory escapes CLI state dir.');
+    }
+    fs.mkdirSync(sessionDir, { recursive: true });
+    return sessionDir;
+}
+export function getSessionStateFile(workspaceRoot, sessionKey, fileName) {
+    if (!/^[a-zA-Z0-9._-]+$/.test(fileName)) {
+        throw new Error(`Invalid session state file name: ${fileName}`);
+    }
+    const sessionDir = getSessionStateDir(workspaceRoot, sessionKey);
+    const filePath = path.join(sessionDir, fileName);
+    if (!isPathInside(sessionDir, filePath)) {
+        throw new Error('Session state file escapes session directory.');
+    }
+    return filePath;
+}
+/**
+ * List every persisted session bucket: returns `{ sessionKey, dir, modifiedAt }`
+ * newest first. Used by `/sessions` to render a picker.
+ */
+export function listSessionDirs(workspaceRoot) {
+    const sessionsDir = path.join(getCliStateDir(workspaceRoot), 'sessions');
+    if (!fs.existsSync(sessionsDir))
+        return [];
+    const entries = fs.readdirSync(sessionsDir, { withFileTypes: true });
+    const out = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const dir = path.join(sessionsDir, entry.name);
+        let mtime = new Date(0);
+        try {
+            const stat = fs.statSync(dir);
+            mtime = stat.mtime;
+            // The transcript drives "last activity" better than the dir mtime.
+            const transcript = path.join(dir, 'transcript.jsonl');
+            if (fs.existsSync(transcript)) {
+                mtime = fs.statSync(transcript).mtime;
+            }
+        }
+        catch { /* unreadable */ }
+        out.push({
+            sessionKey: decodeSessionKey(entry.name),
+            dir,
+            modifiedAt: mtime.toISOString(),
+        });
+    }
+    return out.sort((a, b) => b.modifiedAt.localeCompare(a.modifiedAt));
+}
+export function readJsonFile(filePath, fallback) {
+    if (!fs.existsSync(filePath)) {
+        return fallback;
+    }
+    try {
+        const raw = fs.readFileSync(filePath, 'utf8');
+        if (!raw.trim()) {
+            return fallback;
+        }
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        // Falling back instead of throwing means a single corrupted state file
+        // (truncated JSON from Ctrl-C mid-write, partial migration, hand-edit)
+        // can't prevent the REPL from booting. Quarantine the bad file so the
+        // user can inspect it, then return the caller's fallback value. The
+        // alternative — propagating — meant a half-byte goal.json bricked the
+        // entire CLI because createSystemMessage reads it on every turn start.
+        try {
+            const quarantine = `${filePath}.corrupt-${Date.now()}`;
+            fs.renameSync(filePath, quarantine);
+            console.warn(`[brainrouter] could not parse ${filePath} (${err.message}); ` +
+                `moved to ${quarantine} and falling back to default.`);
+        }
+        catch {
+            // Couldn't quarantine — just warn and continue with the fallback.
+            console.warn(`[brainrouter] could not parse ${filePath}: ${err.message}; using default.`);
+        }
+        return fallback;
+    }
+}
+export function writeJsonFile(filePath, value) {
+    const dir = path.dirname(filePath);
+    fs.mkdirSync(dir, { recursive: true });
+    // Temp suffix needs to be unique even when two writers run in the same
+    // millisecond (e.g. goal + plan + prefs writes during a single
+    // auto-continuation tick). Date.now() is millisecond-resolution so the old
+    // form `${pid}.${ms}.tmp` collides under load; add a 6-byte random nonce.
+    const nonce = crypto.randomBytes(6).toString('hex');
+    const tmpPath = `${filePath}.${process.pid}.${Date.now()}.${nonce}.tmp`;
+    fs.writeFileSync(tmpPath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+    fs.renameSync(tmpPath, filePath);
+}

package/dist/state/goalStore.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Persistent goal / continuation contract for the agent. A goal is not just
+ * a sticky string — it carries lifecycle status, a budget that bounds how
+ * far auto-continuation will go, and timestamps so resumed sessions know
+ * exactly where they left off.
+ *
+ *   - text:           the outcome that should be true when done
+ *   - status:         active | paused | complete | blocked | usage_limited
+ *   - budget:         iteration AND optional token caps; auto-continuation
+ *                     halts (and the goal moves to `usage_limited`) when
+ *                     either is exhausted
+ *   - timestamps:     startedAt, updatedAt, completedAt
+ *   - blockedReason:  filled when the agent calls goal_blocked
+ *
+ * Status semantics:
+ *   - active         — continuation loop is allowed to fire next turn
+ *   - paused         — user-initiated suspend; resume re-arms the loop
+ *   - complete       — outcome satisfied; loop stops permanently
+ *   - blocked        — agent reported a hard impasse (missing data, external
+ *                      dep); loop stops until user intervenes
+ *   - usage_limited  — budget (iterations or tokens) exhausted; resumable
+ *                      after raising the budget. NEW compared to the old
+ *                      paused/blocked-only model: lets the UI distinguish
+ *                      "you ran out of room" from "user paused" from
+ *                      "agent gave up."
+ *
+ * Storage (per-session bucket):
+ *   ~/.brainrouter/workspaces/<encoded>/cli/sessions/<encodedKey>/goal.json
+ *
+ * Legacy fallback paths exist for sessions created before per-session
+ * goal isolation was added. normalize() fills missing fields with defaults
+ * so resumed sessions don't crash on first read.
+ */
+export type GoalStatus = 'active' | 'paused' | 'complete' | 'blocked' | 'usage_limited';
+/** A pausing status is one where continuation is halted but resumable. */
+export declare const PAUSING_STATUSES: readonly GoalStatus[];
+export interface GoalBudget {
+    maxIterations: number;
+    iterationsUsed: number;
+    /**
+     * Optional cumulative-token cap. When set, each turn's prompt+completion
+     * tokens accumulate into `tokensUsed`; once `tokensUsed >= maxTokens` the
+     * goal moves to `usage_limited` instead of just consuming another
+     * iteration. Lets users protect a fixed dollar budget without having to
+     * estimate the iteration count by hand.
+     */
+    maxTokens?: number;
+    tokensUsed?: number;
+}
+export interface Goal {
+    text: string;
+    setAt: string;
+    status: GoalStatus;
+    budget: GoalBudget;
+    startedAt: string;
+    updatedAt: string;
+    completedAt?: string;
+    blockedReason?: string;
+}
+export declare const DEFAULT_GOAL_BUDGET = 10;
+/**
+ * Hard cap on the goal text length. A goal is supposed to be a 1–3 sentence
+ * outcome statement; multi-thousand-character pastes (e.g. full chat logs)
+ * derail every subsequent turn because the goal block is re-injected into
+ * the system prompt on EVERY iteration.
+ */
+export declare const GOAL_TEXT_MAX_CHARS = 4000;
+export declare class GoalTooLongError extends Error {
+    readonly length: number;
+    constructor(length: number);
+}
+/**
+ * Thrown when `setGoal` would overwrite a non-complete existing goal and
+ * the caller didn't pass `force: true`. The REPL catches this and prompts
+ * the user before replacing — interrupting in-flight work without
+ * confirmation is one of the easiest ways to lose progress.
+ *
+ * A `complete` goal does NOT raise this — replacing a finished goal is
+ * just starting fresh, no work is at risk.
+ */
+export declare class GoalConflictError extends Error {
+    readonly existing: Goal;
+    constructor(existing: Goal);
+}
+export declare function readGoal(workspaceRoot: string, sessionKey?: string): Goal | null;
+/**
+ * Set a new active goal. Refuses to overwrite an in-progress goal (active,
+ * paused, blocked, or usage_limited) unless `force: true` is passed. The
+ * REPL catches the resulting GoalConflictError and prompts the user before
+ * replacing. Replacing a `complete` goal is allowed silently — at that
+ * point the prior goal isn't doing any work and a new one is just starting
+ * fresh.
+ */
+export declare function setGoal(workspaceRoot: string, text: string, sessionKey?: string, options?: {
+    maxIterations?: number;
+    maxTokens?: number;
+    force?: boolean;
+}): Goal;
+export declare function clearGoal(workspaceRoot: string, sessionKey?: string): void;
+export declare function pauseGoal(workspaceRoot: string, sessionKey?: string): Goal | null;
+export declare function resumeGoal(workspaceRoot: string, sessionKey?: string): Goal | null;
+export declare function completeGoal(workspaceRoot: string, sessionKey?: string, proof?: string): Goal | null;
+export declare function blockGoal(workspaceRoot: string, sessionKey: string | undefined, reason: string): Goal | null;
+/**
+ * Mark the goal as `usage_limited` — distinct from paused (user-initiated)
+ * and blocked (agent gave up). Used when the iteration or token budget
+ * runs out. The user can resume after raising the budget; the loop won't
+ * fire another turn on its own until they do.
+ */
+export declare function usageLimitGoal(workspaceRoot: string, sessionKey: string | undefined, reason: string): Goal | null;
+export declare function setGoalBudget(workspaceRoot: string, sessionKey: string | undefined, maxIterations: number): Goal | null;
+/**
+ * Set or clear the optional token budget. Pass `0` (or any negative) to
+ * clear; positive integers set the cap. Resets tokensUsed to 0 when first
+ * enabling so the goal doesn't immediately appear exhausted.
+ */
+export declare function setGoalTokenBudget(workspaceRoot: string, sessionKey: string | undefined, maxTokens: number): Goal | null;
+export declare function tickGoalIteration(workspaceRoot: string, sessionKey?: string): Goal | null;
+/**
+ * Add `delta` tokens to the goal's running tally. No-op if a goal has no
+ * token budget set. Returns the updated Goal so callers can decide whether
+ * to transition to `usage_limited` afterwards.
+ */
+export declare function addGoalTokens(workspaceRoot: string, sessionKey: string | undefined, delta: number): Goal | null;
+/**
+ * Unified update entrypoint. Lets callers mutate text/status/budget in a
+ * single call instead of stringing pause→budget→resume together. Used by
+ * the `/goal edit` REPL subcommand.
+ */
+export declare function editGoal(workspaceRoot: string, sessionKey: string | undefined, patch: {
+    text?: string;
+    status?: GoalStatus;
+    maxIterations?: number;
+    maxTokens?: number;
+}): Goal | null;
+/**
+ * True iff scheduling ONE MORE iteration would still fit inside BOTH the
+ * iteration cap and (if set) the token cap.
+ *
+ * The continuation loop ticks AFTER deciding to continue (so `iterationsUsed`
+ * lags by one until the tick runs). To stop after exactly `maxIterations`
+ * runs total, the predicate must ask "is (used+1) still within the cap?",
+ * not "is (used) still under the cap?". The old form gave you N+1 runs.
+ *
+ * Token budget is a hard "currently used vs cap" check — we can't know the
+ * next turn's token cost ahead of time, so we just refuse to schedule when
+ * we're already at or past the cap.
+ */
+export declare function goalHasBudgetLeft(goal: Goal): boolean;
+/**
+ * True iff this is the FINAL turn within the budget — i.e. the iteration
+ * tick is about to land but one more after it would exceed the cap. The
+ * continuation loop uses this to inject a "wrap up gracefully" steering
+ * message so the model lands soft instead of being interrupted mid-thought.
+ *
+ * Specifically: after this turn's tick, iterationsUsed will equal
+ * maxIterations - 1, so `goalHasBudgetLeft` will return false on the next
+ * decision. We detect that ahead of time by checking before the tick.
+ */
+export declare function goalIsOnFinalBudgetTurn(goal: Goal): boolean;
+/**
+ * Wrap-up steering message injected on the final-budget turn. The agent
+ * loop pushes this into the chat history as a system message so the model
+ * pivots from "continue investigating" to "consolidate and report." Plain
+ * directive, no role-play.
+ *
+ * The message specifically reports WHICH cap is tight (iterations, tokens,
+ * or both) so the model doesn't get told "one turn left" when it actually
+ * has many iterations remaining but is near the token cap, or vice versa.
+ * Earlier versions hardcoded the iteration framing even when only the
+ * token heuristic tripped, which misled the model on token-budgeted runs.
+ */
+export declare function buildBudgetSteeringMessage(goal: Goal): string;
+export declare function formatGoalBlock(goal: Goal): string;