@caupulican/pi-adaptative 0.80.86 → 0.80.88

package/CHANGELOG.md

@@ -1,3 +1,128 @@
+## [0.80.88] - 2026-07-02
+
+## [0.80.87] - 2026-07-02
+
+### Added
+
+- Added an opt-in Context / Prompt Policy setting that stubs stale, artifact-backed grep/find tool output
+  in the model-visible prompt only (never the transcript) once configured retention-window and character
+  thresholds are exceeded. Configurable via the Context / Prompt Policy settings submenu; default disabled.
+- Added an opt-in Context / Memory Retrieval setting that searches local Pi OKF memory documents each turn
+  and can optionally surface a bounded, source-labeled evidence block in the model prompt (never the
+  transcript). Configurable via the Context / Memory Retrieval settings submenu, including a separate
+  "Include in prompt" toggle; both default disabled, and retrieval only ever queries the local provider.
+- Extended `context_audit` with a compact Memory retrieval / Prompt inclusion diagnostic section reporting
+  status and counts for the two settings above, without exposing any memory content, query text, or file
+  paths.
+- Added a `goal` tool that records the durable goal ledger (goal, requirements, evidence, and
+  progress/stall events) as session-persisted snapshots. This is the producer that drives the bounded
+  goal continuation loop and `/goal-continue`; without it the continuation runtime always read empty
+  state and could not continue. The tool is active by default and maps to the `memory_write` capability.
+- Added `/autonomy diagnostics`, an effectiveness dashboard summarizing recent model-router decisions,
+  current/spawned/daily cost totals, and, when present, the latest research, worker-delegation,
+  learning, and goal activity. It is additive to `/autonomy [status|off|safe|balanced|full]`.
+- Added the autonomous research lane runtime: an opt-in, read-only background research pass that runs
+  when the session goes idle with an active goal that has open requirements, executes one bounded
+  isolated completion through the (unwired-until-now) research capability/budget gate, and persists a
+  provenance-tagged evidence bundle plus a terminal lane record. Budgets cover cost per pass,
+  wall-clock time, findings/sources caps, and idle runs per session; failures/skips are recorded with
+  reason codes and never block or prompt the foreground. Research spend reports through spawned-usage
+  accounting with an idempotent per-lane report id. Configurable via the new Research Lane settings
+  submenu (default disabled; also requires autonomy mode on); `/autonomy research` triggers an
+  explicit pass. Live lanes now feed the previously-unset `activeLaneCount` in `/autonomy status`
+  snapshots, and `/autonomy diagnostics` shows research lane records, all evidence bundles, and the
+  last skip reason.
+- Added the bounded worker-delegation runtime piloting read-only scout workers: a new `delegate`
+  tool (active by default, mapped to the `delegate` capability, refusing with a reason until the
+  Worker Delegation setting is enabled) lets the foreground model hand one self-contained analysis
+  task to a worker running as a bounded isolated completion on a cheap model lane under a stripped
+  read-only envelope. Every result is validated through the existing `validateWorkerResult` parent
+  gate before acceptance, persisted as a worker-result snapshot plus a terminal lane record, marked
+  untrusted in the tool output, and cost-reported through spawned-usage accounting with an
+  idempotent per-lane report id. Budgets cover cost per worker and wall-clock time; delegation
+  lanes appear in `/autonomy diagnostics` and count toward the live `activeLaneCount`.
+- Added the learning apply/audit/rollback policy runtime: reflection-sourced durable writes now
+  route through the (previously unwired) learning gate, persist a `LearningDecision` snapshot per
+  write, and leave an audit record with a concrete rollback plan for every applied or proposed
+  change. With the new Learning Policy settings disabled (default) the legacy direct-apply
+  behavior is preserved — now fully audited; when enabled, single-session reflection cues become
+  proposals unless the configured confidence/observation thresholds and allowed layers
+  (memory-only by default) permit auto-apply. `/autonomy rollback <auditId>` (and
+  `AgentSession.rollbackLearningWrite`) executes the inverse memory operation or archives a
+  promoted skill, exactly once per change, and records a linked rollback audit. Audit records
+  appear in the `/autonomy diagnostics` learning family.
+- Added model-capability auto-detection so small open models (including sub-1B local models) stay
+  usable for chat: the harness derives a capability class from the model's own `contextWindow`
+  metadata — full (≥32k, unchanged), lean (≥16k, background-autonomy tools like `delegate` and
+  `context_audit` blocked), minimal (≥8k, tools reduced to read/bash/edit/write, background lanes
+  disabled), and chat (<8k, no tools at all). Filtering happens in `setActiveToolsByName`, so the
+  system prompt sheds the blocked tools' schemas and guidelines too; the unfiltered request is
+  remembered and restored when switching back to a larger model, with a visible notice on
+  downgrade. Idle goal auto-continuation and the research lane are gated off below 16k
+  (`model_context_too_small` in diagnostics), and lane output-token budgets scale to the lane
+  model's window. Metadata-first with defaults only when info is missing (unknown window keeps
+  full behavior); configurable via `modelCapability.mode` (`auto` default, `off`, or a forced
+  class).
+- Changed background-lane model resolution to inherit the session model the lane was shipped
+  from unless a lane-specific model is explicitly configured (the router's `cheapModel` no longer
+  implicitly redirects lanes) — single-model setups, e.g. one local open model, now run research
+  and scout workers on that same model.
+- Changed active resource profiles to strict least-privilege grants: when one or more profiles are
+  active, any authority-bearing resource kind (extensions, skills, prompts, tools, agents) that no
+  active profile explicitly mentions is denied outright — a defaults profile no longer loads the
+  full extension/tool surface. Grant-all must be explicit via `allow: ["*"]`; explicitly written
+  block-framed filters keep meaning "all except the listed"; themes are exempt; behavior without
+  an active profile is unchanged.
+- Changed profile denial to gate the disk reads themselves: skill files and prompt templates a
+  profile denies are never read from disk (extensions were already path-filtered before loading).
+  While a restrictive profile is active, denied skills/prompts consequently no longer appear in
+  resource listings; edit profiles with no restrictive profile active to see everything.
+- Added profile-shipped subagents: research and worker lanes accept a `profile` setting whose
+  model MUST be obeyed when set (unresolvable is a visible `no_lane_profile_model` skip, never a
+  fallback), whose soul and thinking level ship with the lane, and whose tool grants are recorded
+  on the lane's capability envelope. Generic lanes keep inheriting the session model.
+- Added a level-0 subagent system-prompt core (<300 tokens of non-negotiable rules) that survives
+  ANY prompt customization: lane settings (`systemPrompt`) and the delegate tool's new
+  `systemPrompt` input can erase and replace everything above it — so a big session model can
+  hand a small open model a minimal purpose-built prompt without shedding the safety floor.
+- Added `run_toolkit_script` (active by default, mapped to the `run_shell` capability): the
+  user's blessed daily-ops script registry (`settings.toolkit.scripts` — name, description,
+  aliases, uv/powershell/bash runner, danger flag) executed with a structural reliability
+  contract. Finding is a conservative registry lookup that NEVER guesses between near-neighbors
+  ("prepare db" vs "update-db" returns a shortlist instead of executing); the harness owns
+  invocation (fixed argv, no shell strings) and always returns exit code, stdout, and stderr —
+  a failed script is an error result by construction and can never look like success; scripts
+  flagged `danger` never run without an explicit `confirm: true`.
+- Added the `model_fitness` probe (tool + `/autonomy fitness <model> [trials]`): runs the real
+  research-lane, scout-worker, and routing-judge runners plus two heavy-lifter surfaces
+  (search-plan formulation, tool-call emission) against any registered model — local Ollama
+  models included — reporting parse/success rates, judge discrimination, mean latency,
+  tokens-per-second, and probe cost. Probe spend is cost-accounted; the tool is registered but
+  not default-active. An opt-in size-class bench (`PI_LOCAL_MODEL_BENCH=1`) asserts per-class
+  minimum bars for locally installed models.
+- Added a host-keyed fitness store (`<agentDir>/state/model-fitness.json`): every probe persists
+  its report under a hardware fingerprint (CPU/cores/RAM), because fitness is a property of a
+  model ON a host — role assignments stay per-machine and synced settings cannot carry one
+  machine's speed numbers onto another. `AgentSession.getStoredFitnessReports()` exposes the
+  current host's measured evidence for profile/role decisions.
+- Added the routing judge: with the model router enabled, a bounded routing-only completion on the
+  judge lane (`modelRouter.judgeModel`, else `mediumModel`; ≤128 output tokens, 10s wall clock,
+  static cached prompt) decides the final cheap/medium/expensive tier over the regex baseline —
+  never the learning tier. Core rule: planning/design prompts are never cheap unless the judge
+  explicitly deems them trivial; the regex classifier now also floors prospective planning prompts
+  at medium (`planning_min_medium`) while plain lookups like "show me the architecture" stay
+  cheap. Judge failures fall back to the baseline with visible reasons, judge spend reports
+  through spawned-usage accounting, and `modelRouter.judgeEnabled: false` restores byte-identical
+  router behavior.
+
+### Changed
+
+- Changed bounded goal continuation to default to 20 turns and auto-inject continuation prompts after a
+  prompt settles idle while an active goal remains open, with internal recursion suppression for
+  continuation prompts. It now also respects new settings for wall-clock budget, idle delay, and turn limits,
+  which can be configured via the Autonomy submenu in the settings TUI.
+- Added a third positional argument `[maxMinutes]` to the `/goal-continue` command to support bounded wall-clock loop termination.
+
 ## [0.80.86] - 2026-06-29
 
 ### Added
