@phuetz/code-buddy 1.0.0-rc.8 → 1.1.0

package/dist/goals/goal-manager.d.ts

@@ -0,0 +1,71 @@
+/**
+ * GoalManager — per-session goal state + continuation decisions.
+ *
+ * The interactive UI holds one GoalManager per session key (lazily resolved
+ * on every operation, so `--resume`/`--continue` reattach automatically and
+ * sessionless runs stay durable via a cwd-derived key).
+ *
+ * Network-free by design: the judge is injected into `evaluateAfterTurn` so
+ * the manager (and its tests) never touch a provider.
+ */
+import { GoalJudgeFn } from './goal-judge.js';
+import { GoalState, GoalStatus, GoalVerdict } from './goal-state.js';
+import { GoalStore } from './goal-store.js';
+export interface GoalTurnDecision {
+    status: GoalStatus | null;
+    shouldContinue: boolean;
+    continuationPrompt: string | null;
+    verdict: GoalVerdict | 'inactive';
+    reason: string;
+    /** User-visible one-liner (✓ / ⏸ / ↻). Empty when nothing to show. */
+    message: string;
+}
+export interface GoalsConfig {
+    maxTurns: number;
+    judgeModel: string;
+    judgeMaxTokens: number;
+    judgeTimeoutMs: number;
+}
+export declare class GoalManager {
+    readonly sessionKey: string;
+    private store;
+    private defaultMaxTurns;
+    private _state;
+    constructor(sessionKey: string, store: GoalStore, defaultMaxTurns?: number);
+    get state(): GoalState | null;
+    isActive(): boolean;
+    hasGoal(): boolean;
+    statusLine(): string;
+    set(goal: string, options?: {
+        maxTurns?: number;
+    }): GoalState;
+    pause(reason?: string): GoalState | null;
+    resume(options?: {
+        resetBudget?: boolean;
+    }): GoalState | null;
+    clear(): void;
+    markDone(reason: string): void;
+    addSubgoal(text: string): string;
+    removeSubgoal(index1Based: number): string;
+    clearSubgoals(): number;
+    renderSubgoals(): string;
+    /**
+     * Run the judge and update state. Both real user prompts and continuation
+     * prompts we fed ourselves increment `turnsUsed` — both consume budget.
+     */
+    evaluateAfterTurn(lastResponse: string, deps: {
+        judge: GoalJudgeFn;
+    }): Promise<GoalTurnDecision>;
+    nextContinuationPrompt(): string | null;
+}
+export declare function resolveGoalsConfig(): GoalsConfig;
+/**
+ * Resolve the key goals are persisted under. Prefers the live session id
+ * (so `--resume`/`--continue` reattach, Hermes `goal:<session_id>`
+ * semantics); falls back to a cwd-derived key so sessionless interactive
+ * runs are still durable.
+ */
+export declare function resolveGoalSessionKey(): string;
+export declare function getGoalManager(sessionKey?: string): GoalManager;
+/** Test seam: clear cached managers and optionally redirect persistence. */
+export declare function resetGoalManagers(store?: GoalStore | null): void;

package/dist/goals/goal-manager.js

