@caupulican/pi-adaptative 0.81.40 → 0.81.41

package/dist/core/agent-session.d.ts

@@ -1,9 +1,9 @@
-import type { Agent, AgentEvent, AgentLoopConfig, AgentMessage, AgentState, AgentTool, StreamIdleOptions, ThinkingLevel } from "@caupulican/pi-agent-core";
+import type { Agent, AgentMessage, AgentState, StreamIdleOptions, ThinkingLevel } from "@caupulican/pi-agent-core";
 import { type CustomMessage } from "@caupulican/pi-agent-core";
 import type { BranchSummaryEntry, CompactionResult, SessionManager } from "@caupulican/pi-agent-core/node";
-import type { Api, CacheRetention, ImageContent, Message, Model, StopReason, TextContent, Usage } from "@caupulican/pi-ai";
+import type { Api, ImageContent, Model, TextContent, Usage } from "@caupulican/pi-ai";
 import type { CapabilityEnvelope, EvidenceBundle, LearningDecision, WorkerClaim, WorkerRequest } from "./autonomy/contracts.ts";
-import type { LaneRecord, LaneTerminalStatus } from "./autonomy/lane-tracker.ts";
+import type { LaneRecord } from "./autonomy/lane-tracker.ts";
 import type { AutonomyDiagnosticSnapshot, AutonomyStatusSnapshot, GateOutcomeHistoryEntry } from "./autonomy/status.ts";
 import type { BashResult } from "./bash-executor.ts";
 import type { CurationTelemetrySnapshot } from "./context/brain-curator.ts";
@@ -19,12 +19,11 @@ import type { SessionCostSummary } from "./cost/cost-summary.ts";
 import type { DailyUsageTotals } from "./cost/daily-usage.ts";
 import { type CostGuardDecision } from "./cost-guard.ts";
 import type { WorkerDelegationRequest } from "./delegation/worker-delegation-request.ts";
-import type { WorkerRunOutcome } from "./delegation/worker-runner.ts";
-import type { ContextUsage, ExtensionCommandContextActions, ExtensionContext, ExtensionErrorListener, ExtensionRunner, ExtensionUIContext, InputSource, ReplacedSessionContext, SessionStartEvent, ShutdownHandler, ToolDefinition, ToolInfo } from "./extensions/index.ts";
+import type { ContextUsage, ExtensionRunner, ReplacedSessionContext, ToolDefinition, ToolInfo } from "./extensions/index.ts";
 import { type ChannelProvider, GatewayRegistry, type JobSchedulerProvider } from "./gateways/channel-provider.ts";
-import type { GoalContinuationPrompt, GoalContinuationPromptLimits } from "./goals/goal-continuation-prompt.ts";
-import { type GoalRuntimeSnapshot, type GoalRuntimeSnapshotSettings } from "./goals/goal-runtime-snapshot.ts";
-import { type GoalState } from "./goals/goal-state.ts";
+import type { GoalStateRevision } from "./goals/goal-lifecycle.ts";
+import type { GoalRuntimeSnapshot, GoalRuntimeSnapshotSettings } from "./goals/goal-runtime-snapshot.ts";
+import type { GoalState } from "./goals/goal-state.ts";
 import type { LearningAuditRecord } from "./learning/learning-audit.ts";
 import type { DemandSignals, ReflectionResult } from "./learning/reflection-engine.ts";
 import { type CurationProposals } from "./learning/skill-curator.ts";
@@ -33,15 +32,11 @@ import { type LaneWorkerRefusal, type ModelCapabilityProfile } from "./model-cap
 import type { ModelRegistry } from "./model-registry.ts";
 import type { StoredFitnessReport } from "./models/fitness-store.ts";
 import type { PrismLlamaCppRuntime } from "./models/llamacpp-runtime.ts";
