@zergai/ztc 0.4.0-beta.1 → 0.5.0-beta.1

package/dist/agent/commands/goal.js

@@ -52,6 +52,8 @@
  * idle transition; headless runs an explicit await loop), but the accounting +
  * stop decision live here in one pure, unit-tested place: decideContinuation().
  */
+import { createHash } from 'node:crypto';
+import { formatGoalPlateau, hasFailedCompileObservation, makeGoalPlateau, observeGoalPlateau, parseGoalPlateauCriteria, parseGoalPlateauState, parseGoalExitReason, parseSustainedGoalAuthority } from './goal_exit.js';
 /**
  * Whether the finished turn did anything observable: it called a tool, or it said
  * something (assistant text or reasoning summary). Mirrors Codex's `has_activity`,
@@ -331,6 +333,10 @@ export const AGENT_GOAL_CONTROL_REFUSAL = 'Only the user can resume, replace, or
  */
 export function goalFinalNote(goal) {
     const tallies = `${goal.turns} turn(s), ${goal.tokensUsed.toLocaleString()} tokens`;
+    if (goal.status === 'complete' && goal.exitReason?.kind === 'measured_plateau') {
+        return `Goal stopped at its configured measured plateau: "${goal.objective}" (${tallies}). `
+            + `${goal.exitReason.reason} Evidence: ${goal.exitReason.evidenceIds.join(', ')}.`;
+    }
     if (goal.status === 'complete') {
         return `✅ Goal complete: "${goal.objective}" (${tallies}).`;
     }
@@ -408,12 +414,35 @@ export function parseGoalArgs(args) {
     const objectiveTokens = [];
     let tokenBudget;
     let maxTurns;
+    let attempts;
+    let benchmarkScope;
+    let minImprovementPercent = 0;
+    let hasThreshold = false;
     for (let i = 0; i < args.length; i++) {
         const tok = args[i];
         const eq = tok.indexOf('=');
         const flag = eq >= 0 ? tok.slice(0, eq) : tok;
         const inlineVal = eq >= 0 ? tok.slice(eq + 1) : undefined;
         const lower = flag.toLowerCase();
+        if (lower === '--plateau') {
+            attempts = parsePositiveInt(inlineVal ?? args[++i]) ?? undefined;
+            if (attempts === undefined || attempts > 32)
+                return { error: '--plateau requires 1–32 comparable attempts.' };
+            continue;
+        }
+        if (lower === '--benchmark-scope') {
+            benchmarkScope = inlineVal ?? args[++i];
+            continue;
+        }
+        if (lower === '--min-improvement-percent') {
+            const raw = inlineVal ?? args[++i];
+            minImprovementPercent = raw?.trim() ? Number(raw) : NaN;
+            hasThreshold = true;
+            if (!Number.isFinite(minImprovementPercent) || minImprovementPercent < 0 || minImprovementPercent > 100) {
+                return { error: '--min-improvement-percent requires a finite percentage from 0 through 100.' };
+            }
+            continue;
+        }
         if (lower === '--budget' || lower === '--tokens') {
             const raw = inlineVal ?? args[++i];
             const parsed = parsePositiveInt(raw);
@@ -450,7 +479,11 @@ export function parseGoalArgs(args) {
     if (/goal[ _]?blocked/i.test(objective)) {
         return { error: `Objective must not contain "${GOAL_BLOCKED_SENTINEL}" — that token is reserved to signal a stalled goal.` };
     }
-    return { objective, ...(tokenBudget != null ? { tokenBudget } : {}), ...(maxTurns != null ? { maxTurns } : {}) };
+    const plateau = attempts === undefined ? undefined : parseGoalPlateauCriteria({ scope: benchmarkScope, attempts, minImprovementPercent });
+    if ((attempts !== undefined && !plateau) || (attempts === undefined && (benchmarkScope !== undefined || hasThreshold))) {
+        return { error: 'A plateau requires --plateau <1–32> and --benchmark-scope benchmark:cpu_integer_sum; other adapters remain unsupported.' };
+    }
+    return { objective, ...(tokenBudget != null ? { tokenBudget } : {}), ...(maxTurns != null ? { maxTurns } : {}), ...(plateau ? { plateau } : {}) };
 }
 function parsePositiveInt(raw) {
     if (raw == null)
@@ -467,6 +500,7 @@ function parsePositiveInt(raw) {
 export function buildKickPrompt(goal) {
     return [
         `GOAL: ${goal.objective}`,
+        ...(goal.plateau ? [formatGoalPlateau(goal.plateau), 'Only retained host-admitted comparisons count. Failed builds, rejected ideas and interrupted runs are not measured attempts. The host evaluates this criterion; do not claim a plateau or emit completion from reported scores. Later user steering, scope, budget and interruption remain authoritative.'] : []),
         '',
         'You are now in autonomous goal mode. Work toward this objective across as many steps',
         'as needed without waiting for confirmation between steps. Use your tools to make',
@@ -496,6 +530,7 @@ export function buildContinuationPrompt(goal) {
     return [
         `Continue working toward your goal (turn ${goal.turns + 1}):`,
         goal.objective,
+        ...(goal.plateau ? [formatGoalPlateau(goal.plateau), 'Continue the next authorized experiment without routine reapproval. Respect later user steering; the host evaluates plateau evidence, not completion prose.'] : []),
         '',
         'Briefly assess what is done and what remains, then take the next concrete step with your tools.',
         '',
@@ -529,7 +564,7 @@ export function buildContinuationPrompt(goal) {
  */
 export function goalPinTask(goal) {
     const objective = goal?.objective.trim() ?? '';
-    return objective.length > 0 ? `GOAL: ${objective}` : null;
+    return objective.length > 0 ? `GOAL: ${objective}${goal?.plateau ? '\n' + formatGoalPlateau(goal.plateau) : ''}` : null;
 }
 /** Short status line posted to the user when a continuation is fired. */
 export function progressNote(goal) {
@@ -560,6 +595,8 @@ export function formatGoalStatus(goal, now) {
         `  Turns:      ${turns}`,
         `  Tokens:     ${budget}`,
         `  Age:        ${ageSec}s`,
+        ...(goal.plateau ? [`  ${formatGoalPlateau(goal.plateau)}`] : []),
+        ...(goal.exitReason ? [`  Exit decision: ${goal.exitReason.kind}: ${goal.exitReason.reason}`] : []),
         ...(goal.blockedReason ? [`  Reason:     ${goal.blockedReason}`] : []),
         hint,
     ].join('\n');
@@ -583,7 +620,11 @@ export function decideContinuation(goal, facts, now) {
     // Codex's execution-unavailable rule: a turn that ran a command which failed
     // with nothing succeeding is evidence the environment, not the agent, is the
     // problem. Three in a row block the goal.
-    const executionFailure = isExecutionFailureTurn(facts);
+    const executionFailure = isExecutionFailureTurn(facts)
+        && !(goal.plateau && hasFailedCompileObservation(facts.evidence, goal.updatedAt));
+    const reportedBlocker = (goal.plateau || goal.sustained) && facts.blockedReason
+        ? facts.blockedReason.replace(/\s+/gu, ' ').trim().slice(0, MAX_BLOCK_REASON_LEN) : '';
+    const condition = reportedBlocker.toLowerCase();
     const next = {
         ...goal,
         tokensUsed: goal.tokensUsed + turnTokens,
@@ -597,9 +638,15 @@ export function decideContinuation(goal, facts, now) {
             // clear), so an unrelated turn must not launder the streak.
             : (facts.hadSuccessfulTool ? 0 : goal.executionFailureStreak),
         updatedAt: now,
+        ...(goal.plateau ? { plateau: observeGoalPlateau(goal.plateau, facts.evidence, goal.createdAt) } : {}),
+        blockedAudit: condition ? { condition, streak: goal.blockedAudit?.condition === condition
+                ? Math.min(3, goal.blockedAudit.streak + 1) : 1 } : undefined,
     };
+    if (!condition)
+        delete next.blockedAudit;
     if (next.tokenBudget != null && next.tokensUsed >= next.tokenBudget) {
         next.status = 'budget_limited';
+        next.exitReason = { kind: 'budget_limited', reason: 'Explicit token budget exhausted.', evidenceIds: [] };
         return {
             next,
             decision: {
@@ -615,6 +662,7 @@ export function decideContinuation(goal, facts, now) {
     // (the default) has no maxTurns to compare against.
     if (next.maxTurns != null && next.turns >= next.maxTurns) {
         next.status = 'paused';
+        next.exitReason = { kind: 'turn_cap', reason: 'Explicit turn cap reached.', evidenceIds: [] };
         return {
             next,
             decision: {
@@ -626,8 +674,29 @@ export function decideContinuation(goal, facts, now) {
             },
         };
     }
+    // Adopted requests use the same completion channel as explicit goals. Caps
+    // above still take precedence, and explicit measurement criteria stay authoritative.
+    if (next.sustained && !next.plateau && detectGoalCompletion(facts.turnSummary)) {
+        next.status = 'complete';
+        next.exitReason = { kind: 'objective_complete', reason: 'Objective completion declared.', evidenceIds: [] };
+        return { next, decision: { kind: 'stop', status: 'complete', reason: 'objective complete', note: goalFinalNote(next) } };
+    }
+    if (next.plateau?.enabled && next.plateau.consecutiveNoImprovement >= next.plateau.criteria.attempts) {
+        next.status = 'complete';
+        next.exitReason = { kind: 'measured_plateau', reason: formatGoalPlateau(next.plateau), evidenceIds: [...next.plateau.comparisonIds] };
+        return { next, decision: { kind: 'stop', status: 'complete', reason: 'measured plateau',
+                note: `${next.exitReason.reason} Evidence: ${next.exitReason.evidenceIds.join(', ')}. Objective: ${next.objective}` } };
+    }
+    if (next.blockedAudit?.streak === 3) {
+        next.status = 'blocked';
+        next.blockedSource = 'agent';
+        next.blockedReason = reportedBlocker;
+        next.exitReason = { kind: 'blocked', reason: `Agent reported the same missing prerequisite for three consecutive turns: ${reportedBlocker}`, evidenceIds: [] };
+        return { next, decision: { kind: 'stop', status: 'blocked', reason: reportedBlocker, note: goalFinalNote(next) } };
+    }
     if (next.noProgressStreak >= NO_PROGRESS_LIMIT) {
         next.status = 'paused';
+        next.exitReason = { kind: 'no_progress', reason: 'Three automatic turns produced no observable activity.', evidenceIds: [] };
         return {
             next,
             decision: {
@@ -641,6 +710,7 @@ export function decideContinuation(goal, facts, now) {
     }
     if (next.stalledStreak >= STALL_LIMIT) {
         next.status = 'paused';
+        next.exitReason = { kind: 'stalled', reason: 'Repeated narration without new work.', evidenceIds: [] };
         return {
             next,
             decision: {
@@ -657,6 +727,7 @@ export function decideContinuation(goal, facts, now) {
         next.status = 'blocked';
         next.blockedSource = 'execution';
         next.blockedReason = `the command tool failed for ${next.executionFailureStreak} consecutive turns`;
+        next.exitReason = { kind: 'blocked', reason: next.blockedReason, evidenceIds: [] };
         return {
             next,
             decision: {
@@ -693,16 +764,72 @@ export class GoalManager {
      * gets a fresh final turn.
      */
     finalTurnAccounted = false;
+    sustainedFirstTurnPending = false;
     constructor(clock = realClock) {
         this.clock = clock;
     }
     /** A defensive copy so callers cannot mutate internal state. */
     get() {
-        return this.goal ? { ...this.goal } : null;
+        return this.goal ? structuredClone(this.goal) : null;
+    }
+    /** Admit an explicit authored sustained-work request into the existing loop, without deriving extra scope or budget. */
+    adoptUserIntent(message, opts = {}) {
+        if (message.role !== 'user' || message.metadata?.synthetic || message.metadata?.compactionSummary || message.metadata?.toolResult)
+            return null;
+        const text = message.content;
+        // Steering stays ordinary user context. Replacing an existing goal requires /goal.
+        if (this.goal && this.goal.status !== 'complete')
+            return null;
+        if (!/\b(?:keep|continue)\s+(?:working|iterating|optimizing|doing|going)\b/iu.test(text)
+            || !/\buntil\b[\s\S]*\b(?:interrupt|stop|done|complete|plateau)\b/iu.test(text) || text.length > MAX_OBJECTIVE_LEN)
+            return null;
+        const parsed = parseGoalArgs(text.split(/\s+/u));
+        if ('error' in parsed)
+            return null;
+        const statedBudgets = [...text.matchAll(/\b(?:budget(?: of)?|limit(?: (?:total )?(?:token )?usage)? to|within|up to)\s+([\d,_]+)\s+tokens\b/giu)]
+            .map(match => parsePositiveInt(match[1]));
+        const budgets = [...new Set([...(parsed.tokenBudget === undefined ? [] : [parsed.tokenBudget]), ...statedBudgets])];
+        if (budgets.some(value => value === null || !Number.isSafeInteger(value)) || budgets.length > 1)
+            return null;
+        if (budgets[0] !== undefined && budgets[0] !== null)
+            parsed.tokenBudget = budgets[0];
+        this.set(parsed.objective, { ...parsed, maxTurns: resolveGoalTurnCap(parsed.maxTurns, opts.configuredMaxTurns) });
+        this.goal.sustained = { sourceMessageId: message.id,
+            sourceTextSha256: createHash('sha256').update(text).digest('hex'), hostExitOnly: false };
+        this.kick = buildKickPrompt(this.goal);
+        this.sustainedFirstTurnPending = true;
+        return this.get();
+    }
+    /** The authored opening turn spends the same budget as later automatic turns. */
+    accountSustainedFirstTurn(facts) {
+        if (!this.sustainedFirstTurnPending)
+            return null;
+        this.sustainedFirstTurnPending = false;
+        const decision = this.onTurnComplete(facts);
+        this.kick = decision.kind === 'continue' ? decision.prompt : null;
+        if (decision.kind === 'stop')
+            this.finalTurnAccounted = true;
+        return decision;
+    }
+    /** Host wait events retain an owned job reference; tool text never establishes waiting. */
+    observeHostWait(event) {
+        if (!this.goal || this.goal.status !== 'active')
+            return this.get();
+        if (event.type === 'command_wait') {
+            this.goal.exitReason = { kind: 'waiting', reason: `Waiting for owned managed command ${event.waiting.jobId}.`,
+                evidenceIds: [event.waiting.toolCallId] };
+        }
+        else if (this.goal.exitReason?.kind === 'waiting' && this.goal.exitReason.evidenceIds.includes(event.toolCallId)) {
+            delete this.goal.exitReason;
+        }
+        return this.get();
     }
     /** Start a brand-new goal (replaces any existing one) and arm the first turn. */
     set(objective, opts = {}) {
         const now = this.clock.now();
+        const plateau = opts.plateau === undefined ? undefined : parseGoalPlateauCriteria(opts.plateau);
+        if (opts.plateau !== undefined && !plateau)
+            throw new TypeError('Invalid explicit goal plateau criteria.');
         // No implicit cap: absent means uncapped. Callers that want the configured
         // default compose it with any explicit flag via resolveGoalTurnCap().
         const maxTurns = opts.maxTurns != null ? clampMaxTurns(opts.maxTurns) : undefined;
@@ -726,19 +853,23 @@ export class GoalManager {
             executionFailureStreak: 0,
             createdAt: now,
             updatedAt: now,
+            ...(plateau ? { plateau: makeGoalPlateau(plateau) } : {}),
         };
         this.kick = buildKickPrompt(this.goal);
         this.finalTurnAccounted = false;
-        return { ...this.goal };
+        this.sustainedFirstTurnPending = false;
+        return structuredClone(this.goal);
     }
-    pause() {
+    pause(kind = 'user_pause') {
         if (!this.goal)
             return null;
         if (this.goal.status === 'active')
             this.goal.status = 'paused';
         this.goal.updatedAt = this.clock.now();
+        this.goal.exitReason = { kind, reason: kind === 'user_cancelled' ? 'User interrupted the active work.' : 'User paused the goal.', evidenceIds: [] };
         this.kick = null;
-        return { ...this.goal };
+        this.sustainedFirstTurnPending = false;
+        return structuredClone(this.goal);
     }
     /**
      * Re-activate a paused / budget-limited goal and arm a continuation turn.
@@ -756,7 +887,7 @@ export class GoalManager {
         if (!this.goal)
             return null;
         if (this.goal.status === 'complete')
-            return { ...this.goal };
+            return structuredClone(this.goal);
         const g = this.goal;
         g.noProgressStreak = 0;
         g.stalledStreak = 0;
@@ -764,6 +895,8 @@ export class GoalManager {
         g.executionFailureStreak = 0;
         delete g.blockedReason;
         delete g.blockedSource;
+        delete g.blockedAudit;
+        delete g.exitReason;
         if (g.maxTurns != null && g.turns >= g.maxTurns)
             g.maxTurns = clampMaxTurns(g.turns + TURN_CAP_STEP);
         if (g.tokenBudget != null && g.tokensUsed >= g.tokenBudget)
@@ -773,13 +906,13 @@ export class GoalManager {
         this.kick = buildContinuationPrompt(g);
         // A resumed goal gets a fresh final turn to account.
         this.finalTurnAccounted = false;
-        return { ...g };
+        return structuredClone(g);
     }
     clear() {
         const prev = this.goal;
         this.goal = null;
         this.kick = null;
-        return prev ? { ...prev } : null;
+        return prev ? structuredClone(prev) : null;
     }
     /**
      * Account one goal-driven turn without touching the status. Used when the goal
@@ -800,7 +933,7 @@ export class GoalManager {
         this.accountTurn(facts);
         this.finalTurnAccounted = true;
         this.goal.updatedAt = this.clock.now();
-        return { ...this.goal };
+        return structuredClone(this.goal);
     }
     /**
      * Mark the goal complete. When `facts` is supplied (sentinel-driven completion
@@ -817,9 +950,10 @@ export class GoalManager {
             this.finalTurnAccounted = true;
         }
         this.goal.status = 'complete';
+        this.goal.exitReason = { kind: 'objective_complete', reason: 'Objective completion declared.', evidenceIds: [] };
         this.goal.updatedAt = this.clock.now();
         this.kick = null;
-        return { ...this.goal };
+        return structuredClone(this.goal);
     }
     /**
      * Mark the goal blocked: the agent declared it cannot reach the objective. Same
@@ -847,9 +981,10 @@ export class GoalManager {
         }
         this.goal.blockedSource = 'agent';
         this.goal.status = 'blocked';
+        this.goal.exitReason = { kind: 'blocked', reason: cleaned || 'Agent reported a missing prerequisite.', evidenceIds: [] };
         this.goal.updatedAt = this.clock.now();
         this.kick = null;
-        return { ...this.goal };
+        return structuredClone(this.goal);
     }
     /** Fold one turn's token delta + turn count into the running totals. */
     accountTurn(facts) {
@@ -866,8 +1001,16 @@ export class GoalManager {
     onTurnComplete(facts) {
         if (!this.goal)
             return { kind: 'idle' };
+        if (this.sustainedFirstTurnPending && !facts.automaticGoalTurn) {
+            this.sustainedFirstTurnPending = false;
+            this.kick = null;
+        }
         const { next, decision } = decideContinuation(this.goal, facts, this.clock.now());
         this.goal = next;
+        if (decision.kind === 'stop' && next.exitReason?.kind === 'objective_complete') {
+            this.finalTurnAccounted = true;
+            this.kick = null;
+        }
         return decision;
     }
     /** Read-and-clear the pending kick prompt (first/continuation turn trigger). */
@@ -881,7 +1024,7 @@ export class GoalManager {
     }
     /** Snapshot for session persistence. */
     serialize() {
-        return this.goal ? { ...this.goal } : null;
+        return this.goal ? structuredClone(this.goal) : null;
     }
     /**
      * Restore from session persistence on resume. Arms no kick (no auto-start).
@@ -892,11 +1035,15 @@ export class GoalManager {
      */
     hydrate(record) {
         this.kick = null;
+        this.sustainedFirstTurnPending = false;
         if (!record || !isValidGoalRecord(record)) {
             this.goal = null;
             return;
         }
         const now = this.clock.now();
+        const plateau = record.plateau === undefined ? undefined : parseGoalPlateauState(record.plateau);
+        const exitReason = parseGoalExitReason(record.exitReason);
+        const sustained = parseSustainedGoalAuthority(record.sustained);
         const finiteOr = (v, fallback) => (typeof v === 'number' && Number.isFinite(v)) ? v : fallback;
         const nonNegInt = (v) => Math.max(0, Math.floor(finiteOr(v, 0)));
         let tokenBudget;
@@ -930,6 +1077,14 @@ export class GoalManager {
                 : {}),
             createdAt: finiteOr(record.createdAt, now),
             updatedAt: finiteOr(record.updatedAt, now),
+            ...(plateau ? { plateau } : {}),
+            ...(exitReason ? { exitReason } : {}),
+            ...(sustained ? { sustained } : {}),
+            ...(record.blockedAudit && typeof record.blockedAudit.condition === 'string' && record.blockedAudit.condition.trim()
+                && record.blockedAudit.condition.length <= MAX_BLOCK_REASON_LEN && Number.isInteger(record.blockedAudit.streak)
+                && record.blockedAudit.streak >= 1 && record.blockedAudit.streak <= 3 ? { blockedAudit: structuredClone(record.blockedAudit) } : {}),
+            ...((record.plateau !== undefined && !plateau) || (record.sustained !== undefined && !sustained) ? { status: 'paused',
+                exitReason: { kind: 'criteria_unavailable', reason: 'Saved sustained authority or plateau criteria are invalid; explicit user replacement is required.', evidenceIds: [] } } : {}),
         };
     }
 }
@@ -1038,6 +1193,10 @@ export const goalCommand = {
                 }
                 case 'complete':
                 case 'done': {
+                    if (ctx.commandOrigin === 'agent' && existing?.plateau) {
+                        ctx.addMessage({ role: 'system', content: 'This sustained goal requires its configured host exit criterion, explicit user stop or budget. Completion prose cannot substitute for admitted measurements.' });
+                        return;
+                    }
                     const g = goalManager.complete();
                     ctx.addMessage({
                         role: 'system',
@@ -1064,6 +1223,7 @@ export const goalCommand = {
             return;
         }
         const g = goalManager.set(parsed.objective, {
+            ...(parsed.plateau ? { plateau: parsed.plateau } : {}),
             ...(parsed.tokenBudget != null ? { tokenBudget: parsed.tokenBudget } : {}),
             // Explicit --max-turns outranks the configured default; nothing here writes
             // config, so a per-goal cap never changes the global setting or the next

package/dist/agent/commands/goal_exit.d.ts

@@ -0,0 +1,36 @@
+import { type EvidenceSnapshot } from '../runtime/evidence.js';
+export interface GoalPlateauCriteria {
+    scope: 'benchmark:cpu_integer_sum';
+    attempts: number;
+    minImprovementPercent: number;
+}
+export interface GoalPlateauState {
+    criteria: GoalPlateauCriteria;
+    enabled: boolean;
+    bestObservationId: string | null;
+    bestReceiptId: string | null;
+    lastMeasurementAt: number;
+    measuredAttempts: number;
+    consecutiveNoImprovement: number;
+    comparisonIds: string[];
+}
+export interface GoalExitReason {
+    kind: 'objective_complete' | 'measured_plateau' | 'user_pause' | 'user_cancelled' | 'budget_limited' | 'turn_cap' | 'no_progress' | 'stalled' | 'blocked' | 'waiting' | 'criteria_unavailable';
+    reason: string;
+    evidenceIds: string[];
+}
+export declare function parseGoalPlateauCriteria(value: unknown): GoalPlateauCriteria | null;
+export declare function makeGoalPlateau(criteria: GoalPlateauCriteria): GoalPlateauState;
+export declare function parseGoalPlateauState(value: unknown): GoalPlateauState | null;
+export declare function parseGoalExitReason(value: unknown): GoalExitReason | null;
+export interface SustainedGoalAuthority {
+    sourceMessageId: string;
+    sourceTextSha256: string;
+    hostExitOnly: boolean;
+}
+export declare function parseSustainedGoalAuthority(value: unknown): SustainedGoalAuthority | null;
+/** Consume canonical admitted comparisons; references and a monotonic original-run watermark are not another evidence ledger. */
+export declare function observeGoalPlateau(state: GoalPlateauState, evidence: EvidenceSnapshot | undefined, createdAt: number): GoalPlateauState;
+/** A real failed compile is an unmeasured attempt, not proof that the environment is inaccessible. */
+export declare function hasFailedCompileObservation(evidence: EvidenceSnapshot | undefined, since: number): boolean;
+export declare function formatGoalPlateau(state: GoalPlateauState): string;

package/dist/agent/commands/goal_exit.js

@@ -0,0 +1,120 @@
+import { parseEvidenceSnapshot } from '../runtime/evidence.js';
+const integer = (value, minimum, maximum) => typeof value === 'number' && Number.isSafeInteger(value) && value >= minimum && value <= maximum;
+const identity = (value) => typeof value === 'string' && value.trim().length > 0
+    && new TextEncoder().encode(value).length <= 256 && !/[\u0000-\u001f\u007f]/u.test(value);
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+}
+function keys(value, allowed) {
+    return Object.keys(value).length === allowed.length && allowed.every(key => Object.hasOwn(value, key));
+}
+export function parseGoalPlateauCriteria(value) {
+    if (!record(value) || !keys(value, ['scope', 'attempts', 'minImprovementPercent']) || value.scope !== 'benchmark:cpu_integer_sum'
+        || !integer(value.attempts, 1, 32) || typeof value.minImprovementPercent !== 'number'
+        || !Number.isFinite(value.minImprovementPercent) || value.minImprovementPercent < 0 || value.minImprovementPercent > 100)
+        return null;
+    return { scope: value.scope, attempts: value.attempts, minImprovementPercent: value.minImprovementPercent };
+}
+export function makeGoalPlateau(criteria) {
+    return { criteria: structuredClone(criteria), enabled: true, bestObservationId: null, bestReceiptId: null,
+        lastMeasurementAt: 0, measuredAttempts: 0, consecutiveNoImprovement: 0, comparisonIds: [] };
+}
+export function parseGoalPlateauState(value) {
+    const required = ['criteria', 'bestObservationId', 'bestReceiptId', 'lastMeasurementAt',
+        'measuredAttempts', 'consecutiveNoImprovement', 'comparisonIds'];
+    if (!record(value) || !keys(value, Object.hasOwn(value, 'enabled') ? [...required, 'enabled'] : required)
+        || (Object.hasOwn(value, 'enabled') && typeof value.enabled !== 'boolean'))
+        return null;
+    const criteria = parseGoalPlateauCriteria(value.criteria);
+    if (!criteria || !(value.bestObservationId === null || identity(value.bestObservationId))
+        || !(value.bestReceiptId === null || identity(value.bestReceiptId))
+        || (value.bestObservationId === null) !== (value.bestReceiptId === null)
+        || !integer(value.lastMeasurementAt, 0, Number.MAX_SAFE_INTEGER)
+        || !integer(value.measuredAttempts, 0, Number.MAX_SAFE_INTEGER)
+        || !integer(value.consecutiveNoImprovement, 0, criteria.attempts)
+        || value.consecutiveNoImprovement > value.measuredAttempts
+        || !Array.isArray(value.comparisonIds) || value.comparisonIds.length > 32 || !value.comparisonIds.every(identity)
+        || value.comparisonIds.length !== value.consecutiveNoImprovement
+        || (value.enabled !== false && value.measuredAttempts > 0 && value.bestObservationId === null)
+        || new Set(value.comparisonIds).size !== value.comparisonIds.length)
+        return null;
+    return { ...structuredClone(value), enabled: value.enabled ?? true };
+}
+export function parseGoalExitReason(value) {
+    if (!record(value) || !keys(value, ['kind', 'reason', 'evidenceIds']) || typeof value.kind !== 'string'
+        || !['objective_complete', 'measured_plateau', 'user_pause', 'user_cancelled', 'budget_limited',
+            'turn_cap', 'no_progress', 'stalled', 'blocked', 'waiting', 'criteria_unavailable'].includes(value.kind)
+        || typeof value.reason !== 'string' || !value.reason.trim() || new TextEncoder().encode(value.reason).length > 2048
+        || !Array.isArray(value.evidenceIds) || value.evidenceIds.length > 32 || !value.evidenceIds.every(identity)
+        || new Set(value.evidenceIds).size !== value.evidenceIds.length)
+        return null;
+    return structuredClone(value);
+}
+export function parseSustainedGoalAuthority(value) {
+    if (!record(value) || !keys(value, ['sourceMessageId', 'sourceTextSha256', 'hostExitOnly'])
+        || !identity(value.sourceMessageId) || typeof value.sourceTextSha256 !== 'string'
+        || !/^[a-f0-9]{64}$/u.test(value.sourceTextSha256) || typeof value.hostExitOnly !== 'boolean')
+        return null;
+    return structuredClone(value);
+}
+/** Consume canonical admitted comparisons; references and a monotonic original-run watermark are not another evidence ledger. */
+export function observeGoalPlateau(state, evidence, createdAt) {
+    const next = structuredClone(state);
+    const snapshot = parseEvidenceSnapshot(evidence);
+    if (!next.enabled || !snapshot)
+        return next;
+    for (const row of snapshot.records) {
+        if (row.kind !== 'observation' || row.availability === 'unavailable')
+            continue;
+        const comparison = row.source.benchmarkComparison;
+        if (!comparison || comparison.outcome !== 'comparable' || comparison.scope !== next.criteria.scope
+            || !comparison.baseline || !comparison.candidate)
+            continue;
+        const candidate = snapshot.records.find(item => item.id === comparison.candidate.observation_id);
+        const receipt = candidate?.source.verification;
+        if (candidate?.kind !== 'observation' || candidate.availability === 'unavailable'
+            || receipt?.receipt_id !== comparison.candidate.receipt_id || !receipt.end_source)
+            continue;
+        const measuredAt = Date.parse(receipt.end_source.captured_at);
+        // A newer comparison of an old run is not a new experiment, including after resume or bounded history eviction.
+        if (!Number.isSafeInteger(measuredAt) || measuredAt < createdAt || measuredAt <= next.lastMeasurementAt)
+            continue;
+        if (next.bestObservationId !== null && (comparison.baseline.observation_id !== next.bestObservationId
+            || comparison.baseline.receipt_id !== next.bestReceiptId))
+            continue;
+        next.bestObservationId ??= comparison.baseline.observation_id;
+        next.bestReceiptId ??= comparison.baseline.receipt_id;
+        next.lastMeasurementAt = measuredAt;
+        next.measuredAttempts++;
+        const improvement = -comparison.relative_change_percent;
+        if (improvement > 0 && improvement >= next.criteria.minImprovementPercent) {
+            next.bestObservationId = comparison.candidate.observation_id;
+            next.bestReceiptId = comparison.candidate.receipt_id;
+            next.consecutiveNoImprovement = 0;
+            next.comparisonIds = [];
+        }
+        else {
+            next.consecutiveNoImprovement++;
+            next.comparisonIds = [...next.comparisonIds, row.id].slice(-32);
+        }
+        if (next.consecutiveNoImprovement >= next.criteria.attempts)
+            break;
+    }
+    return next;
+}
+/** A real failed compile is an unmeasured attempt, not proof that the environment is inaccessible. */
+export function hasFailedCompileObservation(evidence, since) {
+    return parseEvidenceSnapshot(evidence)?.records.some(row => row.kind === 'observation'
+        && row.source.origin === 'host_receipt' && row.source.toolName === 'run_command'
+        && Date.parse(row.recordedAt) >= since && row.source.verification?.purpose === 'compile'
+        && row.source.verification.process_outcome === 'failed') ?? false;
+}
+export function formatGoalPlateau(state) {
+    if (!state.enabled)
+        return `Plateau criterion suspended after scope steering: ${state.criteria.scope}; `
+            + `${state.measuredAttempts} earlier admitted measurements. A new applicable criterion requires explicit user selection.`;
+    return `Plateau criterion: ${state.criteria.attempts} comparable ${state.criteria.scope} attempts without `
+        + `${state.criteria.minImprovementPercent}% improvement (${state.consecutiveNoImprovement}/${state.criteria.attempts}); `
+        + `${state.measuredAttempts} admitted measurements. A measured delta is not a causal performance claim.`;
+}

package/dist/agent/commands/help.js

@@ -1,4 +1,5 @@
 import { buildHelpIntroduction } from '../../onboarding/first_run.js';
+import { STATUS_LINE_ITEMS, STATUS_LINE_ITEM_LABELS, STATUS_LINE_ITEM_DESCRIPTIONS } from '../../ui/status_line_config.js';
 export function makeHelpCommand(getCommands) {
     return {
         name: 'help',
@@ -6,6 +7,7 @@ export function makeHelpCommand(getCommands) {
         agentRunnable: true,
         category: 'core',
         handler: (_, ctx) => {
+            const statusHelp = STATUS_LINE_ITEMS.map(item => `  ${STATUS_LINE_ITEM_LABELS[item]}: ${STATUS_LINE_ITEM_DESCRIPTIONS[item]}`).join('\n');
             const helpText = getCommands()
                 .map(c => {
                 const cmdLine = c.usage ? `  ${c.usage}` : `  /${c.name}`;
@@ -14,7 +16,7 @@ export function makeHelpCommand(getCommands) {
                 .join('\n\n');
             ctx.addMessage({
                 role: 'system',
-                content: `${buildHelpIntroduction()}\n\nAvailable commands:\n\n${helpText || '  No commands registered.'}`
+                content: `${buildHelpIntroduction()}\n\nKeyboard actions:\n  Esc twice within 2 seconds confirms stop of the running turn.\n  In the queue editor (Option+Up), Esc removes only the selected queued message.\n  Forms, choices and completions close with one Esc; idle Esc keeps the draft and queue.\n  /rewind opens the Ratatui history picker; Ctrl+B ? opens zmux shortcut help.\n\nMouse and scrolling:\n  /settings mouseCapture toggles terminal mouse capture.\n  /settings wheelScrollLines sets 1–20 lines per wheel event (default 3).\n  These preferences require a compatible native renderer; otherwise they are saved for the next compatible launch.\n\nStatus line fields:\n${statusHelp}\n\nAvailable commands:\n\n${helpText || '  No commands registered.'}`
             });
         }
     };

package/dist/agent/commands/history.js

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 export const clearCommand = {
     name: 'clear',
     description: 'Clear message history',
@@ -11,7 +12,8 @@ export const clearCommand = {
         ctx.clearTransientState?.();
         ctx.addMessage({
             role: 'system',
-            content: 'Message history cleared.'
+            content: 'Message history cleared.',
+            metadata: { taskHandoffReset: randomUUID() },
         });
     }
 };

package/dist/agent/commands/inbox.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from './types.js';
+export declare const inboxCommand: Command;