@@ -0,0 +1,236 @@
+/**
+ * GoalManager — per-session goal state + continuation decisions.
+ *
+ * The interactive UI holds one GoalManager per session key (lazily resolved
+ * on every operation, so `--resume`/`--continue` reattach automatically and
+ * sessionless runs stay durable via a cwd-derived key).
+ *
+ * Network-free by design: the judge is injected into `evaluateAfterTurn` so
+ * the manager (and its tests) never touch a provider.
+ */
+import crypto from 'crypto';
+import path from 'path';
+import { getSettingsHierarchy } from '../config/settings-hierarchy.js';
+import { getSessionStore } from '../persistence/session-store.js';
+import { logger } from '../utils/logger.js';
+import { DEFAULT_JUDGE_MAX_TOKENS, DEFAULT_JUDGE_TIMEOUT_MS, DEFAULT_MAX_TURNS, applyJudgeOutcome, buildContinuationPrompt, createGoalState, formatGoalStatusLine, renderSubgoalsBlock, } from './goal-state.js';
+import { GoalStore } from './goal-store.js';
+export class GoalManager {
+    sessionKey;
+    store;
+    defaultMaxTurns;
+    _state;
+    constructor(sessionKey, store, defaultMaxTurns = DEFAULT_MAX_TURNS) {
+        this.sessionKey = sessionKey;
+        this.store = store;
+        this.defaultMaxTurns = defaultMaxTurns;
+        const loaded = this.store.load(sessionKey);
+        // A cleared tombstone reads as "no goal" (kept on disk for audit).
+        this._state = loaded && loaded.status !== 'cleared' ? loaded : null;
+    }
+    // --- introspection ------------------------------------------------
+    get state() {
+        return this._state;
+    }
+    isActive() {
+        return this._state?.status === 'active';
+    }
+    hasGoal() {
+        return this._state !== null && ['active', 'paused'].includes(this._state.status);
+    }
+    statusLine() {
+        return formatGoalStatusLine(this._state);
+    }
+    // --- mutation -----------------------------------------------------
+    set(goal, options = {}) {
+        const text = (goal || '').trim();
+        if (!text) {
+            throw new Error('goal text is empty');
+        }
+        const state = createGoalState(text, options.maxTurns || this.defaultMaxTurns);
+        this._state = state;
+        this.store.save(this.sessionKey, state);
+        return state;
+    }
+    pause(reason = 'user-paused') {
+        if (!this._state)
+            return null;
+        this._state.status = 'paused';
+        this._state.pausedReason = reason;
+        this.store.save(this.sessionKey, this._state);
+        return this._state;
+    }
+    resume(options = {}) {
+        if (!this._state)
+            return null;
+        this._state.status = 'active';
+        delete this._state.pausedReason;
+        if (options.resetBudget ?? true) {
+            this._state.turnsUsed = 0;
+        }
+        this.store.save(this.sessionKey, this._state);
+        return this._state;
+    }
+    clear() {
+        if (!this._state)
+            return;
+        this._state.status = 'cleared';
+        this.store.save(this.sessionKey, this._state);
+        this._state = null;
+    }
+    markDone(reason) {
+        if (!this._state)
+            return;
+        this._state.status = 'done';
+        this._state.lastVerdict = 'done';
+        this._state.lastReason = reason;
+        this.store.save(this.sessionKey, this._state);
+    }
+    // --- /subgoal user controls ---------------------------------------
+    addSubgoal(text) {
+        if (!this.hasGoal() || !this._state) {
+            throw new Error('no active goal');
+        }
+        const clean = (text || '').trim();
+        if (!clean) {
+            throw new Error('subgoal text is empty');
+        }
+        this._state.subgoals.push(clean);
+        this.store.save(this.sessionKey, this._state);
+        return clean;
+    }
+    removeSubgoal(index1Based) {
+        if (!this.hasGoal() || !this._state) {
+            throw new Error('no active goal');
+        }
+        const idx = Math.trunc(index1Based) - 1;
+        if (idx < 0 || idx >= this._state.subgoals.length) {
+            throw new Error(`index out of range (1..${this._state.subgoals.length})`);
+        }
+        const [removed] = this._state.subgoals.splice(idx, 1);
+        this.store.save(this.sessionKey, this._state);
+        return removed ?? '';
+    }
+    clearSubgoals() {
+        if (!this.hasGoal() || !this._state) {
+            throw new Error('no active goal');
+        }
+        const prev = this._state.subgoals.length;
+        this._state.subgoals = [];
+        this.store.save(this.sessionKey, this._state);
+        return prev;
+    }
+    renderSubgoals() {
+        if (!this._state)
+            return '(no active goal)';
+        if (!this._state.subgoals.length) {
+            return '(no subgoals — use /subgoal <text> to add criteria)';
+        }
+        return renderSubgoalsBlock(this._state.subgoals);
+    }
+    // --- the main entry point called after every turn -----------------
+    /**
+     * Run the judge and update state. Both real user prompts and continuation
+     * prompts we fed ourselves increment `turnsUsed` — both consume budget.
+     */
+    async evaluateAfterTurn(lastResponse, deps) {
+        const state = this._state;
+        if (!state || state.status !== 'active') {
+            return {
+                status: state?.status ?? null,
+                shouldContinue: false,
+                continuationPrompt: null,
+                verdict: 'inactive',
+                reason: 'no active goal',
+                message: '',
+            };
+        }
+        const outcome = await deps.judge({
+            goal: state.goal,
+            lastResponse,
+            ...(state.subgoals.length ? { subgoals: state.subgoals } : {}),
+        });
+        const decision = applyJudgeOutcome(state, outcome);
+        this.store.save(this.sessionKey, state);
+        return decision;
+    }
+    nextContinuationPrompt() {
+        if (!this._state || this._state.status !== 'active')
+            return null;
+        return buildContinuationPrompt(this._state);
+    }
+}
+// ============================================================================
+// Config
+// ============================================================================
+export function resolveGoalsConfig() {
+    let raw = {};
+    try {
+        const settings = getSettingsHierarchy().getAllSettings();
+        if (settings && typeof settings.goals === 'object' && settings.goals !== null) {
+            raw = settings.goals;
+        }
+    }
+    catch (error) {
+        logger.debug('goals: settings hierarchy unavailable, using defaults', { error: String(error) });
+    }
+    const envMaxTurns = Number(process.env.CODEBUDDY_GOAL_MAX_TURNS);
+    const maxTurns = Number.isFinite(envMaxTurns) && envMaxTurns > 0
+        ? Math.trunc(envMaxTurns)
+        : positiveInt(raw.maxTurns, DEFAULT_MAX_TURNS);
+    const judgeModel = process.env.CODEBUDDY_GOAL_JUDGE_MODEL || String(raw.judgeModel ?? '').trim();
+    return {
+        maxTurns,
+        judgeModel,
+        judgeMaxTokens: positiveInt(raw.judgeMaxTokens, DEFAULT_JUDGE_MAX_TOKENS),
+        judgeTimeoutMs: positiveInt(raw.judgeTimeoutMs, DEFAULT_JUDGE_TIMEOUT_MS),
+    };
+}
+function positiveInt(value, fallback) {
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? Math.trunc(n) : fallback;
+}
+// ============================================================================
+// Singleton registry (one manager per session key)
+// ============================================================================
+const registry = new Map();
+let storeOverride = null;
+/**
+ * Resolve the key goals are persisted under. Prefers the live session id
+ * (so `--resume`/`--continue` reattach, Hermes `goal:<session_id>`
+ * semantics); falls back to a cwd-derived key so sessionless interactive
+ * runs are still durable.
+ */
+export function resolveGoalSessionKey() {
+    try {
+        const sessionId = getSessionStore().getCurrentSessionId();
+        if (sessionId)
+            return sessionId;
+    }
+    catch (error) {
+        logger.debug('goals: session store unavailable, using cwd key', { error: String(error) });
+    }
+    const cwdHash = crypto.createHash('sha256').update(path.resolve(process.cwd())).digest('hex');
+    return `dir-${cwdHash.slice(0, 12)}`;
+}
+export function getGoalManager(sessionKey) {
+    const key = sessionKey ?? resolveGoalSessionKey();
+    let manager = registry.get(key);
+    if (!manager) {
+        const store = storeOverride ?? new GoalStore();
+        manager = new GoalManager(key, store, resolveGoalsConfig().maxTurns);
+        registry.set(key, manager);
+        if (registry.size > 20) {
+            const firstKey = registry.keys().next().value;
+            if (firstKey)
+                registry.delete(firstKey);
+        }
+    }
+    return manager;
+}
+/** Test seam: clear cached managers and optionally redirect persistence. */
+export function resetGoalManagers(store = null) {
+    registry.clear();
+    storeOverride = store;
+}
+//# sourceMappingURL=goal-manager.js.map