-import type { LocalRuntimeDeps, OllamaRuntime, TransformersRuntime } from "./models/local-runtime.ts";
-import type { OrchestrationProfile } from "./orchestration/contracts.ts";
+import type { OllamaRuntime, TransformersRuntime } from "./models/local-runtime.ts";
 import { type PromptTemplate } from "./prompt-templates.ts";
 import type { ModelFitnessReport } from "./research/model-fitness.ts";
-import type { ResearchRunResult } from "./research/research-runner.ts";
-import { collectWorkspaceSources } from "./research/workspace-collector.ts";
 import type { ResourceLoader } from "./resource-loader.ts";
-import { type ToolArgumentValidationStats } from "./session-analytics.ts";
-import type { ResourceProfileFilterSettings, SettingsManager } from "./settings-manager.ts";
+import type { SettingsManager } from "./settings-manager.ts";
 import { type TaskStepsState } from "./tasks/task-state.ts";
 import { type ToolProbeReport } from "./tool-protocol-controller.ts";
 import type { BashOperations } from "./tools/bash.ts";
@@ -52,380 +47,9 @@ import type { BashOperations } from "./tools/bash.ts";
  * may be set or changed at any time before the request that should observe it.
  */
 export declare function setStreamIdleOptionsForTests(opts: Partial<StreamIdleOptions> | undefined): void;
