@velum-labs/routekit-harness-core 0.18.6 → 1.0.0

package/dist/channel.d.ts

@@ -4,9 +4,18 @@
  * drivers (ACP, SSE) to bridge notification callbacks into the `sendTurn`
  * async iterable.
  */
+export type AsyncChannelOptions = {
+    /** Maximum number of values retained while the consumer is not reading. */
+    capacity?: number;
+    /** Overflow is explicit: fail the stream or retain only the newest values. */
+    overflow?: "error" | "drop-oldest";
+    /** Invoked when the consumer returns before the producer closes the stream. */
+    onConsumerReturn?: () => void;
+};
 export declare class AsyncChannel<T> {
     #private;
-    push(value: T): void;
+    constructor(options?: AsyncChannelOptions);
+    push(value: T): boolean;
     close(error?: unknown): void;
     [Symbol.asyncIterator](): AsyncGenerator<T>;
 }

package/dist/channel.js

@@ -1,24 +1,39 @@
-/**
- * A single-consumer async channel: producers `push` values (or `close`), the
- * consumer drains them via `[Symbol.asyncIterator]`. Used by transport-driven
- * drivers (ACP, SSE) to bridge notification callbacks into the `sendTurn`
- * async iterable.
- */
 export class AsyncChannel {
     #queue = [];
+    #capacity;
+    #overflow;
+    #onConsumerReturn;
     #waiter;
     #closed = false;
     #error;
+    constructor(options = {}) {
+        this.#capacity = options.capacity ?? 256;
+        if (!Number.isSafeInteger(this.#capacity) || this.#capacity < 1) {
+            throw new RangeError("AsyncChannel capacity must be a positive safe integer");
+        }
+        this.#overflow = options.overflow ?? "error";
+        this.#onConsumerReturn = options.onConsumerReturn;
+    }
     push(value) {
         if (this.#closed)
-            return;
+            return false;
         if (this.#waiter !== undefined) {
             const resolve = this.#waiter;
             this.#waiter = undefined;
             resolve({ value, done: false });
-            return;
+            return true;
+        }
+        if (this.#queue.length >= this.#capacity) {
+            if (this.#overflow === "drop-oldest") {
+                this.#queue.shift();
+            }
+            else {
+                this.close(new Error(`AsyncChannel capacity ${this.#capacity} exceeded`));
+                return false;
+            }
         }
         this.#queue.push(value);
+        return true;
     }
     close(error) {
         if (this.#closed)
@@ -38,25 +53,34 @@ export class AsyncChannel {
         }
     }
     async *[Symbol.asyncIterator]() {
-        for (;;) {
-            if (this.#queue.length > 0) {
-                yield this.#queue.shift();
-                continue;
-            }
-            if (this.#closed) {
-                if (this.#error !== undefined)
-                    throw this.#error;
-                return;
+        let drained = false;
+        try {
+            for (;;) {
+                if (this.#queue.length > 0) {
+                    yield this.#queue.shift();
+                    continue;
+                }
+                if (this.#closed) {
+                    drained = true;
+                    if (this.#error !== undefined)
+                        throw this.#error;
+                    return;
+                }
+                const next = await new Promise((resolve) => {
+                    this.#waiter = resolve;
+                });
+                if (next.done === true) {
+                    drained = true;
+                    if (this.#error !== undefined)
+                        throw this.#error;
+                    return;
+                }
+                yield next.value;
             }
-            const next = await new Promise((resolve) => {
-                this.#waiter = resolve;
-            });
-            if (next.done === true) {
-                if (this.#error !== undefined)
-                    throw this.#error;
-                return;
-            }
-            yield next.value;
+        }
+        finally {
+            if (!drained && !this.#closed)
+                this.#onConsumerReturn?.();
         }
     }
 }

package/dist/effect/lifecycle.d.ts

@@ -0,0 +1,10 @@
+import { Effect } from "effect";
+import { SessionResourceRegistry, SingleFlightTurnController, type TurnLease } from "../lifecycle.js";
+/**
+ * Effect façade over harness turn and session lifetime.
+ *
+ * The one-live-turn rule stays on `SingleFlightTurnController`. Scope close
+ * disposes an incomplete lease, which aborts the native operation.
+ */
+export declare function scopedTurn(controller: SingleFlightTurnController, external?: AbortSignal): Effect.Effect<TurnLease, import("@velum-labs/routekit-runtime/effect").RouteKitFailure, import("effect/Scope").Scope>;
+export declare function scopedSessionRegistry(registry: SessionResourceRegistry): Effect.Effect<SessionResourceRegistry, never, import("effect/Scope").Scope>;

package/dist/effect/lifecycle.js

@@ -0,0 +1,20 @@
+import { toRouteKitFailure } from "@velum-labs/routekit-runtime/effect";
+import { Effect } from "effect";
+/**
+ * Effect façade over harness turn and session lifetime.
+ *
+ * The one-live-turn rule stays on `SingleFlightTurnController`. Scope close
+ * disposes an incomplete lease, which aborts the native operation.
+ */
+export function scopedTurn(controller, external) {
+    return Effect.acquireRelease(Effect.try({
+        try: () => controller.start(external),
+        catch: (cause) => toRouteKitFailure(cause)
+    }), (lease) => Effect.sync(() => lease.dispose()));
+}
+export function scopedSessionRegistry(registry) {
+    return Effect.acquireRelease(Effect.succeed(registry), (owned) => Effect.tryPromise({
+        try: () => owned.dispose(),
+        catch: (cause) => toRouteKitFailure(cause)
+    }).pipe(Effect.ignore));
+}

package/dist/effect-api.d.ts

@@ -0,0 +1 @@
+export { scopedSessionRegistry, scopedTurn } from "./effect/lifecycle.js";

package/dist/effect-api.js

@@ -0,0 +1 @@
+export { scopedSessionRegistry, scopedTurn } from "./effect/lifecycle.js";

package/dist/errors.d.ts

@@ -3,7 +3,7 @@
  * these codes at the boundary where they occur; retryability and failover
  * category are derived from the code, never hand-picked per call site.
  */
-export declare const HARNESS_ERROR_CODES: readonly ["not_installed", "not_authenticated", "version_unsupported", "invalid_config", "session_closed", "protocol_parse", "timeout", "aborted", "provider_error"];
+export declare const HARNESS_ERROR_CODES: readonly ["not_installed", "not_authenticated", "version_unsupported", "invalid_config", "session_closed", "session_busy", "protocol_parse", "timeout", "aborted", "provider_error"];
 export type HarnessErrorCode = (typeof HARNESS_ERROR_CODES)[number];
 /** The gateway's provider-failover taxonomy. */
 export type HarnessErrorCategory = "transient" | "quota_exhausted" | "auth_permanent" | "context_overflow" | "unknown";

package/dist/errors.js

@@ -14,6 +14,8 @@ export const HARNESS_ERROR_CODES = [
     "invalid_config",
     /** The session existed but its process/connection has gone away. */
     "session_closed",
+    /** A second turn was attempted while the session already had a live turn. */
+    "session_busy",
     /** A wire payload failed schema/shape validation. */
     "protocol_parse",
     /** The run exceeded its deadline. */
@@ -41,6 +43,7 @@ function defaultCategoryFor(code) {
     switch (code) {
         case "timeout":
         case "session_closed":
+        case "session_busy":
             return "transient";
         case "not_authenticated":
             return "auth_permanent";

package/dist/index.d.ts

@@ -7,24 +7,27 @@
  * registry. Drivers (tool-codex, tool-claude, tool-cursor, tool-opencode)
  * implement this contract; orchestrators and launchers consume it.
  */
-export { HARNESS_KINDS, isHarnessKind } from "./kinds.js";
-export type { HarnessKind } from "./kinds.js";
-export { HARNESS_ERROR_CODES, HarnessError, asHarnessError, isRetryable } from "./errors.js";
-export type { HarnessErrorCategory, HarnessErrorCode } from "./errors.js";
-export type { HarnessContentStream, HarnessEvent, HarnessEventRaw, HarnessEventType, HarnessItemType, HarnessRequestType, HarnessTokenUsage, HarnessTurnEndReason } from "./events.js";
-export { DEFAULT_AUTOMATION_APPROVAL_POLICY, PendingRequests, createDeferred, decideApproval } from "./approvals.js";
 export type { ApprovalDecision, ApprovalPolicy, Deferred, PendingRequest } from "./approvals.js";
-export { DEFAULT_STATUS_CACHE_DIR, readCachedStatus, statusSkipReason, writeCachedStatus } from "./status.js";
-export type { HarnessAuthStatus, HarnessModelDescriptor, HarnessStatus } from "./status.js";
+export { createDeferred, DEFAULT_AUTOMATION_APPROVAL_POLICY, decideApproval, PendingRequests } from "./approvals.js";
+export type { AsyncChannelOptions } from "./channel.js";
+export { AsyncChannel } from "./channel.js";
 export type { AnyHarnessDriver, DriverContext, HarnessDriver, HarnessInstance, ResumeCursor, SessionHandle, SessionTurnInput, StartSessionOptions } from "./contract.js";
-export { DriverRegistry } from "./registry.js";
-export { createCachedHarnessDriver, probeCliVersion, resolveDriverEnv } from "./driver-factory.js";
 export type { CachedHarnessDriverInput, CliVersionProbeInput } from "./driver-factory.js";
-export { AsyncChannel } from "./channel.js";
-export { EventLog } from "./logging.js";
+export { createCachedHarnessDriver, probeCliVersion, resolveDriverEnv } from "./driver-factory.js";
+export type { HarnessErrorCategory, HarnessErrorCode } from "./errors.js";
+export { asHarnessError, HARNESS_ERROR_CODES, HarnessError, isRetryable } from "./errors.js";
+export type { HarnessContentStream, HarnessEvent, HarnessEventRaw, HarnessEventType, HarnessItemType, HarnessRequestType, HarnessTokenUsage, HarnessTurnEndReason } from "./events.js";
+export type { HarnessKind } from "./kinds.js";
+export { HARNESS_KINDS, isHarnessKind } from "./kinds.js";
+export type { TurnLease } from "./lifecycle.js";
+export { ManagedSession, nowIso, resumeStringField, SessionResourceRegistry, SingleFlightTurnController } from "./lifecycle.js";
 export type { EventLogOptions } from "./logging.js";
-export { asArray, asObject, asString, createStreamJsonStepEmitter, parseStreamJsonLine, parseStreamJsonTrajectory, streamJsonResultContentText, stringifyStreamJsonValue, STREAM_JSON_MAX_TEXT, STREAM_JSON_MAX_TOOL_INPUT, truncateStreamJsonText } from "./stream-json.js";
-export type { ParsedStreamJson, ParseStreamJsonOptions, StreamJsonEmitterOptions, StreamJsonStepText } from "./stream-json.js";
-export { DEFAULT_TMP_MANIFEST, createTrackedTmpDir, releaseTrackedTmpDir, sweepTrackedTmpDirs } from "./tmp-sweep.js";
-export { buildChildEnv, freePort, runCliCapture, spawnLogged, terminate, waitForHttp, waitForOutput, withDeadline, withTimeout } from "./process.js";
+export { EventLog } from "./logging.js";
 export type { BuildChildEnvInput, CliCaptureOptions, CliCaptureResult, LoggedChild, LoggedSpawnOptions } from "./process.js";
+export { buildChildEnv, freePort, runCliCapture, spawnLogged, terminate, waitForHttp, waitForOutput, withDeadline, withTimeout } from "./process.js";
+export { DriverRegistry } from "./registry.js";
+export type { HarnessAuthStatus, HarnessModelDescriptor, HarnessStatus } from "./status.js";
+export { DEFAULT_STATUS_CACHE_DIR, readCachedStatus, statusSkipReason, writeCachedStatus } from "./status.js";
+export type { ParsedStreamJson, ParseStreamJsonOptions, StreamJsonEmitterOptions, StreamJsonStepText } from "./stream-json.js";
+export { asArray, asObject, asString, createStreamJsonStepEmitter, parseStreamJsonLine, parseStreamJsonTrajectory, STREAM_JSON_MAX_TEXT, STREAM_JSON_MAX_TOOL_INPUT, streamJsonResultContentText, stringifyStreamJsonValue, truncateStreamJsonText } from "./stream-json.js";
+export { createTrackedTmpDir, DEFAULT_TMP_MANIFEST, releaseTrackedTmpDir, sweepTrackedTmpDirs } from "./tmp-sweep.js";

package/dist/index.js

@@ -7,14 +7,15 @@
  * registry. Drivers (tool-codex, tool-claude, tool-cursor, tool-opencode)
  * implement this contract; orchestrators and launchers consume it.
  */
-export { HARNESS_KINDS, isHarnessKind } from "./kinds.js";
-export { HARNESS_ERROR_CODES, HarnessError, asHarnessError, isRetryable } from "./errors.js";
-export { DEFAULT_AUTOMATION_APPROVAL_POLICY, PendingRequests, createDeferred, decideApproval } from "./approvals.js";
-export { DEFAULT_STATUS_CACHE_DIR, readCachedStatus, statusSkipReason, writeCachedStatus } from "./status.js";
-export { DriverRegistry } from "./registry.js";
-export { createCachedHarnessDriver, probeCliVersion, resolveDriverEnv } from "./driver-factory.js";
+export { createDeferred, DEFAULT_AUTOMATION_APPROVAL_POLICY, decideApproval, PendingRequests } from "./approvals.js";
 export { AsyncChannel } from "./channel.js";
+export { createCachedHarnessDriver, probeCliVersion, resolveDriverEnv } from "./driver-factory.js";
+export { asHarnessError, HARNESS_ERROR_CODES, HarnessError, isRetryable } from "./errors.js";
+export { HARNESS_KINDS, isHarnessKind } from "./kinds.js";
+export { ManagedSession, nowIso, resumeStringField, SessionResourceRegistry, SingleFlightTurnController } from "./lifecycle.js";
 export { EventLog } from "./logging.js";
-export { asArray, asObject, asString, createStreamJsonStepEmitter, parseStreamJsonLine, parseStreamJsonTrajectory, streamJsonResultContentText, stringifyStreamJsonValue, STREAM_JSON_MAX_TEXT, STREAM_JSON_MAX_TOOL_INPUT, truncateStreamJsonText } from "./stream-json.js";
-export { DEFAULT_TMP_MANIFEST, createTrackedTmpDir, releaseTrackedTmpDir, sweepTrackedTmpDirs } from "./tmp-sweep.js";
 export { buildChildEnv, freePort, runCliCapture, spawnLogged, terminate, waitForHttp, waitForOutput, withDeadline, withTimeout } from "./process.js";
+export { DriverRegistry } from "./registry.js";
+export { DEFAULT_STATUS_CACHE_DIR, readCachedStatus, statusSkipReason, writeCachedStatus } from "./status.js";
+export { asArray, asObject, asString, createStreamJsonStepEmitter, parseStreamJsonLine, parseStreamJsonTrajectory, STREAM_JSON_MAX_TEXT, STREAM_JSON_MAX_TOOL_INPUT, streamJsonResultContentText, stringifyStreamJsonValue, truncateStreamJsonText } from "./stream-json.js";
+export { createTrackedTmpDir, DEFAULT_TMP_MANIFEST, releaseTrackedTmpDir, sweepTrackedTmpDirs } from "./tmp-sweep.js";

package/dist/lifecycle-api.d.ts

@@ -0,0 +1,2 @@
+export type { TurnLease } from "./lifecycle.js";
+export { ManagedSession, nowIso, resumeStringField, SessionResourceRegistry, SingleFlightTurnController } from "./lifecycle.js";

package/dist/lifecycle-api.js

@@ -0,0 +1 @@
+export { ManagedSession, nowIso, resumeStringField, SessionResourceRegistry, SingleFlightTurnController } from "./lifecycle.js";

package/dist/lifecycle.d.ts

@@ -0,0 +1,47 @@
+import type { ApprovalDecision } from "./approvals.js";
+import type { ResumeCursor, SessionHandle, SessionTurnInput } from "./contract.js";
+import type { HarnessEvent } from "./events.js";
+export declare function nowIso(): string;
+export type TurnLease = {
+    readonly signal: AbortSignal;
+    complete(): void;
+    dispose(): void;
+};
+/**
+ * Enforces the session contract's one-live-turn rule and gives every driver
+ * an internal abort signal. Disposing an incomplete lease aborts the native
+ * operation, which makes an async iterator's `return()` a real cancellation.
+ */
+export declare class SingleFlightTurnController {
+    #private;
+    start(external?: AbortSignal): TurnLease;
+    interrupt(reason?: unknown): void;
+    get active(): boolean;
+}
+/**
+ * A session wrapper that owns unregistering itself from its instance. `stop`
+ * is idempotent even when the underlying driver's stop operation rejects.
+ */
+export declare class ManagedSession implements SessionHandle {
+    #private;
+    constructor(session: SessionHandle, release: () => void);
+    get sessionId(): string;
+    sendTurn(input: SessionTurnInput): AsyncIterable<HarnessEvent>;
+    respondToRequest(requestId: string, decision: ApprovalDecision): Promise<void>;
+    interrupt(): Promise<void>;
+    resumeCursor(): ResumeCursor | undefined;
+    stop(): Promise<void>;
+}
+/**
+ * Owns the live sessions created by one harness instance. Stopped sessions
+ * unregister immediately, while instance disposal settles every still-live
+ * session and aggregates failures only after all stop operations were tried.
+ */
+export declare class SessionResourceRegistry {
+    #private;
+    manage(session: SessionHandle): ManagedSession;
+    get size(): number;
+    assertOpen(): void;
+    dispose(): Promise<void>;
+}
+export declare function resumeStringField(resume: ResumeCursor | undefined, kind: ResumeCursor["kind"], field: string): string | undefined;

package/dist/lifecycle.js

@@ -0,0 +1,138 @@
+import { HarnessError } from "./errors.js";
+export function nowIso() {
+    return new Date().toISOString();
+}
+/**
+ * Enforces the session contract's one-live-turn rule and gives every driver
+ * an internal abort signal. Disposing an incomplete lease aborts the native
+ * operation, which makes an async iterator's `return()` a real cancellation.
+ */
+export class SingleFlightTurnController {
+    #active;
+    start(external) {
+        if (this.#active !== undefined) {
+            throw new HarnessError("session_busy", "a turn is already active for this session");
+        }
+        const controller = new AbortController();
+        const onAbort = () => controller.abort(external?.reason);
+        if (external?.aborted === true)
+            onAbort();
+        else
+            external?.addEventListener("abort", onAbort, { once: true });
+        const active = {
+            controller,
+            detachExternal: () => external?.removeEventListener("abort", onAbort)
+        };
+        this.#active = active;
+        let completed = false;
+        let disposed = false;
+        return {
+            signal: controller.signal,
+            complete: () => {
+                completed = true;
+            },
+            dispose: () => {
+                if (disposed)
+                    return;
+                disposed = true;
+                if (!completed)
+                    controller.abort(new Error("turn iterator closed"));
+                active.detachExternal();
+                if (this.#active === active)
+                    this.#active = undefined;
+            }
+        };
+    }
+    interrupt(reason = new Error("turn interrupted")) {
+        this.#active?.controller.abort(reason);
+    }
+    get active() {
+        return this.#active !== undefined;
+    }
+}
+/**
+ * A session wrapper that owns unregistering itself from its instance. `stop`
+ * is idempotent even when the underlying driver's stop operation rejects.
+ */
+export class ManagedSession {
+    #session;
+    #release;
+    #stopPromise;
+    constructor(session, release) {
+        this.#session = session;
+        this.#release = release;
+    }
+    get sessionId() {
+        return this.#session.sessionId;
+    }
+    sendTurn(input) {
+        return this.#session.sendTurn(input);
+    }
+    respondToRequest(requestId, decision) {
+        return this.#session.respondToRequest(requestId, decision);
+    }
+    interrupt() {
+        return this.#session.interrupt();
+    }
+    resumeCursor() {
+        return this.#session.resumeCursor();
+    }
+    stop() {
+        this.#stopPromise ??= (async () => {
+            try {
+                await this.#session.stop();
+            }
+            finally {
+                this.#release();
+            }
+        })();
+        return this.#stopPromise;
+    }
+}
+/**
+ * Owns the live sessions created by one harness instance. Stopped sessions
+ * unregister immediately, while instance disposal settles every still-live
+ * session and aggregates failures only after all stop operations were tried.
+ */
+export class SessionResourceRegistry {
+    #sessions = new Set();
+    #disposed = false;
+    #disposePromise;
+    manage(session) {
+        if (this.#disposed) {
+            throw new HarnessError("session_closed", "harness instance is disposed");
+        }
+        let managed;
+        managed = new ManagedSession(session, () => this.#sessions.delete(managed));
+        this.#sessions.add(managed);
+        return managed;
+    }
+    get size() {
+        return this.#sessions.size;
+    }
+    assertOpen() {
+        if (this.#disposed) {
+            throw new HarnessError("session_closed", "harness instance is disposed");
+        }
+    }
+    dispose() {
+        this.#disposed = true;
+        this.#disposePromise ??= (async () => {
+            const sessions = [...this.#sessions];
+            const results = await Promise.allSettled(sessions.map((session) => session.stop()));
+            const errors = results.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+            if (errors.length > 0) {
+                throw new AggregateError(errors, "one or more harness sessions failed to stop");
+            }
+        })();
+        return this.#disposePromise;
+    }
+}
+export function resumeStringField(resume, kind, field) {
+    if (resume === undefined || resume.kind !== kind || resume.data === null)
+        return undefined;
+    if (typeof resume.data !== "object" || Array.isArray(resume.data))
+        return undefined;
+    const value = resume.data[field];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}

package/dist/process.d.ts

@@ -4,5 +4,9 @@
  * runs with group-kill + SIGTERM->SIGKILL escalation, logged long-lived
  * children, readiness helpers, and port allocation.
  */
-export { buildChildEnv, freePort, runCliCapture, spawnLogged, terminate, waitForHttp, waitForOutput, withDeadline, withTimeout } from "@velum-labs/routekit-runtime";
-export type { BuildChildEnvInput, CliCaptureOptions, CliCaptureResult, LoggedChild, LoggedSpawnOptions } from "@velum-labs/routekit-runtime";
+export { runCliCapture, spawnLogged, terminate, waitForHttp, waitForOutput } from "@velum-labs/routekit-runtime/process";
+export { buildChildEnv } from "@velum-labs/routekit-runtime/environment";
+export { freePort } from "@velum-labs/routekit-runtime/ports";
+export { withDeadline, withTimeout } from "@velum-labs/routekit-runtime/timing";
+export type { CliCaptureOptions, CliCaptureResult, LoggedChild, LoggedSpawnOptions } from "@velum-labs/routekit-runtime/process";
+export type { BuildChildEnvInput } from "@velum-labs/routekit-runtime/environment";

package/dist/process.js

@@ -4,4 +4,7 @@
  * runs with group-kill + SIGTERM->SIGKILL escalation, logged long-lived
  * children, readiness helpers, and port allocation.
  */
-export { buildChildEnv, freePort, runCliCapture, spawnLogged, terminate, waitForHttp, waitForOutput, withDeadline, withTimeout } from "@velum-labs/routekit-runtime";
+export { runCliCapture, spawnLogged, terminate, waitForHttp, waitForOutput } from "@velum-labs/routekit-runtime/process";
+export { buildChildEnv } from "@velum-labs/routekit-runtime/environment";
+export { freePort } from "@velum-labs/routekit-runtime/ports";
+export { withDeadline, withTimeout } from "@velum-labs/routekit-runtime/timing";

package/dist/test/effect-lifecycle.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/effect-lifecycle.test.js

@@ -0,0 +1,33 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { Effect } from "effect";
+import { scopedTurn } from "../effect-api.js";
+import { HarnessError } from "../errors.js";
+import { SingleFlightTurnController } from "../lifecycle.js";
+test("scoped turns release the one-live-turn lease on scope close", async () => {
+    const controller = new SingleFlightTurnController();
+    await Effect.runPromise(Effect.scoped(Effect.gen(function* () {
+        const lease = yield* scopedTurn(controller);
+        assert.equal(controller.active, true);
+        assert.equal(lease.signal.aborted, false);
+    })));
+    assert.equal(controller.active, false);
+});
+test("incomplete scoped turns abort the native operation", async () => {
+    const controller = new SingleFlightTurnController();
+    let aborted = false;
+    await Effect.runPromise(Effect.scoped(Effect.gen(function* () {
+        const lease = yield* scopedTurn(controller);
+        lease.signal.addEventListener("abort", () => {
+            aborted = true;
+        });
+    })));
+    assert.equal(aborted, true);
+});
+test("a second turn still fails while a scoped lease is live", async () => {
+    const controller = new SingleFlightTurnController();
+    await Effect.runPromise(Effect.scoped(Effect.gen(function* () {
+        yield* scopedTurn(controller);
+        assert.throws(() => controller.start(), (error) => error instanceof HarnessError);
+    })));
+});

package/dist/test/harness-core.test.js

@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { test } from "node:test";
 import { z } from "zod";
-import { DriverRegistry, EventLog, HarnessError, PendingRequests, asHarnessError, createCachedHarnessDriver, createStreamJsonStepEmitter, createTrackedTmpDir, decideApproval, parseStreamJsonTrajectory, probeCliVersion, readCachedStatus, releaseTrackedTmpDir, resolveDriverEnv, statusSkipReason, streamJsonResultContentText, sweepTrackedTmpDirs, writeCachedStatus } from "../index.js";
+import { AsyncChannel, asHarnessError, createCachedHarnessDriver, createStreamJsonStepEmitter, createTrackedTmpDir, DriverRegistry, decideApproval, EventLog, HarnessError, PendingRequests, parseStreamJsonTrajectory, probeCliVersion, readCachedStatus, releaseTrackedTmpDir, resolveDriverEnv, SessionResourceRegistry, SingleFlightTurnController, statusSkipReason, streamJsonResultContentText, sweepTrackedTmpDirs, writeCachedStatus } from "../index.js";
 import { createMockDriver, driverContractSuite } from "../testing/index.js";
 // The mock driver is the reference implementation: it must pass the same
 // contract suite every real driver is held against.
@@ -17,13 +17,64 @@ driverContractSuite({
     startOptions: () => ({ cwd: process.cwd() }),
     supportsResume: true
 });
+test("bounded AsyncChannel fails deterministically on overflow", async () => {
+    const channel = new AsyncChannel({ capacity: 2 });
+    assert.equal(channel.push(1), true);
+    assert.equal(channel.push(2), true);
+    assert.equal(channel.push(3), false);
+    const values = [];
+    await assert.rejects(async () => {
+        for await (const value of channel)
+            values.push(value);
+    }, /capacity 2 exceeded/);
+    assert.deepEqual(values, [1, 2]);
+});
+test("SingleFlightTurnController rejects overlap and cancels abandoned turns", () => {
+    const turns = new SingleFlightTurnController();
+    const first = turns.start();
+    assert.throws(() => turns.start(), (error) => error.code === "session_busy");
+    first.dispose();
+    assert.equal(first.signal.aborted, true);
+    const second = turns.start();
+    second.complete();
+    second.dispose();
+    assert.equal(second.signal.aborted, false);
+});
+test("session resource registry attempts every stop and unregisters completed sessions", async () => {
+    const stopped = [];
+    const registry = new SessionResourceRegistry();
+    const session = (id, fails = false) => ({
+        sessionId: id,
+        sendTurn: async function* () { },
+        respondToRequest: async () => { },
+        interrupt: async () => { },
+        resumeCursor: () => undefined,
+        stop: async () => {
+            stopped.push(id);
+            if (fails)
+                throw new Error(`failed ${id}`);
+        }
+    });
+    const completed = registry.manage(session("completed"));
+    registry.manage(session("bad", true));
+    registry.manage(session("later"));
+    await completed.stop();
+    assert.equal(registry.size, 2);
+    await assert.rejects(registry.dispose(), AggregateError);
+    assert.deepEqual(stopped.sort(), ["bad", "completed", "later"]);
+    assert.equal(registry.size, 0);
+});
 test("shared stream JSON primitives normalize incremental and buffered events", () => {
     const stepsForEvent = (event) => event.type === "message" && typeof event.text === "string"
         ? [{ kind: "message", text: event.text }]
         : [];
     const resultStep = (result) => ({ kind: "result", text: result });
     const emitted = [];
-    const emit = createStreamJsonStepEmitter({ stepsForEvent, resultStep, onStep: (step) => emitted.push(step) });
+    const emit = createStreamJsonStepEmitter({
+        stepsForEvent,
+        resultStep,
+        onStep: (step) => emitted.push(step)
+    });
     emit('{"type":"message","text":"hello"}');
     emit('{"type":"result","result":"done"}');
     assert.deepEqual(emitted, [
@@ -39,7 +90,10 @@ test("shared stream JSON primitives normalize incremental and buffered events",
     assert.equal(parsed.finalOutput, "done");
     assert.equal(parsed.sawResult, true);
     assert.equal(parsed.isError, false);
-    assert.equal(streamJsonResultContentText([{ type: "text", text: "a" }, { type: "text", text: "b" }]), "ab");
+    assert.equal(streamJsonResultContentText([
+        { type: "text", text: "a" },
+        { type: "text", text: "b" }
+    ]), "ab");
 });
 test("registry decodes config exactly once and classifies failures", async () => {
     const registry = new DriverRegistry().register(createMockDriver());
@@ -180,7 +234,9 @@ test("cached driver construction reuses status written by probe", async () => {
     });
     try {
         await driver.probe({ statusCacheDir: cacheDir });
-        const created = await driver.createInstance(driver.configSchema.parse({}), { statusCacheDir: cacheDir });
+        const created = await driver.createInstance(driver.configSchema.parse({}), {
+            statusCacheDir: cacheDir
+        });
         assert.equal(created, instance);
         assert.deepEqual(instanceStatus, status);
         assert.equal(probeCount, 1);

package/dist/testing/contract-suite.js

@@ -78,6 +78,45 @@ export function driverContractSuite(input) {
             await instance.dispose();
         }
     });
+    test(`${input.name}: concurrent turns are rejected explicitly`, { skip }, async () => {
+        const instance = await input.createInstance();
+        try {
+            const session = await instance.startSession(input.startOptions());
+            const first = session.sendTurn({ prompt })[Symbol.asyncIterator]();
+            await first.next();
+            const second = session.sendTurn({ prompt })[Symbol.asyncIterator]();
+            await assert.rejects(second.next(), (error) => error instanceof Error &&
+                "code" in error &&
+                error.code === "session_busy");
+            await first.return?.();
+            await session.stop();
+        }
+        finally {
+            await instance.dispose();
+        }
+    });
+    test(`${input.name}: early iterator return cancels and releases the turn`, { skip }, async () => {
+        const instance = await input.createInstance();
+        try {
+            const session = await instance.startSession(input.startOptions());
+            const first = session.sendTurn({ prompt })[Symbol.asyncIterator]();
+            await first.next();
+            await first.return?.();
+            // A closed iterator must not leave the session permanently busy.
+            await collect(session.sendTurn({ prompt }), timeoutMs);
+            await session.stop();
+        }
+        finally {
+            await instance.dispose();
+        }
+    });
+    test(`${input.name}: stop and instance disposal are idempotent`, { skip }, async () => {
+        const instance = await input.createInstance();
+        const session = await instance.startSession(input.startOptions());
+        await Promise.all([session.stop(), session.stop()]);
+        await instance.dispose();
+        await instance.dispose();
+    });
     if (input.supportsResume === true) {
         test(`${input.name}: resume cursor round-trips into a new session`, { skip }, async () => {
             const instance = await input.createInstance();

package/dist/testing/mock-driver.js

@@ -1,7 +1,8 @@
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
+import { DEFAULT_AUTOMATION_APPROVAL_POLICY, decideApproval, PendingRequests } from "../approvals.js";
 import { HarnessError } from "../errors.js";
-import { DEFAULT_AUTOMATION_APPROVAL_POLICY, PendingRequests, decideApproval } from "../approvals.js";
+import { SessionResourceRegistry, SingleFlightTurnController } from "../lifecycle.js";
 export const mockDriverConfigSchema = z.object({
     /** Scripted assistant replies, consumed one per turn (last one repeats). */
     replies: z.array(z.string()).default(["mock reply"]),
@@ -29,6 +30,7 @@ class MockSession {
     #approvalPolicy;
     #turnCount;
     #stopped = false;
+    #turns = new SingleFlightTurnController();
     constructor(config, options) {
         this.#config = config;
         this.#approvalPolicy = options.approvalPolicy ?? DEFAULT_AUTOMATION_APPROVAL_POLICY;
@@ -46,44 +48,59 @@ class MockSession {
         if (this.#stopped) {
             throw new HarnessError("session_closed", "mock session is stopped");
         }
-        const base = { kind: "generic", sessionId: this.sessionId, at: nowIso() };
-        const turnId = `turn_${this.#turnCount + 1}`;
-        yield { ...base, type: "turn.started", turnId };
-        if (input.signal?.aborted === true) {
-            yield { ...base, type: "turn.completed", turnId, endReason: "aborted" };
-            return;
-        }
-        if (this.#config.approvalDetail !== undefined) {
-            const auto = decideApproval(this.#approvalPolicy ?? DEFAULT_AUTOMATION_APPROVAL_POLICY, "exec_command_approval");
-            if (auto === undefined) {
-                const request = this.#pending.open({
-                    requestType: "exec_command_approval",
-                    detail: this.#config.approvalDetail
-                });
-                yield {
-                    ...base,
-                    type: "request.opened",
-                    turnId,
-                    requestId: request.requestId,
-                    requestType: request.requestType,
-                    ...(request.detail !== undefined ? { detail: request.detail } : {})
-                };
-                const decision = await Promise.race([
-                    request.decision,
-                    abortAsDecision(input.signal)
-                ]);
-                yield { ...base, type: "request.resolved", turnId, requestId: request.requestId, decision };
-                if (decision === "decline" || decision === "cancel") {
-                    yield { ...base, type: "turn.completed", turnId, endReason: "aborted" };
-                    return;
+        const turn = this.#turns.start(input.signal);
+        let settled = false;
+        try {
+            const base = { kind: "generic", sessionId: this.sessionId, at: nowIso() };
+            const turnId = `turn_${this.#turnCount + 1}`;
+            yield { ...base, type: "turn.started", turnId };
+            if (turn.signal.aborted) {
+                yield { ...base, type: "turn.completed", turnId, endReason: "aborted" };
+                settled = true;
+                return;
+            }
+            if (this.#config.approvalDetail !== undefined) {
+                const auto = decideApproval(this.#approvalPolicy ?? DEFAULT_AUTOMATION_APPROVAL_POLICY, "exec_command_approval");
+                if (auto === undefined) {
+                    const request = this.#pending.open({
+                        requestType: "exec_command_approval",
+                        detail: this.#config.approvalDetail
+                    });
+                    yield {
+                        ...base,
+                        type: "request.opened",
+                        turnId,
+                        requestId: request.requestId,
+                        requestType: request.requestType,
+                        ...(request.detail !== undefined ? { detail: request.detail } : {})
+                    };
+                    const decision = await Promise.race([request.decision, abortAsDecision(turn.signal)]);
+                    yield {
+                        ...base,
+                        type: "request.resolved",
+                        turnId,
+                        requestId: request.requestId,
+                        decision
+                    };
+                    if (decision === "decline" || decision === "cancel") {
+                        yield { ...base, type: "turn.completed", turnId, endReason: "aborted" };
+                        settled = true;
+                        return;
+                    }
                 }
             }
+            const reply = this.#config.replies[Math.min(this.#turnCount, this.#config.replies.length - 1)] ??
+                "mock reply";
+            this.#turnCount += 1;
+            yield { ...base, type: "content.delta", turnId, stream: "assistant_text", text: reply };
+            yield { ...base, type: "turn.completed", turnId, endReason: "completed" };
+            settled = true;
+        }
+        finally {
+            if (settled)
+                turn.complete();
+            turn.dispose();
         }
-        const reply = this.#config.replies[Math.min(this.#turnCount, this.#config.replies.length - 1)] ??
-            "mock reply";
-        this.#turnCount += 1;
-        yield { ...base, type: "content.delta", turnId, stream: "assistant_text", text: reply };
-        yield { ...base, type: "turn.completed", turnId, endReason: "completed" };
     }
     async respondToRequest(requestId, decision) {
         if (!this.#pending.resolve(requestId, decision)) {
@@ -91,6 +108,7 @@ class MockSession {
         }
     }
     async interrupt() {
+        this.#turns.interrupt();
         this.#pending.settleAll("cancel");
     }
     resumeCursor() {
@@ -101,14 +119,17 @@ class MockSession {
         };
     }
     async stop() {
+        if (this.#stopped)
+            return;
         this.#stopped = true;
+        this.#turns.interrupt(new Error("mock session stopped"));
         this.#pending.settleAll("cancel");
     }
 }
 class MockInstance {
     kind = "generic";
     #config;
-    #sessions = new Set();
+    #sessions = new SessionResourceRegistry();
     constructor(config) {
         this.#config = config;
     }
@@ -116,6 +137,7 @@ class MockInstance {
         return statusFor(this.#config);
     }
     async startSession(options) {
+        this.#sessions.assertOpen();
         if (!this.#config.installed) {
             throw new HarnessError("not_installed", "mock CLI is not installed");
         }
@@ -123,13 +145,10 @@ class MockInstance {
             throw new HarnessError("not_authenticated", "mock CLI is not logged in");
         }
         const session = new MockSession(this.#config, options);
-        this.#sessions.add(session);
-        return session;
+        return this.#sessions.manage(session);
     }
     async dispose() {
-        for (const session of this.#sessions)
-            await session.stop();
-        this.#sessions.clear();
+        await this.#sessions.dispose();
     }
 }
 function abortAsDecision(signal) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@velum-labs/routekit-harness-core",
   "private": false,
-  "version": "0.18.6",
+  "version": "1.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/velum-labs/routekit.git",
@@ -18,6 +18,14 @@
     "./testing": {
       "types": "./dist/testing/index.d.ts",
       "default": "./dist/testing/index.js"
+    },
+    "./lifecycle": {
+      "types": "./dist/lifecycle-api.d.ts",
+      "default": "./dist/lifecycle-api.js"
+    },
+    "./effect": {
+      "types": "./dist/effect-api.d.ts",
+      "default": "./dist/effect-api.js"
     }
   },
   "files": [
@@ -25,9 +33,10 @@
     "LICENSE"
   ],
   "dependencies": {
+    "effect": "4.0.0-rc.108",
     "zod": "4.4.3",
-    "@velum-labs/routekit-runtime": "0.18.6",
-    "@velum-labs/routekit-contracts": "0.18.6"
+    "@velum-labs/routekit-runtime": "1.0.0",
+    "@velum-labs/routekit-contracts": "1.0.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",