@@ -8,6 +133,30 @@
 
 - Fixed adaptive scaling of compaction parameters (`reserveTokens` and `keepRecentTokens`) for models with small context windows to avoid immediate auto-compaction loops.
 - Fixed a scope redeclaration issue with `activeProfileNames` in the resource loader.
+- Fixed the semantic-memory context GC never packing the recall pages the bundled default memory
+  provider emits: active providers' page markers are now merged into the GC marker list at runtime
+  (and the generic `<memory_context` marker joined the settings default), so stale cross-session
+  recall pages no longer accumulate raw — and re-bill — for the life of the session.
+- Fixed internal tool-registry refreshes (extension `refreshTools`, memory init, `/reload`,
+  live extension load/unload) permanently shrinking the restorable tool set: they re-derived from
+  the capability/profile-filtered ACTIVE tools instead of the pre-filter request, so switching back
+  to a larger model restored only the reduced set.
+- Fixed the model router judge being consulted on internally generated continuation turns (one
+  judge call per loop iteration) and enforced the planning floor in code: a cheap downgrade of a
+  non-cheap baseline now requires the judge's explicit `trivial` verdict.
+- Fixed `model_fitness` probes: per-surface calls are now wall-clock bounded (a hung local model
+  can no longer hang the probe), tokens/sec is measured in the shipped session path, and an empty
+  judge prompt set no longer yields NaN latency.
+- Fixed reflection learning-audit ids colliding after no-op decisions (the rollback key now counts
+  only stored snapshots), which could block or misdirect `learning rollback`.
+- Fixed the lane tracker growing without bound in long sessions (terminal lanes beyond 100 are
+  evicted from memory; the session log keeps full history) and lane ids being reused after resume.
+- Fixed toolkit script execution discarding spawn-failure diagnostics: a missing runner
+  (ENOENT/EACCES) now surfaces the real cause in stderr instead of an empty `exited null`, and an
+  output-overflow kill is no longer mislabeled as a timeout. Repeated words in a request no longer
+  multiply the Level-0 matcher score into a false confident match.
+- Fixed NaN/invalid model `contextWindow` metadata leaking into capability profiles and lane
+  budgets in `off`/forced modes.
 
 
 ## [0.80.85] - 2026-06-29

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

