@kinqs/brainrouter-cli 0.3.5 → 0.3.7

package/dist/state/goalStore.js

@@ -1,8 +1,29 @@
 import fs from 'node:fs';
-import { getCliStateFile, getSessionStateFile, readJsonFile, writeJsonFile } from './cliState.js';
+import path from 'node:path';
+import { getCliStateDir, getCliStateFile, getSessionStateFile, readJsonFile, writeJsonFile } from './cliState.js';
 /** A pausing status is one where continuation is halted but resumable. */
 export const PAUSING_STATUSES = ['paused', 'blocked', 'usage_limited'];
-export const DEFAULT_GOAL_BUDGET = 10;
+/**
+ * Default iteration cap when the user doesn't pass one.
+ *
+ * Set to a very high number (effectively "unlimited" for any real task)
+ * rather than a tight 10. Rationale: the goal lifecycle has three
+ * independent safety nets that already prevent runaway loops —
+ *   1. Anti-spin   — a turn that made zero tool calls doesn't continue
+ *   2. Repeat-loop — calling the same tool with identical args 3× errors
+ *   3. Manual stop — Ctrl-C, /goal pause, /goal clear
+ *
+ * A hard iteration cap on top of those is overly paternalistic for users
+ * running local models (no $ cost) and is easily lifted with /goal budget
+ * <n> when wanted. Display layers should treat any value >= UNLIMITED_THRESHOLD
+ * as "unlimited" for friendlier UX.
+ */
+export const DEFAULT_GOAL_BUDGET = 1_000_000;
+export const UNLIMITED_BUDGET_THRESHOLD = 100_000;
+/** Format helper — used by REPL display + status output. */
+export function formatBudget(maxIterations) {
+    return maxIterations >= UNLIMITED_BUDGET_THRESHOLD ? 'unlimited' : String(maxIterations);
+}
 /**
  * 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)
@@ -67,26 +88,55 @@ function normalize(raw) {
         blockedReason: raw.blockedReason,
     };
 }
-function resolveGoalFile(workspaceRoot, sessionKey) {
+/**
+ * Resolve the on-disk location where the active goal for this CLI process
+ * lives.
+ *
+ * **Design (0.3.6 decouple-goal-from-workflow, supersedes Item 3):** goal
+ * is **always per-session**. Workflows are durable artifact folders
+ * (spec.md, tasks.md, walkthrough.md, meta.json) that have nothing to do
+ * with the agent's autonomy primitive. The earlier Item 3 design coupled
+ * the two by storing goal state inside `<workflow>/goal.json`, which
+ * meant any two CLI sessions in the same workspace that happened to land
+ * on the same workflow shared a goal — silently reintroducing the
+ * cross-session leak PR #26 had fixed. We removed that coupling
+ * entirely: workflows are storage, goals are runtime, no overlap.
+ *
+ * Priority chain:
+ *   1. Session-scoped — `<session>/goal.json`. The normal case.
+ *   2. Legacy — `<cli-state>/goal.json`. Only hit by callers without a
+ *      sessionKey (rare; mostly tooling paths that pre-date Item 1).
+ */
+export function resolveGoalScope(workspaceRoot, sessionKey) {
     if (sessionKey) {
-        const sessionPath = getSessionStateFile(workspaceRoot, sessionKey, 'goal.json');
-        if (fs.existsSync(sessionPath))
-            return sessionPath;
+        return {
+            scope: 'session',
+            sessionKey,
+            path: getSessionStateFile(workspaceRoot, sessionKey, 'goal.json'),
+        };
     }
-    return getCliStateFile(workspaceRoot, 'goal.json');
+    return { scope: 'legacy', path: getCliStateFile(workspaceRoot, 'goal.json') };
 }
 export function readGoal(workspaceRoot, sessionKey) {
-    if (sessionKey) {
-        const sessionPath = getSessionStateFile(workspaceRoot, sessionKey, 'goal.json');
-        if (fs.existsSync(sessionPath)) {
-            return normalize(readJsonFile(sessionPath, null));
-        }
-    }
+    const scope = resolveGoalScope(workspaceRoot, sessionKey);
+    if (!fs.existsSync(scope.path))
+        return null;
+    return normalize(readJsonFile(scope.path, null));
+}
+function archiveLegacyGoal(workspaceRoot) {
     const legacyPath = getCliStateFile(workspaceRoot, 'goal.json');
-    if (fs.existsSync(legacyPath)) {
-        return normalize(readJsonFile(legacyPath, null));
+    if (!fs.existsSync(legacyPath))
+        return;
+    const archiveDir = path.join(getCliStateDir(workspaceRoot), '.brainrouter.migrated');
+    fs.mkdirSync(archiveDir, { recursive: true });
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    let archivePath = path.join(archiveDir, `legacy-goal-${stamp}.json`);
+    let suffix = 1;
+    while (fs.existsSync(archivePath)) {
+        archivePath = path.join(archiveDir, `legacy-goal-${stamp}-${suffix}.json`);
+        suffix += 1;
     }
-    return null;
+    fs.renameSync(legacyPath, archivePath);
 }
 /**
  * Set a new active goal. Refuses to overwrite an in-progress goal (active,
@@ -111,6 +161,13 @@ export function setGoal(workspaceRoot, text, sessionKey, options = {}) {
             throw new GoalConflictError(existing);
         }
     }
+    const scope = resolveGoalScope(workspaceRoot, sessionKey);
+    // Archive any stale workspace-level goal.json the moment we write to a
+    // non-legacy scope (workflow OR session). This preserves the Item 1 fix:
+    // never leave the legacy file where a future session would re-pick it up.
+    if (scope.scope !== 'legacy') {
+        archiveLegacyGoal(workspaceRoot);
+    }
     const now = new Date().toISOString();
     const goal = {
         text: trimmed,
@@ -124,19 +181,19 @@ export function setGoal(workspaceRoot, text, sessionKey, options = {}) {
         startedAt: now,
         updatedAt: now,
     };
-    const filePath = sessionKey
-        ? getSessionStateFile(workspaceRoot, sessionKey, 'goal.json')
-        : getCliStateFile(workspaceRoot, 'goal.json');
-    writeJsonFile(filePath, goal);
+    writeJsonFile(scope.path, goal);
     return goal;
 }
 export function clearGoal(workspaceRoot, sessionKey) {
-    if (sessionKey) {
-        writeJsonFile(getSessionStateFile(workspaceRoot, sessionKey, 'goal.json'), null);
-    }
-    const legacy = getCliStateFile(workspaceRoot, 'goal.json');
-    if (fs.existsSync(legacy)) {
-        writeJsonFile(legacy, null);
+    const scope = resolveGoalScope(workspaceRoot, sessionKey);
+    writeJsonFile(scope.path, null);
+    // Also clear the legacy workspace file when we're operating on a higher-
+    // priority scope — leaving it behind would let a future no-sessionKey
+    // read resurface a stale goal.
+    if (scope.scope !== 'legacy') {
+        const legacy = getCliStateFile(workspaceRoot, 'goal.json');
+        if (fs.existsSync(legacy))
+            writeJsonFile(legacy, null);
     }
 }
 function patchGoal(workspaceRoot, sessionKey, patch) {
@@ -148,7 +205,7 @@ function patchGoal(workspaceRoot, sessionKey, patch) {
         ...patch,
         updatedAt: new Date().toISOString(),
     };
-    writeJsonFile(resolveGoalFile(workspaceRoot, sessionKey), next);
+    writeJsonFile(resolveGoalScope(workspaceRoot, sessionKey).path, next);
     return next;
 }
 export function pauseGoal(workspaceRoot, sessionKey) {
@@ -311,18 +368,19 @@ export function goalIsOnFinalBudgetTurn(goal) {
     return false;
 }
 /**
- * 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.
+ * Wrap-up directive folded into the goal-anchor block when the goal is on
+ * its final budget turn. Reports WHICH cap is tight (iterations, tokens,
+ * or both) so the model isn't told "one turn left" when it actually has
+ * many iterations remaining but is near the token cap, or vice versa.
  *
- * 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.
+ * Pre-0.3.6-9d this lived in its own `buildBudgetSteeringMessage` function
+ * emitted as a separate `goal-budget-steering` tagged system message —
+ * which meant the same iteration/token counts appeared in TWO places per
+ * turn (the goal anchor AND the steering message). 9d folded the wrap-up
+ * directive into the anchor itself; `formatGoalBlock(goal)` calls this
+ * helper internally when `goalIsOnFinalBudgetTurn(goal)` returns true.
  */
-export function buildBudgetSteeringMessage(goal) {
+function buildWrapUpDirective(goal) {
     const iterationsRemaining = Math.max(0, goal.budget.maxIterations - goal.budget.iterationsUsed - 1);
     const iterationTight = goal.budget.iterationsUsed + 2 >= goal.budget.maxIterations;
     const tokensTight = typeof goal.budget.maxTokens === 'number' &&
@@ -345,7 +403,6 @@ export function buildBudgetSteeringMessage(goal) {
                 `(cap ${goal.budget.maxIterations})${tokensClause}. This is your last turn.`;
     }
     else {
-        // Token cap is the trigger; iterations may still have plenty of headroom.
         const tokensUsed = goal.budget.tokensUsed ?? 0;
         const tokensCap = goal.budget.maxTokens ?? 0;
         const tokensRemaining = Math.max(0, tokensCap - tokensUsed);
@@ -355,7 +412,7 @@ export function buildBudgetSteeringMessage(goal) {
                 `Iteration count still has headroom but the token cap will trip before another full turn fits.`;
     }
     return [
-        '## Budget about to run out',
+        '## ⚠️ Final iteration — wrap up cleanly',
         headline,
         'Do not start any new long-running investigation, spawn new children, or read more files.',
         'Instead:',
@@ -365,16 +422,21 @@ export function buildBudgetSteeringMessage(goal) {
         '4. If you need more budget, say so explicitly so the user can extend it.',
     ].join('\n');
 }
-export function formatGoalBlock(goal) {
-    const remaining = Math.max(0, goal.budget.maxIterations - goal.budget.iterationsUsed);
+export function formatGoalBlock(goal, options = {}) {
+    const cap = formatBudget(goal.budget.maxIterations);
+    const remaining = cap === 'unlimited'
+        ? 'unlimited'
+        : String(Math.max(0, goal.budget.maxIterations - goal.budget.iterationsUsed));
     const tokenLine = goal.budget.maxTokens
         ? `**Tokens:** ${(goal.budget.tokensUsed ?? 0).toLocaleString()} of ${goal.budget.maxTokens.toLocaleString()} used`
         : '';
+    const isFinalBudgetTurn = options.finalBudgetTurn ?? goalIsOnFinalBudgetTurn(goal);
+    const wrapUp = isFinalBudgetTurn && goal.status === 'active' ? buildWrapUpDirective(goal) : '';
     return [
         `## Active Goal — ${goal.status.toUpperCase().replace('_', ' ')}`,
         '',
         `**Outcome:** ${goal.text}`,
-        `**Iteration:** ${goal.budget.iterationsUsed + 1} of ${goal.budget.maxIterations} (${remaining} remaining)`,
+        `**Iteration:** ${goal.budget.iterationsUsed + 1} of ${cap} (${remaining} remaining)`,
         tokenLine,
         `**Started:** ${goal.startedAt}`,
         goal.blockedReason ? `**Reason:** ${goal.blockedReason}` : '',
@@ -406,5 +468,33 @@ export function formatGoalBlock(goal) {
         '',
         'Always audit the evidence before declaring complete — failing tests, missing files,',
         'or unverified claims mean the goal is NOT done yet.',
+        wrapUp ? '' : '',
+        wrapUp,
     ].filter(Boolean).join('\n');
 }
+/**
+ * Drift / ready check used by the goal-continuation prompt. Compressed
+ * from the prose-heavy 4-paragraph form into a 2-line checklist as part
+ * of 9d's prompt deduplication — the goal text, status, and budget are
+ * now owned by the goal-anchor system message; the continuation prompt
+ * carries only the per-turn drift check + a pointer to the anchor.
+ *
+ * Distinct from `buildGoalKickoffPrompt` (in `commands/_helpers.ts`),
+ * which is the FIRST-turn prompt fired by `/goal <text>` and `/goal resume`.
+ */
+export function buildGoalContinuationPrompt(goal, lastPrompt, lastAnswer) {
+    const iter = goal.budget.iterationsUsed + 1;
+    const cap = formatBudget(goal.budget.maxIterations);
+    return [
+        `[GOAL CONTINUATION — iteration ${iter}/${cap}]`,
+        '',
+        'Your goal, budget, and the goal_complete / goal_blocked contract are pinned in the goal-anchor system message above. This turn must serve that contract.',
+        '',
+        '**Drift check (mandatory):**',
+        '1. Does the next tool call advance the outcome stated in the anchor? If no, stop and either pick one that does, or call `goal_complete` / `goal_blocked`.',
+        '2. Restating intent in prose without a tool call is anti-spin — the loop will halt on intermediate turns that emit only prose. Final goal-completing turns require prose alongside the tool call.',
+        '',
+        `Last user message: ${lastPrompt || '(none)'}`,
+        `Your previous response (truncated): ${lastAnswer.slice(0, 600)}${lastAnswer.length > 600 ? '…' : ''}`,
+    ].join('\n');
+}

package/dist/state/preferencesStore.d.ts

@@ -5,6 +5,9 @@
  * CLI restarts but stay scoped to the project (different repos can have
  * different settings).
  */
+export type ExecutionMode = 'planning' | 'fast';
+export type ReviewPolicy = 'request' | 'proceed';
+export type EffortLevel = 'low' | 'medium' | 'high';
 export interface Preferences {
     /** When true, every worker spawn is auto-followed by a reviewer pass on the diff. */
     autoReview: boolean;
@@ -13,9 +16,25 @@ export interface Preferences {
     /** Status-line layout: comma-separated segments from {mode,branch,dirty,model,tokens,session}. */
     statusline: string;
     /**
-     * When true, `run_command` skips the per-call confirmation prompt and runs
-     * immediately. Pair with sandboxing (BRAINROUTER_SANDBOX=on) if you want
-     * the safety net without the friction. Off by default — opt-in via /yolo.
+     * Session execution stance. `planning` (default) routes `run_command`
+     * through the per-call `askYesNo` confirmation and keeps the system prompt
+     * leaning toward clarify-before-act. `fast` skips the confirmation for
+     * non-dangerous commands (see `isDangerousCommand`) and tells the model
+     * to jump to implementation. Toggle with `/mode`.
+     */
+    executionMode: ExecutionMode;
+    /**
+     * Behaviour at workflow / multi-file approval gates. `request` (default)
+     * keeps today's prose-based "ready for your approval?" gesture in front
+     * of `/approve`. `proceed` tells the model to apply the plan and report
+     * after, without the explicit ask. Toggle with `/review-policy`.
+     */
+    reviewPolicy: ReviewPolicy;
+    /**
+     * DEPRECATED — superseded by `executionMode` + `reviewPolicy` in 0.3.6.
+     * Kept on disk so older callers keep functioning during the alias
+     * transition. New code MUST read `executionMode === 'fast'` instead;
+     * `readPreferences` back-fills the new fields from this on first read.
      */
     autoApproveShell: boolean;
     /** Syntax highlighting theme for markdown output. Tied to/theme. */
@@ -36,6 +55,51 @@ export interface Preferences {
     sandboxReadPaths: string[];
     /** Extra write-allowed paths granted to sandboxed run_command. */
     sandboxWritePaths: string[];
+    /**
+     * When true, hide non-essential chrome from the REPL: briefing/recall
+     * tables, tool-completion previews, spawn dumps. Leaves spinner + model
+     * prose. Tied to /quiet and the --quiet startup flag. Off by default.
+     */
+    quiet: boolean;
+    /**
+     * Reasoning depth preference. `medium` (default) is today's behaviour and
+     * emits no system-prompt overlay and no provider-side reasoning slot.
+     * `low` adds a "be terse, skip ceremony" overlay; `high` adds a
+     * step-by-step audit overlay. When the LLM endpoint exposes a reasoning
+     * slot (gpt-5 / o-series via Chat Completions accept `reasoning_effort`),
+     * the level is also forwarded as the provider-native enum. Tied to
+     * `/effort` and the `BRAINROUTER_EFFORT` env override.
+     */
+    effort: EffortLevel;
 }
 export declare function readPreferences(workspaceRoot: string): Preferences;
 export declare function writePreferences(workspaceRoot: string, prefs: Partial<Preferences>): Preferences;
+/**
+ * `/yolo on` shorthand: flip both new fields to their "do not interrupt me"
+ * setting. We also keep the legacy `autoApproveShell` mirror in sync so any
+ * external tooling that still inspects it sees a consistent state during
+ * the alias period.
+ */
+export declare function applyYoloOn(workspaceRoot: string): Preferences;
+/**
+ * `/yolo off` shorthand: restore the conservative defaults on both axes.
+ */
+export declare function applyYoloOff(workspaceRoot: string): Preferences;
+export interface ResolvedEffort {
+    effort: EffortLevel;
+    source: 'env' | 'preference' | 'default';
+}
+/**
+ * Resolve the active reasoning-depth level using env > preference > default.
+ * Matches the precedence pattern set by `resolveTheme` and the
+ * `BRAINROUTER_QUIET` override.
+ *
+ * A garbled `BRAINROUTER_EFFORT` value (e.g. `BRAINROUTER_EFFORT=ludicrous`)
+ * is treated as unset so users don't get cryptic crashes — the preference
+ * takes over.
+ *
+ * We read the raw file (not `readPreferences`) so we can distinguish a
+ * preference that was explicitly written from the default that
+ * `readPreferences` injects via its spread.
+ */
+export declare function resolveEffort(workspaceRoot?: string): ResolvedEffort;

package/dist/state/preferencesStore.js

@@ -3,6 +3,8 @@ const DEFAULT = {
     autoReview: false,
     editorMode: 'emacs',
     statusline: 'mode',
+    executionMode: 'planning',
+    reviewPolicy: 'request',
     autoApproveShell: false,
     theme: 'auto',
     terminalTitle: 'model,session',
@@ -13,13 +15,94 @@ const DEFAULT = {
     keymap: '',
     sandboxReadPaths: [],
     sandboxWritePaths: [],
+    quiet: false,
+    effort: 'medium',
 };
+/**
+ * Back-fill `executionMode` / `reviewPolicy` from the legacy
+ * `autoApproveShell` flag when an older prefs file is read for the first
+ * time. Migration is read-only and idempotent: if either new field is
+ * already present we leave both alone (the user has already opted into the
+ * new model and any drift between the two is intentional). The legacy field
+ * stays on disk so other readers don't break during the alias period.
+ */
+function migrateLegacyShell(stored) {
+    const hasNewFields = stored.executionMode !== undefined || stored.reviewPolicy !== undefined;
+    if (hasNewFields)
+        return stored;
+    if (stored.autoApproveShell !== true)
+        return stored;
+    return {
+        ...stored,
+        executionMode: 'fast',
+        reviewPolicy: 'proceed',
+    };
+}
 export function readPreferences(workspaceRoot) {
     const stored = readJsonFile(getCliStateFile(workspaceRoot, 'preferences.json'), {});
-    return { ...DEFAULT, ...stored };
+    return { ...DEFAULT, ...migrateLegacyShell(stored) };
 }
 export function writePreferences(workspaceRoot, prefs) {
     const merged = { ...readPreferences(workspaceRoot), ...prefs };
     writeJsonFile(getCliStateFile(workspaceRoot, 'preferences.json'), merged);
     return merged;
 }
+/**
+ * `/yolo on` shorthand: flip both new fields to their "do not interrupt me"
+ * setting. We also keep the legacy `autoApproveShell` mirror in sync so any
+ * external tooling that still inspects it sees a consistent state during
+ * the alias period.
+ */
+export function applyYoloOn(workspaceRoot) {
+    return writePreferences(workspaceRoot, {
+        executionMode: 'fast',
+        reviewPolicy: 'proceed',
+        autoApproveShell: true,
+    });
+}
+/**
+ * `/yolo off` shorthand: restore the conservative defaults on both axes.
+ */
+export function applyYoloOff(workspaceRoot) {
+    return writePreferences(workspaceRoot, {
+        executionMode: 'planning',
+        reviewPolicy: 'request',
+        autoApproveShell: false,
+    });
+}
+function normalizeEffort(raw) {
+    if (typeof raw !== 'string')
+        return undefined;
+    const v = raw.trim().toLowerCase();
+    return v === 'low' || v === 'medium' || v === 'high' ? v : undefined;
+}
+/**
+ * Resolve the active reasoning-depth level using env > preference > default.
+ * Matches the precedence pattern set by `resolveTheme` and the
+ * `BRAINROUTER_QUIET` override.
+ *
+ * A garbled `BRAINROUTER_EFFORT` value (e.g. `BRAINROUTER_EFFORT=ludicrous`)
+ * is treated as unset so users don't get cryptic crashes — the preference
+ * takes over.
+ *
+ * We read the raw file (not `readPreferences`) so we can distinguish a
+ * preference that was explicitly written from the default that
+ * `readPreferences` injects via its spread.
+ */
+export function resolveEffort(workspaceRoot) {
+    const envEffort = normalizeEffort(process.env.BRAINROUTER_EFFORT);
+    if (envEffort)
+        return { effort: envEffort, source: 'env' };
+    if (workspaceRoot) {
+        try {
+            const stored = readJsonFile(getCliStateFile(workspaceRoot, 'preferences.json'), {});
+            const prefEffort = normalizeEffort(stored.effort);
+            if (prefEffort)
+                return { effort: prefEffort, source: 'preference' };
+        }
+        catch {
+            // Preferences file unreadable — fall through to default.
+        }
+    }
+    return { effort: 'medium', source: 'default' };
+}

package/dist/state/workflowArtifacts.d.ts

@@ -15,15 +15,76 @@ export declare const ARTIFACT: {
 export declare function slugify(input: string, fallback?: string): string;
 export declare function getWorkflowsRoot(workspaceRoot: string): string;
 export declare function getWorkflowDir(workspaceRoot: string, slug: string): string;
+/**
+ * Create (or reopen) a workflow folder + bind it as the current
+ * workflow.
+ *
+ * `sessionKey` is threaded through to `setCurrentWorkflow` so that the
+ * created workflow is bound to THIS session (not to every other CLI
+ * session in the workspace via the workspace-level pointer). Legacy
+ * callers without a session context fall through to workspace-level
+ * binding only — same back-compat path `setCurrentWorkflow` provides.
+ */
 export declare function createWorkflow(workspaceRoot: string, input: {
     title: string;
     kind: WorkflowMeta['kind'];
     slug?: string;
+    sessionKey?: string;
 }): WorkflowMeta;
 export declare function updateWorkflowStatus(workspaceRoot: string, slug: string, status: WorkflowMeta['status']): WorkflowMeta | undefined;
 export declare function listWorkflows(workspaceRoot: string): WorkflowMeta[];
-export declare function setCurrentWorkflow(workspaceRoot: string, slug: string): void;
-export declare function getCurrentWorkflow(workspaceRoot: string): string | undefined;
+/**
+ * Bind a workflow to the current CLI session AND update the workspace-
+ * level "last used" hint. When `sessionKey` is omitted (legacy callers,
+ * some first-run paths), only the workspace pointer is written — those
+ * callers don't have a session context yet, so per-session binding
+ * doesn't apply.
+ *
+ * The workspace pointer is updated unconditionally because we still
+ * want a fresh CLI in the same workspace to be ABLE to see "X is the
+ * last workflow that was touched here" — for display via
+ * `getLastUsedWorkflow`, for the `/workflows` listing's `★` marker, and
+ * for the post-9d "do you want to switch to <X>?" UX (the latter not
+ * yet shipped, tracked separately).
+ */
+export declare function setCurrentWorkflow(workspaceRoot: string, slug: string, sessionKey?: string): void;
+/**
+ * Which workflow is bound to THIS CLI session?
+ *
+ * - With `sessionKey`: reads ONLY the session-level pointer. A fresh
+ *   CLI session has no session-level pointer → returns `undefined`,
+ *   even when a workspace-level "last used" hint exists. This is the
+ *   load-bearing fix: new sessions don't auto-inherit another session's
+ *   workflow binding (which previously dragged that workflow's goal
+ *   into the new session via `resolveGoalScope`).
+ * - Without `sessionKey` (legacy / display-only callers): falls back
+ *   to the workspace-level pointer for back-compat.
+ *
+ * Display surfaces that want to show "the last workflow touched here,
+ * regardless of session binding" should call `getLastUsedWorkflow`
+ * instead so the distinction stays explicit.
+ */
+export declare function getCurrentWorkflow(workspaceRoot: string, sessionKey?: string): string | undefined;
+/**
+ * Display-only "last workflow used in this workspace" lookup. Reads
+ * the workspace-level pointer unconditionally — never consults the
+ * session-level binding. Use when you want to render a hint like
+ * "you were last on workflow X" without implying that the current
+ * session is bound to it.
+ */
+export declare function getLastUsedWorkflow(workspaceRoot: string): string | undefined;
+/**
+ * Clear the session-level workflow binding (workspace-level hint
+ * preserved). Used by `/new` and `/fork` so a freshly-forked session
+ * doesn't drag the parent's binding along.
+ */
+export declare function clearSessionWorkflow(workspaceRoot: string, sessionKey: string): void;
+/**
+ * True iff a workflow folder with the given slug exists (and carries a
+ * meta.json). Used by `/workflow switch <slug>` to surface "no such
+ * workflow" without the side-effect mkdir that `getWorkflowDir` performs.
+ */
+export declare function workflowExists(workspaceRoot: string, slug: string): boolean;
 /**
  * Path (relative to workspace root) the LLM should `write_file` to for a
  * given artifact. We return a workspace-relative path because that's the