operon-agents 0.1.0-alpha.2 → 0.1.0-alpha.21

package/dist/harness.js

@@ -11,11 +11,19 @@
  * low-level "assemble it yourself / stateless server" path, import from
  * `operon-agents/core` instead.
  */
-import { readLog, SessionProjection, ListenerSink, agentEventFromRecord, newAgentEventId, Agent, buildAgentFromProfile, INTERRUPTION_STATE_KEY, flattenPendingInterrupts, parseInterruptionState, Runner, Session, emptyUsage, renderSteerText, isGuardrailTripwireError, askUserQuestionTool, backgroundCapability, compactionCapability, filesystemTools, goalCapability, LocalMachine, McpOAuthService, MemorySessionRepository, SessionRepositoryNotFoundError, planCapability, skillsCapability, SkillRegistry, mcpServersCapability, pluginsCapability, userHooksCapability, taskCapability, workflowCapability, DEFAULT_AGENT_PROFILES, DEFAULT_AGENT_PROFILE_NAME, DEFAULT_SUBAGENT_NAMES, profileSubagentProvider, DEFAULT_ADDRESS, } from "operon-agents-core";
+import { readSessionTails, SessionProjection, ListenerSink, agentEventFromRecord, newAgentEventId, Agent, buildAgentFromProfile, INTERRUPTION_STATE_KEY, flattenPendingInterrupts, parseInterruptionState, Runner, Session, emptyUsage, isGuardrailTripwireError, askUserQuestionTool, backgroundCapability, compactionCapability, filesystemTools, goalCapability, LocalEnvironment, McpOAuthService, MemorySessionRepository, SessionRepositoryNotFoundError, planCapability, skillsCapability, SkillRegistry, mcpServersCapability, pluginsCapability, userHooksCapability, taskCapability, workflowCapability, DEFAULT_AGENT_PROFILES, DEFAULT_AGENT_PROFILE_NAME, DEFAULT_SUBAGENT_NAMES, profileSubagentProvider, DEFAULT_ADDRESS, envLogger, noopLogger, } from "operon-agents-core";
 import { mkdirSync } from "node:fs";
+import { workspaceMcpCapability } from "./workspace-mcp.js";
 import { join } from "node:path";
-import { extensionsCapability, ExtensionRuntime, HarnessExtensionManager, ServiceRegistry, stageDefinition } from "./extensions/index.js";
+import { extensionCapability, extensionRuntimeOf, extensionsCapability, HarnessExtensionManager, ServiceRegistry, stageDefinition } from "./extensions/index.js";
 import { createExtensionCommandRegistry } from "operon-agents-core";
+/** How long `HarnessSession.close()` waits for aborted runs to settle before continuing teardown. */
+let CLOSE_RUN_WAIT_MS = 5_000;
+/** Test-only (exported via `operon-agents/internal`): shrink the close deadlines. */
+export function setHarnessCloseTimeoutsForTest(ms) {
+    if (ms.runSettle !== undefined)
+        CLOSE_RUN_WAIT_MS = ms.runSettle;
+}
 /** Rendezvous budget for `replaceExtension` when the caller names none. */
 const DEFAULT_REPLACE_TIMEOUT_MS = 30_000;
 /** Session-store key holding the per-session extension params map (see `createSession({ params })`). */
@@ -26,21 +34,34 @@ const EXTENSION_PARAMS_STATE_KEY = "extensions:params";
  * on the agent (`filesystemTools()`), not a capability; so is AskUserQuestion
  * (`askUserQuestionTool`, wired through ToolRunContext.responder).
  *
