operon-agents 0.1.0-alpha.5 → 0.1.0-alpha.6

package/dist/harness.d.ts

@@ -19,6 +19,11 @@ export type QuestionHandler = (request: QuestionRequest, options?: {
     readonly signal?: AbortSignal;
 }) => Promise<QuestionResult> | QuestionResult;
 export type HarnessSessionState = "idle" | "running" | "interrupted" | "closed";
+/** Test-only (exported via `operon-agents/internal`): shrink the close deadlines. */
+export declare function setHarnessCloseTimeoutsForTest(ms: {
+    runSettle?: number;
+    scopeDispose?: number;
+}): void;
 export type DeliveryMode = "auto" | "steer" | "follow_up";
 export interface DeliveryOptions {
     readonly source: string;
@@ -402,17 +407,27 @@ export declare class HarnessSession<TContext = unknown> {
     private readonly responder;
     private readonly onClosed;
     private runContext;
-    private 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. */
     private runGate;
-    /** Resolves when the latest run settles — the "arrived at the boundary" signal a barrier
-     *  coordinator awaits. Undefined while idle. */
-    private runSettled;
-    private readonly runSettles;
+    /**
+     * 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.
+     */
+    private readonly runs;
     private lastRunInterrupted;
-    private closed;
+    /** open → closing (runs being drained, resources going down) → closed. Never goes back. */
+    private lifecycle;
+    /** The one close in flight (or finished): every `close()` call returns THIS promise. */
+    private 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. */
+    private notifyClosing;
+    private readonly closingNotified;
     private deliveryCounter;
     /** A wake is already scheduled on the microtask queue; more enqueues fold into it. */
     private wakeScheduled;
@@ -435,11 +450,19 @@ export declare class HarnessSession<TContext = unknown> {
      * 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.
      */
     private scheduleIdleWake;
+    /** Not open: closing or closed. Every run entry point refuses from here on. */
+    private get closed();
+    /**
+     * 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.
+     */
+    private parkAtGate;
     /** Run options every run on this session carries — currently the session's turn cap. */
     private get runOverrides();
     /** Current runtime-only application context supplied to Agent callbacks. */
@@ -452,6 +475,10 @@ export declare class HarnessSession<TContext = unknown> {
     setContext(context: TContext | undefined): void;
     private beginRun;
     private endRun;
+    /** A run is in flight or queued behind the core's run lock. */
+    private hasActiveRuns;
+    /** Settles when every run begun so far has settled (trivially, when idle). */
+    private allRunsSettled;
     /**
      * Barrier support (docs/architecture.md §5.5): refuse NEW runs until released and
      * report when this session reaches its run boundary. Installing the gate is synchronous — a
@@ -538,7 +565,7 @@ export declare class HarnessSession<TContext = unknown> {
      * active run — use `prompt` instead in that case.
      */
     followUp(input: string): string | null;
-    /** Abort the current run. */
+    /** Abort every run this session has accepted: the one in flight AND any queued behind it. */
     cancel(): void;
     /** Subscribe to this session's event stream. Returns an unsubscribe fn. */
     onEvent(listener: AgentEventListener): () => void;
@@ -621,8 +648,18 @@ export declare class HarnessSession<TContext = unknown> {
     listMcpTools(...args: Parameters<Session["listMcpTools"]>): ReturnType<Session["listMcpTools"]>;
     listMcpServers(...args: Parameters<Session["listMcpServers"]>): ReturnType<Session["listMcpServers"]>;
     reconnectMcpServer(...args: Parameters<Session["reconnectMcpServer"]>): ReturnType<Session["reconnectMcpServer"]>;
-    /** Close the session and release its resources. */
+    /**
+     * 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(): Promise<void>;
+    private runClose;
 }
 /** Manages a fleet of in-process sessions over a shared engine config. */
 export declare class Harness<TContext = unknown> {
@@ -631,6 +668,11 @@ export declare class Harness<TContext = unknown> {
     /** Concrete tools the default profile's tool NAMES resolve against (keyed by schema name). */
     private readonly toolPalette;
     private readonly activeSessions;
+    /** 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. */
+    private readonly opening;
+    /** The one close in flight (or finished): every `close()` call returns THIS promise. */
+    private closing;
     /** The harness-tier scope: every process-lived object, and the parent of every workspace scope. */
     readonly scope: Scope<"harness">;
     /** Workspace scopes by key, reference-counted by the sessions open under them. */
@@ -692,6 +734,19 @@ export declare class Harness<TContext = unknown> {
     private buildDefaultAgent;
     get sessions(): ReadonlyMap<string, HarnessSession<TContext>>;
     createSession(opts?: CreateSessionOptions<TContext>): Promise<HarnessSession<TContext>>;
+    /**
+     * 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.
+     */
+    private trackOpen;
+    /**
+     * 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: string, opts?: ResumeSessionOptions<TContext>): Promise<HarnessSession<TContext>>;
     /** Fork an existing session into a new one (copies its log + state) and open it. */
     forkSession(sourceId: string, opts?: ForkSessionOptions<TContext>): Promise<HarnessSession<TContext>>;
@@ -703,7 +758,8 @@ export declare class Harness<TContext = unknown> {
     inspectSession(id: string, options?: OpenSessionOptions): Promise<SessionHandle | undefined>;
     /** Read one catalog row without the O(N) `listSessions()` scan. */
     getSessionSummary(id: string): Promise<SessionSummary | undefined>;
-    /** 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. */
     closeSession(id: string): Promise<void>;
     /**
      * Delete a session after releasing any open in-process handle. Soft by default — the durable
@@ -720,6 +776,9 @@ export declare class Harness<TContext = unknown> {
      * registrations, then the defaults.
      */
     close(): Promise<void>;
+    private runClose;
+    /** Every path that opens a session starts here: a closing harness opens nothing new. */
+    private assertAcceptingSessions;
     /**
      * 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
@@ -779,6 +838,12 @@ export declare class Harness<TContext = unknown> {
      */
     private extensionHost;
     private openFromStore;
+    /**
+     * 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), and the
+     * workspace hold this open took is always returned.
+     */
+    private rollbackOpen;
     /**
      * The workspace scope for `key`, composed on first use — the host's `workspace` hook, then
      * every registered extension's `workspace` half — and ref-counted by the sessions under it.
@@ -786,6 +851,8 @@ export declare class Harness<TContext = unknown> {
     private acquireWorkspace;
     /** Drop one session's hold; the last one out closes the workspace scope. */
     private releaseWorkspace;
+    /** Close options for a scope the harness tears down itself: per-service deadline, failures logged. */
+    private scopeCloseOptions;
     /**
      * A handle to a workspace-tier extension service in ONE workspace — how a host reaches a
      * `workspace` half's instance (`harness.services.handle` only answers for the harness tier).

package/dist/harness.js

@@ -19,6 +19,19 @@ import { mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { assertOneSharedHalf, extensionsCapability, ExtensionRuntime, 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;
+/** Per-service dispose deadline when the harness tears a scope down itself — a workspace whose
+ *  last session left, a session scope a failed open rolls back, the harness scope on close.
+ *  Mirrors the core session's own close deadline: one hung MCP shutdown must not hang close(). */
+let SCOPE_DISPOSE_TIMEOUT_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;
+    if (ms.scopeDispose !== undefined)
+        SCOPE_DISPOSE_TIMEOUT_MS = ms.scopeDispose;
+}
 /** 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 })`). */
@@ -153,17 +166,29 @@ 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;
+    /** 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;
+    });
     deliveryCounter = 0;
     /** A wake is already scheduled on the microtask queue; more enqueues fold into it. */
     wakeScheduled = false;
@@ -193,7 +218,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.
      */
@@ -211,7 +236,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
@@ -223,6 +248,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 } : {};
@@ -235,7 +276,7 @@ export class HarnessSession {
         return {
             state: this.closed
                 ? "closed"
-                : this.currentRun !== undefined
+                : this.hasActiveRuns()
                     ? "running"
                     : this.lastRunInterrupted
                         ? "interrupted"
@@ -258,16 +299,23 @@ 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);
+    }
+    /** 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
@@ -284,7 +332,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: () => {
@@ -303,10 +351,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 {
@@ -330,7 +379,7 @@ 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.
+            // saw an active run and stood down, so the run itself has to look once on the way out.
             this.scheduleIdleWake();
         }
     }
@@ -343,7 +392,7 @@ export class HarnessSession {
         if (this.closed || this.lastRunInterrupted)
             return false;
         // A run in flight drains its own queues, so handing the message to the frame is enough.
-        if (this.currentRun !== undefined)
+        if (this.hasActiveRuns())
             return this.core.steerTo(address, content, origin);
         // 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
@@ -375,7 +424,7 @@ export class HarnessSession {
     async deliver(input, options) {
         if (this.closed)
             throw new Error(`session "${this.id}" is closed`);
-        if (this.lastRunInterrupted && this.currentRun === undefined) {
+        if (this.lastRunInterrupted && !this.hasActiveRuns()) {
             throw new Error(`session "${this.id}" is interrupted; resume it before delivering new work`);
         }
         if (!options.source.trim())
@@ -438,7 +487,7 @@ export class HarnessSession {
         const channel = origin.kind === "external"
             ? origin.channel ?? "steering"
             : origin.kind === "user_follow_up" ? "follow_up" : "steering";
-        if (this.currentRun !== undefined) {
+        if (this.hasActiveRuns()) {
             const receipt = this.core.steer.steer(input, origin);
             return {
                 deliveryId,
@@ -491,11 +540,13 @@ 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
@@ -535,6 +586,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 —
@@ -544,8 +597,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, {
@@ -571,6 +623,9 @@ export class HarnessSession {
         })
             .finally(() => {
             this.endRun(controller);
+            // Same as runPrompt's exit: input queued after this run's last drain (a background
+            // notification landing at agent.ended) needs a wake, or it sits until the next prompt.
+            this.scheduleIdleWake();
         });
         // Guard the floating promise so iterate-only callers don't trip an unhandled rejection
         // (mirrors runStream's own internal guard); awaiters still receive a real rejection.
@@ -619,13 +674,14 @@ export class HarnessSession {
      * 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;
     }
-    /** 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) {
@@ -833,15 +889,50 @@ export class HarnessSession {
     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();
-        await this.onClosed(this.id);
+    /**
+     * 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 {
+            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);
+        }
+        finally {
+            this.lifecycle = "closed";
+        }
     }
 }
 /** Manages a fleet of in-process sessions over a shared engine config. */
@@ -851,6 +942,11 @@ export class Harness {
     /** Concrete tools the default profile's tool NAMES resolve against (keyed by schema name). */
     toolPalette;
     activeSessions = new Map();
+    /** 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 harness-tier scope: every process-lived object, and the parent of every workspace scope. */
     scope;
     /** Workspace scopes by key, reference-counted by the sessions open under them. */
@@ -1070,36 +1166,91 @@ export class Harness {
         return this.activeSessions;
     }
     async createSession(opts = {}) {
+        this.assertAcceptingSessions();
         const workDir = opts.workDir ?? this.options.workDir ?? process.cwd();
         const handle = await (await this.repository()).create({ id: opts.id, workDir, ownerKey: opts.ownerKey, title: opts.title });
-        return this.openFromStore(handle.id, handle.workDir, handle.store, opts);
+        return this.trackOpen(handle.id, () => this.openFromStore(handle.id, handle.workDir, handle.store, 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;
     }
-    async resumeSession(id, opts = {}) {
+    /**
+     * 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 (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.
-        await session.reconcileSubagents();
-        return session;
+        return this.trackOpen(id, async () => {
+            // `existing` here is one that is closing: wait for that close (its registration and
+            // workspace hold go 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.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 = {}) {
+        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.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) {
@@ -1115,8 +1266,15 @@ export class Harness {
     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();
     }
     /**
@@ -1140,12 +1298,27 @@ export class Harness {
      * drained, then its dispose hook — default the instance's close()), then the host's own
      * registrations, then the defaults.
      */
-    async close() {
+    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();
         await this.sharedReady.catch(() => undefined);
         this.createdServices.length = 0;
-        await this.scope.close();
+        await this.scope.close(this.scopeCloseOptions());
+    }
+    /** 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
@@ -1401,88 +1574,126 @@ export class Harness {
         // The workspace scope (one per key, shared) and under it the session scope: what the harness
         // decides for this session goes in here; Session.open provides the defaults for the rest,
         // and from then on the session owns the scope.
+        // 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 — projection, the
+        // session scope (via the core when it got that far), the workspace hold — before rethrowing.
+        // Half-open leftovers are what kept a workspace alive after its last real session closed.
         const workspace = await this.acquireWorkspace(workspaceKey, workDir);
         let scope;
+        let projection;
+        let core;
         try {
             scope = workspace.child("session");
+            scope.register(T.SessionId, id);
+            scope.register(T.StoreBackend, store, { owned: false }); // the repository owns the store's lifetime
+            const events = new ListenerSink();
+            scope.register(T.Events, events);
+            const responder = new MutableResponder();
+            scope.register(T.Responder, responder);
+            // Machine: this call's override → the harness-level factory (resolved by Session.open) →
+            // a LocalMachine at the session's own workDir. The session only OPERATES a caller-supplied
+            // machine; the default one is its own.
+            if (opts.machine !== undefined) {
+                if (typeof opts.machine === "function")
+                    scope.register(T.SessionMachineFactory, opts.machine);
+                else
+                    scope.register(T.Machine, opts.machine, { owned: false });
+            }
+            else if (!workspace.has(T.WorkspaceMachineFactory) && !this.scope.has(T.MachineFactory)) {
+                scope.provide(T.Machine, () => new LocalMachine(workDir));
+            }
+            scope.register(T.PermissionOptions, opts.permission ?? this.options.permission ?? { mode: "yolo" });
+            if (opts.eventPublication !== undefined)
+                scope.register(T.SessionEventPublication, opts.eventPublication);
+            // 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);
+            // 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(scope, {
+                sessionId: id,
+                workDir,
+                ownMachine: opts.machine !== undefined,
+                ...(opts.mcpServers !== undefined ? { mcpServers: opts.mcpServers } : {}),
+            }, params);
+            core = await Session.open(scope, { capabilities, preloadedLog, resumed });
+            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: async (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. The workspace hold is this
+                    // instance's regardless and is always returned.
+                    if (this.activeSessions.get(sid) === session)
+                        this.activeSessions.delete(sid);
+                    await this.releaseWorkspace(workspaceKey);
+                },
+            });
+            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.releaseWorkspace(workspaceKey);
+            await this.rollbackOpen(id, workspaceKey, { projection, core, scope }, error);
             throw error;
         }
-        scope.register(T.SessionId, id);
-        scope.register(T.StoreBackend, store, { owned: false }); // the repository owns the store's lifetime
-        const events = new ListenerSink();
-        scope.register(T.Events, events);
-        const responder = new MutableResponder();
-        scope.register(T.Responder, responder);
-        // Machine: this call's override → the harness-level factory (resolved by Session.open) →
-        // a LocalMachine at the session's own workDir. The session only OPERATES a caller-supplied
-        // machine; the default one is its own.
-        if (opts.machine !== undefined) {
-            if (typeof opts.machine === "function")
-                scope.register(T.SessionMachineFactory, opts.machine);
-            else
-                scope.register(T.Machine, opts.machine, { owned: false });
-        }
-        else if (!workspace.has(T.WorkspaceMachineFactory) && !this.scope.has(T.MachineFactory)) {
-            scope.provide(T.Machine, () => new LocalMachine(workDir));
-        }
-        scope.register(T.PermissionOptions, opts.permission ?? this.options.permission ?? { mode: "yolo" });
-        if (opts.eventPublication !== undefined)
-            scope.register(T.SessionEventPublication, opts.eventPublication);
-        // 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);
-        // A fresh session has an empty log; anything else is a reopen. Telemetry is the only reader.
-        const resumed = preloadedLog.length > 0;
-        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 capabilities = await this.resolveCapabilities(scope, {
-            sessionId: id,
-            workDir,
-            ownMachine: opts.machine !== undefined,
-            ...(opts.mcpServers !== undefined ? { mcpServers: opts.mcpServers } : {}),
-        }, params);
-        const core = await Session.open(scope, { capabilities, preloadedLog, resumed });
-        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: async (sid) => {
-                this.activeSessions.delete(sid);
-                await this.releaseWorkspace(workspaceKey);
-            },
-        });
-        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;
+    }
+    /**
+     * 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), and the
+     * workspace hold this open took is always returned.
+     */
+    async rollbackOpen(id, workspaceKey, built, cause) {
+        const logger = this.scope.get(T.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());
+        // The core owns the scope once it opened; before that the scope is ours to close.
+        if (built.core !== undefined)
+            await attempt("close core", () => built.core.close());
+        else if (built.scope !== undefined)
+            await attempt("close scope", () => built.scope.close(this.scopeCloseOptions(id)));
+        await attempt("release workspace", () => this.releaseWorkspace(workspaceKey));
     }
     /**
      * The workspace scope for `key`, composed on first use — the host's `workspace` hook, then
@@ -1520,7 +1731,21 @@ export class Harness {
         if (entry.refs > 0)
             return;
         this.workspaces.delete(key);
-        await entry.scope.close();
+        await entry.scope.close(this.scopeCloseOptions(undefined, key));
+    }
+    /** Close options for a scope the harness tears down itself: per-service deadline, failures logged. */
+    scopeCloseOptions(sessionId, workspaceKey) {
+        return {
+            disposeTimeoutMs: SCOPE_DISPOSE_TIMEOUT_MS,
+            onDisposeError: (name, error) => {
+                this.scope.get(T.Logger)?.log("warn", `service "${name}" dispose failed/timed out`, {
+                    service: name,
+                    ...(sessionId !== undefined ? { sessionId } : {}),
+                    ...(workspaceKey !== undefined ? { workspaceKey } : {}),
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            },
+        };
     }
     /**
      * A handle to a workspace-tier extension service in ONE workspace — how a host reaches a

package/dist/internal.d.ts

@@ -6,4 +6,5 @@
  * No stability guarantees — prefer the main `operon-agents` surface.
  */
 export * from "operon-agents-core/internal";
+export { setHarnessCloseTimeoutsForTest } from "./harness.ts";
 //# sourceMappingURL=internal.d.ts.map

package/dist/internal.js

@@ -6,4 +6,5 @@
  * No stability guarantees — prefer the main `operon-agents` surface.
  */
 export * from "operon-agents-core/internal";
+export { setHarnessCloseTimeoutsForTest } from "./harness.js";
 //# sourceMappingURL=internal.js.map

package/dist/local.js

@@ -56,11 +56,13 @@ export async function localHarnessOptions(options) {
             await workspace?.(scope, ctx);
             // Skills follow the workspace's EXECUTION machine, not the host's disk: the catalog the
             // model sees must be the one whose scripts its Bash can reach. A remote workspace
-            // registers its machine above and the scan runs through it. A machine FACTORY (one
+            // registers its machine above and the scan runs through it; absent that, the harness's
+            // default (`T.MachineFactory`, read through the parent chain) is what sessions here will
+            // execute on — the same precedence `Session.open` resolves. A machine FACTORY (one
             // machine per session) has no single filesystem to scan — no shared registry then; each
             // session scans through its own `T.Machine` (`defaultCapabilities` without `T.SkillRegistry`).
             if (!scope.hasLocal(T.SkillRegistry)) {
-                const workspaceMachine = scope.get(T.WorkspaceMachineFactory) ?? new LocalMachine(ctx.workDir);
+                const workspaceMachine = scope.get(T.WorkspaceMachineFactory) ?? scope.get(T.MachineFactory) ?? new LocalMachine(ctx.workDir);
                 if (typeof workspaceMachine !== "function") {
                     const registry = new SkillRegistry();
                     await loadSkillRoots(workspaceMachine, registry, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "operon-agents",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.6",
   "description": "Public SDK entrypoint for building agents.",
   "type": "module",
   "engines": {
@@ -72,7 +72,7 @@
   "dependencies": {
     "posthog-node": "^5.51.6",
     "zod": "^4.4.3",
-    "operon-agents-core": "0.1.0-alpha.5"
+    "operon-agents-core": "0.1.0-alpha.6"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "0.84.1"