-/** Parsed skill block from a user message */
-export interface ParsedSkillBlock {
-    name: string;
-    location: string;
-    content: string;
-    userMessage: string | undefined;
-}
-/**
- * Parse a skill block from message text.
- * Returns null if the text doesn't contain a skill block.
- */
-export declare function parseSkillBlock(text: string): ParsedSkillBlock | null;
-/** Session-specific events that extend the core AgentEvent */
-export type AgentSessionEvent = Exclude<AgentEvent, {
-    type: "agent_end";
-}> | {
-    type: "agent_end";
-    messages: AgentMessage[];
-    willRetry: boolean;
-} | {
-    type: "queue_update";
-    steering: readonly string[];
-    followUp: readonly string[];
-    commands: readonly string[];
-} | {
-    type: "compaction_start";
-    reason: "manual" | "threshold" | "overflow";
-} | {
-    type: "session_info_changed";
-    name: string | undefined;
-} | {
-    type: "thinking_level_changed";
-    level: ThinkingLevel;
-} | {
-    type: "warning";
-    message: string;
-} | {
-    type: "compaction_end";
-    reason: "manual" | "threshold" | "overflow";
-    result: CompactionResult | undefined;
-    aborted: boolean;
-    willRetry: boolean;
-    errorMessage?: string;
-    /**
-     * Benign no-op explanation for auto-compaction (e.g. "nothing to compact yet"). Auto
-     * bails must never be silent: without a result, either errorMessage (real failure) or
-     * skipReason (harmless skip) is set so the UI can show why nothing changed.
-     */
-    skipReason?: string;
-} | {
-    type: "auto_retry_start";
-    attempt: number;
-    maxAttempts: number;
-    delayMs: number;
-    errorMessage: string;
-} | {
-    type: "auto_retry_end";
-    success: boolean;
-    attempt: number;
-    finalError?: string;
-} | {
-    type: "routing_start";
-} | {
-    type: "routing_end";
-} | {
-    type: "delegate_workers";
-    active: number;
-    queued: number;
-    running: number;
-    completedSinceFlush: number;
-    failedSinceFlush: number;
-    terminalSinceFlush: Array<{
-        laneId: string;
-        status: LaneTerminalStatus;
-        reasonCode?: string;
-    }>;
-};
-/** Listener function for agent session events */
-export type AgentSessionEventListener = (event: AgentSessionEvent) => void;
-export interface AgentSessionConfig {
-    agent: Agent;
-    sessionManager: SessionManager;
-    settingsManager: SettingsManager;
-    cwd: string;
-    /** User-level agent state directory for generated runtime artifacts. */
-    agentDir?: string;
-    /** Models to cycle through with Ctrl+P (from --models flag) */
-    scopedModels?: Array<{
-        model: Model<Api>;
-        thinkingLevel?: ThinkingLevel;
-    }>;
-    /** Resource loader for skills, prompts, themes, context files, system prompt */
-    resourceLoader: ResourceLoader;
-    /** SDK custom tools registered outside extensions */
-    customTools?: ToolDefinition[];
-    /** Model registry for API key resolution and model discovery */
-    modelRegistry: ModelRegistry;
-    /** Initial active built-in tool names. Default: [read, bash, edit, write, context_audit, goal] */
-    initialActiveToolNames?: string[];
-    /** Optional allowlist of tool names. When provided, only these tool names are exposed. */
-    allowedToolNames?: string[];
-    /** Optional denylist of tool names. When provided, these tool names are not exposed. */
-    excludedToolNames?: string[];
-    /** Optional resource-profile allow/block filters for tool names. */
-    toolProfileFilter?: ResourceProfileFilterSettings;
-    /**
-     * Whether the model/thinking level came from an explicit launch flag. When false, the active
-     * profile's model/thinking is re-applied on reload() so live profile edits take effect; when
-     * true, the explicit launch-time choice is preserved.
-     */
-    isExplicitModel?: boolean;
-    isExplicitThinking?: boolean;
-    /** True when this session is a spawned subagent/child — gates durable memory writes. */
-    isChildSession?: boolean;
-    /**
-     * Override base tools (useful for custom runtimes).
-     *
-     * These are synthesized into minimal ToolDefinitions internally so AgentSession can keep
-     * a definition-first registry even when callers provide plain AgentTool instances.
-     */
-    baseToolsOverride?: Record<string, AgentTool>;
-    /** Mutable ref used by Agent to access the current ExtensionRunner */
-    extensionRunnerRef?: {
-        current?: ExtensionRunner;
-    };
-    /** Session start event metadata emitted when extensions bind to this runtime. */
-    sessionStartEvent?: SessionStartEvent;
-    /**
-     * Pointer-first workspace source collector for the autonomous research lane. Injected in unit
-     * tests so they don't spawn a real ripgrep child (which would escape fake timers); production
-     * defaults to the real, best-effort collector.
-     */
-    collectWorkspaceSources?: typeof collectWorkspaceSources;
-    /** Immutable owner-authored orchestration policy; dispatch cannot mutate it. */
-    orchestrationProfile?: OrchestrationProfile;
-    /**
-     * Injected fetch/spawn/exists for the local (Ollama) runtime health-check + boot used by the
-     * model router before a turn routed to a local model (see LocalRuntimeController.ensureLocalModelReady).
-     * Unit tests inject fakes so they never hit a real network/process; production defaults to the real ones.
-     */
-    localRuntimeDeps?: LocalRuntimeDeps;
-}
-export interface ExtensionBindings {
-    uiContext?: ExtensionUIContext;
-    mode?: ExtensionContext["mode"];
-    commandContextActions?: ExtensionCommandContextActions;
-    abortHandler?: () => void;
-    shutdownHandler?: ShutdownHandler;
-    onError?: ExtensionErrorListener;
-}
-/** Options for AgentSession.prompt() */
-export interface PromptOptions {
-    /** Whether to expand file-based prompt templates and skills (default: true). */
-    expandPromptTemplates?: boolean;
-    /** Whether slash commands should be handled before sending to the model. Defaults to expandPromptTemplates. */
-    processSlashCommands?: boolean;
-    /** Image attachments */
-    images?: ImageContent[];
-    /** When streaming, how to queue the message: "steer" (interrupt) or "followUp" (wait). Required if streaming. */
-    streamingBehavior?: "steer" | "followUp";
-    /** Source of input for extension input event handlers. Defaults to "interactive". */
-    source?: InputSource;
-    /** Internal hook used by RPC mode to observe prompt preflight acceptance or rejection. */
-    preflightResult?: (success: boolean) => void;
-    /** Whether an idle active goal should auto-inject bounded continuation prompts after this prompt settles. Default: true. */
-    autoContinueGoal?: boolean;
-}
+export * from "./agent-session-contracts.ts";
+import type { AgentSessionConfig, AgentSessionEventListener, ExtensionBindings, GoalContinuationLoopOptions, GoalContinuationLoopResult, GoalContinuationOnceOptions, GoalContinuationOnceResult, IsolatedCompletionOptions, IsolatedCompletionResult, ModelCycleResult, PromptOptions, ResearchLaneRunOutcome, SessionStats, SpawnedUsageTotals, WorkerDelegationRunOutcome } from "./agent-session-contracts.ts";
 export type { ToolProbeReport, ToolProbeResult, ToolProbeVerdict } from "./tool-protocol-controller.ts";