@@ -1,18 +1,35 @@
 import type { Agent, AgentEvent, AgentMessage, AgentState, AgentTool, ThinkingLevel } from "@caupulican/pi-agent-core";
 import type { CacheRetention, ImageContent, Message, Model, StopReason, TextContent, Usage } from "@caupulican/pi-ai";
+import type { CapabilityEnvelope, EvidenceBundle, LearningDecision, WorkerResult } from "./autonomy/contracts.ts";
+import { type LaneRecord } from "./autonomy/lane-tracker.ts";
+import type { AutonomyDiagnosticSnapshot, AutonomyStatusSnapshot } from "./autonomy/status.ts";
 import { type BashResult } from "./bash-executor.ts";
 import { type CompactionResult } from "./compaction/index.ts";
+import { type ContextAuditReport } from "./context/context-audit.ts";
+import { type PromptEnforcementReport } from "./context/context-prompt-enforcement.ts";
+import { type PromptPolicyGcCorrelationReport, type PromptPolicyShadowReport } from "./context/context-prompt-policy.ts";
+import { type MemoryPromptInclusionReport } from "./context/memory-diagnostics.ts";
+import { type MemoryRetrievalReport } from "./context/memory-retrieval.ts";
 import { type ContextGcReport } from "./context-gc.ts";
 import { type DailyUsageTotals } from "./cost/daily-usage.ts";
 import { type CostGuardDecision } from "./cost-guard.ts";