package/dist/goals/goal-state.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Persistent session goals — the Ralph loop for Code Buddy.
+ *
+ * A goal is a free-form user objective that stays active across turns. After
+ * each turn completes, a small judge call asks an auxiliary model "is this
+ * goal satisfied by the assistant's last response?". If not, Code Buddy feeds
+ * a continuation prompt back into the same session and keeps working until
+ * the goal is done, the turn budget is exhausted, the user pauses/clears it,
+ * or a real user message preempts the loop.
+ *
+ * Ported from Hermes Agent's goal system (hermes_cli/goals.py). Invariants:
+ * - The continuation prompt is a plain user message — no system-prompt
+ *   mutation, no toolset swap, prompt caching stays intact.
+ * - Judge failures are fail-OPEN ("continue"): a broken judge must not wedge
+ *   progress; the turn budget is the backstop.
+ * - A real user message mid-loop preempts the continuation prompt; the judge
+ *   re-runs after that turn.
+ */
+export type GoalStatus = 'active' | 'paused' | 'done' | 'cleared';
+export type GoalVerdict = 'done' | 'continue' | 'skipped';
+export interface GoalState {
+    goal: string;
+    status: GoalStatus;
+    turnsUsed: number;
+    maxTurns: number;
+    createdAt: number;
+    lastTurnAt: number;
+    lastVerdict?: GoalVerdict;
+    lastReason?: string;
+    /** Why we auto-paused (budget exhausted, judge parse failures, interrupt). */
+    pausedReason?: string;
+    /** Judge-output parse failures in a row. API/transport errors don't count. */
+    consecutiveParseFailures: number;
+    /**
+     * User-added criteria appended mid-loop via /subgoal. When non-empty both
+     * the judge prompt and the continuation prompt include them. Defaults to
+     * empty so old persisted state loads unchanged.
+     */
+    subgoals: string[];
+}
+export declare const DEFAULT_MAX_TURNS = 20;
+export declare const DEFAULT_JUDGE_TIMEOUT_MS = 30000;
+export declare const DEFAULT_JUDGE_MAX_TOKENS = 4096;
+export declare const JUDGE_GOAL_SNIPPET_CHARS = 2000;
+export declare const JUDGE_SUBGOALS_SNIPPET_CHARS = 2000;
+export declare const JUDGE_RESPONSE_SNIPPET_CHARS = 4000;
+export declare const MAX_CONSECUTIVE_PARSE_FAILURES = 3;
+export declare const CONTINUATION_PROMPT_TEMPLATE: string;
+export declare const CONTINUATION_PROMPT_WITH_SUBGOALS_TEMPLATE: string;
+export declare const JUDGE_SYSTEM_PROMPT: string;
+export declare const JUDGE_USER_PROMPT_TEMPLATE: string;
+export declare const JUDGE_USER_PROMPT_WITH_SUBGOALS_TEMPLATE: string;
+export declare function truncateText(text: string, limit: number): string;
+/** Render subgoals as a numbered `- N. text` block. Empty string when none. */
+export declare function renderSubgoalsBlock(subgoals: string[]): string;
+export declare function createGoalState(goal: string, maxTurns?: number): GoalState;
+/**
+ * Defensive deserialization of a persisted goal state. Returns null when the
+ * payload isn't a usable goal. Old payloads without `subgoals` load unchanged.
+ */
+export declare function normalizeGoalState(raw: unknown): GoalState | null;
+/** Printable one-liner for /goal status. */
+export declare function formatGoalStatusLine(state: GoalState | null): string;
+/** The canonical user-role continuation message for an active goal. */
+export declare function buildContinuationPrompt(state: GoalState): string;
+export interface GoalJudgeOutcome {
+    verdict: GoalVerdict;
+    reason: string;
+    parseFailed: boolean;
+}
+export interface GoalTurnDecisionCore {
+    status: GoalStatus;
+    shouldContinue: boolean;
+    continuationPrompt: string | null;
+    verdict: GoalVerdict;
+    reason: string;
+    /** User-visible one-liner (✓ / ⏸ / ↻). */
+    message: string;
+}
+/**
+ * Apply a judge outcome to an active goal — the exact Hermes ladder.
+ * MUTATES `state` (turn counter, verdict bookkeeping, status transitions)
+ * and returns the decision; the caller persists the state wherever it
+ * lives (GoalStore file, peer-session record, …).
+ */
+export declare function applyJudgeOutcome(state: GoalState, outcome: GoalJudgeOutcome, nowMs?: number): GoalTurnDecisionCore;