-/** Result from cycleModel() */
-export interface ModelCycleResult {
-    model: Model<Api>;
-    thinkingLevel: ThinkingLevel;
-    /** Whether cycling through scoped models (--models flag) or all available */
-    isScoped: boolean;
-}
-/** Session statistics for /session command */
-export interface CompactionGateCheckStats {
-    failures: number;
-    minScore?: number;
-    maxScore?: number;
-    threshold?: number;
-    comparator?: "minimum" | "maximum";
-}
-export interface CompactionGateStats {
-    gateFailures: number;
-    deterministicGapFills: number;
-    compactionsWithGateFailures: number;
-    checks: Record<string, CompactionGateCheckStats>;
-}
-export interface SessionStats {
-    sessionFile: string | undefined;
-    sessionId: string;
-    userMessages: number;
-    assistantMessages: number;
-    toolCalls: number;
-    toolResults: number;
-    totalMessages: number;
-    tokens: {
-        input: number;
-        output: number;
-        cacheRead: number;
-        cacheWrite: number;
-        total: number;
-    };
-    cost: number;
-    contextUsage?: ContextUsage;
-    toolArgumentValidation: ToolArgumentValidationStats;
-    compactionGates: CompactionGateStats;
-}
-/** customType for spawned-usage roll-up entries (Cost Aggregation, Model A). */
-export declare const SPAWNED_USAGE_CUSTOM_TYPE = "spawned_usage";
-/**
- * customType for a persisted runaway-loop-backstop entry: the agent loop stopped a turn stuck
- * repeating one identical tool-call signature. This is the session-log/telemetry sink for
- * {@link Agent.onRunawayStop} — see `_installAgentToolHooks`.
- */
-export declare const RUNAWAY_STOP_CUSTOM_TYPE = "runaway_stop";
-/** Payload persisted for a {@link RUNAWAY_STOP_CUSTOM_TYPE} entry. */
-export interface RunawayStopRecord {
-    signature: string;
-    repeats: number;
-    model?: string;
-    provider?: string;
-    at: string;
-}
-/**
- * customType for a persisted tool-validation-escalation entry: the agent loop bounced the same
- * tool-call validation failure enough times to escalate. This is the session-log/telemetry sink for
- * {@link Agent.onToolValidationEscalation} — see `_installAgentToolHooks`.
- */
-export declare const TOOL_VALIDATION_ESCALATION_CUSTOM_TYPE = "tool_validation_escalation";
-/** Payload persisted for a {@link TOOL_VALIDATION_ESCALATION_CUSTOM_TYPE} entry. */
-export interface ToolValidationEscalationRecord {
-    tool: string;
-    signature: string;
-    repeats: number;
-    model: string;
-    provider: string;
-    at: string;
-}
-/**
- * A single spawned/subagent usage report, persisted as a `CustomEntry`
- * (`customType: "spawned_usage"`). Persistence-only — does NOT enter LLM context.
- *
- * Single-hop invariant: each report MUST already include the reporter's own usage AND its
- * accumulated sub-usage. A child rolls up its grandchildren, then reports once to its direct
- * parent. Only the direct parent records the report — never a grandparent — so cost cannot be
- * double-counted across levels.
- */
-export interface SpawnedUsageReport {
-    /** Cumulative usage attributed to the spawned session (own + its own sub-usage). */
-    usage: Usage;
-    /** Human-readable source label for diagnostics (e.g. subagent name). */
-    label?: string;
-    /** Session id of the reporting child, if known. */
-    sourceSessionId?: string;
-    /** Stable id used to de-duplicate re-reports (retries, double agent_end). */
-    reportId?: string;
-}
-/** Aggregated spawned-usage totals derived from `spawned_usage` custom entries. */
-export interface SpawnedUsageTotals {
-    /** Summed `usage.cost.total` across all recorded reports. */
-    cost: number;
-    /** Number of distinct reports recorded. */
-    reports: number;
-}
-/**
- * Options for {@link AgentSession.runIsolatedCompletion} — an LLM call fully isolated from the main
- * session. With no tools it is one-shot (reflection); lane callers may supply a bounded child loop.
- */
-export interface IsolatedCompletionOptions {
-    /** System prompt for the isolated call. */
-    systemPrompt: string;
-    /** The isolated conversation (e.g. the reflection prompt). NOT the main session history. */
-    messages: Message[];
-    /** Model to use. Defaults to the session model; callers should pass a cheap model. */
-    model?: Model<Api>;
-    /** Thinking level. Defaults to "off" to keep the call cheap. */
-    thinkingLevel?: ThinkingLevel;
-    /** Output token cap. */
-    maxTokens?: number;
-    /** Fresh tools owned by the isolated child. Omitted/empty preserves one-shot behavior. */
-    tools?: AgentTool[];
-    /** Maximum assistant turns for a tool-enabled child loop. Ignored by one-shot calls. */
-    maxTurns?: number;
-    /**
-     * Optional tool-free finalization prompt. When the bounded child loop exhausts its turns on an
-     * assistant tool-call message with no text, one final provider call receives the gathered transcript
-     * plus this prompt so useful work is not discarded solely for lacking a terminal summary.
-     */
-    finalTextPrompt?: string;
-    /** Child-only capability/path gate. Never inherited from the foreground session. */
-    beforeToolCall?: AgentLoopConfig["beforeToolCall"];
-    /** Child-only result observer (for example, successful scoped-write accounting). */
-    afterToolCall?: AgentLoopConfig["afterToolCall"];
-    /** Abort signal. */
-    signal?: AbortSignal;
-    /**
-     * Prompt-cache retention for this isolated call. REQUIRED — the provider-level default is
-     * `"short"`, the opposite of this primitive's old implicit default, so a caller that forgot to
-     * set it would silently pay full input price forever. Pass `"none"` explicitly to preserve full
-     * isolation (no caching); callers whose `systemPrompt` is STATIC across calls (e.g. reflection,
-     * #33) should pass `"short"`/`"long"` so the provider reuses the cached prefix and bills only the
-     * variable tail.
-     */
-    cacheRetention: CacheRetention;
-    /**
-     * Lane/caller kind (e.g. `"reflection"`, `"research"`, `"worker"`, `"fitness"`) used to derive this
-     * call's synthetic cache-affinity key (see {@link computeLaneAffinityKey}). Omitted callers fall
-     * back to {@link DEFAULT_ISOLATED_LANE_KIND} — still a stable, namespaced key, just not
-     * lane-differentiated. Never the real session id.
-     */
-    laneKind?: string;
-}
-/** Fallback {@link IsolatedCompletionOptions.laneKind} for callers that do not tag their lane. */
-export declare const DEFAULT_ISOLATED_LANE_KIND = "isolated";
-/**
- * Derive a STABLE synthetic cache-affinity key for an isolated completion lane. Isolated calls
- * deliberately never carry the real session id (see reflection-controller.ts's isolation invariants —
- * an isolated call must not entangle with the main session), which today also means every isolated
- * call looks like a brand-new, uncorrelated session to providers with session-affinity headers /
- * `prompt_cache_key` (anthropic.ts's `x-session-affinity`, openai-responses.ts /
- * openai-completions.ts's `prompt_cache_key`), defeating their cache routing.
- *
- * This key is deterministic per `(laneKind, model, systemPrompt)` — the SAME lane calling the SAME
- * model with the SAME (static) system prompt always gets the SAME key, so repeat calls route to the
- * same cache-warm backend — while remaining fully synthetic: it is a salted hash, namespaced with a
- * `lane:` prefix, and never derived from or equal to the real session id.
- */
-export declare function computeLaneAffinityKey(laneKind: string, model: Model<Api> | undefined, systemPrompt: string): string;
-/** Result of an isolated completion: the text, the usage spent, and the stop reason. */
-export interface IsolatedCompletionResult {
-    text: string;
-    usage: Usage;
-    stopReason: StopReason;
-}
-export interface ResearchLaneRunOutcome {
-    /** False when the pass was skipped before starting (see skipReason). */
-    started: boolean;
-    skipReason?: string;
-    /** Terminal lane record when the pass ran. */
-    record?: LaneRecord;
-    result?: ResearchRunResult;
-}
-export interface WorkerDelegationRunOutcome {
-    /** False when the delegation was skipped before starting (see skipReason). */
-    started: boolean;
-    skipReason?: string;
-    /** Terminal lane record when the delegation ran. */
-    record?: LaneRecord;
-    outcome?: WorkerRunOutcome;
-}
-export interface GoalContinuationOnceOptions {
-    maxStallTurns: number;
-    promptLimits?: GoalContinuationPromptLimits;
-}
-export interface GoalContinuationOnceResult {
-    submitted: boolean;
-    snapshot: GoalRuntimeSnapshot;
-    prompt?: GoalContinuationPrompt;
-}
-export type GoalContinuationLoopStopReason = "continuation_not_allowed" | "max_turns_reached" | "wall_clock_budget_reached" | "goal_state_not_advanced" | "goal_budget_exhausted" | "already_continuing" | "session_disposed" | "goal_tool_unavailable" | "worker_in_flight";
-export interface GoalContinuationLoopOptions extends GoalContinuationOnceOptions {
-    maxTurns: number;
-    /** 0 or undefined disables wall-clock budget. */
-    maxWallClockMinutes?: number;
-    /** Test seam for wall-clock budget enforcement. Defaults to Date.now. */
-    now?: () => number;
-}
-export interface GoalContinuationLoopResult {
-    turnsSubmitted: number;
-    stopReason: GoalContinuationLoopStopReason;
-    finalSnapshot: GoalRuntimeSnapshot;
-}
 export declare class AgentSession {
     readonly agent: Agent;
     readonly sessionManager: SessionManager;
@@ -440,9 +64,6 @@ export declare class AgentSession {
     private _queuedExtensionCommands;
     private _pendingNextTurnMessages;
     private _streamingPromptSubmissionTail;
-    /** Serializes owner-input overlays so concurrent worker terminals cannot replace each other. */
-    private _humanInputTail;
-    private _activeHumanInputRequestIds;
     /**
      * The last tool set requested via setActiveToolsByName BEFORE model-capability filtering, so
      * switching from a small-window model back to a large one restores the full requested set.
@@ -479,6 +100,7 @@ export declare class AgentSession {
      * background-lane-controller.ts); owns the lane timers/guards, the last research-lane skip
      * reason, the live LaneTracker, and the in-flight research/worker abort controllers. */
     private readonly _backgroundLanes;
+    private readonly _humanInput;
     /** Plug-and-play memory subsystem (see memory-controller.ts); owns the OKF retrieval provider, the
      * latest retrieval/prompt-inclusion reports, the reload-safe MemoryManager, the recall
      * effectiveness tracker, and the extension-contributed pending providers. */
@@ -525,9 +147,8 @@ export declare class AgentSession {
     /** Native reflection engine + learning-apply/rollback path (see reflection-controller.ts); owns no
      * session state, applies durable writes through the bundled memory tool and the session log. */
     private readonly _reflection;
-    /** Bounded goal auto-continuation loop (see goal-loop-controller.ts); reads goal state fresh
-     * each pass and re-enters the session's own prompt path. */
-    private readonly _goalContinuation;
+    /** Durable goal lifecycle, accounting, and raw continuation loop. */
+    private readonly _goals;
     private readonly _isChildSession;
     private _baseToolsOverride?;
     private _sessionStartEvent;
@@ -901,10 +522,6 @@ export declare class AgentSession {
      */
     private _buildSystemPromptForToolNames;
     private _runAgentPrompt;
-    private _queueWorkerHumanInput;
-    private _schedulePendingWorkerHumanInputs;
-    private _scheduleWorkerHumanInput;
-    private _resolveWorkerHumanInput;
     /**
      * Re-enter an interrupted ask_question call from its durable request snapshot. Pending requests
      * are presented again; already-checkpointed answers are replayed without asking twice. The
@@ -1208,26 +825,30 @@ export declare class AgentSession {
      *
      * @returns the id of the appended custom entry
      */
-    saveGoalStateSnapshot(state: GoalState): string;
+    saveGoalStateSnapshot(state: GoalState, expected?: GoalStateRevision): string;
+    /** Persist a branch-scoped tombstone and stop goal-owned execution without resurrecting old state. */
+    clearGoalStateSnapshot(state: GoalState, now: string): string;
     /**
      * Retrieve the latest valid goal state snapshot from the session log.
      */
     getGoalStateSnapshot(): GoalState | undefined;
     /**
-     * Persist one submitted continuation pass's turn/wall-clock/spend contribution onto the active
-     * goal's durable cumulative budget (see `GoalState.continuationTurnsUsed` et al.). This is the
+     * Persist one submitted continuation pass's exact turn/wall-clock/token/spend contribution onto the active
+     * goal's durable cumulative accounting (see `GoalState.continuationTurnsUsed` et al.). This is the
      * "persistence dep" `GoalLoopController` calls once per pass actually submitted — it, not the
-     * loop controller, is where USD gets attributed: it reads the session's OWN cumulative model
-     * spend (`getCostSummary().ownCost` — deliberately excludes worker/subagent spend, which is
-     * tracked and budgeted separately) and threads that single absolute reading into a
-     * `record_continuation_budget` event; the pure reducer in `goal-state.ts` derives the delta.
+     * loop controller, is where usage gets attributed: it scans only assistant messages appended on
+     * the active branch after the pass's captured cursor. Compaction cannot erase or reattribute that
+     * append-only interval, and unrelated foreground turns outside the interval are excluded.
      * A no-op when no goal state exists (defensive — in practice this is only ever called right
      * after a pass the loop already confirmed was submitted against an active goal).
      */
     recordGoalContinuationPass(pass: {
         turns: number;
         wallClockMs: number;
+        usageCursor: string | null;
     }): void;
+    /** Restore runtime intent without mutating persisted goal lifecycle state. */
+    restoreGoalRuntimeAfterResume(): void;
     /** Save native task-step state to the active session log. */
     saveTaskStepsStateSnapshot(state: TaskStepsState): string;
     /** Retrieve the latest valid native task-step state from the active session log. */
@@ -1313,7 +934,7 @@ export declare class AgentSession {
      * continuation. Delegates to {@link BackgroundLaneController.continueGoalLoopExclusive}, the
      * single-flight guard that prevents two goal loops from racing to submit prompts through the
      * same session (which throws "Agent is already processing" from the second submission). Do not
-     * call `this._goalContinuation.continueGoalLoop` directly from here — that bypasses the guard.
+     * call `this._goals.continueLoop` directly from here — that bypasses the guard.
      */
     continueGoalLoop(options: GoalContinuationLoopOptions): Promise<GoalContinuationLoopResult>;
     /**