+import { type WorkerRunOutcome } from "./delegation/worker-runner.ts";
 import { type ContextUsage, type ExtensionCommandContextActions, type ExtensionContext, type ExtensionErrorListener, ExtensionRunner, type ExtensionUIContext, type InputSource, type ReplacedSessionContext, type SessionStartEvent, type ShutdownHandler, type ToolDefinition, type ToolInfo } from "./extensions/index.ts";
 import { type ChannelProvider, GatewayRegistry, type JobSchedulerProvider } from "./gateways/channel-provider.ts";
+import { type GoalContinuationPrompt, type 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 LearningAuditRecord } from "./learning/learning-audit.ts";
 import { type DemandSignals, type ReflectionResult } from "./learning/reflection-engine.ts";
 import { type CurationProposals } from "./learning/skill-curator.ts";
 import type { MemoryProvider } from "./memory/memory-provider.ts";
 import { type CustomMessage } from "./messages.ts";
+import { type ModelCapabilityProfile } from "./model-capability.ts";
 import type { ModelRegistry } from "./model-registry.ts";
+import { type StoredFitnessReport } from "./models/fitness-store.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 type { ResourceLoader } from "./resource-loader.ts";
 import type { BranchSummaryEntry, SessionManager } from "./session-manager.ts";
 import { type ResourceProfileFilterSettings, type SettingsManager } from "./settings-manager.ts";
@@ -92,7 +109,7 @@ export interface AgentSessionConfig {
     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] */
