@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/engine/engine.d.ts

@@ -1,22 +1,24 @@
 /**
  * Engine — the main facade that wires all components together.
  */
-import type { LLMConfig, StreamCallback } from "../types.js";
+import type { Message, SessionWorkspace } from "../types.js";
 import { ToolRegistry } from "../tool-system/registry.js";
 import { type BuiltinToolFn } from "../tool-system/builtin/index.js";
+import { type LiveChildState } from "../tool-system/builtin/agent-registry.js";
 import { HookRegistry } from "../hooks/registry.js";
-import { type GoalConfig, type GoalExtension } from "./goal.js";
+import { type GoalConfig, type GoalExtension } from "../goal/lifecycle.js";
 import { type CompactStrategy } from "../context/manager.js";
-import { SessionManager } from "../session/session-manager.js";
+import { SessionManager, type ForkSessionOptions, type ForkSessionResult, type SummaryForkOptions } from "../session/session-manager.js";
+import type { SessionMessageRouter } from "../session/session-message.js";
 import type { AskUserFn } from "../tool-system/builtin/ask-user.js";
-import type { CapabilityOverride } from "../settings/schema.js";
+import type { CapabilityOverride, CapabilityOverrides } from "../settings/schema.js";
 import { type FeatureFlagName } from "../settings/feature-flags.js";
 import type { ToolContext } from "../tool-system/context.js";
-import { type SandboxBackend } from "../tool-system/sandbox/index.js";
 import { ModelPool, type ModelEntry } from "../llm/model-pool.js";
 import { AgentDefinitionRegistry } from "../agent/agent-definition-registry.js";
 import { EngineRuntime } from "./runtime.js";
-import type { InputAttachmentMeta } from "../protocol/types.js";
+import { type EngineRunOptions } from "./run-types.js";
+import type { InputAttachmentMeta } from "../types.js";
 /**
  * Build ScanOptions.compatFileNames from the user's instruction compat toggles.
  * Primary file name stays hard-wired to CODESHELL.md (not exposed). Turning a
@@ -34,7 +36,7 @@ export interface EnqueueSteerResult {
     accepted: boolean;
     id: string;
 }
-export { diskDefaultsFrom, type DiskDefaultPatch } from "../settings/disk-defaults.js";
+export { diskDefaultsFrom, type DiskDefaultPatch } from "./disk-defaults.js";
 /**
  * Resolve the LLM config for a spawned child Engine.
  * - `modelKey` set + present in pool → that model's config (pure entry-derived
@@ -47,30 +49,14 @@ export { diskDefaultsFrom, type DiskDefaultPatch } from "../settings/disk-defaul
  * Engine directly via EngineConfig.clientDefaults — they do not flow through
  * this helper because they're not part of LLMConfig anymore.
  */
-export declare function resolveChildLlm(modelKey: string | undefined, pool: ModelPool | undefined, parentLlm: LLMConfig): LLMConfig;
+export { resolveChildLlm, resolveChildToolScope } from "./subagent-spawner.js";
+export { resolveRunCwd } from "./run-workspace.js";
 /**
  * Load reusable sub-agent role definitions, merging:
  *   1. project-level  <cwd>/.code-shell/agents/*.md   (ships built-ins)
  *   2. user-level     ~/.code-shell/agents/*.md        (user wins on name)
  * Names in `disabledAgents` are filtered out so the LLM never sees them.
  */
-/**
- * Resolve the working directory for a run. Precedence for legacy sessions:
- *   options.cwd  >  resumed session's state.cwd  >  config.cwd  >  process.cwd()
- *
- * The session-cwd tier is what stops a project-bound session from being
- * resumed against the wrong directory: when a host omits options.cwd (e.g. its
- * sidebar repo selection drifted to null), the session's own recorded cwd is
- * recovered so the engine still loads THAT project's agents/settings/memory,
- * not whatever process.cwd() happens to be. Pure so the precedence is testable
- * without standing up an Engine.
- */
-export declare function resolveRunCwd(args: {
-    optionCwd?: string;
-    sessionCwd?: string;
-    configCwd?: string;
-    processCwd: string;
-}): string;
 export declare function loadAgentDefinitionsForCwd(cwd: string, disabledAgents?: string[], disabledPlugins?: string[]): AgentDefinitionRegistry;
 /**
  * #7: apply a project's per-turn builtin capability override to a tool list.
@@ -90,16 +76,25 @@ export declare function applyBuiltinOverrideVisibility<T extends {
  * - `allowlist` undefined → inherit parent enabled/disabled, always with the
  *   nested-agent tools forced into `disabled` (no grandchildren).
  */