package/dist/goals/goal-state.js

@@ -0,0 +1,245 @@
+/**
+ * Persistent session goals — the Ralph loop for Code Buddy.
+ *
+ * A goal is a free-form user objective that stays active across turns. After
+ * each turn completes, a small judge call asks an auxiliary model "is this
+ * goal satisfied by the assistant's last response?". If not, Code Buddy feeds
+ * a continuation prompt back into the same session and keeps working until
+ * the goal is done, the turn budget is exhausted, the user pauses/clears it,
+ * or a real user message preempts the loop.
+ *
+ * Ported from Hermes Agent's goal system (hermes_cli/goals.py). Invariants:
+ * - The continuation prompt is a plain user message — no system-prompt
+ *   mutation, no toolset swap, prompt caching stays intact.
+ * - Judge failures are fail-OPEN ("continue"): a broken judge must not wedge
+ *   progress; the turn budget is the backstop.
+ * - A real user message mid-loop preempts the continuation prompt; the judge
+ *   re-runs after that turn.
+ */
+// ──────────────────────────────────────────────────────────────────────
+// Constants & defaults
+// ──────────────────────────────────────────────────────────────────────
+export const DEFAULT_MAX_TURNS = 20;
+export const DEFAULT_JUDGE_TIMEOUT_MS = 30_000;
+// Judge output budget. The judge returns a one-line JSON verdict, but
+// reasoning models burn tokens on hidden reasoning before emitting the
+// visible JSON. Tight caps truncate the JSON and trip the auto-pause.
+export const DEFAULT_JUDGE_MAX_TOKENS = 4096;
+// Caps how much of the inputs we send to the judge.
+export const JUDGE_GOAL_SNIPPET_CHARS = 2000;
+export const JUDGE_SUBGOALS_SNIPPET_CHARS = 2000;
+export const JUDGE_RESPONSE_SNIPPET_CHARS = 4000;
+// After this many consecutive judge *parse* failures (empty output /
+// non-JSON), the loop auto-pauses and points the user at the judge config.
+// Guards against small models that can't follow the strict JSON contract.
+export const MAX_CONSECUTIVE_PARSE_FAILURES = 3;
+export const CONTINUATION_PROMPT_TEMPLATE = '[Continuing toward your standing goal]\n' +
+    'Goal: {goal}\n\n' +
+    'Continue working toward this goal. Take the next concrete step. ' +
+    'If you believe the goal is complete, state so explicitly and stop. ' +
+    'If you are blocked and need input from the user, say so clearly and stop.';
+export const CONTINUATION_PROMPT_WITH_SUBGOALS_TEMPLATE = '[Continuing toward your standing goal]\n' +
+    'Goal: {goal}\n\n' +
+    'Additional criteria the user added mid-loop:\n' +
+    '{subgoals_block}\n\n' +
+    'Continue working toward the goal AND all additional criteria. Take ' +
+    'the next concrete step. If you believe the goal and every ' +
+    'additional criterion are complete, state so explicitly and stop. ' +
+    'If you are blocked and need input from the user, say so clearly ' +
+    'and stop.';
+export const JUDGE_SYSTEM_PROMPT = "You are a strict judge evaluating whether an autonomous agent has " +
+    "achieved a user's stated goal. You receive the goal text and the " +
+    "agent's most recent response. Your only job is to decide whether " +
+    'the goal is fully satisfied based on that response.\n\n' +
+    'A goal is DONE only when:\n' +
+    '- The response explicitly confirms the goal was completed, OR\n' +
+    '- The response clearly shows the final deliverable was produced, OR\n' +
+    '- The response explains the goal is unachievable / blocked / needs ' +
+    'user input (treat this as DONE with reason describing the block).\n\n' +
+    'Otherwise the goal is NOT done — CONTINUE.\n\n' +
+    'Reply ONLY with a single JSON object on one line:\n' +
+    '{"done": <true|false>, "reason": "<one-sentence rationale>"}';
+export const JUDGE_USER_PROMPT_TEMPLATE = 'Goal:\n{goal}\n\n' +
+    "Agent's most recent response:\n{response}\n\n" +
+    'Current time: {current_time}\n\n' +
+    'Is the goal satisfied?';
+export const JUDGE_USER_PROMPT_WITH_SUBGOALS_TEMPLATE = 'Goal:\n{goal}\n\n' +
+    'Additional criteria the user added mid-loop (all must also be ' +
+    'satisfied for the goal to be DONE):\n{subgoals_block}\n\n' +
+    "Agent's most recent response:\n{response}\n\n" +
+    'Current time: {current_time}\n\n' +
+    'Decision: For each numbered criterion above, find concrete ' +
+    "evidence in the agent's response that the criterion is " +
+    "satisfied. Do not accept generic phrases like 'all requirements " +
+    "met' or 'implying it was done' — require specific evidence (a " +
+    'file contents excerpt, an output line, a command result). If ' +
+    'ANY criterion lacks specific evidence in the response, the goal ' +
+    'is NOT done — return CONTINUE.\n\n' +
+    'Is the goal AND every additional criterion satisfied?';
+// ──────────────────────────────────────────────────────────────────────
+// Helpers
+// ──────────────────────────────────────────────────────────────────────
+export function truncateText(text, limit) {
+    if (!text)
+        return '';
+    if (text.length <= limit)
+        return text;
+    return text.slice(0, limit) + '… [truncated]';
+}
+/** Render subgoals as a numbered `- N. text` block. Empty string when none. */
+export function renderSubgoalsBlock(subgoals) {
+    if (!subgoals.length)
+        return '';
+    return subgoals.map((text, i) => `- ${i + 1}. ${text}`).join('\n');
+}
+export function createGoalState(goal, maxTurns = DEFAULT_MAX_TURNS) {
+    return {
+        goal,
+        status: 'active',
+        turnsUsed: 0,
+        maxTurns,
+        createdAt: Date.now(),
+        lastTurnAt: 0,
+        consecutiveParseFailures: 0,
+        subgoals: [],
+    };
+}
+/**
+ * Defensive deserialization of a persisted goal state. Returns null when the
+ * payload isn't a usable goal. Old payloads without `subgoals` load unchanged.
+ */
+export function normalizeGoalState(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const data = raw;
+    const goal = typeof data.goal === 'string' ? data.goal : '';
+    if (!goal.trim())
+        return null;
+    const status = ['active', 'paused', 'done', 'cleared'].includes(String(data.status))
+        ? data.status
+        : 'active';
+    const subgoals = Array.isArray(data.subgoals)
+        ? data.subgoals.map(s => String(s).trim()).filter(Boolean)
+        : [];
+    const verdict = ['done', 'continue', 'skipped'].includes(String(data.lastVerdict))
+        ? data.lastVerdict
+        : undefined;
+    const state = {
+        goal,
+        status,
+        turnsUsed: toInt(data.turnsUsed, 0),
+        maxTurns: toInt(data.maxTurns, DEFAULT_MAX_TURNS) || DEFAULT_MAX_TURNS,
+        createdAt: toNumber(data.createdAt, 0),
+        lastTurnAt: toNumber(data.lastTurnAt, 0),
+        consecutiveParseFailures: toInt(data.consecutiveParseFailures, 0),
+        subgoals,
+    };
+    if (verdict)
+        state.lastVerdict = verdict;
+    if (typeof data.lastReason === 'string')
+        state.lastReason = data.lastReason;
+    if (typeof data.pausedReason === 'string')
+        state.pausedReason = data.pausedReason;
+    return state;
+}
+function toInt(value, fallback) {
+    const n = Number(value);
+    return Number.isFinite(n) ? Math.trunc(n) : fallback;
+}
+function toNumber(value, fallback) {
+    const n = Number(value);
+    return Number.isFinite(n) ? n : fallback;
+}
+/** Printable one-liner for /goal status. */
+export function formatGoalStatusLine(state) {
+    if (!state || state.status === 'cleared') {
+        return 'No active goal. Set one with /goal <text>.';
+    }
+    const turns = `${state.turnsUsed}/${state.maxTurns} turns`;
+    const sub = state.subgoals.length
+        ? `, ${state.subgoals.length} subgoal${state.subgoals.length !== 1 ? 's' : ''}`
+        : '';
+    if (state.status === 'active') {
+        return `⊙ Goal (active, ${turns}${sub}): ${state.goal}`;
+    }
+    if (state.status === 'paused') {
+        const extra = state.pausedReason ? ` — ${state.pausedReason}` : '';
+        return `⏸ Goal (paused, ${turns}${sub}${extra}): ${state.goal}`;
+    }
+    if (state.status === 'done') {
+        return `✓ Goal done (${turns}${sub}): ${state.goal}`;
+    }
+    return `Goal (${state.status}, ${turns}${sub}): ${state.goal}`;
+}
+/** The canonical user-role continuation message for an active goal. */
+export function buildContinuationPrompt(state) {
+    if (state.subgoals.length) {
+        return CONTINUATION_PROMPT_WITH_SUBGOALS_TEMPLATE.replace('{goal}', state.goal).replace('{subgoals_block}', renderSubgoalsBlock(state.subgoals));
+    }
+    return CONTINUATION_PROMPT_TEMPLATE.replace('{goal}', state.goal);
+}
+/**
+ * Apply a judge outcome to an active goal — the exact Hermes ladder.
+ * MUTATES `state` (turn counter, verdict bookkeeping, status transitions)
+ * and returns the decision; the caller persists the state wherever it
+ * lives (GoalStore file, peer-session record, …).
+ */
+export function applyJudgeOutcome(state, outcome, nowMs = Date.now()) {
+    state.turnsUsed += 1;
+    state.lastTurnAt = nowMs;
+    state.lastVerdict = outcome.verdict;
+    state.lastReason = outcome.reason;
+    // Reset the parse-failure streak on any usable reply, including
+    // API/transport errors (parseFailed=false), so a flaky network doesn't
+    // trip the auto-pause meant for bad judge models.
+    state.consecutiveParseFailures = outcome.parseFailed ? state.consecutiveParseFailures + 1 : 0;
+    if (outcome.verdict === 'done') {
+        state.status = 'done';
+        return {
+            status: 'done',
+            shouldContinue: false,
+            continuationPrompt: null,
+            verdict: 'done',
+            reason: outcome.reason,
+            message: `✓ Goal achieved: ${outcome.reason}`,
+        };
+    }
+    if (state.consecutiveParseFailures >= MAX_CONSECUTIVE_PARSE_FAILURES) {
+        state.status = 'paused';
+        state.pausedReason = `judge model returned unparseable output ${state.consecutiveParseFailures} turns in a row`;
+        return {
+            status: 'paused',
+            shouldContinue: false,
+            continuationPrompt: null,
+            verdict: 'continue',
+            reason: outcome.reason,
+            message: `⏸ Goal paused — the judge model (${state.consecutiveParseFailures} turns) ` +
+                'isn\'t returning the required JSON verdict. Route the judge to a stricter ' +
+                'model in .codebuddy/settings.json:\n' +
+                '  { "goals": { "judgeModel": "<a model that follows JSON instructions>" } }\n' +
+                'Then /goal resume to continue.',
+        };
+    }
+    if (state.turnsUsed >= state.maxTurns) {
+        state.status = 'paused';
+        state.pausedReason = `turn budget exhausted (${state.turnsUsed}/${state.maxTurns})`;
+        return {
+            status: 'paused',
+            shouldContinue: false,
+            continuationPrompt: null,
+            verdict: 'continue',
+            reason: outcome.reason,
+            message: `⏸ Goal paused — ${state.turnsUsed}/${state.maxTurns} turns used. ` +
+                'Use /goal resume to keep going, or /goal clear to stop.',
+        };
+    }
+    return {
+        status: 'active',
+        shouldContinue: true,
+        continuationPrompt: buildContinuationPrompt(state),
+        verdict: 'continue',
+        reason: outcome.reason,
+        message: `↻ Continuing toward goal (${state.turnsUsed}/${state.maxTurns}): ${outcome.reason}`,
+    };
+}
+//# sourceMappingURL=goal-state.js.map

package/dist/goals/goal-store.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Durable per-session goal persistence.
+ *
+ * One JSON file per session key under `~/.codebuddy/goals/` (honors
+ * CODEBUDDY_HOME). Files are tiny (<1 KB) so I/O is synchronous — same
+ * trade-off as TodoTracker. Writes are atomic (tmp + rename). Loads are
+ * fail-soft: a corrupt or unreadable file reads as "no goal".
+ *
+ * Cleared goals keep a tombstone (`status: 'cleared'`) for audit, mirroring
+ * Hermes' SessionDB behavior.
+ */
+import { GoalState } from './goal-state.js';
+export interface GoalStoreOptions {
+    /** Override the storage directory (test isolation). */
+    storeDir?: string;
+}
+export declare class GoalStore {
+    private storeDir;
+    constructor(options?: GoalStoreOptions);
+    getStoreDir(): string;
+    load(key: string): GoalState | null;
+    save(key: string, state: GoalState): void;
+    delete(key: string): void;
+    private fileFor;
+}