- * With `mcpServers` and/or `pluginManager`, an MCP capability is added; with `pluginManager`, the
+ * With `mcpServers`, `sessionMcpServers` and/or `pluginManager`, an MCP capability is added; with `pluginManager`, the
  * plugin's skills/MCP/session-start are wired in too. Intended to be called fresh per session (via
  * a harness capability factory) so per-session state (goal/plan/todo/…) and the plugin set are
  * isolated per session, mirroring a fresh-Session-per-create model.
  */
 export function defaultCapabilities(options = {}) {
-    const manager = options.pluginManager;
+    const manager = options.pluginManager ?? options.shared?.pluginManager;
+    // A session on its own environment ignores the process-wide registry: it was scanned elsewhere.
+    const strict = options.strictIsolation === true;
+    // A session on its own environment, or one tenant among many, gets nothing the process shares.
+    const isolated = strict || options.ownEnvironment === true;
+    const sharedSkills = isolated ? undefined : options.shared?.skillRegistry;
+    const sharedServers = isolated ? undefined : options.shared?.mcpServers;
+    const oauthService = options.oauthService ?? (strict ? undefined : options.shared?.oauthService);
+    const allowedMcpTransports = strict
+        ? (options.allowedMcpTransports ?? ["http", "stdio"]).filter((kind) => kind === "http")
+        : options.allowedMcpTransports;
     // Shared registry so the plugin session-start injector can render a skill the skills capability
-    // loaded (its roots include the plugin skill dirs below).
-    const registry = manager !== undefined ? new SkillRegistry() : undefined;
+    // loaded (its roots include the plugin skill dirs below). A process-wide registry is scanned
+    // once for every session; a session-level one is scanned here.
+    const registry = sharedSkills ?? (manager !== undefined ? new SkillRegistry() : undefined);
     // `includeDefaultRoots` because the plugin dirs ADD to the project/user `.agents/skills` roots —
     // without it, enabling a single skill-bearing plugin would hide every local skill.
-    const skills = manager !== undefined
-        ? skillsCapability({ registry, roots: manager.skillRoots(), includeDefaultRoots: true })
-        : skillsCapability();
+    const skills = sharedSkills !== undefined
+        ? skillsCapability({ registry: sharedSkills, scan: false })
+        : manager !== undefined
+            ? skillsCapability({ registry, roots: manager.skillRoots(), includeDefaultRoots: true })
+            : skillsCapability();
     const capabilities = [
         goalCapability(),
         workflowCapability(),
@@ -51,9 +72,40 @@ export function defaultCapabilities(options = {}) {
         compactionCapability({ maxContextTokens: options.maxContextTokens ?? 200_000 }),
     ];
     // Cron is a local-only capability (Invariant 7): the server host doesn't install it.
-    // MCP: workspace servers + enabled plugin servers (namespaced, so they can't collide).
-    if (options.mcpServers !== undefined || manager !== undefined) {
-        capabilities.push(mcpServersCapability({ ...(options.mcpServers ?? {}), ...(manager?.mcpServerConfigs() ?? {}) }, options.oauthService !== undefined ? { oauthService: options.oauthService } : {}));
+    const sessionMcp = options.sessionMcpServers ?? {};
+    const mcpOptions = {
+        ...(oauthService !== undefined ? { oauthService } : {}),
+        ...(allowedMcpTransports !== undefined ? { allowedTransports: allowedMcpTransports } : {}),
+        ...(options.mcpCredentials !== undefined ? { credentials: options.mcpCredentials } : {}),
+    };
+    // Everything this session would connect that is not private to it: the directory's servers
+    // last, so they win over a same-named plugin server the way they did as a session overlay.
+    const shareable = {
+        ...(options.mcpServers ?? {}),
+        ...(manager?.mcpServerConfigs() ?? {}),
+        ...(options.workspaceMcp?.servers ?? {}),
+    };
+    if (strict) {
+        // The process environment has no tenant boundary: a token read from it is every tenant's.
+        for (const [name, config] of Object.entries({ ...shareable, ...sessionMcp })) {
+            if (config.bearerTokenEnvVar !== undefined) {
+                throw new Error(`MCP server "${name}" reads its token from the process environment (bearerTokenEnvVar), which every tenant on this host shares; hand it out per session with mcpCredentials instead.`);
+            }
+        }
+    }
+    const pooled = sharedServers === undefined && !isolated ? options.workspaceMcp : undefined;
+    if (pooled !== undefined && Object.keys(shareable).length > 0) {
+        // Borrowed per directory: the capability views the pool's set, `sessionMcp` is its overlay.
+        capabilities.push(workspaceMcpCapability({ pool: pooled.pool, workDir: pooled.workDir, servers: shareable, overlay: sessionMcp, overlayOptions: mcpOptions }));
+    }
+    else {
+        // With process-shared connections, the capability is a VIEW over them and `configs` is this
+        // session's overlay. Without, everything this session sees is its own — session servers last,
+        // so the same name still resolves to the session's.
+        const mcpConfigs = sharedServers !== undefined ? sessionMcp : { ...shareable, ...sessionMcp };
+        if (sharedServers !== undefined || Object.keys(mcpConfigs).length > 0) {
+            capabilities.push(mcpServersCapability(mcpConfigs, { ...mcpOptions, ...(sharedServers !== undefined ? { sharedServers } : {}) }));
+        }
     }
     // Plugins: load the manager + render the plugin's session-start skill from the shared registry
     // (skills opens before this, so by injection time the registry holds the plugin skills).
@@ -98,6 +150,11 @@ class MutableResponder {
     isLiveApprover() {
         return this.approvalHandler !== undefined;
     }
+    /** Same rule for questions: no handler ⇒ nobody attached ⇒ AskUserQuestion suspends durably
+     *  (the question is on the paused run's pending list) instead of being dismissed unanswered. */
+    isLiveQuestioner() {
+        return this.questionHandler !== undefined;
+    }
     async requestApproval(request, options) {
         if (this.approvalHandler)
             return this.approvalHandler(request, options);
@@ -133,22 +190,36 @@ export class HarnessSession {
     responder;
     onClosed;
     runContext;
-    currentRun;
     /** Barrier gate (docs/architecture.md §5.5): while set, no NEW run starts on this
      *  session — prompt/resume park at it, promptStream starts lazily behind it. The in-flight
      *  run is never touched. */
     runGate;
-    /** Resolves when the latest run settles — the "arrived at the boundary" signal a barrier
-     *  coordinator awaits. Undefined while idle. */
-    runSettled;
-    runSettles = new Map();
+    /**
+     * Every run this facade has begun and not yet seen settle, by its controller. More than one
+     * entry means runs are queued behind the core's run lock (`prompt` while a turn is in flight):
+     * "busy" is this set being non-empty, `cancel()` aborts ALL of them, and the barrier's
+     * quiescence is ALL of them settling — tracking only the last-begun run would abort the
+     * queued one and leave the running one untouched.
+     */
+    runs = new Map();
     lastRunInterrupted = false;
-    closed = false;
-    deliveryCounter = 0;
+    /** open → closing (runs being drained, resources going down) → closed. Never goes back. */
+    lifecycle = "open";
+    /** The one close in flight (or finished): every `close()` call returns THIS promise. */
+    closing;
+    /** Resolves the moment close() begins — what wakes a caller parked at the barrier gate so it
+     *  can fail with the closed error instead of hanging on a gate nobody will release. */
+    notifyClosing;
+    closingNotified = new Promise((resolve) => {
+        this.notifyClosing = resolve;
+    });
     /** A wake is already scheduled on the microtask queue; more enqueues fold into it. */
     wakeScheduled = false;
     /** Per-session turn cap; the Runner's own config is the fallback. */
     maxTurns;
+    /** Builds the capability an extension attached to THIS session runs as — bound to the
+     *  session's harness reach and its per-session params. */
+    mountExtension;
     constructor(args) {
         this.core = args.core;
         this.id = args.core.id;
@@ -162,6 +233,7 @@ export class HarnessSession {
         this.maxTurns = args.maxTurns;
         this.lastRunInterrupted = args.interrupted ?? false;
         this.onClosed = args.onClosed;
+        this.mountExtension = args.mountExtension;
         // Nothing drains a queue that fills while the session sits idle — the run loop's
         // turn-boundary drain only exists while a run is in flight. Without this, a background
         // task settling minutes after its spawning turn ended (the normal case: spawning to the
@@ -173,7 +245,7 @@ export class HarnessSession {
      * Start a turn to consume queued follow-ups, once the current synchronous work is done.
      *
      * Deferred to a microtask for two reasons: several enqueues in one stack fold into a single
-     * wake, and a settle that lands in a finishing run's own stack sees `currentRun` already
+     * wake, and a settle that lands in a finishing run's own stack sees its run already
      * cleared. Re-checked at fire time because either can change in between — and re-checked
      * again after every run, since the queue may have filled during one whose drain had passed.
      */
@@ -191,7 +263,7 @@ export class HarnessSession {
                 return;
             // A run in flight drains at its own turn boundary; an interrupted one must be resumed,
             // not talked over.
-            if (this.currentRun !== undefined)
+            if (this.hasActiveRuns())
                 return;
             // Either channel counts. A "steering" item is an interruption of work in flight, but with
             // nothing in flight there is nothing to interrupt — it is simply the next input, and the
@@ -203,6 +275,22 @@ export class HarnessSession {
             void this.runPrompt([]).catch(() => undefined);
         });
     }
+    /** Not open: closing or closed. Every run entry point refuses from here on. */
+    get closed() {
+        return this.lifecycle !== "open";
+    }
+    /**
+     * Park at the barrier gate until released — or until this session starts closing, in which
+     * case fail with the closed error rather than wait on a gate no coordinator will release.
+     * Re-checked in a loop: a new hold can land between a release and this task resuming.
+     */
+    async parkAtGate() {
+        while (this.runGate !== undefined) {
+            await Promise.race([this.runGate.released, this.closingNotified]);
+            if (this.closed)
+                throw new Error(`session "${this.id}" is closed`);
+        }
+    }
     /** Run options every run on this session carries — currently the session's turn cap. */
     get runOverrides() {
         return this.maxTurns !== undefined ? { maxTurns: this.maxTurns } : {};
@@ -215,7 +303,7 @@ export class HarnessSession {
         return {
             state: this.closed
                 ? "closed"
-                : this.currentRun !== undefined
+                : this.hasActiveRuns()
                     ? "running"
                     : this.lastRunInterrupted
                         ? "interrupted"
@@ -238,16 +326,26 @@ export class HarnessSession {
     }
     // ── Run driving (the methods core Session does not have) ──
     beginRun(controller) {
-        this.currentRun = controller;
-        this.runSettled = new Promise((resolve) => {
-            this.runSettles.set(controller, resolve);
+        let resolve;
+        const settled = new Promise((r) => {
+            resolve = r;
         });
+        this.runs.set(controller, { settled, resolve });
     }
     endRun(controller) {
-        if (this.currentRun === controller)
-            this.currentRun = undefined;
-        this.runSettles.get(controller)?.();
-        this.runSettles.delete(controller);
+        this.runs.get(controller)?.resolve();
+        this.runs.delete(controller);
+        // Input can arrive after the last drain while this run still counts as active. Every
+        // entry point must recheck on exit; the wake itself respects pauses, gates and other runs.
+        this.scheduleIdleWake();
+    }
+    /** A run is in flight or queued behind the core's run lock. */
+    hasActiveRuns() {
+        return this.runs.size > 0;
+    }
+    /** Settles when every run begun so far has settled (trivially, when idle). */
+    allRunsSettled() {
+        return Promise.all([...this.runs.values()].map((run) => run.settled)).then(() => undefined);
     }
     /**
      * Barrier support (docs/architecture.md §5.5): refuse NEW runs until released and
@@ -264,7 +362,7 @@ export class HarnessSession {
         });
         const gate = { released, release: releaseGate };
         this.runGate = gate;
-        const quiescent = this.currentRun !== undefined ? (this.runSettled ?? Promise.resolve()) : Promise.resolve();
+        const quiescent = this.allRunsSettled();
         return {
             quiescent,
             release: () => {
@@ -283,10 +381,11 @@ export class HarnessSession {
     async runPrompt(input, inputOrigin) {
         if (this.closed)
             throw new Error(`session "${this.id}" is closed`);
-        // Barrier gate: park (never fail) until released. A loop, not an if — a new hold can land
-        // between the release and this task resuming.
-        while (this.runGate !== undefined)
-            await this.runGate.released;
+        // Barrier gate: park until released (a hold is "wait", not "fail") — unless the session
+        // closes meanwhile, which is the one thing that turns the wait into a failure. Ungated, the
+        // run is registered SYNCHRONOUSLY: a cancel() or close() on the next line must find it.
+        if (this.runGate !== undefined)
+            await this.parkAtGate();
         const controller = new AbortController();
         this.beginRun(controller);
         try {
@@ -309,141 +408,61 @@ export class HarnessSession {
         }
         finally {
             this.endRun(controller);
-            // A follow-up can land after this run's last drain but before it settles — that enqueue
-            // saw `currentRun` set and stood down, so the run itself has to look once on the way out.
-            this.scheduleIdleWake();
         }
     }
     /**
      * Hand a message to the frame running at `address` in this session (`main` for the root agent,
-     * `main/<agentId>` for a subagent); `false` when nobody is there. The seam an out-of-process
-     * coordinator uses to address a specific subagent.
+     * `main/<agentId>` for a subagent); undefined when nobody is there, or the session is paused
+     * on a question. The seam an out-of-process coordinator uses to address a specific subagent.
+     *
+     * The receipt's `journaled` settles once the `steer.queued` record is on disk — the moment a
+     * caller may answer "accepted" to someone else and mean it survives a crash. A running frame
+     * drains the message at its next boundary; an idle root frame is woken to take it.
      */
-    steerTo(address, content, origin) {
-        if (this.closed || this.lastRunInterrupted)
-            return false;
+    steerTo(address, content, origin, options) {
+        if (this.closed)
+            return undefined;
         // A run in flight drains its own queues, so handing the message to the frame is enough.
-        if (this.currentRun !== undefined)
-            return this.core.steerTo(address, content, origin);
+        // A resume keeps the prior interruption flag until it settles, but is already running.
+        if (this.hasActiveRuns())
+            return this.core.steerTo(address, content, origin, options);
+        if (this.lastRunInterrupted)
+            return undefined;
         // Idle: only the root frame can be woken. A subagent whose frame has ended is not a teammate
         // waiting for mail — it is a finished delegation, and only the parent that delegated it can
         // decide to continue it (`Agent(resume=...)`). Its store, capabilities, permissions and
         // lifetime are all the parent's; there is no independent agent here to start.
         if (address !== DEFAULT_ADDRESS)
-            return false;
+            return undefined;
         // Queue it and let the idle-wake listener start the turn. Going through the bus (rather
-        // than synthesizing a prompt here) is what gives the message a `steerId` on its journal
-        // record, same as every other producer — the enqueue→consume trail stays unbroken.
-        this.core.steer.steer(content, origin);
-        return true;
+        // than synthesizing a prompt here) is what gives the message its `steer.queued` record and
+        // a `steerId` on its journal record, same as every other producer.
+        return this.core.steer.steer(content, origin, options);
     }
     /**
-     * Deliver an externally-originated message. A running session receives it through the
-     * requested SteerBus channel; an idle session starts a new turn immediately.
-     *
-     * ACCEPTANCE IS DURABLE BEFORE THIS RESOLVES. The input is journaled as `inbox.received`
-     * and that write is awaited before a receipt exists, so the receipt means "this survives a
-     * crash", not merely "this reached a process". Previously the message lived only in memory
-     * (SteerBus, or an argument to `runPrompt`) until the run that consumed it journaled it —
-     * a crash in that window lost a delivery the caller had already been told was accepted.
+     * Put a message whose `steer.queued` record ALREADY exists back on the bus.
      *
-     * The provenance of what the model ultimately sees is still persisted on the eventual
-     * `message.appended` record: acceptance and processing are journaled separately because
-     * they can legitimately differ (capability rewrite, guardrail rejection, or a capability
-     * answering the prompt outright).
+     * For whoever holds a reopened session and finds, in its log, accepted messages no turn ever
+     * consumed — a `steer.queued` with no `message.appended` carrying its `steerId`. That happens
+     * when acceptance and execution are different processes (a managed API node writes the record,
+     * a worker runs it later, possibly on another machine) or when the process that accepted a
+     * message died before a turn drained it. Nothing is journaled again: the record and its
+     * `steer.queued` event exist from the first acceptance. Run state is read NOW, not then — a
+     * running turn drains it at its next boundary, an idle session is woken to take it.
      */
-    async deliver(input, options) {
+    requeue(item) {
         if (this.closed)
             throw new Error(`session "${this.id}" is closed`);
-        if (this.lastRunInterrupted && this.currentRun === undefined) {
-            throw new Error(`session "${this.id}" is interrupted; resume it before delivering new work`);
-        }
-        if (!options.source.trim())
-            throw new Error("delivery source must not be empty");
-        this.deliveryCounter += 1;
-        const deliveryId = `delivery_${Date.now().toString(36)}_${this.deliveryCounter.toString(36)}`;
-        const mode = options.mode ?? "auto";
-        const channel = mode === "follow_up" ? "follow_up" : "steering";
-        const external = {
-            kind: "external",
-            source: options.source,
-            deliveryId,
-            actor: options.actor,
-            metadata: options.metadata,
-            channel,
-        };
-        const acceptedAt = Date.now();
-        // Durable acceptance, before anything is dispatched. A stored session gets its receipt from
-        // this record (the store is publication-aware, so the append also produces the
-        // `delivery.accepted` event); a storeless one has nothing to be durable about and emits the
-        // event directly.
-        if (this.core.store !== undefined) {
-            await this.core.store.appendRecord({
-                type: "inbox.received",
-                time: acceptedAt,
-                address: "main",
-                input,
-                origin: external,
-                mode,
-            });
-        }
-        else {
-            void this.core.events.emit({
-                type: "delivery.accepted",
-                deliveryId,
-                source: options.source,
-                channel,
-                address: "main",
-                sessionId: this.id,
-            });
-        }
-        return this.dispatchAccepted(input, external, acceptedAt);
+        return this.core.steer.requeue(item);
     }
     /**
-     * Dispatch an input whose acceptance is ALREADY journaled.
-     *
-     * A worker draining a session's inbox calls this directly: the `inbox.received` record exists,
-     * so going back through `deliver` would write a second one and count the delivery twice. The
-     * split is the whole reason acceptance and dispatch are separable — accepting is a durable
-     * write that must happen before a receipt exists, dispatching is what someone holding the
-     * session's lease does with it afterwards, possibly on another machine, possibly much later.
-     *
-     * Run state is read HERE, not at acceptance: by now a turn may have started or ended, so
-     * whether this steers work in flight or starts a fresh turn can only be decided now.
+     * Settles when no run is in flight. Yields once first, so a run that an enqueue on the
+     * previous line scheduled (the idle wake fires from a microtask) is counted as in flight
+     * rather than missed. A run that starts afterwards is not waited for.
      */
-    dispatchAccepted(input, origin, acceptedAt = Date.now()) {
-        if (this.closed)
-            throw new Error(`session "${this.id}" is closed`);
-        const deliveryId = origin.deliveryId;
-        const channel = origin.channel ?? "steering";
-        if (this.currentRun !== undefined) {
-            const receipt = this.core.steer.steer(input, origin);
-            return {
-                deliveryId,
-                sessionId: this.id,
-                acceptedAt,
-                status: "queued",
-                channel,
-                steerId: receipt.steerId,
-            };
-        }
-        const promptOrigin = {
-            kind: "external",
-            source: origin.source,
-            deliveryId,
-            ...(origin.actor !== undefined ? { actor: origin.actor } : {}),
-            ...(origin.metadata !== undefined ? { metadata: origin.metadata } : {}),
-        };
-        const message = {
-            role: "user",
-            content: [{ type: "text", text: renderSteerText(origin, input) }],
-            timestamp: acceptedAt,
-        };
-        const completion = this.runPrompt([message], promptOrigin);
-        // Callers may only need acceptance. Keep a fire-and-observe delivery from becoming an
-        // unhandled rejection; awaiting `completion` still receives the original rejection.
-        completion.catch(() => undefined);
-        return { deliveryId, sessionId: this.id, acceptedAt, status: "started", channel: "turn", completion };
+    async whenIdle() {
+        await Promise.resolve();
+        await this.allRunsSettled();
     }
     /**
      * Resume a durably-interrupted run. When a `prompt` returns `status:"interrupted"` — which
@@ -465,15 +484,17 @@ export class HarnessSession {
      * copy see a "stale interruption state" error; re-fetching the persisted state clears it.
      */
     async resume(answers) {
+        if (this.closed)
+            throw new Error(`session "${this.id}" is closed`);
         // Barrier gate first (a coordinator holding the barrier should not be resumed against —
-        // the call parks here until release rather than failing).
-        while (this.runGate !== undefined)
-            await this.runGate.released;
-        if (this.currentRun !== undefined)
+        // the call parks here until release rather than failing; closing meanwhile does fail it).
+        if (this.runGate !== undefined)
+            await this.parkAtGate();
+        if (this.hasActiveRuns())
             throw new Error(`session "${this.id}" already has an active run`);
         const controller = new AbortController();
         // Set this BEFORE the first await (past the gate). A host returning 202 from resume can
-        // immediately observe `running`, and a concurrent delivery joins this resumed turn instead
+        // immediately observe `running`, and a concurrent steer joins this resumed turn instead
         // of seeing stale interrupted state while the control record is being read.
         this.beginRun(controller);
         try {
@@ -509,6 +530,8 @@ export class HarnessSession {
     }
     /** Streaming variant: iterate events, await `.completed` for the result. */
     promptStream(input) {
+        if (this.closed)
+            throw new Error(`session "${this.id}" is closed`);
         const controller = new AbortController();
         // Ungated: start synchronously, byte-identical to the pre-barrier behavior. Gated: the
         // handle returns immediately but the underlying run starts only after release (lazy start —
@@ -518,8 +541,7 @@ export class HarnessSession {
             this.beginRun(controller);
         const start = (async () => {
             if (gated) {
-                while (this.runGate !== undefined)
-                    await this.runGate.released;
+                await this.parkAtGate();
                 this.beginRun(controller);
             }
             return this.runner.runStream(this.agent, input, {
@@ -580,26 +602,30 @@ export class HarnessSession {
         };
     }
     /**
-     * Inject a user message into the in-flight (or next) turn. Returns the steer's correlation
-     * id: a `steer.queued` event carries it now, and the consuming `message.appended` event's
-     * `origin.steerId` matches it when the model actually sees the message.
+     * Inject a user message into the in-flight (or next) turn. The receipt's `steerId` is the
+     * correlation key: a `steer.queued` event carries it now, and the consuming `message.appended`
+     * event's `origin.steerId` matches it when the model actually sees the message; `journaled`
+     * settles once the `steer.queued` record is durable.
      */
     steer(input) {
-        return this.core.steer.steer(input, { kind: "user" }).steerId;
+        if (this.closed)
+            throw new Error(`session "${this.id}" is closed`);
+        return this.core.steer.steer(input, { kind: "user" });
     }
     /**
      * Queue a user message for a new turn after the current run's active turn finishes.
-     * Returns the steer's correlation id (see `steer`), or null when the session has no
-     * active run — use `prompt` instead in that case.
+     * Returns the receipt (see `steer`), or null when the session has no active run — use
+     * `prompt` instead in that case.
      */
     followUp(input) {
-        if (this.currentRun === undefined)
+        if (!this.hasActiveRuns())
             return null;
-        return this.core.steer.followUp(input).steerId;
+        return this.core.steer.followUp(input);
     }
-    /** Abort the current run. */
+    /** Abort every run this session has accepted: the one in flight AND any queued behind it. */
     cancel() {
-        this.currentRun?.abort();
+        for (const controller of [...this.runs.keys()])
+            controller.abort();
     }
     /** Subscribe to this session's event stream. Returns an unsubscribe fn. */
     onEvent(listener) {
@@ -643,82 +669,103 @@ export class HarnessSession {
     setPermissionMode(mode) {
         return this.core.setPermissionMode(mode);
     }
-    createGoal(...args) {
-        return this.core.createGoal(...args);
+    /** The model this session runs on, as last set; undefined means the agent's own. */
+    get modelSetting() {
+        return this.core.modelSetting;
     }
-    getGoal() {
-        return this.core.getGoal();
+    /** The thinking level this session runs at, as last set; undefined means the model's default. */
+    get thinkingSetting() {
+        return this.core.thinkingSetting;
     }
-    setPlanMode(...args) {
-        return this.core.setPlanMode(...args);
+    /** The permission mode in force right now — what a status line reads instead of tracking it. */
+    get permissionMode() {
+        return this.core.permissionModeSetting;
     }
-    getPlan() {
-        return this.core.getPlan();
+    // ── capability services ───────────────────────────────────────────────────────────────
+    // The same accessors the core `Session` exposes, forwarded. There used to be one wrapper
+    // method per operation here, mirroring one facade method per operation there — two layers
+    // that had to be kept in step by hand every time a capability grew an operation. Forwarding
+    // the SERVICE means a new operation needs no change in either layer.
+    get goal() {
+        return this.core.goal;
     }
-    compact(...args) {
-        return this.core.compact(...args);
+    get plan() {
+        return this.core.plan;
     }
-    listSkills() {
-        return this.core.listSkills();
+    get skills() {
+        return this.core.skills;
     }
-    activateSkill(...args) {
-        return this.core.activateSkill(...args);
+    get plugins() {
+        return this.core.plugins;
     }
-    listPlugins() {
-        return this.core.listPlugins();
+    get compaction() {
+        return this.core.compaction;
     }
-    installPlugin(...args) {
-        return this.core.installPlugin(...args);
+    /** PROBE tier: absent without the background capability — see `Session.background`. */
+    get background() {
+        return this.core.background;
     }
-    listBackgroundTasks(...args) {
-        return this.core.listBackgroundTasks(...args);
+    /** PROBE tier: absent without an MCP capability. */
+    get mcp() {
+        return this.core.mcp;
     }
     // ── Conversation log (flat, linear) — read the record stream for transcript rendering ──
     getRecords(...args) {
         return this.core.getRecords(...args);
     }
-    listSubagents(...args) {
-        return this.core.listSubagents(...args);
-    }
-    reconcileSubagents(...args) {
-        return this.core.reconcileSubagents(...args);
+    getAuditRecords() {
+        return this.core.getAuditRecords();
     }
     // ── context introspection — where the model's window is spent, as of the last turn ──
     getContextBreakdown() {
         return this.core.getContextBreakdown();
     }
+    /** Where this session's tools run. A host uses it to run a command in the same place the agent
+     *  does — one shell, one filesystem, one working directory. */
+    get environment() {
+        return this.core.environment;
+    }
+    /** The current todo list (the `TodoList` tool's latest state); empty without the todo capability. */
+    getTodos() {
+        return this.core.service("todo")?.get() ?? [];
+    }
+    /** Every slash command this session answers to — the static registry plus the ones its
+     *  capabilities and extensions contribute — for a UI's palette and autocompletion. */
+    listCommands() {
+        return sharedCommands()
+            .list(this.core)
+            .map((command) => ({ name: command.name, aliases: command.aliases ?? [], description: command.description }));
+    }
     // ── extensions — hot attach/detach on the live session (host API; never a model tool) ──
     /**
      * Add an extension mid-session. Applied at the next quiet point: immediately when idle,
      * at the run's stop boundary when one is in flight — its tools appear at the next run's
      * assembly. The change is journaled; it does NOT survive `resumeSession` (re-attach, or
      * register it in `createHarness({ extensions })`, which every open re-evaluates). A definition
-     * with a `create` half is accepted only once registered — its service must already exist.
+     * with a `harness` half is accepted only once registered — its service must already exist.
      */
-    attachExtension(definition) {
-        return this.extensionRuntime().attach(definition);
+    async attachExtension(definition) {
+        await this.core.attachCapability(this.mountExtension(definition));
     }
     /** Remove an extension mid-session: `session.end("detach")` fires, then its scope unwinds. */
-    detachExtension(extensionId) {
-        return this.extensionRuntime().detach(extensionId);
+    async detachExtension(extensionId) {
+        if (this.extensionRuntime(extensionId) === undefined)
+            throw new Error(`unknown extension "${extensionId}"`);
+        await this.core.detachCapability(extensionId);
     }
-    /** Ids of currently attached extensions; empty when the session has no extensions capability. */
+    /** Ids of currently attached extensions, in mount order. */
     attachedExtensionIds() {
-        try {
-            return this.extensionRuntime().attachedIds();
-        }
-        catch {
-            return [];
-        }
+        return this.attachedExtensions().map((extension) => extension.id);
     }
-    /** Currently attached extensions with what each `uses`; empty without an extensions capability. */
+    /** Currently attached extensions with what each `uses`. */
     attachedExtensions() {
-        try {
-            return this.extensionRuntime().attachedExtensions();
-        }
-        catch {
-            return [];
+        const out = [];
+        for (const capability of this.core.capabilities) {
+            const runtime = extensionRuntimeOf(capability);
+            if (runtime !== undefined)
+                out.push({ id: runtime.id, uses: runtime.definition.uses ?? [] });
         }
+        return out;
     }
     /** Run a slash command against this session: the static registry plus capability-contributed
      *  dynamic commands (extensions' `registerCommand`). Commands are the SERIALIZABLE control
@@ -731,108 +778,82 @@ export class HarnessSession {
      *  is absent, detached, or exposed nothing. The generic replacement for per-feature session
      *  facade methods (e.g. cron's — see `cronExtension`). */
     extensionHandle(extensionId) {
+        return this.extensionRuntime(extensionId)?.exposedHandle();
+    }
+    extensionRuntime(extensionId) {
+        const capability = this.core.capabilities.find((open) => open.name === extensionId);
+        return capability === undefined ? undefined : extensionRuntimeOf(capability);
+    }
+    /**
+     * Close the session and release its resources. Order: stop accepting runs, abort the ones
+     * accepted (in flight and queued) and wait for them to settle — their tools' finally blocks,
+     * their journal writes — then detach the projection and take the core down. Every call
+     * returns the SAME promise, so nobody returns while the teardown is still running.
+     *
+     * The wait for runs is bounded (`CLOSE_RUN_WAIT_MS`, 5s): a run that ignores its abort signal
+     * is logged and left behind, and the teardown continues — the deadline caps the wait for
+     * runs, not the whole close (flushes and disposes carry their own deadlines).
+     */
+    close() {
+        if (this.closing !== undefined)
+            return this.closing;
+        this.lifecycle = "closing";
+        this.notifyClosing();
+        this.closing = this.runClose();
+        return this.closing;
+    }
+    async runClose() {
         try {
-            return this.extensionRuntime().exposedHandle(extensionId);
+            const settled = this.allRunsSettled();
+            this.cancel();
+            let timer;
+            const timedOut = await Promise.race([
+                settled.then(() => false),
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve(true), CLOSE_RUN_WAIT_MS);
+                }),
+            ]);
+            clearTimeout(timer);
+            if (timedOut) {
+                this.core.logger.log("warn", "session close: runs still settling after the deadline; continuing teardown", {
+                    sessionId: this.id,
+                    runs: this.runs.size,
+                    deadlineMs: CLOSE_RUN_WAIT_MS,
+                });
+            }
+            this.projection.detach();
+            await this.core.close();
+            await this.onClosed(this.id);
         }
-        catch {
-            return undefined;
+        finally {
+            this.lifecycle = "closed";
         }
     }
-    extensionRuntime() {
-        const runtime = this.core.service("extensions");
-        if (!runtime)
-            throw new Error("this session has no extensions capability");
-        return runtime;
-    }
-    // ── goal lifecycle ──
-    pauseGoal(...args) {
-        return this.core.pauseGoal(...args);
-    }
-    resumeGoal(...args) {
-        return this.core.resumeGoal(...args);
-    }
-    cancelGoal(...args) {
-        return this.core.cancelGoal(...args);
-    }
-    setGoalBudget(...args) {
-        return this.core.setGoalBudget(...args);
-    }
-    // ── plan + compaction ──
-    clearPlan(...args) {
-        return this.core.clearPlan(...args);
-    }
-    pendingCompaction(...args) {
-        return this.core.pendingCompaction(...args);
-    }
-    cancelCompaction(...args) {
-        return this.core.cancelCompaction(...args);
-    }
-    // ── background tasks ──
-    readBackgroundTaskOutput(...args) {
-        return this.core.readBackgroundTaskOutput(...args);
-    }
-    readBackgroundTaskOutputDelta(...args) {
-        return this.core.readBackgroundTaskOutputDelta(...args);
-    }
-    stopBackgroundTask(...args) {
-        return this.core.stopBackgroundTask(...args);
-    }
-    /** Move a running detachable tool call (bash/subagent/workflow) into a background task. */
-    detachTool(...args) {
-        return this.core.detachTool(...args);
-    }
-    // ── plugins (full lifecycle) ──
-    getPluginInfo(...args) {
-        return this.core.getPluginInfo(...args);
-    }
-    setPluginEnabled(...args) {
-        return this.core.setPluginEnabled(...args);
-    }
-    setPluginMcpServerEnabled(...args) {
-        return this.core.setPluginMcpServerEnabled(...args);
-    }
-    removePlugin(...args) {
-        return this.core.removePlugin(...args);
-    }
-    reloadPlugins(...args) {
-        return this.core.reloadPlugins(...args);
-    }
-    // ── MCP ──
-    listMcpServers(...args) {
-        return this.core.listMcpServers(...args);
-    }
-    reconnectMcpServer(...args) {
-        return this.core.reconnectMcpServer(...args);
-    }
-    /** Close the session and release its resources. */
-    async close() {
-        if (this.closed)
-            return;
-        this.closed = true;
-        this.cancel();
-        this.projection.detach();
-        await this.core.close();
-        this.onClosed(this.id);
-    }
 }
 /** Manages a fleet of in-process sessions over a shared engine config. */
 export class Harness {
     options;
     runner;
-    repo;
     /** Concrete tools the default profile's tool NAMES resolve against (keyed by schema name). */
     toolPalette;
     activeSessions = new Map();
-    /** Process-level shared services. The host replaces providers here (`services.replace`);
-     *  sessions only ever see handles (`ctx.shared`, `ctx.services`). */
-    services = new ServiceRegistry();
+    /** Opens in flight by session id (`resumeSession`): concurrent callers share ONE open — the
+     *  whole of it, reconcile and failure cleanup included — instead of each building an instance. */
+    opening = new Map();
+    /** The one close in flight (or finished): every `close()` call returns THIS promise. */
+    closing;
+    /** The process-lived objects this harness runs on (`HarnessOptions.harness`), plus defaults. */
+    parts = {};
+    /** Process-level extension services by name (a facade over `scope`). The host replaces
+     *  providers here (`services.replace`); sessions only ever see handles (`ctx.shared`, `ctx.services`). */
+    services;
     /** The one in-flight reshape barrier (mutex: a second barrier operation rejects). Sessions
      *  appearing while it holds are gated at birth — see the tail of `openFromStore`. */
     activeBarrier;
     /** File-extension manager (both tiers) — present only when the host opted in with
      *  `extensionDir`. NOT the Codex-compatible skill/MCP plugin system (`pluginManager`). */
     extensions;
-    /** Service ids published by by-value `create` halves, in creation order — unregistered (and
+    /** Service ids published by by-value `harness` halves, in creation order — unregistered (and
      *  disposed) by `close()`, newest first. */
     createdServices = [];
     /** The by-value definitions this harness currently mounts into newborn sessions, in
@@ -843,12 +864,13 @@ export class Harness {
     valueDefs = new Map();
     /** Root of extensions' data folders (`host.dataDir` = `<root>/<id>`); absent ⇒ none handed out. */
     dataRoot;
-    /** Settles once every by-value `create` half has published its service; sessions open after it. */
+    /** Settles once every by-value `harness` half has published its service; sessions open after it. */
     sharedReady;
-    /** The extension whose `create` is running right now — its `createSession` must refuse. */
+    /** The extension whose `harness` is running right now — its `createSession` must refuse. */
     runningCreate;
     constructor(options) {
         this.options = options;
+        this.services = new ServiceRegistry();
         const agentTools = options.tools ?? [...filesystemTools(), askUserQuestionTool];
         this.toolPalette = Object.fromEntries(agentTools.map((tool) => [tool.schema.name, tool]));
         // The Agent/Workflow tools only appear when the run has subagents to spawn. Default the fleet
@@ -865,8 +887,6 @@ export class Harness {
             maxStepsPerTurn: options.maxStepsPerTurn,
             ...(options.maxConcurrentSubagents !== undefined ? { maxConcurrentSubagents: options.maxConcurrentSubagents } : {}),
         });
-        // Injected repository (disk locally, Pg/Redis on a server); in-memory when omitted.
-        this.repo = options.repository ?? new MemorySessionRepository();
         this.dataRoot = options.extensionDataDir ?? (options.extensionDir !== undefined ? join(options.extensionDir, ".data") : undefined);
         this.extensions = options.extensionDir === undefined
             ? undefined
@@ -897,18 +917,65 @@ export class Harness {
                 throw new Error(`duplicate by-value extension id "${definition.id}" in createHarness({ extensions })`);
             this.valueDefs.set(definition.id, definition);
         }
-        this.sharedReady = this.registerDefinitions(options.extensions);
+        // The host's process-tier registrations come first (extension `harness` halves may consume
+        // them); a synchronous hook keeps the whole chain synchronous, so a synchronous extension's
+        // service exists the moment `createHarness` returns.
+        const composed = options.harness?.();
+        const absorb = (parts) => {
+            this.parts = {
+                ...(parts ?? {}),
+                // Explicit options win over what the preset built, and both win over the defaults below.
+                ...(options.telemetry !== undefined ? { telemetry: options.telemetry } : {}),
+                ...(options.eventPublication !== undefined ? { eventPublication: options.eventPublication } : {}),
+            };
+        };
+        this.sharedReady = composed instanceof Promise
+            ? composed.then((parts) => {
+                absorb(parts);
+                return this.registerDefinitions(options.extensions);
+            })
+            : (absorb(composed), this.registerDefinitions(options.extensions));
         // Surfaced to whoever opens a session; never an unhandled rejection on its own.
         this.sharedReady.catch(() => undefined);
     }
     /**
-     * Run one by-value definition's `create` half against a staging host: the service is COLLECTED,
-     * not registered, so a throwing `create` publishes nothing. Stays synchronous when `create` is
+     * Which session-facing parts the `harness` hook built for the whole process — what a
+     * multi-tenant host must not have, since every session on the process would share them.
+     * Infrastructure (repository, logger, model runtime) is not listed: sharing it is the point.
+     */
+    async processSharedParts() {
+        await this.sharedReady;
+        const parts = [];
+        if (this.parts.mcpServers !== undefined)
+            parts.push("mcpServers");
+        if (this.parts.oauthService !== undefined)
+            parts.push("oauthService");
+        if (this.parts.skillRegistry !== undefined)
+            parts.push("skillRegistry");
+        return parts;
+    }
+    /** The session repository, once the `harness` hook has had its say. */
+    async repository() {
+        await this.sharedReady;
+        this.memoryRepository ??= new MemorySessionRepository();
+        return this.parts.sessionRepository ?? this.memoryRepository;
+    }
+    /** The fallback repository, built once so two opens share one in-memory store. */
+    memoryRepository;
+    /** The harness logger: the preset's, else the `AGENTS_LOG` env logger, else silent. */
+    get logger() {
+        this.defaultLogger ??= envLogger() ?? noopLogger;
+        return this.parts.logger ?? this.defaultLogger;
+    }
+    defaultLogger;
+    /**
+     * Run one by-value definition's `harness` half against a staging host: the service is COLLECTED,
+     * not registered, so a throwing `harness` publishes nothing. Stays synchronous when `harness` is
      * — what lets a synchronous extension's service exist the moment `createHarness` returns.
      * Shared by construction and `replaceExtension`.
      */
     stageValue(definition) {
-        // The data folder exists before `create` runs (synchronously: `create` may be too).
+        // The data folder exists before `harness` runs (synchronously: `harness` may be too).
         const dataDir = this.dataRoot !== undefined ? join(this.dataRoot, definition.id) : undefined;
         if (dataDir !== undefined)
             mkdirSync(dataDir, { recursive: true });
@@ -931,6 +998,7 @@ export class Harness {
                     }
                     return this.createSession(sessionOptions);
                 },
+                service: (name) => this.services.handle(name),
                 warn: (message) => console.warn(`[extensions] ${message}`),
             });
             return staged instanceof Promise ? staged.then(done, failed) : done(staged);
@@ -941,12 +1009,12 @@ export class Harness {
     }
     /**
      * Register the by-value definitions, in order: check each one's `uses` against the registry
-     * (a consumer must come after its provider), then run its `create` half if it has one and
+     * (a consumer must come after its provider), then run its `harness` half if it has one and
      * register the result as a service under the extension's `id`. Stays synchronous as long as
-     * every `create` is — so `createHarness` returns with a synchronous extension's service
-     * already registered; the first async `create` turns the rest of the sequence into a promise
+     * every `harness` is — so `createHarness` returns with a synchronous extension's service
+     * already registered; the first async `harness` turns the rest of the sequence into a promise
      * chain that `openFromStore` awaits. Staging (`stageDefinition`) collects before registering,
-     * so a throwing `create` publishes nothing.
+     * so a throwing `harness` publishes nothing.
      */
     registerDefinitions(extensions) {
         if (extensions === undefined)
@@ -957,7 +1025,7 @@ export class Harness {
                     throw new Error(`extension "${definition.id}" uses service "${name}", which is not registered — list its provider earlier in createHarness({ extensions }) (or register it in services)`);
                 }
             }
-            if (definition.create === undefined)
+            if (definition.harness === undefined)
                 return;
             const staged = this.stageValue(definition);
             const publish = (result) => {
@@ -990,8 +1058,8 @@ export class Harness {
      * session's capabilities.
      *
      * Built fresh per session. Runtime-specific prompt data is not captured here: `instructions`
-     * resolves the current frame's machine + cwd through the Session cache, so root/subagent/worktree
-     * prompts stay isolated without coupling Agent lifetime to machine lifetime.
+     * resolves the current frame's environment + cwd through the Session cache, so root/subagent/worktree
+     * prompts stay isolated without coupling Agent lifetime to environment lifetime.
      */
     buildDefaultAgent(appendSystemPrompt, maxStepsPerTurn) {
         const additional = appendSystemPrompt ?? this.options.appendSystemPrompt;
@@ -1008,36 +1076,91 @@ export class Harness {
         return this.activeSessions;
     }
     async createSession(opts = {}) {
+        this.assertAcceptingSessions();
         const workDir = opts.workDir ?? this.options.workDir ?? process.cwd();
-        const handle = await this.repo.create({ id: opts.id, workDir, ownerKey: opts.ownerKey, title: opts.title });
-        return this.openFromStore(handle.id, handle.workDir, handle.store, opts);
+        const handle = await (await this.repository()).create({ id: opts.id, workDir, ownerKey: opts.ownerKey, title: opts.title });
+        return this.trackOpen(handle.id, () => this.openFromStore(handle.id, handle.workDir, handle.store, opts));
     }
-    async resumeSession(id, opts = {}) {
+    /**
+     * Register an open in flight under its id for as long as it runs. Every path that builds a
+     * session goes through here — create, resume, fork — so a `resumeSession` for an id that is
+     * being created joins that open instead of building a twin over the same store, and
+     * `closeSession` / `harness.close()` wait for it instead of closing its scope under it.
+     */
+    trackOpen(id, open) {
+        const promise = open().finally(() => {
+            if (this.opening.get(id) === promise)
+                this.opening.delete(id);
+        });
+        this.opening.set(id, promise);
+        return promise;
+    }
+    /**
+     * The open session with this id, or reopen it from the store. Concurrent calls for one id share
+     * a single open (`opening`): the second caller waits for the first's — reconcile included — and
+     * receives the same instance, never a second one that a close would then unregister. An
+     * instance that is closing is not handed out: the reopen waits for its close to finish first.
+     */
+    resumeSession(id, opts = {}) {
+        // Not async (the in-flight/active fast paths return existing promises), so refuse by rejecting.
+        if (this.closing !== undefined)
+            return Promise.reject(new Error("harness is closed"));
+        const inflight = this.opening.get(id);
+        if (inflight !== undefined) {
+            return hasOwnContext(opts)
+                ? inflight.then((session) => {
+                    session.setContext(opts.context);
+                    return session;
+                })
+                : inflight;
+        }
         const existing = this.activeSessions.get(id);
-        if (existing) {
+        if (existing !== undefined && existing.status.state !== "closed") {
             if (hasOwnContext(opts))
                 existing.setContext(opts.context);
-            return existing;
+            return Promise.resolve(existing);
         }
-        const handle = await this.repo.open(id);
-        if (handle === undefined)
-            throw new SessionRepositoryNotFoundError(id);
-        const session = await this.openFromStore(handle.id, handle.workDir, handle.store, opts);
-        // Reopening: orphaned background subagents (running from a dead process) → lost.
-        await session.reconcileSubagents();
-        return session;
+        return this.trackOpen(id, async () => {
+            // `existing` here is one that is closing: wait for that close (its registration goes
+            // with it) rather than open a twin beside it.
+            if (existing !== undefined)
+                await existing.close();
+            const handle = await (await this.repository()).open(id);
+            if (handle === undefined)
+                throw new SessionRepositoryNotFoundError(id);
+            const session = await this.openFromStore(handle.id, handle.workDir, handle.store, opts);
+            // Reopening: orphaned background subagents (running from a dead process) → lost. A failure
+            // here is an open failure: the session is torn down, not left registered and unreturned.
+            try {
+                await session.background?.reconcileSubagents() ?? [];
+            }
+            catch (error) {
+                await session.close();
+                throw error;
+            }
+            return session;
+        });
     }
     /** Fork an existing session into a new one (copies its log + state) and open it. */
     async forkSession(sourceId, opts = {}) {
-        const handle = await this.repo.fork(sourceId, {
+        this.assertAcceptingSessions();
+        const handle = await (await this.repository()).fork(sourceId, {
             ...(opts.id !== undefined ? { id: opts.id } : {}),
             ...(opts.ownerKey !== undefined ? { ownerKey: opts.ownerKey } : {}),
             ...(opts.title !== undefined ? { title: opts.title } : {}),
         });
-        const session = await this.openFromStore(handle.id, handle.workDir, handle.store, opts);
-        // A fork copies the subagent ledger; its background "running" rows have no live task → lost.
-        await session.reconcileSubagents();
-        return session;
+        return this.trackOpen(handle.id, async () => {
+            const session = await this.openFromStore(handle.id, handle.workDir, handle.store, opts);
+            // A fork copies the subagent ledger; its background "running" rows have no live task → lost.
+            try {
+                await session.background?.reconcileSubagents() ?? [];
+            }
+            catch (error) {
+                await session.close();
+                throw error;
+            }
+            return session;
+        });
     }
     /** The currently-open session with this id, or undefined (does not reopen — use resumeSession). */
     getSession(id) {
@@ -1046,15 +1169,22 @@ export class Harness {
     /** Read a session's durable handle without constructing a Session, opening capabilities,
      *  reconciling background tasks, or subscribing Projection. Intended for read-only servers.
      *  Soft-deleted sessions resolve only with `{ includeDeleted: true }` — audit/purge tooling. */
-    inspectSession(id, options) {
-        return this.repo.open(id, options);
+    async inspectSession(id, options) {
+        return (await this.repository()).open(id, options);
     }
     /** Read one catalog row without the O(N) `listSessions()` scan. */
-    getSessionSummary(id) {
-        return this.repo.get(id);
+    async getSessionSummary(id) {
+        return (await this.repository()).get(id);
     }
-    /** Close one open session by id (no-op if it isn't open). */
+    /** Close one open session by id (no-op if it isn't open). An open in flight for this id is
+     *  waited for and then closed, so a close/delete never races a half-built session. */
     async closeSession(id) {
+        const inflight = this.opening.get(id);
+        if (inflight !== undefined) {
+            const session = await inflight.catch(() => undefined);
+            await session?.close();
+            return;
+        }
         await this.activeSessions.get(id)?.close();
     }
     /**
@@ -1063,30 +1193,72 @@ export class Harness {
      */
     async deleteSession(id, options) {
         await this.closeSession(id);
-        await this.repo.delete(id, options);
+        await (await this.repository()).delete(id, options);
     }
     /** Undo a soft delete. No-op when the session is absent or was never deleted. */
-    restoreSession(id) {
-        return this.repo.restore(id);
+    async restoreSession(id) {
+        return (await this.repository()).restore(id);
     }
     async listSessions(filter) {
-        return this.repo.list(filter);
+        return (await this.repository()).list(filter);
+    }
+    /** Set a session's title (an empty string clears it). Works on open and closed sessions alike. */
+    async renameSession(id, title) {
+        await (await this.repository()).rename(id, title.trim());
     }
-    async close() {
+    /**
+     * Close every open session, then the harness scope — which disposes everything registered
+     * there in reverse order: by-value `harness` halves die with the harness that ran them (each
+     * drained, then its dispose hook — default the instance's close()), then the host's own
+     * registrations, then the defaults.
+     */
+    close() {
+        if (this.closing !== undefined)
+            return this.closing;
+        this.closing = this.runClose();
+        return this.closing;
+    }
+    async runClose() {
+        // Opens in flight finish (or fail) first: closing the scope tree under a half-built session
+        // would tear its scope out from under `Session.open`. New opens are refused from here on
+        // (`assertAcceptingSessions`), so the set only shrinks.
+        await Promise.allSettled([...this.opening.values()]);
         for (const session of [...this.activeSessions.values()])
             await session.close();
-        // By-value `create` halves die with the harness that ran them: unregister each service,
-        // newest first, which drains it and runs its dispose hook (default: the instance's close()).
         await this.sharedReady.catch(() => undefined);
-        for (const name of [...this.createdServices].reverse())
-            await this.services.unregister(name);
+        // The `harness` halves' services, newest first: each is drained, then disposed (default, the
+        // instance's own close()). A failure here is logged, never allowed to skip the rest.
+        for (const name of [...this.createdServices].reverse()) {
+            try {
+                await this.services.unregister(name);
+            }
+            catch (error) {
+                this.logger.log("warn", `service "${name}" unregister failed during harness close`, {
+                    service: name,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
         this.createdServices.length = 0;
+        // Last: the process-shared objects the preset opened (MCP connections, handles). Every
+        // session is closed by now, so nothing is still reading them.
+        try {
+            await this.parts.close?.();
+        }
+        catch (error) {
+            this.logger.log("warn", "harness parts close failed", { error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    /** Every path that opens a session starts here: a closing harness opens nothing new. */
+    assertAcceptingSessions() {
+        if (this.closing !== undefined)
+            throw new Error("harness is closed");
     }
     /**
      * Replace by-value extensions with new versions, as one coordinated act — the by-value twin of
      * `harness.extensions.reload()` (docs/architecture.md §5.5). Every session holding
      * one of them rendezvous at its run boundary (in-flight runs finish untouched — nothing is
-     * aborted); in that global quiet moment the old halves detach, each `create` half re-runs and
+     * aborted); in that global quiet moment the old halves detach, each `harness` half re-runs and
      * its service is swapped, and the new halves attach; then everyone resumes. Sessions born from
      * the quiet moment on are born with the new definitions. On rendezvous timeout NOTHING changes:
      * the barrier lifts, `BarrierTimeout` names the stuck sessions, and the caller retries later
@@ -1098,7 +1270,7 @@ export class Harness {
      *
      * `services` swaps HOST-registered services (`createHarness({ services })`) in the same quiet
      * moment, for when the shape that changed is the host's rather than an extension's. Those obey
-     * their `replaceable` flag; an extension's own `create` service swaps unconditionally, since
+     * their `replaceable` flag; an extension's own `harness` service swaps unconditionally, since
      * its owner is being replaced along with it.
      *
      * Implementation-only swaps need none of this — `harness.services.replace` (layer 1) lands on
@@ -1114,14 +1286,14 @@ export class Harness {
                 throw new Error(`cannot replace extension "${definition.id}": it is not registered on this harness by value — pass it in createHarness({ extensions }), or use harness.extensions.reload("${definition.id}") for a file extension`);
             }
         }
-        // A `create` half still publishing would race the swap.
+        // A `harness` half still publishing would race the swap.
         await this.sharedReady;
-        // Every new `create` runs BEFORE the barrier: staging COLLECTS, so one that throws leaves the
+        // Every new `harness` runs BEFORE the barrier: staging COLLECTS, so one that throws leaves the
         // world completely untouched (no session detached, no service swapped) — the same discipline
         // construction and the file manager use. Whatever a failed act staged is disposed below.
         const staged = new Map();
         for (const definition of definitions) {
-            if (definition.create !== undefined)
+            if (definition.harness !== undefined)
                 staged.set(definition.id, await this.stageValue(definition));
         }
         const published = new Set();
@@ -1160,7 +1332,7 @@ export class Harness {
         }
         catch (error) {
             // Rendezvous timed out, or a step failed: nothing staged was published, so dispose it —
-            // a `create` that opened a pool must not leak it because the barrier never converged.
+            // a `harness` that opened a pool must not leak it because the barrier never converged.
             for (const [id, entry] of staged) {
                 if (!published.has(id) && entry.service !== undefined)
                     await this.disposeStaged(id, entry.service.instance);
@@ -1169,7 +1341,7 @@ export class Harness {
         }
     }
     /**
-     * The service half of one replaced extension: publish what its `create` staged. `replace`
+     * The service half of one replaced extension: publish what its `harness` staged. `replace`
      * rather than unregister + register, so consumers this barrier never gated — other extensions
      * holding a `uses` handle — see no gap; `force` because the owner is being replaced along with
      * it (see `ServiceRegistry.replace`).
@@ -1188,13 +1360,13 @@ export class Harness {
             }
             return;
         }
-        // The new version dropped its `create` half: its service goes away with it.
+        // The new version dropped its `harness` half: its service goes away with it.
         if (previous >= 0) {
             await this.services.unregister(id, drain);
             this.createdServices.splice(previous, 1);
         }
     }
-    /** Dispose a `create` result that was staged but never published (default rule: its `close()`). */
+    /** Dispose a `harness` result that was staged but never published (default rule: its `close()`). */
     async disposeStaged(id, instance) {
         try {
             const close = instance?.close;
@@ -1202,7 +1374,7 @@ export class Harness {
                 await close.call(instance);
         }
         catch (error) {
-            console.warn(`[extensions] extension "${id}": disposing the unpublished create result failed: ${error instanceof Error ? error.message : String(error)}`);
+            console.warn(`[extensions] extension "${id}": disposing the unpublished harness() result failed: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
     /**
@@ -1239,20 +1411,33 @@ export class Harness {
             this.activeBarrier = undefined;
         }
     }
-    /** Resolve the capability set for one session — calling the factory fresh when one was given. */
+    /** Resolve the capability set for one session — the `session` hook, called fresh every time. */
     async resolveCapabilities(ctx, params = {}) {
-        const configured = this.options.capabilities;
-        const base = typeof configured === "function"
-            ? await configured(ctx)
-            : configured ?? defaultCapabilities({ maxContextTokens: this.options.maxContextTokens });
-        // Every definition registered on this harness: by value (`extensions`, create halves
-        // included — their per-session `setup` is mounted here like any other), then from files.
+        // A session on its own environment (a sandbox) does not get the process's MCP connections or
+        // skill scan: both describe the HARNESS's machine, not the one this session's tools run on.
+        const base = this.options.session !== undefined
+            ? await this.options.session(ctx)
+            : defaultCapabilities({
+                shared: this.parts,
+                ownEnvironment: ctx.ownEnvironment,
+                strictIsolation: ctx.strictIsolation,
+                ...(ctx.mcpServers !== undefined ? { sessionMcpServers: ctx.mcpServers } : {}),
+                ...(ctx.mcpCredentials !== undefined ? { mcpCredentials: ctx.mcpCredentials } : {}),
+            });
+        // Every definition registered on this harness: by value (`extensions`, harness halves
+        // included — their per-session `session` is mounted here like any other), then from files.
         const extensions = [...this.valueDefs.values(), ...(this.extensions?.sessionDefinitions() ?? [])];
+        // An extension is mounted under its id, so one named like a capability the session already
+        // has would displace it — refused by name rather than resolved by order.
+        const baseNames = new Set(base.map((capability) => capability.name));
+        for (const definition of extensions) {
+            if (baseNames.has(definition.id)) {
+                throw new Error(`extension "${definition.id}" has the name of one of this session's capabilities; give it another id`);
+            }
+        }
         // Put extension transforms first. Shell PreToolUse remains in the staged permission policy,
         // so it evaluates the final rewritten args before normal authorization.
-        // Installed even when empty: the runtime must exist for `attachExtension` to have
-        // somewhere to land on sessions born without extensions.
-        return [extensionsCapability(extensions, { host: this.extensionHost(ctx.sessionId), params }), ...base];
+        return [...extensionsCapability(extensions, { host: this.extensionHost(ctx.sessionId), params }), ...base];
     }
     /**
      * The harness-tier reach handed to a session's extensions: other sessions, and the model
@@ -1264,7 +1449,7 @@ export class Harness {
      */
     extensionHost(sessionId) {
         const self = this;
-        const runtime = this.options.modelRuntime;
+        const runtime = this.parts.modelRuntime;
         return {
             sessionId,
             newSession: (options) => self.createSession({ ...(options?.title !== undefined ? { title: options.title } : {}) }),
@@ -1281,7 +1466,10 @@ export class Harness {
                     throw new Error("unregisterProvider() requires the harness to be built with a `modelRuntime`");
                 runtime.models.deleteProvider(id);
             },
-            services: self.services,
+            services: {
+                has: (name) => self.services.has(name),
+                handle: (name) => self.services.handle(name),
+            },
             isIdle: () => self.activeSessions.get(sessionId)?.status.state !== "running",
             waitForIdle: async () => {
                 const session = self.activeSessions.get(sessionId);
@@ -1293,8 +1481,8 @@ export class Harness {
         };
     }
     async openFromStore(id, workDir, store, opts) {
-        // A session's `setup` reaches a create half through its service, so none opens before the
-        // create halves have registered them.
+        // A session's `session` reaches a harness half through its service, so none opens before the
+        // harness halves have registered them.
         await this.sharedReady;
         // Per-session extension params: given at create, persisted, and read back on every later
         // open (resume, fork) so a session keeps them without the caller repeating them.
@@ -1303,65 +1491,130 @@ export class Harness {
             await store.putState(EXTENSION_PARAMS_STATE_KEY, params);
         else
             params = (await store.getState(EXTENSION_PARAMS_STATE_KEY)) ?? undefined;
-        const events = new ListenerSink();
-        const responder = new MutableResponder();
-        // ONE open-time log read, shared: the projection seeds from it, and Session.open
-        // receives it as `preloadedLog` so its capability restore + context pre-build fold the
-        // same records — same IO, and the same `Message` objects (no second parsed copy).
-        // Attach still happens BEFORE Session.open: no events flow yet, so the seed cannot
-        // race the subscription, and anything capabilities emit during open is already folded.
-        let preloadedLog = await readLog(store);
-        const projection = await SessionProjection.attach({ id, store, events }, preloadedLog);
-        const interrupted = await store.getState(INTERRUPTION_STATE_KEY) !== null;
-        if (!interrupted) {
-            const recoveryRecords = await closeOrphanedProjectionFrames(id, store, projection);
-            if (recoveryRecords.length > 0)
-                preloadedLog = [...preloadedLog, ...recoveryRecords];
-        }
-        const core = await Session.open({
-            sessionId: id,
-            store,
-            preloadedLog,
-            events,
-            responder,
-            machine: opts.machine ?? this.options.machine ?? new LocalMachine(workDir),
-            capabilities: await this.resolveCapabilities({
+        await this.sharedReady;
+        // From here the open is a transaction: the session is registered as active only once every
+        // step has succeeded, and any failure tears down exactly what was built — the projection, the
+        // core when it got that far — before rethrowing.
+        let projection;
+        let core;
+        try {
+            const events = new ListenerSink();
+            const responder = new MutableResponder();
+            // Environment: this call's override → the harness's default → a LocalEnvironment at the
+            // session's own workDir. The session only OPERATES a caller-supplied environment.
+            const environment = opts.environment ?? this.parts.environment ?? new LocalEnvironment(workDir);
+            // ONE open-time log read, shared: every shard from its newest checkpoint on (each
+            // checkpoint carries the history and lifecycle before it). The projection seeds from it,
+            // and Session.open receives it as `preloadedLog` so its capability restore + context
+            // pre-build fold the same records — same IO, and the same `Message` objects.
+            // Attach still happens BEFORE Session.open: no events flow yet, so the seed cannot
+            // race the subscription, and anything capabilities emit during open is already folded.
+            let preloadedLog = await readSessionTails(store);
+            // A fresh session has an empty log; anything else is a reopen. Telemetry is the only reader.
+            const resumed = preloadedLog.length > 0;
+            projection = await SessionProjection.attach({ id, store, events }, preloadedLog);
+            const interrupted = await store.getState(INTERRUPTION_STATE_KEY) !== null;
+            if (!interrupted) {
+                const recoveryRecords = await closeOrphanedProjectionFrames(id, store, projection);
+                if (recoveryRecords.length > 0)
+                    preloadedLog = [...preloadedLog, ...recoveryRecords];
+            }
+            const capabilities = await this.resolveCapabilities({
                 sessionId: id,
                 workDir,
+                ownEnvironment: opts.environment !== undefined,
+                strictIsolation: opts.strictIsolation === true,
                 ...(opts.mcpServers !== undefined ? { mcpServers: opts.mcpServers } : {}),
-            }, params),
-            permission: opts.permission ?? this.options.permission ?? { mode: "yolo" },
-            eventPublication: opts.eventPublication ?? this.options.eventPublication ?? "immediate",
-            // undefined → core resolves the `AGENTS_LOG` env fallback in Session.open.
-            logger: this.options.logger,
-        });
-        const agent = opts.agent ??
-            this.options.agent ??
-            (await this.buildDefaultAgent(opts.appendSystemPrompt, opts.maxStepsPerTurn));
-        const session = new HarnessSession({
-            core,
-            // The two caps land in different places: maxStepsPerTurn is an Agent property
-            // (the Runner reads the agent's value first), maxTurns is a per-run option.
-            agent,
-            runner: this.runner,
-            events,
-            responder,
-            projection,
-            workDir,
-            context: this.contextFor(opts),
-            ...(opts.maxTurns ?? this.options.maxTurns) !== undefined
-                ? { maxTurns: opts.maxTurns ?? this.options.maxTurns }
-                : {},
-            interrupted,
-            onClosed: (sid) => this.activeSessions.delete(sid),
-        });
-        this.activeSessions.set(id, session);
-        // Born gated: a session appearing while a reshape barrier holds (createSession,
-        // resumeSession and openSession all land here) must not start runs mid-swap. Its
-        // quiescent is trivially settled — it has no run — so it never delays the rendezvous.
-        if (this.activeBarrier !== undefined)
-            this.activeBarrier.holds.set(id, session.holdAtBoundary());
-        return session;
+                ...(opts.mcpCredentials !== undefined ? { mcpCredentials: opts.mcpCredentials } : {}),
+            }, params);
+            // Everything the session runs on, by value. The repository owns the store's lifetime.
+            core = await Session.open({
+                capabilities,
+                preloadedLog,
+                resumed,
+                sessionId: id,
+                store,
+                events,
+                responder,
+                environment,
+                permissionOptions: opts.permission ?? this.options.permission ?? { mode: "yolo" },
+                ...(this.parts.logger !== undefined ? { logger: this.parts.logger } : {}),
+                ...(this.parts.tracing !== undefined ? { tracing: this.parts.tracing } : {}),
+                ...(this.parts.telemetry !== undefined ? { telemetry: this.parts.telemetry } : {}),
+                ...(opts.eventPublication ?? this.parts.eventPublication) !== undefined
+                    ? { eventPublication: (opts.eventPublication ?? this.parts.eventPublication) }
+                    : {},
+            });
+            const agent = opts.agent ??
+                this.options.agent ??
+                (await this.buildDefaultAgent(opts.appendSystemPrompt, opts.maxStepsPerTurn));
+            const session = new HarnessSession({
+                core,
+                // The two caps land in different places: maxStepsPerTurn is an Agent property
+                // (the Runner reads the agent's value first), maxTurns is a per-run option.
+                agent,
+                runner: this.runner,
+                events,
+                responder,
+                projection,
+                workDir,
+                context: this.contextFor(opts),
+                ...(opts.maxTurns ?? this.options.maxTurns) !== undefined
+                    ? { maxTurns: opts.maxTurns ?? this.options.maxTurns }
+                    : {},
+                interrupted,
+                mountExtension: (definition) => {
+                    if (params?.[definition.id] === false) {
+                        throw new Error(`extension "${definition.id}" is opted out for this session (params["${definition.id}"] is false)`);
+                    }
+                    return extensionCapability(definition, { host: this.extensionHost(id), params: params?.[definition.id], startReason: "attach" });
+                },
+                onClosed: (sid) => {
+                    // Only THIS instance's registration goes — a later open under the same id (a resume
+                    // that waited for this close) must keep its own.
+                    if (this.activeSessions.get(sid) === session)
+                        this.activeSessions.delete(sid);
+                },
+            });
+            this.activeSessions.set(id, session);
+            // Born gated: a session appearing while a reshape barrier holds (createSession,
+            // resumeSession and openSession all land here) must not start runs mid-swap. Its
+            // quiescent is trivially settled — it has no run — so it never delays the rendezvous.
+            if (this.activeBarrier !== undefined)
+                this.activeBarrier.holds.set(id, session.holdAtBoundary());
+            return session;
+        }
+        catch (error) {
+            await this.rollbackOpen(id, { projection, core }, error);
+            throw error;
+        }
+    }
+    /**
+     * Undo a failed `openFromStore`, newest artifact first. Every step runs even if an earlier one
+     * throws (a cleanup failure is logged, never allowed to mask the open's own error).
+     */
+    async rollbackOpen(id, built, cause) {
+        const logger = this.parts.logger;
+        const attempt = async (step, run) => {
+            try {
+                await run();
+            }
+            catch (error) {
+                logger?.log("warn", `session open rollback: ${step} failed`, {
+                    sessionId: id,
+                    step,
+                    error: error instanceof Error ? error.message : String(error),
+                    cause: cause instanceof Error ? cause.message : String(cause),
+                });
+            }
+        };
+        await attempt("detach projection", () => built.projection?.detach());
+        if (built.core !== undefined)
+            await attempt("close core", () => built.core.close());
+    }
+    /** Every definition this harness mounts, by value then from files. */
+    allDefinitions() {
+        return [...this.valueDefs.values(), ...(this.extensions?.sessionDefinitions() ?? [])];
     }
     contextFor(options) {
         return hasOwnContext(options) ? options.context : this.options.context;
@@ -1378,7 +1631,7 @@ export class Harness {
  *
  * A worker that dies mid-turn journals no `turn.ended`; to every reader the turn is still
  * running. Opening the session repairs that (the same recovery runs inside `resumeSession`),
- * but opening boots capabilities and a machine just to write two records. This does only the
+ * but opening boots capabilities and an environment just to write two records. This does only the
  * repair: fold the log, and for every frame still inside a turn append `turn.ended` with
  * `reason: "failed"` (and `agent.ended` for a live sub-agent). Returns the events those records
  * project to, so a host that has live subscribers can hand them on — a record appended here
@@ -1389,7 +1642,7 @@ export class Harness {
 export async function closeOrphanedTurns(sessionId, store) {
     if ((await store.getState(INTERRUPTION_STATE_KEY)) !== null)
         return [];
-    const projection = await SessionProjection.attach({ id: sessionId, store, events: new ListenerSink() }, await readLog(store));
+    const projection = await SessionProjection.attach({ id: sessionId, store, events: new ListenerSink() }, await readSessionTails(store));
     const records = await closeOrphanedProjectionFrames(sessionId, store, projection);
     const events = [];
     for (const record of records) {