-export declare function resolveChildToolScope(allowlist: string[] | undefined, parentDisabled: string[] | undefined, parentEnabled: string[] | undefined): {
-    enabled?: string[];
-    disabled: string[];
-};
 export declare class Engine {
     private config;
     private preset;
+    /** Capability-free seed owned by the runtime/host; never mutated by an Engine. */
+    private runtimeToolRegistry;
+    /** Engine-local view containing only this Engine's capability modules. */
     private toolRegistry;
+    private readonly capabilities;
+    private readonly toolCatalog;
+    private readonly toolGuards;
+    /** Per-turn dynamic definition rewriters contributed by builtin exposures. */
+    private readonly toolRewriters;
+    /** Named per-run behavior profiles (core defaults + config + extensions). */
+    private readonly behaviorProfiles;
+    private readonly capabilityPromptSections;
+    private readonly capabilityDynamicContextProviders;
     private hooks;
     private sessionManager;
+    private sessionMessageRouter;
     private mcpManager;
     private modelPool;
     /**
@@ -121,19 +116,10 @@ export declare class Engine {
     private agentDefsCache?;
     /** Shared resources supplied at construction (adapter pattern — null when self-constructed). */
     readonly runtime: EngineRuntime | null;
-    private readonly sandboxCache;
-    /** Active permission mode for this Engine instance. */
-    permissionMode: NonNullable<EngineConfig["permissionMode"]>;
-    /** True when permissionMode === "plan". */
-    planMode: boolean;
+    private readonly runEnvironmentResolver;
+    private readonly auxiliaryPipeline;
+    private readonly permissionController;
     private settingsManager;
-    /**
-     * Cached auxiliary-task LLM client, keyed by the models[].key it was built
-     * from. Background calls (memory extraction, auto-dream) reuse it across
-     * runs so we don't redo the provider handshake every session. Invalidated
-     * implicitly: a changed auxModelKey produces a different cache key.
-     */
-    private auxClientCache?;
     private lastContextManager;
     private lastMessages;
     private lastSessionId;
@@ -154,7 +140,7 @@ export declare class Engine {
      * LLM response arrives.
      */
     private ctxOverheadBySid;
-    private lastCacheReadBySid;
+    private promptCacheDiagnostics;
     /**
      * Step-gap steering queue (per sessionId, in-memory). Host pushes user
      * messages here via enqueueSteer while a run is in flight; the turn loop
@@ -164,7 +150,6 @@ export declare class Engine {
      * multiple Engines don't interfere and it stays cleanly extractable.
      */
     private steerQueueBySid;
-    private activePermission;
     /**
      * The TurnLoop of the in-flight run(), exposed so extendGoalRun() can bump a
      * running goal's turn/budget ceilings mid-run (TODO 3.1). Null when idle.
@@ -176,18 +161,34 @@ export declare class Engine {
      * otherwise keep re-blocking the stop). Null when no goal run is active.
      */
     private activeGoalHook;
+    /** Whether activeGoalHook is currently registered (pause detaches it). */
+    private activeGoalHookAttached;
+    /** Mutable goal view consumed by the running judge after edits/resume. */
+    private activeRuntimeGoal;
+    /** Mutable terminal snapshot kept in sync with a mid-run objective edit. */
+    private activePersistedRunGoal;
     /**
      * The in-flight run's session bundle, held so clearGoal() can wipe the goal
      * on the SAME instance the run loop is persisting each turn — not a fresh
      * detached copy from resume(). Without this, a mid-run 清除 clears disk, but
      * the still-running loop's next saveState(bundle.state) resurrects the goal
-     * (bundle.state.activeGoal was never dropped). A never-completing goal run
+     * (bundle.state.goalLifecycle was never rebased). A never-completing goal run
      * (judge keeps returning not_met → continueSession) stays live for a long
      * time, so this write-back race is the norm, not an edge case, for such runs.
      * Single-valued like activeTurnLoop — one top-level run per engine at a time.
      * Null when idle; set at run start, cleared in run's finally.
      */
     private activeRunSession;
+    /**
+     * Same-instance run guard. Engine owns single-valued live controls and one
+     * HookRegistry, so a second run must not enter until the first has completed
+     * all state persistence and end hooks. Cross-instance/process whole-state
+     * writers are additionally fenced by SessionManager's persisted revision CAS.
+     */
+    private runInProgress;
+    private agentControlStateListener?;
+    private agentDirectionsDeliveredListener?;
+    /** Permission update requested while runInProgress. Applied in run() finally. */
     /** Public accessor so UI/clients can read the resolved per-model window. */
     get maxContextTokens(): number;
     private resolveMaxContextTokens;
@@ -251,12 +252,22 @@ export declare class Engine {
      * Must be called before run().
      */
     registerCustomTool(definition: import("../types.js").RegisteredTool, executor: BuiltinToolFn): void;
+    /** Dispatch a host-installed capability query without teaching core its name. */
+    queryCapability(type: string, params?: Readonly<Record<string, unknown>>): Promise<{
+        handled: false;
+    } | {
+        handled: true;
+        data: unknown;
+    }>;
     /**
      * Inject the askUser handler after construction. Used by AgentServer
      * to wire its protocol-backed askUser into an Engine that was created
      * before the server existed (chicken-and-egg: server takes engine in ctor).
      */
     setAskUser(fn: AskUserFn | undefined): void;
+    /** Internal child-runtime seam used by the single-writer supervisor. */
+    setAgentControlStateListener(listener: ((state: LiveChildState) => void) | undefined): void;
+    setAgentDirectionsDeliveredListener(listener: ((envelopeIds: string[]) => void) | undefined): void;
     /**
      * Inject the browser automation bridge after construction (same chicken-and-egg
      * as setAskUser: the desktop host builds the bridge — which drives a webview —
@@ -266,6 +277,10 @@ export declare class Engine {
     setBrowserBridge(bridge: import("../tool-system/browser-bridge.js").BrowserBridge | undefined): void;
     /** Inject the host-backed workspace bridge after construction. */
     setWorkspaceBridge(bridge: import("../tool-system/workspace-bridge.js").WorkspaceBridge | undefined): void;
+    /** Inject the host-backed panel discovery/focus bridge after construction. */
+    setPanelBridge(bridge: import("../tool-system/panel-bridge.js").PanelHostBridge | undefined): void;
+    /** Inject the host router used by SendMessageToSession. */
+    setSessionMessageRouter(router: SessionMessageRouter | undefined): void;
     /**
      * Queue a user message to be spliced into the in-flight run for `sessionId`
      * at the next turn-loop step boundary — the 不打断 steering path (vs cancel +
@@ -298,6 +313,8 @@ export declare class Engine {
      * in-process AgentServer to decide whether to wire an interactive askUser.
      */
     isHeadless(): boolean;
+    get permissionMode(): NonNullable<EngineConfig["permissionMode"]>;
+    get planMode(): boolean;
     /**
      * Probe whether a session already exists on disk (its state/transcript dir is
      * present). Used by the protocol server to distinguish "resume an existing
@@ -306,73 +323,136 @@ export declare class Engine {
      * against a blank session. A stat probe, not a load.
      */
     sessionExistsOnDisk(sessionId: string): boolean;
-    /**
-     * Run a task from start to finish.
-     */
-    run(task: string, options?: {
-        cwd?: string;
-        onStream?: StreamCallback;
-        signal?: AbortSignal;
-        sessionId?: string;
-        /**
-         * Goal mode for this run: the engine registers a GoalStopHook so the
-         * turn loop runs until the session model judges this goal met. Falls
-         * back to config.goal. Orthogonal to permissionMode. Accepts a raw
-         * string or a full GoalConfig; normalized once at the run boundary.
-         */
-        goal?: string | GoalConfig;
-        /**
-         * Marks this turn's task as a SYNTHETIC system-reminder injection (e.g. a
-         * background-job completion notification the server re-injects to wake an
-         * idle session) rather than the user's own input. The task is still sent
-         * to the model as a `role:"user"` message, but it is persisted with an
-         * `injected` flag so the disk reader skips rendering it as a user bubble
-         * on replay (matching the live UI, which shows only the assistant reply).
-         */
-        injected?: boolean;
-        /** Stable id for this user-intent, used to make duplicate submits idempotent. */
-        clientMessageId?: string;
-        /** Structured input attachments. Legacy `<codeshell-image>` blocks remain supported. */
-        attachments?: InputAttachmentMeta[];
-    }): Promise<EngineResult>;
-    /**
-     * Run the end-of-session memory pipeline as a fire-and-forget background
-     * task. Extracts durable memories from the transcript, saves a session
-     * summary, and conditionally triggers auto-dream consolidation.
-     */
-    /**
-     * Resolve the LLM client for background/auxiliary work (memory extraction,
-     * auto-dream). When settings.defaults.auxText names a valid pool model, build
-     * (and cache) a dedicated client for it so per-turn book-keeping runs on a cheap
-     * fast model instead of the expensive primary. Falls back to `fallback` (the
-     * active run's client) when unset, unknown, or on any build failure — aux
-     * work is best-effort and must never break a run.
-     */
-    /**
-     * Build the SummarizeFn used for context compaction. Extracted so both the
-     * run path and forceCompact share one definition of the summarization call.
-     */
+    forkSession(sourceSessionId: string, options?: ForkSessionOptions): ForkSessionResult;
+    selectContextPackage(sourceSessionId: string, range: {
+        fromEventId: string;
+        toEventId: string;
+    }): ReturnType<SessionManager["selectContextPackage"]>;
+    createSummaryFork(sourceSessionId: string, options: SummaryForkOptions): ForkSessionResult;
+    /** Summarize a selected transcript package using the configured aux tier. */
+    summarizeContextPackage(messages: Message[], signal?: AbortSignal, sourceSessionId?: string): Promise<{
+        summary: string;
+        estimatedTokens: number;
+    }>;
+    /** Restore a cold Engine's configured model from persisted source state without resetting usage. */
+    restoreSessionModel(sessionId: string): void;
+    /**
+     * Run a task from start to finish. Rejects immediately when this Engine
+     * instance already has a run in progress; hosts that want queueing own that
+     * policy (for example ChatSession's FIFO queue).
+     */
+    run(task: string, options?: EngineRunOptions): Promise<EngineResult>;
+    /**
+     * Resolve the run's active behavior profile. A profile bound to the
+     * persisted session kind wins (so e.g. a resumed pet session keeps the safe
+     * profile even when the host omits behaviorMode); otherwise the explicit
+     * behaviorMode names a registered profile directly. Explicit unknown modes
+     * and non-work session kinds without an owning profile fail closed: silently
+     * falling back to an unrestricted run would turn a missing extension into a
+     * permission-boundary bypass.
+     */
+    private resolveBehaviorProfile;
+    private runExclusive;
+    /** A receipt write failure must not turn an already finalized model result
+     * into a second synthetic failure (or reject the Engine.run contract). */
+    private appendClientRunReceipt;
+    /**
+     * Terminal success path: forward to {@link finalizeRunSuccess} with the
+     * engine-bound persistence / memory / hook closures filled in. Extracted from
+     * the {@link runExclusive} skeleton so the terminal-state assembly reads as a
+     * single call; behavior is unchanged.
+     */
+    private finalizeRun;
+    /**
+     * Build the stream callback that wraps the caller's `onStream`: it snapshots
+     * TodoWrite `task_update` events for TaskGuard and persists `goal_progress`
+     * events to the transcript before delegating. Extracted verbatim from the
+     * {@link runExclusive} skeleton; the todo buffer and (not-yet-open) session
+     * are reached through the `setLatestTodos` / `getSession` accessors.
+     */
+    private buildWrappedOnStream;
+    /**
+     * Run the turn loop once, apply its goal termination, and — for a top-level
+     * headless run only — drain background sub-agents before resolving. Extracted
+     * verbatim from the body of the {@link runExclusive} try block; the cleanup
+     * `finally` stays in the skeleton so the run-scoped hook/loop teardown is
+     * guaranteed regardless of how this method returns or throws.
+     */
+    private runTurnLoopWithHeadlessDrain;
+    /**
+     * Stamp the resolved session identity and session-scoped side-effect sinks
+     * onto the run's {@link ToolContext}, now that the session bundle is open.
+     * Extracted verbatim from the {@link runExclusive} skeleton.
+     */
+    private stampRunToolContext;
+    /** Attach a closed-set, host-routed Session message sender to this run. */
+    private attachSessionMessageService;
+    /**
+     * Await the parallel prompt/context assembly (LLM client handshake, system
+     * prompt, dynamic + user context messages), splice the hook-injected and
+     * context messages into `messages`, publish this run's last-session snapshot,
+     * and prime the {@link ContextManager}'s transcript path + replacement state.
+     * Extracted verbatim from the {@link runExclusive} skeleton.
+     */
+    private assembleRunPrompts;
+    /**
+     * Seed the run's {@link ContextManager}, emit the early `session_started`
+     * event, replay the last TodoWrite snapshot on resume, kick off the LLM client
+     * handshake, and build the permission-gated {@link ToolExecutor}. Extracted
+     * verbatim from the {@link runExclusive} skeleton; the todo snapshot is read
+     * and written through the `getLatestTodos` / `setLatestTodos` accessors so the
+     * outer wrapped-onStream and TaskGuard keep observing the same buffer.
+     */
+    private wireRunContextAndPermission;
+    /**
+     * Resolve the run sandbox, construct the child sub-agent spawner (the sole
+     * `new Engine(...)` call path, kept in engine.ts so the protocol bypass guard
+     * stays satisfied), and assemble the per-run {@link ToolContext}. Extracted
+     * verbatim from the {@link runExclusive} skeleton; the session bundle is read
+     * lazily via `getSession` because it is opened after this wiring runs.
+     */
+    private wireRunSandboxToolContext;
+    /**
+     * Wire every run-scoped dependency the turn loop needs: usage accounting +
+     * summarizer, the {@link ModelFacade}, the file-history hook, the
+     * `on_agent_start` hook, goal resolution / arming, the {@link TurnLoop} itself,
+     * and the goal-termination applier. Extracted verbatim from the
+     * {@link runExclusive} skeleton; the goal slots, judge-context buffer and usage
+     * baseline are fully local here — only the values the try/finally + finalize
+     * phases consume cross back out.
+     */
+    private wireRunLoop;
+    /**
+     * Record the session start and fire the once-per-run `on_session_start` and
+     * per-turn `user_prompt_submit` / `agent_direction_submit` hooks, applying any
+     * `updatedPrompt` rewrite in place on `messages`. Extracted verbatim from the
+     * {@link runExclusive} skeleton; returns the combined hook-injected messages
+     * for {@link assembleRunMessages}.
+     */
+    private runSessionStartHooks;
+    /**
+     * Resolve goal visibility, disabled skill/plugin lists, build the
+     * {@link PromptComposer}, connect MCP, and assemble the visibility-filtered
+     * tool defs for this run. Extracted verbatim from the {@link runExclusive}
+     * skeleton; the intermediate visibility/disabled/mcp values are fully local to
+     * this method — only the composer and tool defs cross back out.
+     */
+    private wireRunTooling;
+    /**
+     * Assemble the run-scoped {@link TurnLoop} (its dependency object + option
+     * object) from the per-run locals gathered in {@link runExclusive}. Extracted
+     * verbatim from the orchestration skeleton so `runExclusive` stays a readable
+     * sequence of phase calls; the buffered-compaction `let` lives entirely inside
+     * here now, and the only value crossing back out is the goal-judge context,
+     * published through the `publishGoalJudgeContext` callback.
+     */
+    private buildTurnLoop;
     private buildSummarizeFn;
     private resolveAuxClient;
     private runMemoryPipeline;
-    /**
-     * Drive the auto-dream tool-call loop.
-     *
-     * Runs the LLM with a whitelisted subset of memory tools (MemoryList,
-     * MemoryRead, MemorySave, MemoryDelete). The loop is intentionally small
-     * and offline:
-     *   - No streaming, no UI events — runs in the background after a session.
-     *   - No permission prompts — UI isn't attached, so we hard-reject any
-     *     attempt to Save/Delete in the "user" scope before dispatching. Dream
-     *     scope is the LLM's workspace and goes through freely.
-     *   - Capped at MAX_TURNS LLM round-trips and MAX_WRITES total
-     *     mutations to bound damage on misbehavior.
-     *
-     * Returns true if the loop ran (with or without writes); false if we
-     * bailed before the first LLM call (e.g. registry missing the tools).
-     */
-    private runDreamLoop;
     getToolRegistry(): ToolRegistry;
+    /** Registry suitable for constructing EngineRuntime; excludes local capabilities. */
+    getRuntimeToolRegistry(): ToolRegistry;
     /**
      * Switch the active model by pool key. Takes effect on the next run() call.
      * Returns the new model entry.
@@ -382,7 +462,9 @@ export declare class Engine {
      * only live in memory and every restart reverts to the previously persisted
      * defaults.text.
      */
-    switchModel(key: string): ModelEntry;
+    switchModel(key: string, opts?: {
+        persist?: boolean;
+    }): ModelEntry;
     /**
      * Zero the legacy/model-scoped token/cache usage window on disk. The
      * whole-session cumulative counters are intentionally left alone.
@@ -403,6 +485,23 @@ export declare class Engine {
     getCurrentModel(): string;
     getHookRegistry(): HookRegistry;
     getSessionManager(): SessionManager;
+    /**
+     * Apply a field-level disk update and rebase this Engine's matching live
+     * bundle onto the returned revision so its next whole-state CAS can proceed.
+     */
+    private updatePersistedSessionState;
+    /**
+     * Adopt the exact persisted snapshot that won a Goal-control CAS without
+     * discarding counters which the current run has advanced since its previous
+     * heartbeat. Merely copying the new stateRevision is unsafe: the next
+     * whole-state save would then be allowed to publish stale title/workspace
+     * metadata over a concurrent field-level writer.
+     */
+    private rebaseActiveRunAfterGoalUpdate;
+    private persistGoalTerminal;
+    private persistGoalTerminalOutcome;
+    private persistFinalRunState;
+    private persistRunProgress;
     getConfig(): EngineConfig;
     /**
      * Config hot-reload "layer 2": merge a disk-default config patch into this
@@ -426,7 +525,7 @@ export declare class Engine {
      * the main user-visible preset effect and it IS hot. The toolRegistry's
      * builtin tool SET, however, is ctor-frozen (and may be shared via runtime):
      * it is NOT rebuilt here. So a preset change that alters the builtin tool set
-     * (e.g. general → terminal-coding adds LSP/Brief) only takes effect on the
+     * (e.g. switching to a capability-contributed preset adds tools) only takes effect on the
      * next session restart; we log a warning when that case is detected.
      *
      * disk-default-vs-slice caveat (#8): the patch carries pure DISK-default
@@ -453,28 +552,51 @@ export declare class Engine {
      * Read a session's persisted active goal WITHOUT resuming it (cheap — reads
      * only state.json via SessionManager.readActiveGoal). The desktop host calls
      * this on session load to re-surface the goal block + its Cancel button: a
-     * persistent goal lives only in state.activeGoal and is never replayed from
+     * persistent goal lives only in state.goalLifecycle and is never replayed from
      * the transcript, so after a reload of an aborted goal run the UI would
      * otherwise show nothing (the "goal 还在但页面不显示、取消不了" bug). Returns
      * undefined when the session is unknown or has no active goal.
      */
     getGoal(sessionId: string): GoalConfig | undefined;
+    /** True when the current run was built with Goal prompt/tools and can resume in place. */
+    canResumeGoalInPlace(sessionId: string): boolean;
+    /**
+     * Edit or pause/resume a persisted goal. Mid-run edits use the same step-gap
+     * delivery seam as Steer: the current model/tool call is not aborted, and the
+     * updated objective is injected before the next model step. Pausing detaches
+     * the goal judge and stops this run before another model request is started.
+     */
+    updateGoal(sessionId: string, patch: {
+        objective?: string;
+        paused?: boolean;
+        expectedGoalId?: string;
+        expectedRevision?: number;
+    }): GoalConfig | undefined;
     /**
      * Clear a session's persisted active goal (CC `/goal clear`). Works whether
      * the session is idle or its goal run is in flight: it wipes
-     * `state.activeGoal` (so the next bare send won't re-inherit it) and, if a
+     * `state.goalLifecycle` (so the next bare send won't re-inherit it) and, if a
      * goal hook is currently registered for this engine, unregisters it so an
      * in-flight run can stop instead of being re-blocked by the now-cleared goal.
      * Returns true if a goal was actually cleared. Idempotent — clearing a
      * session with no active goal is a no-op returning false.
      */
-    clearGoal(sessionId: string): boolean;
+    clearGoal(sessionId: string, expected?: {
+        goalId?: string;
+        revision?: number;
+    }): boolean;
+    /**
+     * Persist a workspace pointer through the Engine that owns the live bundle.
+     * Host-side workspace actions use this RPC-facing seam so advancing the disk
+     * revision also rebases the active run before its next progress write.
+     */
+    setSessionWorkspace(sessionId: string, workspace: SessionWorkspace): SessionWorkspace | null;
     /**
      * Reset a session's workspace pointer back to its main root. If the session is
      * actively running, mutate that live SessionBundle first so the run's next
      * saveState cannot resurrect a stale worktree pointer.
      */
-    releaseSessionWorkspace(sessionId: string): import("../types.js").SessionWorkspace | null;
+    releaseSessionWorkspace(sessionId: string): SessionWorkspace | null;
     injectContext(sessionId: string, content: string): void;
     /**
      * Force context compaction on a session.
@@ -485,7 +607,38 @@ export declare class Engine {
         after: number;
         strategy: "none (no active session)" | "no compaction needed" | "compacted" | CompactStrategy;
     }>;
-    private stripInjectedContextMessages;
+    /**
+     * Lazily build (or reuse) the ContextManager for a resumed session and wire a
+     * PRIMARY-model summarizeFn onto it. Shared by forceCompact and
+     * archiveTurnRange: both need a summarizer on a session that may have been
+     * resumed-but-never-run (so no run wired one), and both bill compaction usage
+     * against the session.
+     *
+     * The PRIMARY model is used deliberately — automatic background compaction
+     * routes to the cheap aux model, but a user-/host-initiated compaction or
+     * range archival is low-frequency and demands fidelity (a dropped decision =
+     * the conversation "forgets"). Client-construction failure is logged and
+     * swallowed so the caller degrades gracefully (forceSummarize falls back to
+     * snip/window; summarizeRange returns the input untouched).
+     */
+    private prepareContextManagerForSession;
+    /**
+     * Archive a caller-chosen contiguous message-index window `[range.start,
+     * range.end)` of a session into a single anchored summary, leaving everything
+     * outside the window untouched, and cache the result so a later
+     * forceCompact/resume reads the archived history. This is a generic
+     * range-archival facade over ContextManager.summarizeRange — the caller
+     * decides which span to collapse (the range is a half-open message-index
+     * window, matching summarizeRange). Returns token stats before/after; equal
+     * before/after means the window was empty or the summary was rejected.
+     */
+    archiveTurnRange(sessionId: string, range: {
+        start: number;
+        end: number;
+    }): Promise<{
+        before: number;
+        after: number;
+    }>;
     private recordCacheReadDiagnostics;
     private getSettingsManager;
     /**
@@ -493,15 +646,14 @@ export declare class Engine {
      */
     updateConfig(key: string, value: unknown): void;
     /**
-     * Read a settings value by dotted key (e.g. "arena.participants").
+     * Read a settings value by dotted key (e.g. "capabilities.foo.enabled").
      * Returns undefined if any segment is missing.
      */
     readSetting(key: string): unknown;
-    private buildPermissionConfig;
     /**
-     * Switch permission mode at runtime. Takes effect immediately for any
-     * in-flight ToolExecutor (which holds a reference to the same classifier),
-     * and the new mode is used for any subsequent run() calls.
+     * Switch permission mode at runtime. Idle updates apply immediately; busy
+     * updates are committed atomically when the current run settles, so its
+     * classifier and ToolContext retain the immutable start-of-run snapshot.
      * Session-only — does not persist to settings.
      */
     setPermissionMode(mode: NonNullable<EngineConfig["permissionMode"]>): void;
@@ -585,64 +737,7 @@ export declare class Engine {
      * overlays turn-specific fields like sandbox and subAgentSpawner) and
      * by tests that want a ToolContext without a full run() cycle.
      */
-    private resolveSandboxWithoutRuntime;
-    private resolveSandboxConfigForCwd;
-    /**
-     * Build the shell env layered onto the Bash tool / background shells (see
-     * mergeShellEnv). Three user-configured sources, merged lowest → highest:
-     *
-     *   1. project `localEnvironment.env`  — the per-project "local environment"
-     *      panel (DATABASE_URL etc.); the floor, so a project's own panel values
-     *      can be overridden by an explicit top-level `env`.
-     *   2. global top-level `env`          — ~/.code-shell/settings.json; the
-     *      canonical home for API keys (OPENAI_API_KEY) a skill script reads —
-     *      configure once, every project's skills get it.
-     *   3. project top-level `env`         — .code-shell/settings.json; a project
-     *      that wants to override a global key wins.
-     *
-     * Each scope is read UNMERGED so the layering here is the single source of
-     * precedence (getForScope merges nothing). Returns undefined when no layer
-     * contributes a key, so the caller passes it through unchanged for projects
-     * that configure none.
-     *
-     * Sub-agents: a sub-agent is the user's OWN agent doing the user's work
-     * (mirrors Claude Code, where sub-agents inherit the parent environment), so
-     * it now reads the SAME env as the parent. The sub-agent branch is kept as an
-     * explicit seam (`filterSubagentEnv`) rather than removed — a future policy
-     * could narrow what a sub-agent sees (e.g. drop credential secrets) by
-     * changing that one hook; today it passes everything through unchanged.
-     * A no-cwd context still gets nothing (there is genuinely no project to read).
-     *
-     * None of these is filtered through the deny regex (mergeShellEnv): the user
-     * put them there deliberately. The allowlist/deny machinery only guards the
-     * host's process.env from a tainted model exfiltrating it via `env | curl`.
-     */
-    private readShellEnv;
-    /**
-     * Policy seam for what a sub-agent's shell sees. A sub-agent inherits the
-     * parent environment by default (mirrors Claude Code), so this is the
-     * identity function today. It exists so a future policy can narrow the set
-     * (e.g. strip credential `exposeAsEnv` secrets, or allowlist by name) in ONE
-     * place instead of scattering `isSubAgent` checks through readShellEnv.
-     */
-    private filterSubagentEnv;
-    /**
-     * Read the project's `localEnvironment.setupScripts` for this cwd (the raw
-     * per-platform map). Used by EnterWorktree to run setup once in a freshly
-     * created worktree. Returns undefined for sub-agents / no cwd (same minimal
-     * surface as readShellEnv). The platform selection + run live in
-     * git/worktree.ts; this only fetches the configured scripts.
-     */
-    readWorktreeSetupScripts(cwd?: string): {
-        default?: string;
-        macos?: string;
-        linux?: string;
-        windows?: string;
-    } | undefined;
-    readWorktreeBranchPrefix(cwd?: string): string | undefined;
-    resolveWorktreeSetupSandbox(cwd: string): Promise<SandboxBackend | undefined>;
-    readWorktreeSetupShellEnv(cwd?: string): Record<string, string> | undefined;
-    buildToolContext(): ToolContext;
+    buildToolContext(cwd?: string, explicitProfileOverrides?: CapabilityOverrides, profileMemoryDir?: string): ToolContext;
     /**
      * Read settings.disabledSkills + settings.disabledPlugins in a single
      * pass. Sub-agents skip both for the same reason they skip
@@ -684,11 +779,4 @@ export declare class Engine {
      * falls back to its built-in defaults.
      */
     private readMemoriesConfig;
-    /**
-     * LLM client for memory extraction (TODO 8.1). Prefers
-     * settings.memories.extractionModel when it names a valid pool model;
-     * otherwise falls back to the aux client (which itself falls back to the
-     * passed primary). Build failures fall back too — extraction is best-effort.
-     */
-    private resolveExtractionClient;
 }