+    /** 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[];
@@ -145,6 +162,8 @@ export interface PromptOptions {
     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;
 }
 /** Result from cycleModel() */
 export interface ModelCycleResult {
@@ -230,10 +249,49 @@ export interface IsolatedCompletionResult {
     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";
+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;
     readonly settingsManager: SettingsManager;
+    capabilityEnvelope?: CapabilityEnvelope;
     private _scopedModels;
     private _unsubscribeAgent?;
     private _eventListeners;
@@ -248,10 +306,41 @@ export declare class AgentSession {
     private _pendingNextTurnMessages;
     /** Serializes prompt() submissions made while streaming so queued steering/follow-ups keep user-typed FIFO order. */
     private _streamingPromptSubmissionTail;
+    /** Pending idle timer that starts bounded goal continuation after the session becomes idle. */
+    private _goalAutoContinueTimer;
+    /** Guards bounded idle autosteer so continuation prompts do not recursively trigger themselves. */
+    private _isGoalAutoContinuing;
+    /** Pending idle timer that starts an autonomous research pass after the session becomes idle. */
+    private _researchLaneTimer;
+    /** Single-flight guard: at most one research pass runs at a time per session. */
+    private _isResearchLaneRunning;
+    /** Why the last idle research-lane evaluation skipped, for /autonomy diagnostics. */
+    private _lastResearchLaneSkipReason;
+    /** Live lane registry — the real source for AutonomyStatusSnapshot.activeLaneCount. */
+    private readonly _laneTracker;
+    /** Session-lifetime abort for in-flight research passes (same pattern as _reflectionAbort). */
+    private readonly _researchLaneAbort;
+    /** Single-flight guard: at most one delegated worker runs at a time per session. */
+    private _isWorkerDelegationRunning;
+    /** Session-lifetime abort for in-flight delegated workers. */
+    private readonly _workerDelegationAbort;
+    /**
+     * 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.
+     */
+    private _requestedActiveToolNames;
     private _compactionAbortController;
     private _autoCompactionAbortController;
     private _overflowRecoveryAttempted;
     private _latestContextGcReport;
+    private _toolArtifactStore;
+    private _latestContextAuditReport;
+    private _latestPromptPolicyReport;
+    private _latestPromptPolicyGcCorrelation;
+    private _latestPromptEnforcementReport;
+    private _memoryOkfProvider;
+    private _latestMemoryRetrievalReport;
+    private _latestMemoryPromptInclusionReport;
     private _branchSummaryAbortController;
     private _retryAbortController;
     private _retryAttempt;
@@ -286,10 +375,12 @@ export declare class AgentSession {
     private _costGuardDowngraded;
     /** Active model-router intent for the current transient routed turn, if any. */
     private _activeModelRouterIntent?;
+    private _activeModelRouterRoute?;
     private _modelRouterSessionBuffer?;
     private _modelRouterEscalationRequested;
     private _isModelRouterRetry;
     private _lastModelRouterDecision?;
+    private _lastAutonomyGateOutcome?;
     private _lastModelRouterSkipReason?;
     private _lastModelRouterIntent?;
     /** Lazily-built skill curator (#32) over `<agentDir>/skills`. */
@@ -373,7 +464,145 @@ export declare class AgentSession {
     private _installAgentTurnRefresh;
     private _createAgentContextSnapshot;
     private _contextGcStorageDir;
+    private _toolArtifactsDir;
+    /**
+     * Session-scoped, filesystem-backed artifact store for first-capture-then-bound tool
+     * output (grep/find only, for now -- see tool-output-artifacts.md). Lazily created and
+     * cached so every tool construction in this session shares one store instance.
+     *
+     * `packToolOutput()` registers a reference (the packing tool call's id) at pack time
+     * and fails closed, so packed artifacts are never prematurely collected.
+     * `_releaseGcPackedArtifactReferences()` (called from `_applyContextGc()`) releases
+     * that reference once context-gc packs the result out of live context, and
+     * opportunistically reclaims now-unreferenced artifacts via `cleanup()`.
+     * Remaining carry-forward gap: cleanup() now also runs at dispose(), but only reclaims
+     * already-released (zero-reference) artifacts. A session that ends before context-gc
+     * ever evicts a result never releases that reference, so its artifact stays on disk by
+     * design (resolvable on resume). Reclaiming those requires an explicit cross-session
+     * expiry/liveness policy, not just a sweep.
+     */
+    private _getToolArtifactStore;
+    /**
+     * Fixed path for this slice's local Pi OKF memory documents, shared across sessions
+     * under this agentDir (not session-scoped, unlike tool-artifacts/context-gc, since OKF
+     * memory represents durable cross-session knowledge, not a per-session capture). Not
+     * yet user-configurable -- see the memory-retrieval settings doc comment.
+     */
+    private _memoryOkfDir;
+    /**
+     * Session-scoped, read-only local OKF memory provider. Lazily created ONLY when memory
+     * retrieval is enabled (see `_runMemoryRetrieval`) -- never force-created, so a session
+     * with the setting off never touches `_memoryOkfDir()` at all (no directory access, no
+     * creation; `createOkfMemoryProvider` itself never writes/mkdirs either way).
+     */
+    private _getMemoryOkfProvider;
+    /**
+     * One pass over the current branch, mapping each toolResult's toolCallId to its
+     * persisted session-entry id. Rebuilt every audit pass (O(branch) per turn), so this is
+     * O(n^2) over a long session. Fine at current scale; after the artifact-read fix this is
+     * the next per-turn audit cost to optimize if it ever matters (e.g. cache/incrementally
+     * update instead of a full rebuild).
+     */
+    private _buildSessionEntryIdLookup;
+    /**
+     * Phase 1 observe-only audit pass (see context/context-audit.ts): converts live
+     * toolResult messages into ContextItems and runs the existing retention/hard-constraint
+     * evaluators over them, storing the latest deterministic report for tests/debugging.
+     * Read-only with respect to messages, the transcript, and artifact references -- uses
+     * `_toolArtifactStore` (the field), not `_getToolArtifactStore()` (the getter), so a
+     * session that never packed anything doesn't force-create a store/dir just to audit.
+     * Never throws into a live turn: any failure degrades to an empty report.
+     */
+    private _runContextAudit;
+    /**
+     * Read-only inspection of the context audit. With `messages`, recomputes fresh against
+     * the given array (still no mutation of messages/transcript/artifact refs); without,
+     * returns the last report computed during a real transform pass.
+     */
+    getContextAuditReport(messages?: AgentMessage[]): ContextAuditReport;
+    /**
+     * Observe-first shadow/planning pass (see context/context-prompt-policy.ts): re-shapes
+     * the audit report into a per-item policy plan whose `appliedAction` is always
+     * "keep_raw" -- this never enforces anything, it only records what the policy engine
+     * would say. Never throws into a live turn: any failure degrades to an empty report.
+     */
+    private _runPromptPolicyPlanning;
+    /**
+     * Read-only inspection of the shadow policy plan. With `messages`, recomputes fresh
+     * (audit + plan) against the given array; without, returns the last plan computed
+     * during a real transform pass. Never mutates messages/transcript/artifact refs.
+     */
+    getPromptPolicyReport(messages?: AgentMessage[]): PromptPolicyShadowReport;
+    /**
+     * Report-only correlation between the shadow plan just computed this turn and what the
+     * legacy context-gc pass actually packed. Runs after `_applyContextGc()` has already
+     * produced its report; never influences context-gc itself. Never throws into a live
+     * turn: any failure degrades to an empty correlation.
+     */
+    private _correlatePromptPolicyWithContextGc;
+    /** Read-only inspection of the latest shadow-plan/legacy-gc correlation, for tests/debugging. */
+    getPromptPolicyGcCorrelation(): PromptPolicyGcCorrelationReport;
+    /**
+     * First enforcement pilot (see context/context-prompt-enforcement.ts): opt-in,
+     * default-disabled stub-in-place of stale artifact-backed tool_output results in the
+     * provider-visible message array only. Runs on `messages` AFTER context-gc has already
+     * produced its own result, so legacy context-gc's own packing/reporting is completely
+     * unaffected by this pass -- it only ever acts on messages gc left untouched this turn.
+     * Never throws into a live turn: any failure degrades to returning `messages` unchanged.
+     */
+    private _runPromptEnforcement;
+    /** Read-only inspection of the latest prompt-enforcement report, for tests/debugging. */
+    getPromptEnforcementReport(): PromptEnforcementReport;
+    private _runMemoryRetrieval;
+    /** Read-only inspection of the latest memory-retrieval report, for tests/debugging. */
+    getMemoryRetrievalReport(): MemoryRetrievalReport;
+    /**
+     * Bounded prompt-surfacing pilot for local memory evidence (see
+     * context/memory-prompt-block.ts): opt-in, default disabled, and gated on TWO settings
+     * (`enabled` AND `includeInPrompt`) plus a non-empty `report.contextItems` -- the first
+     * two are belt-and-suspenders on top of the fact that `_runMemoryRetrieval` already
+     * leaves `contextItems` empty whenever `enabled` is false, regardless of
+     * `includeInPrompt`. Reuses the `report` this pass's `_runMemoryRetrieval` call already
+     * computed -- never re-queries the provider here.
+     *
+     * Appends exactly one ephemeral `custom`/"memory_evidence" message wrapped by
+     * `wrapUntrustedText` (the same nonce-fenced boundary + always-on system-prompt rule
+     * used for other untrusted content) to the END of `messages`. This is purely additive
+     * (never mutates an existing message) and purely transient: `messages` here is the
+     * array about to be sent to the provider, not `this.agent.state.messages` or anything
+     * persisted via `sessionManager` -- so the injected message can never reach the
+     * transcript, regardless of how many times this pass runs.
+     *
+     * Also records a `MemoryPromptInclusionReport` (context/memory-diagnostics.ts) at each
+     * branch below, for context_audit's diagnostic surface only -- this is pure bookkeeping
+     * alongside the existing branches, not a new branch/condition: the messages returned
+     * are unchanged by this recording.
+     */
+    private _maybeAppendMemoryEvidenceBlock;
+    /** Read-only inspection of the latest memory-prompt-inclusion decision, for tests/debugging and context_audit. */
+    getMemoryPromptInclusionReport(): MemoryPromptInclusionReport;
+    /**
+     * Combines the already-stored, no-arg latest reports (never re-queries the provider or
+     * touches the OKF directory) into the safe, allow-list-projected shape context_audit
+     * exposes. See context/memory-diagnostics.ts for why this projection is allow-list
+     * based rather than a spread-then-delete of the raw report.
+     */
+    private _getMemoryAuditDiagnostics;
     private _applyContextGc;
+    /**
+     * Reference-release + cleanup lifecycle: once context-gc has packed a grep/find tool
+     * result out of the live prompt (the message is no longer current/active working
+     * context -- see contracts-and-retention.md's "ephemeral"/"expired" retention
+     * classes), release the pack-time reference `packToolOutput()` registered for it, and
+     * opportunistically reclaim now-unreferenced artifacts. This is the other half of the
+     * D2b-1 gate: artifacts were being registered but never released, so they accumulated
+     * for the life of the session.
+     *
+     * `record.toolCallId` (from context-gc's packed record) is exactly the holder id
+     * `packToolOutput()` used when it called `addReference()` -- both trace back to the
+     * same tool call's id -- so no separate bookkeeping is needed to find it.
+     */
+    private _releaseGcPackedArtifactReferences;
     getContextGcReport(messages?: AgentMessage[]): ContextGcReport;
     private _estimateCurrentContextTokens;
     private _installAgentToolHooks;
@@ -449,6 +678,16 @@ export declare class AgentSession {
      * Only tools in the registry can be enabled. Unknown tool names are ignored.
      * Also rebuilds the system prompt to reflect the new tool set.
      * Changes take effect on the next agent turn.
+     *
+     * artifact_retrieve is auto-activated as a companion whenever grep or find ends up
+     * in the resulting active set and artifact_retrieve is registered (i.e. not excluded/
+     * blocked/outside an allowlist -- the registry itself is built with that same filter,
+     * so registry presence already tracks "allowed"). This is enforced here, not just in
+     * the settings/profile refresh flow, because this method is a public, extension-
+     * exposed activation path (`setActiveTools`) on its own: without this, grep/find could
+     * end up active while still being handed an artifact store (gated on "allowed" in
+     * `_buildRuntime`) with no active tool able to resolve the resulting
+     * "Full output: artifact tool-output:<id>" handle.
      */
     setActiveToolsByName(toolNames: string[]): void;
     /** Whether compaction or branch summarization is currently running */
@@ -488,7 +727,11 @@ export declare class AgentSession {
     private _buildAutonomyPrompt;
     private _rebuildSystemPrompt;
     private _runAgentPrompt;
+    private _isModelAvailableAndAuthed;
+    private _resolveModelRouterTurnRoute;
     private _resolveModelRouterModelForIntent;
+    private _resolveConfiguredTierModel;
+    private _resolveModelRouterTurnRouteJudged;
     private _resolveModelRouterTurnModel;
     getModelRouterStatus(formatLabel?: (label: string) => string): string;
     private _runAgentPromptWithModelRouter;
@@ -863,6 +1106,118 @@ export declare class AgentSession {
     getSpawnedUsage(): SpawnedUsageTotals;
     getDailyUsageTotals(now?: Date): DailyUsageTotals;
     getDailyUsageBreakdown(formatLabel?: (label: string) => string, now?: Date): string;
+    /**
+     * Save a snapshot of the goal state to the session log.
+     *
+     * @returns the id of the appended custom entry
+     */
+    saveGoalStateSnapshot(state: GoalState): string;
+    /**
+     * Retrieve the latest valid goal state snapshot from the session log.
+     */
+    getGoalStateSnapshot(): GoalState | undefined;
+    /**
+     * Save a snapshot of the evidence bundle to the session log.
+     *
+     * @returns the id of the appended custom entry
+     */
+    saveEvidenceBundleSnapshot(bundle: EvidenceBundle): string;
+    /**
+     * Retrieve the latest valid evidence bundle snapshot from the session log.
+     */
+    getEvidenceBundleSnapshot(): EvidenceBundle | undefined;
+    getEvidenceBundleSnapshots(): EvidenceBundle[];
+    /** Live lane records tracked by this process (running and terminal). */
+    getLaneRecords(): LaneRecord[];
+    saveWorkerResultSnapshot(result: WorkerResult): string;
+    getWorkerResultSnapshots(): WorkerResult[];
+    saveLearningDecisionSnapshot(decision: LearningDecision): string;
+    getLearningDecisionSnapshots(): LearningDecision[];
+    getGoalRuntimeSnapshot(settings: GoalRuntimeSnapshotSettings): GoalRuntimeSnapshot;
+    private _clearGoalAutoContinueTimer;
+    private _scheduleGoalAutoContinueFromIdle;
+    private _runScheduledGoalAutoContinue;
+    private _clearResearchLaneTimer;
+    /**
+     * Derive the research demand from durable goal state: an active goal with open requirements,
+     * deduplicated against the latest persisted bundle so the same requirement set is never
+     * researched twice (the query is deterministic, so dedupe survives session reload).
+     */
+    private _buildResearchLaneDemand;
+    /**
+     * Idle trigger for the autonomous research lane (mirrors {@link _scheduleGoalAutoContinueFromIdle}).
+     * All skips are recorded in `_lastResearchLaneSkipReason` and surfaced via diagnostics — the lane
+     * informs, it never prompts or blocks the foreground.
+     */
+    private _scheduleResearchLaneFromIdle;
+    private _runScheduledResearchLane;
+    /**
+     * Capability profile derived from the CURRENT session model's own metadata (context window),
+     * honoring the modelCapability.mode setting ("off" disables, a class name forces).
+     */
+    getModelCapabilityProfile(): ModelCapabilityProfile;
+    /** Capability profile for a specific lane model (lane budgets scale to the lane model's window). */
+    private _laneCapabilityProfile;
+    /**
+     * Resolve the model for a background lane. Lanes are shipped BY this session, so they inherit
+     * the session's own model unless a lane-specific model is explicitly configured — a single-model
+     * setup (e.g. one local open model) runs its lanes on that same model. An explicitly configured
+     * pattern that cannot resolve/authenticate is a visible skip, not a silent fallback.
+     */
+    private _resolveLaneModel;
+    /**
+     * Resolve what a lane ships with. Precedence: explicit lane model setting, then the lane
+     * profile's model (a shipped profile with a model MUST be obeyed — unresolvable is a visible
+     * skip, never a fallback), then generic inheritance of the session model.
+     */
+    private _resolveLaneShipment;
+    /** UAC tool grants from a shipped lane profile, recorded on the lane envelope. */
+    private _laneProfileToolGrants;
+    /** Stripped research envelope — never the foreground/architect envelope. */
+    private _buildResearchLaneEnvelope;
+    /**
+     * Run one bounded, read-only research pass and persist its results: evidence bundle snapshot,
+     * terminal lane record, and spawned-usage cost report (single-hop invariant, idempotent on the
+     * lane's reportId). Explicit calls (e.g. `/autonomy research`) express user intent and bypass the
+     * enabled/mode/dedupe gates the idle scheduler enforces; budget and capability gates always apply.
+     */
+    runResearchLaneOnce(request?: {
+        query?: string;
+        context?: string;
+        goalId?: string;
+    }): Promise<ResearchLaneRunOutcome>;
+    /**
+     * Run one bounded scout-worker delegation: build a WorkerRequest with a stripped read-only
+     * envelope, execute it as an isolated completion on a cheap lane, validate the result via
+     * {@link validateWorkerResult} before acceptance, and persist result + lane record + spawned
+     * usage (idempotent per-lane reportId). Consumed by the `delegate` tool.
+     */
+    runWorkerDelegationOnce(request: {
+        instructions: string;
+        /** Model-provided replacement for the worker role prompt (the level-0 core always remains). */
+        systemPrompt?: string;
+    }): Promise<WorkerDelegationRunOutcome>;
+    /**
+     * Probe a candidate model against the subagent contracts (research/worker/judge/search/
+     * tool-call surfaces) via {@link runModelFitnessProbe}. The model must resolve and
+     * authenticate; every probe call runs as an isolated completion on that model, and probe
+     * spend is reported through spawned-usage accounting.
+     */
+    runModelFitness(args: {
+        model: string;
+        trials?: number;
+    }): Promise<{
+        started: true;
+        model: string;
+        report: ModelFitnessReport;
+    } | {
+        started: false;
+        skipReason: string;
+    }>;
+    /** Fitness reports persisted for THIS host (measured evidence for architect/profile decisions). */
+    getStoredFitnessReports(): StoredFitnessReport[];
+    continueGoalOnce(options: GoalContinuationOnceOptions): Promise<GoalContinuationOnceResult>;
+    continueGoalLoop(options: GoalContinuationLoopOptions): Promise<GoalContinuationLoopResult>;
     /**
      * Run a one-shot LLM completion fully ISOLATED from the main session — the load-bearing
      * primitive for the native reflection engine (adaptive-agent design §6c/§7).
@@ -894,6 +1249,17 @@ export declare class AgentSession {
         /** Stable id so a duplicate scheduling/retry of the same pass can't double-count its cost. */
         reportId?: string;
     }): Promise<ReflectionResult | null>;
+    getLearningAuditRecords(): LearningAuditRecord[];
+    /**
+     * Roll back one applied durable learning change by executing the inverse operation recorded in
+     * its audit record (memory ops run through the same bundled memory-tool path as the original
+     * apply; promoted skills are archived). Appends a linked "rollback" audit record on success so
+     * the change history stays complete and a change cannot be rolled back twice.
+     */
+    rollbackLearningWrite(auditId: string): Promise<{
+        ok: boolean;
+        reason: string;
+    }>;
     private _applyReflectionWrite;
     /**
      * R7: write a reflection-promoted skill as `<agentDir>/skills/<name>/SKILL.md` so it loads like any
@@ -920,6 +1286,16 @@ export declare class AgentSession {
      * @returns Text content, or undefined if no assistant message exists
      */
     getLastAssistantText(): string | undefined;
+    getAutonomyStatusSnapshot(): AutonomyStatusSnapshot;
+    /**
+     * Aggregate an effectiveness/autonomy dashboard: what Pi has actually been doing (recent
+     * route choices, latest gate outcome, cost, and any research/delegation/learning/goal
+     * activity). Read-only — combines existing session-log getters, never mutates state or
+     * recomputes a route/gate decision.
+     */
+    getAutonomyDiagnosticSnapshot(options?: {
+        maxEntriesPerFamily?: number;
+    }): AutonomyDiagnosticSnapshot;
     createReplacedSessionContext(): ReplacedSessionContext;
     /**
      * Check if extensions have handlers for a specific event type.