open-multi-agent-kit 0.99.0 → 1.2.0

package/dist/coordination/resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.js","sourceRoot":"","sources":["../../src/coordination/resource.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Resource claim identity and conflict algebra.\n *\n * Two claims conflict when they name overlapping resources and at least one\n * side writes. Overlap is prefix containment on path components, so `src`\n * covers `src/a/x` but never `src/ab` — a shared character prefix that straddles\n * a component boundary is a different resource, not a nested one.\n */\n\nimport type { ClaimAccess, ClaimNamespace, ResourceClaim } from \"./types.ts\";\nimport { sequence } from \"./types.ts\";\n\nconst CLAIM_NAMESPACES: ReadonlySet<string> = new Set<ClaimNamespace>([\n\t\"filesystem\",\n\t\"git-ref\",\n\t\"contract\",\n\t\"socket\",\n\t\"database\",\n\t\"host-budget\",\n]);\nconst CLAIM_ACCESS: ReadonlySet<string> = new Set<ClaimAccess>([\"read\", \"write\"]);\nconst MAX_KEY_LENGTH = 4096;\n\nexport interface ResourceClaimInput {\n\treadonly namespace: string;\n\treadonly instanceId: string;\n\treadonly canonicalKey: string;\n\treadonly access: string;\n\treadonly generation: string;\n}\n\n/**\n * Validate and freeze one claim.\n *\n * A non-canonical key is rejected rather than normalized: normalizing\n * `a/../b` here would let one session hold `a/../b` and another hold `b`\n * while both believe their scopes are disjoint.\n */\nexport function canonicalClaim(input: ResourceClaimInput): ResourceClaim {\n\tif (!CLAIM_NAMESPACES.has(input.namespace)) {\n\t\tthrow new TypeError(`unsupported claim namespace: ${String(input.namespace)}`);\n\t}\n\tif (!CLAIM_ACCESS.has(input.access)) {\n\t\tthrow new TypeError(`unsupported claim access: ${String(input.access)}`);\n\t}\n\tif (typeof input.instanceId !== \"string\" || input.instanceId.length === 0) {\n\t\tthrow new TypeError(\"claim instanceId must be a non-empty string\");\n\t}\n\tassertCanonicalKey(input.canonicalKey);\n\treturn Object.freeze({\n\t\tnamespace: input.namespace as ClaimNamespace,\n\t\tinstanceId: input.instanceId,\n\t\tcanonicalKey: input.canonicalKey,\n\t\taccess: input.access as ClaimAccess,\n\t\tgeneration: sequence(input.generation),\n\t});\n}\n\nfunction assertCanonicalKey(key: unknown): asserts key is string {\n\tif (typeof key !== \"string\" || key.length === 0 || key.length > MAX_KEY_LENGTH) {\n\t\tthrow new TypeError(\"claim canonicalKey must be a bounded non-empty string\");\n\t}\n\tif (key.startsWith(\"/\")) throw new TypeError(\"claim canonicalKey must be relative\");\n\tfor (const part of key.split(\"/\")) {\n\t\tif (part === \"\" || part === \".\" || part === \"..\") {\n\t\t\tthrow new TypeError(`claim canonicalKey is not canonical: ${key}`);\n\t\t}\n\t}\n}\n\n/** Same resource identity, or one key nested under the other. Ignores access. */\nexport function resourcesOverlap(a: ResourceClaim, b: ResourceClaim): boolean {\n\tif (a.namespace !== b.namespace || a.instanceId !== b.instanceId) return false;\n\tif (a.canonicalKey === b.canonicalKey) return true;\n\treturn a.canonicalKey.startsWith(`${b.canonicalKey}/`) || b.canonicalKey.startsWith(`${a.canonicalKey}/`);\n}\n\nexport function claimsConflict(a: ResourceClaim, b: ResourceClaim): boolean {\n\treturn resourcesOverlap(a, b) && (a.access === \"write\" || b.access === \"write\");\n}\n\nexport function claimSetsConflict(a: readonly ResourceClaim[], b: readonly ResourceClaim[]): boolean {\n\treturn a.some((x) => b.some((y) => claimsConflict(x, y)));\n}\n\n/** Stable key for exact-set comparison when binding a start to its reservation. */\nexport function claimKey(claim: ResourceClaim): string {\n\treturn `${claim.namespace}\\u0000${claim.instanceId}\\u0000${claim.canonicalKey}\\u0000${claim.access}`;\n}\n\n/** Exact set equality by identity+access; a post-hook that widened scope fails this. */\nexport function sameClaimSet(a: readonly ResourceClaim[], b: readonly ResourceClaim[]): boolean {\n\tif (a.length !== b.length) return false;\n\tconst byCodeUnit = (x: string, y: string): number => {\n\t\tif (x < y) return -1;\n\t\treturn x > y ? 1 : 0;\n\t};\n\tconst left = a.map(claimKey).sort(byCodeUnit);\n\tconst right = b.map(claimKey).sort(byCodeUnit);\n\treturn left.every((value, index) => value === right[index]);\n}\n"]}

package/dist/coordination/session.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Generation-tagged browser session lifecycle (Jev audit F03, algorithm A6 §12.5).
+ *
+ *   idle → initializing(g) → ready(g) → draining(g) → closed(g)
+ *                        ↘ init failure → idle
+ *        ready | draining → close failure → close-failed(g)
+ *
+ * Two reproduced defects motivate every rule here:
+ *   R09 — shutdown read an empty session slot while init was in flight, then
+ *         the init completed and assigned it, resurrecting a closed session.
+ *   R10 — close cleared the handle before the driver call resolved, so a close
+ *         that threw left no handle and the next call claimed success.
+ *
+ * The invariant is that a handle is never dropped on the floor: a late init
+ * from a superseded generation is moved to `discardedHandles` for the caller
+ * to clean up, and a failed close keeps its handle in `close-failed`.
+ */
+import type { Sequence } from "./types.ts";
+export type SessionState = "idle" | "initializing" | "ready" | "draining" | "closed" | "close-failed";
+export declare class SessionLifecycle<THandle = unknown> {
+    private currentState;
+    private generation;
+    private currentHandle;
+    private failure;
+    private shutdownRequested;
+    private readonly discarded;
+    get state(): SessionState;
+    get currentGeneration(): Sequence;
+    get handle(): THandle | undefined;
+    /** Handles from superseded or unknown generations; the caller must close them. */
+    get discardedHandles(): readonly THandle[];
+    get closeFailure(): Error | undefined;
+    /** Only a completed close counts. A close failure is not closed. */
+    get isClosed(): boolean;
+    /**
+     * Open a new generation.
+     *
+     * Refused while a close failure is unresolved: launching a second browser
+     * on top of one that may still be running is how orphan processes and
+     * duplicate effects start.
+     */
+    beginInit(): Sequence;
+    /**
+     * Adopt an initialized handle.
+     *
+     * Returns false when this generation is no longer the one being awaited —
+     * the handle is retained for cleanup rather than installed, because the
+     * session it belonged to is already gone.
+     */
+    completeInit(generation: Sequence, handle: THandle): boolean;
+    failInit(generation: Sequence, error: Error): boolean;
+    /**
+     * Ask the session to stop.
+     *
+     * With no handle yet there is nothing to drain, so this closes immediately
+     * and any in-flight init will be discarded on arrival. With a live handle
+     * the session must drain: the caller still has to close the driver.
+     */
+    requestShutdown(): void;
+    beginClose(): void;
+    /** The driver confirmed the session is gone; only now is the handle released. */
+    completeClose(): void;
+    /** The close attempt threw. Keep the handle so a retry can still reach it. */
+    failClose(error: Error): void;
+    /**
+     * Fencing gate: accept a command only from the current generation of a
+     * ready session. A generation number in a log proves nothing; the gate that
+     * hands commands to the driver has to be the one refusing stale ones.
+     */
+    accepts(generation: Sequence): boolean;
+    /** True once a shutdown was asked for, regardless of how far draining got. */
+    get shutdownPending(): boolean;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/coordination/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/coordination/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG3C,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,cAAc,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,GAAG,cAAc,CAAC;AAEtG,qBAAa,gBAAgB,CAAC,OAAO,GAAG,OAAO;IAC9C,OAAO,CAAC,YAAY,CAAwB;IAC5C,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,OAAO,CAAoB;IACnC,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiB;IAE3C,IAAI,KAAK,IAAI,YAAY,CAExB;IAED,IAAI,iBAAiB,IAAI,QAAQ,CAEhC;IAED,IAAI,MAAM,IAAI,OAAO,GAAG,SAAS,CAEhC;IAED,kFAAkF;IAClF,IAAI,gBAAgB,IAAI,SAAS,OAAO,EAAE,CAEzC;IAED,IAAI,YAAY,IAAI,KAAK,GAAG,SAAS,CAEpC;IAED,oEAAoE;IACpE,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;;;;OAMG;IACH,SAAS,IAAI,QAAQ,CAWpB;IAED;;;;;;OAMG;IACH,YAAY,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAQ3D;IAED,QAAQ,CAAC,UAAU,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAOpD;IAED;;;;;;OAMG;IACH,eAAe,IAAI,IAAI,CAOtB;IAED,UAAU,IAAI,IAAI,CAMjB;IAED,iFAAiF;IACjF,aAAa,IAAI,IAAI,CAOpB;IAED,8EAA8E;IAC9E,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAM5B;IAED;;;;OAIG;IACH,OAAO,CAAC,UAAU,EAAE,QAAQ,GAAG,OAAO,CAErC;IAED,8EAA8E;IAC9E,IAAI,eAAe,IAAI,OAAO,CAE7B;CACD","sourcesContent":["/**\n * Generation-tagged browser session lifecycle (Jev audit F03, algorithm A6 §12.5).\n *\n *   idle → initializing(g) → ready(g) → draining(g) → closed(g)\n *                        ↘ init failure → idle\n *        ready | draining → close failure → close-failed(g)\n *\n * Two reproduced defects motivate every rule here:\n *   R09 — shutdown read an empty session slot while init was in flight, then\n *         the init completed and assigned it, resurrecting a closed session.\n *   R10 — close cleared the handle before the driver call resolved, so a close\n *         that threw left no handle and the next call claimed success.\n *\n * The invariant is that a handle is never dropped on the floor: a late init\n * from a superseded generation is moved to `discardedHandles` for the caller\n * to clean up, and a failed close keeps its handle in `close-failed`.\n */\n\nimport type { Sequence } from \"./types.ts\";\nimport { nextSequence, sequence } from \"./types.ts\";\n\nexport type SessionState = \"idle\" | \"initializing\" | \"ready\" | \"draining\" | \"closed\" | \"close-failed\";\n\nexport class SessionLifecycle<THandle = unknown> {\n\tprivate currentState: SessionState = \"idle\";\n\tprivate generation: Sequence = sequence(\"0\");\n\tprivate currentHandle: THandle | undefined;\n\tprivate failure: Error | undefined;\n\tprivate shutdownRequested = false;\n\tprivate readonly discarded: THandle[] = [];\n\n\tget state(): SessionState {\n\t\treturn this.currentState;\n\t}\n\n\tget currentGeneration(): Sequence {\n\t\treturn this.generation;\n\t}\n\n\tget handle(): THandle | undefined {\n\t\treturn this.currentHandle;\n\t}\n\n\t/** Handles from superseded or unknown generations; the caller must close them. */\n\tget discardedHandles(): readonly THandle[] {\n\t\treturn [...this.discarded];\n\t}\n\n\tget closeFailure(): Error | undefined {\n\t\treturn this.failure;\n\t}\n\n\t/** Only a completed close counts. A close failure is not closed. */\n\tget isClosed(): boolean {\n\t\treturn this.currentState === \"closed\";\n\t}\n\n\t/**\n\t * Open a new generation.\n\t *\n\t * Refused while a close failure is unresolved: launching a second browser\n\t * on top of one that may still be running is how orphan processes and\n\t * duplicate effects start.\n\t */\n\tbeginInit(): Sequence {\n\t\tif (this.currentState === \"close-failed\") {\n\t\t\tthrow new Error(\"cannot initialize while a close-failed session is unresolved\");\n\t\t}\n\t\tif (this.currentState === \"initializing\" || this.currentState === \"ready\" || this.currentState === \"draining\") {\n\t\t\tthrow new Error(`cannot initialize from state ${this.currentState}`);\n\t\t}\n\t\tthis.generation = nextSequence(this.generation);\n\t\tthis.shutdownRequested = false;\n\t\tthis.currentState = \"initializing\";\n\t\treturn this.generation;\n\t}\n\n\t/**\n\t * Adopt an initialized handle.\n\t *\n\t * Returns false when this generation is no longer the one being awaited —\n\t * the handle is retained for cleanup rather than installed, because the\n\t * session it belonged to is already gone.\n\t */\n\tcompleteInit(generation: Sequence, handle: THandle): boolean {\n\t\tif (generation !== this.generation || this.currentState !== \"initializing\") {\n\t\t\tthis.discarded.push(handle);\n\t\t\treturn false;\n\t\t}\n\t\tthis.currentHandle = handle;\n\t\tthis.currentState = \"ready\";\n\t\treturn true;\n\t}\n\n\tfailInit(generation: Sequence, error: Error): boolean {\n\t\tif (generation !== this.generation || this.currentState !== \"initializing\") return false;\n\t\tthis.failure = undefined;\n\t\tthis.currentHandle = undefined;\n\t\tthis.currentState = \"idle\";\n\t\tvoid error;\n\t\treturn true;\n\t}\n\n\t/**\n\t * Ask the session to stop.\n\t *\n\t * With no handle yet there is nothing to drain, so this closes immediately\n\t * and any in-flight init will be discarded on arrival. With a live handle\n\t * the session must drain: the caller still has to close the driver.\n\t */\n\trequestShutdown(): void {\n\t\tthis.shutdownRequested = true;\n\t\tif (this.currentState === \"initializing\" || this.currentState === \"idle\") {\n\t\t\tthis.currentState = \"closed\";\n\t\t\treturn;\n\t\t}\n\t\tif (this.currentState === \"ready\") this.currentState = \"draining\";\n\t}\n\n\tbeginClose(): void {\n\t\tif (this.currentState !== \"ready\" && this.currentState !== \"close-failed\") {\n\t\t\tthrow new Error(`cannot close from state ${this.currentState}`);\n\t\t}\n\t\tthis.failure = undefined;\n\t\tthis.currentState = \"draining\";\n\t}\n\n\t/** The driver confirmed the session is gone; only now is the handle released. */\n\tcompleteClose(): void {\n\t\tif (this.currentState !== \"draining\") {\n\t\t\tthrow new Error(`cannot complete close from state ${this.currentState}`);\n\t\t}\n\t\tthis.currentHandle = undefined;\n\t\tthis.failure = undefined;\n\t\tthis.currentState = \"closed\";\n\t}\n\n\t/** The close attempt threw. Keep the handle so a retry can still reach it. */\n\tfailClose(error: Error): void {\n\t\tif (this.currentState !== \"draining\") {\n\t\t\tthrow new Error(`cannot fail close from state ${this.currentState}`);\n\t\t}\n\t\tthis.failure = error;\n\t\tthis.currentState = \"close-failed\";\n\t}\n\n\t/**\n\t * Fencing gate: accept a command only from the current generation of a\n\t * ready session. A generation number in a log proves nothing; the gate that\n\t * hands commands to the driver has to be the one refusing stale ones.\n\t */\n\taccepts(generation: Sequence): boolean {\n\t\treturn this.currentState === \"ready\" && generation === this.generation;\n\t}\n\n\t/** True once a shutdown was asked for, regardless of how far draining got. */\n\tget shutdownPending(): boolean {\n\t\treturn this.shutdownRequested;\n\t}\n}\n"]}

package/dist/coordination/session.js

@@ -0,0 +1,143 @@
+/**
+ * Generation-tagged browser session lifecycle (Jev audit F03, algorithm A6 §12.5).
+ *
+ *   idle → initializing(g) → ready(g) → draining(g) → closed(g)
+ *                        ↘ init failure → idle
+ *        ready | draining → close failure → close-failed(g)
+ *
+ * Two reproduced defects motivate every rule here:
+ *   R09 — shutdown read an empty session slot while init was in flight, then
+ *         the init completed and assigned it, resurrecting a closed session.
+ *   R10 — close cleared the handle before the driver call resolved, so a close
+ *         that threw left no handle and the next call claimed success.
+ *
+ * The invariant is that a handle is never dropped on the floor: a late init
+ * from a superseded generation is moved to `discardedHandles` for the caller
+ * to clean up, and a failed close keeps its handle in `close-failed`.
+ */
+import { nextSequence, sequence } from "./types.js";
+export class SessionLifecycle {
+    currentState = "idle";
+    generation = sequence("0");
+    currentHandle;
+    failure;
+    shutdownRequested = false;
+    discarded = [];
+    get state() {
+        return this.currentState;
+    }
+    get currentGeneration() {
+        return this.generation;
+    }
+    get handle() {
+        return this.currentHandle;
+    }
+    /** Handles from superseded or unknown generations; the caller must close them. */
+    get discardedHandles() {
+        return [...this.discarded];
+    }
+    get closeFailure() {
+        return this.failure;
+    }
+    /** Only a completed close counts. A close failure is not closed. */
+    get isClosed() {
+        return this.currentState === "closed";
+    }
+    /**
+     * Open a new generation.
+     *
+     * Refused while a close failure is unresolved: launching a second browser
+     * on top of one that may still be running is how orphan processes and
+     * duplicate effects start.
+     */
+    beginInit() {
+        if (this.currentState === "close-failed") {
+            throw new Error("cannot initialize while a close-failed session is unresolved");
+        }
+        if (this.currentState === "initializing" || this.currentState === "ready" || this.currentState === "draining") {
+            throw new Error(`cannot initialize from state ${this.currentState}`);
+        }
+        this.generation = nextSequence(this.generation);
+        this.shutdownRequested = false;
+        this.currentState = "initializing";
+        return this.generation;
+    }
+    /**
+     * Adopt an initialized handle.
+     *
+     * Returns false when this generation is no longer the one being awaited —
+     * the handle is retained for cleanup rather than installed, because the
+     * session it belonged to is already gone.
+     */
+    completeInit(generation, handle) {
+        if (generation !== this.generation || this.currentState !== "initializing") {
+            this.discarded.push(handle);
+            return false;
+        }
+        this.currentHandle = handle;
+        this.currentState = "ready";
+        return true;
+    }
+    failInit(generation, error) {
+        if (generation !== this.generation || this.currentState !== "initializing")
+            return false;
+        this.failure = undefined;
+        this.currentHandle = undefined;
+        this.currentState = "idle";
+        void error;
+        return true;
+    }
+    /**
+     * Ask the session to stop.
+     *
+     * With no handle yet there is nothing to drain, so this closes immediately
+     * and any in-flight init will be discarded on arrival. With a live handle
+     * the session must drain: the caller still has to close the driver.
+     */
+    requestShutdown() {
+        this.shutdownRequested = true;
+        if (this.currentState === "initializing" || this.currentState === "idle") {
+            this.currentState = "closed";
+            return;
+        }
+        if (this.currentState === "ready")
+            this.currentState = "draining";
+    }
+    beginClose() {
+        if (this.currentState !== "ready" && this.currentState !== "close-failed") {
+            throw new Error(`cannot close from state ${this.currentState}`);
+        }
+        this.failure = undefined;
+        this.currentState = "draining";
+    }
+    /** The driver confirmed the session is gone; only now is the handle released. */
+    completeClose() {
+        if (this.currentState !== "draining") {
+            throw new Error(`cannot complete close from state ${this.currentState}`);
+        }
+        this.currentHandle = undefined;
+        this.failure = undefined;
+        this.currentState = "closed";
+    }
+    /** The close attempt threw. Keep the handle so a retry can still reach it. */
+    failClose(error) {
+        if (this.currentState !== "draining") {
+            throw new Error(`cannot fail close from state ${this.currentState}`);
+        }
+        this.failure = error;
+        this.currentState = "close-failed";
+    }
+    /**
+     * Fencing gate: accept a command only from the current generation of a
+     * ready session. A generation number in a log proves nothing; the gate that
+     * hands commands to the driver has to be the one refusing stale ones.
+     */
+    accepts(generation) {
+        return this.currentState === "ready" && generation === this.generation;
+    }
+    /** True once a shutdown was asked for, regardless of how far draining got. */
+    get shutdownPending() {
+        return this.shutdownRequested;
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/coordination/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/coordination/session.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Generation-tagged browser session lifecycle (Jev audit F03, algorithm A6 §12.5).\n *\n *   idle → initializing(g) → ready(g) → draining(g) → closed(g)\n *                        ↘ init failure → idle\n *        ready | draining → close failure → close-failed(g)\n *\n * Two reproduced defects motivate every rule here:\n *   R09 — shutdown read an empty session slot while init was in flight, then\n *         the init completed and assigned it, resurrecting a closed session.\n *   R10 — close cleared the handle before the driver call resolved, so a close\n *         that threw left no handle and the next call claimed success.\n *\n * The invariant is that a handle is never dropped on the floor: a late init\n * from a superseded generation is moved to `discardedHandles` for the caller\n * to clean up, and a failed close keeps its handle in `close-failed`.\n */\n\nimport type { Sequence } from \"./types.ts\";\nimport { nextSequence, sequence } from \"./types.ts\";\n\nexport type SessionState = \"idle\" | \"initializing\" | \"ready\" | \"draining\" | \"closed\" | \"close-failed\";\n\nexport class SessionLifecycle<THandle = unknown> {\n\tprivate currentState: SessionState = \"idle\";\n\tprivate generation: Sequence = sequence(\"0\");\n\tprivate currentHandle: THandle | undefined;\n\tprivate failure: Error | undefined;\n\tprivate shutdownRequested = false;\n\tprivate readonly discarded: THandle[] = [];\n\n\tget state(): SessionState {\n\t\treturn this.currentState;\n\t}\n\n\tget currentGeneration(): Sequence {\n\t\treturn this.generation;\n\t}\n\n\tget handle(): THandle | undefined {\n\t\treturn this.currentHandle;\n\t}\n\n\t/** Handles from superseded or unknown generations; the caller must close them. */\n\tget discardedHandles(): readonly THandle[] {\n\t\treturn [...this.discarded];\n\t}\n\n\tget closeFailure(): Error | undefined {\n\t\treturn this.failure;\n\t}\n\n\t/** Only a completed close counts. A close failure is not closed. */\n\tget isClosed(): boolean {\n\t\treturn this.currentState === \"closed\";\n\t}\n\n\t/**\n\t * Open a new generation.\n\t *\n\t * Refused while a close failure is unresolved: launching a second browser\n\t * on top of one that may still be running is how orphan processes and\n\t * duplicate effects start.\n\t */\n\tbeginInit(): Sequence {\n\t\tif (this.currentState === \"close-failed\") {\n\t\t\tthrow new Error(\"cannot initialize while a close-failed session is unresolved\");\n\t\t}\n\t\tif (this.currentState === \"initializing\" || this.currentState === \"ready\" || this.currentState === \"draining\") {\n\t\t\tthrow new Error(`cannot initialize from state ${this.currentState}`);\n\t\t}\n\t\tthis.generation = nextSequence(this.generation);\n\t\tthis.shutdownRequested = false;\n\t\tthis.currentState = \"initializing\";\n\t\treturn this.generation;\n\t}\n\n\t/**\n\t * Adopt an initialized handle.\n\t *\n\t * Returns false when this generation is no longer the one being awaited —\n\t * the handle is retained for cleanup rather than installed, because the\n\t * session it belonged to is already gone.\n\t */\n\tcompleteInit(generation: Sequence, handle: THandle): boolean {\n\t\tif (generation !== this.generation || this.currentState !== \"initializing\") {\n\t\t\tthis.discarded.push(handle);\n\t\t\treturn false;\n\t\t}\n\t\tthis.currentHandle = handle;\n\t\tthis.currentState = \"ready\";\n\t\treturn true;\n\t}\n\n\tfailInit(generation: Sequence, error: Error): boolean {\n\t\tif (generation !== this.generation || this.currentState !== \"initializing\") return false;\n\t\tthis.failure = undefined;\n\t\tthis.currentHandle = undefined;\n\t\tthis.currentState = \"idle\";\n\t\tvoid error;\n\t\treturn true;\n\t}\n\n\t/**\n\t * Ask the session to stop.\n\t *\n\t * With no handle yet there is nothing to drain, so this closes immediately\n\t * and any in-flight init will be discarded on arrival. With a live handle\n\t * the session must drain: the caller still has to close the driver.\n\t */\n\trequestShutdown(): void {\n\t\tthis.shutdownRequested = true;\n\t\tif (this.currentState === \"initializing\" || this.currentState === \"idle\") {\n\t\t\tthis.currentState = \"closed\";\n\t\t\treturn;\n\t\t}\n\t\tif (this.currentState === \"ready\") this.currentState = \"draining\";\n\t}\n\n\tbeginClose(): void {\n\t\tif (this.currentState !== \"ready\" && this.currentState !== \"close-failed\") {\n\t\t\tthrow new Error(`cannot close from state ${this.currentState}`);\n\t\t}\n\t\tthis.failure = undefined;\n\t\tthis.currentState = \"draining\";\n\t}\n\n\t/** The driver confirmed the session is gone; only now is the handle released. */\n\tcompleteClose(): void {\n\t\tif (this.currentState !== \"draining\") {\n\t\t\tthrow new Error(`cannot complete close from state ${this.currentState}`);\n\t\t}\n\t\tthis.currentHandle = undefined;\n\t\tthis.failure = undefined;\n\t\tthis.currentState = \"closed\";\n\t}\n\n\t/** The close attempt threw. Keep the handle so a retry can still reach it. */\n\tfailClose(error: Error): void {\n\t\tif (this.currentState !== \"draining\") {\n\t\t\tthrow new Error(`cannot fail close from state ${this.currentState}`);\n\t\t}\n\t\tthis.failure = error;\n\t\tthis.currentState = \"close-failed\";\n\t}\n\n\t/**\n\t * Fencing gate: accept a command only from the current generation of a\n\t * ready session. A generation number in a log proves nothing; the gate that\n\t * hands commands to the driver has to be the one refusing stale ones.\n\t */\n\taccepts(generation: Sequence): boolean {\n\t\treturn this.currentState === \"ready\" && generation === this.generation;\n\t}\n\n\t/** True once a shutdown was asked for, regardless of how far draining got. */\n\tget shutdownPending(): boolean {\n\t\treturn this.shutdownRequested;\n\t}\n}\n"]}

package/dist/coordination/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Wire contracts for parallel-session coordination.
+ *
+ * Ported from the proposed `contracts.ts` of the 2026-09-20 coordination
+ * design. These are new contracts, not pre-existing OMK exports.
+ *
+ * The central distinction the types encode: an authorization deadline is not a
+ * termination proof. A grant whose deadline passed while an external effect was
+ * live becomes `quarantined` — still holding its claims — rather than free.
+ */
+/** Canonical nonnegative decimal string. Ordering is numeric, not lexical. */
+export type Sequence = string & {
+    readonly __sequence: unique symbol;
+};
+export declare function sequence(value: unknown): Sequence;
+export declare function nextSequence(value: Sequence): Sequence;
+/**
+ * Lifecycle of an authorized effect.
+ *
+ * The in-process broker currently mints `reserved`, `running`, `quarantined`,
+ * `terminated` and `cancelled`. `starting` and `terminating` are reserved for
+ * the out-of-process supervisor that reports those transitions over the wire;
+ * nothing emits them yet, and the broker must not infer them.
+ */
+export type EffectState = "reserved" | "starting" | "running" | "terminating" | "quarantined" | "terminated" | "cancelled";
+/** States in which a grant no longer holds its claims. */
+export declare const SETTLED_EFFECT_STATES: ReadonlySet<EffectState>;
+export type ClaimNamespace = "filesystem" | "git-ref" | "contract" | "socket" | "database" | "host-budget";
+export type ClaimAccess = "read" | "write";
+/**
+ * One declared resource claim.
+ *
+ * `canonicalKey` must already be normalized by the caller: the broker rejects
+ * rather than guesses, because silently normalizing `a/../b` would let two
+ * sessions believe they hold disjoint keys.
+ */
+export interface ResourceClaim {
+    readonly namespace: ClaimNamespace;
+    readonly instanceId: string;
+    readonly canonicalKey: string;
+    readonly access: ClaimAccess;
+    readonly generation: Sequence;
+}
+/**
+ * Proof of admission for exactly one operation of one session incarnation.
+ *
+ * `authorizationDeadline` bounds the authorization only. Termination is a
+ * separate, supervisor-reported fact.
+ */
+export interface GrantToken {
+    readonly authorityEpoch: Sequence;
+    readonly grantSequence: Sequence;
+    readonly sessionId: string;
+    readonly sessionIncarnation: Sequence;
+    readonly authorizationDeadline: number;
+}
+export type AdmissionOutcome = {
+    readonly status: "granted";
+    readonly token: GrantToken;
+} | {
+    readonly status: "blocked";
+    readonly blockers: readonly Sequence[];
+} | {
+    readonly status: "over-capacity";
+    readonly requestedWeight: number;
+    readonly availableWeight: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/coordination/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/coordination/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,8EAA8E;AAC9E,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,UAAU,EAAE,OAAO,MAAM,CAAA;CAAE,CAAC;AAKvE,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAMjD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAEtD;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GACpB,UAAU,GACV,UAAU,GACV,SAAS,GACT,aAAa,GACb,aAAa,GACb,YAAY,GACZ,WAAW,CAAC;AAEf,0DAA0D;AAC1D,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,WAAW,CAAqD,CAAC;AAEjH,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,UAAU,GAAG,aAAa,CAAC;AAC3G,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,cAAc,EAAE,QAAQ,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,kBAAkB,EAAE,QAAQ,CAAC;IACtC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;CACvC;AAED,MAAM,MAAM,gBAAgB,GACzB;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GAC1D;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,QAAQ,EAAE,CAAA;CAAE,GACtE;IAAE,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CAAC","sourcesContent":["/**\n * Wire contracts for parallel-session coordination.\n *\n * Ported from the proposed `contracts.ts` of the 2026-09-20 coordination\n * design. These are new contracts, not pre-existing OMK exports.\n *\n * The central distinction the types encode: an authorization deadline is not a\n * termination proof. A grant whose deadline passed while an external effect was\n * live becomes `quarantined` — still holding its claims — rather than free.\n */\n\n/** Canonical nonnegative decimal string. Ordering is numeric, not lexical. */\nexport type Sequence = string & { readonly __sequence: unique symbol };\n\nconst SEQUENCE_PATTERN = /^(0|[1-9][0-9]*)$/;\nconst MAX_SEQUENCE_LENGTH = 40;\n\nexport function sequence(value: unknown): Sequence {\n\tif (typeof value !== \"string\" || !SEQUENCE_PATTERN.test(value)) {\n\t\tthrow new TypeError(\"sequence must be a canonical nonnegative decimal string\");\n\t}\n\tif (value.length > MAX_SEQUENCE_LENGTH) throw new RangeError(\"sequence too long\");\n\treturn value as Sequence;\n}\n\nexport function nextSequence(value: Sequence): Sequence {\n\treturn String(BigInt(value) + 1n) as Sequence;\n}\n\n/**\n * Lifecycle of an authorized effect.\n *\n * The in-process broker currently mints `reserved`, `running`, `quarantined`,\n * `terminated` and `cancelled`. `starting` and `terminating` are reserved for\n * the out-of-process supervisor that reports those transitions over the wire;\n * nothing emits them yet, and the broker must not infer them.\n */\nexport type EffectState =\n\t| \"reserved\"\n\t| \"starting\"\n\t| \"running\"\n\t| \"terminating\"\n\t| \"quarantined\"\n\t| \"terminated\"\n\t| \"cancelled\";\n\n/** States in which a grant no longer holds its claims. */\nexport const SETTLED_EFFECT_STATES: ReadonlySet<EffectState> = new Set<EffectState>([\"terminated\", \"cancelled\"]);\n\nexport type ClaimNamespace = \"filesystem\" | \"git-ref\" | \"contract\" | \"socket\" | \"database\" | \"host-budget\";\nexport type ClaimAccess = \"read\" | \"write\";\n\n/**\n * One declared resource claim.\n *\n * `canonicalKey` must already be normalized by the caller: the broker rejects\n * rather than guesses, because silently normalizing `a/../b` would let two\n * sessions believe they hold disjoint keys.\n */\nexport interface ResourceClaim {\n\treadonly namespace: ClaimNamespace;\n\treadonly instanceId: string;\n\treadonly canonicalKey: string;\n\treadonly access: ClaimAccess;\n\treadonly generation: Sequence;\n}\n\n/**\n * Proof of admission for exactly one operation of one session incarnation.\n *\n * `authorizationDeadline` bounds the authorization only. Termination is a\n * separate, supervisor-reported fact.\n */\nexport interface GrantToken {\n\treadonly authorityEpoch: Sequence;\n\treadonly grantSequence: Sequence;\n\treadonly sessionId: string;\n\treadonly sessionIncarnation: Sequence;\n\treadonly authorizationDeadline: number;\n}\n\nexport type AdmissionOutcome =\n\t| { readonly status: \"granted\"; readonly token: GrantToken }\n\t| { readonly status: \"blocked\"; readonly blockers: readonly Sequence[] }\n\t| { readonly status: \"over-capacity\"; readonly requestedWeight: number; readonly availableWeight: number };\n"]}

package/dist/coordination/types.js

@@ -0,0 +1,26 @@
+/**
+ * Wire contracts for parallel-session coordination.
+ *
+ * Ported from the proposed `contracts.ts` of the 2026-09-20 coordination
+ * design. These are new contracts, not pre-existing OMK exports.
+ *
+ * The central distinction the types encode: an authorization deadline is not a
+ * termination proof. A grant whose deadline passed while an external effect was
+ * live becomes `quarantined` — still holding its claims — rather than free.
+ */
+const SEQUENCE_PATTERN = /^(0|[1-9][0-9]*)$/;
+const MAX_SEQUENCE_LENGTH = 40;
+export function sequence(value) {
+    if (typeof value !== "string" || !SEQUENCE_PATTERN.test(value)) {
+        throw new TypeError("sequence must be a canonical nonnegative decimal string");
+    }
+    if (value.length > MAX_SEQUENCE_LENGTH)
+        throw new RangeError("sequence too long");
+    return value;
+}
+export function nextSequence(value) {
+    return String(BigInt(value) + 1n);
+}
+/** States in which a grant no longer holds its claims. */
+export const SETTLED_EFFECT_STATES = new Set(["terminated", "cancelled"]);
+//# sourceMappingURL=types.js.map

package/dist/coordination/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/coordination/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AAC7C,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAE/B,MAAM,UAAU,QAAQ,CAAC,KAAc,EAAY;IAClD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,SAAS,CAAC,yDAAyD,CAAC,CAAC;IAChF,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,GAAG,mBAAmB;QAAE,MAAM,IAAI,UAAU,CAAC,mBAAmB,CAAC,CAAC;IAClF,OAAO,KAAiB,CAAC;AAAA,CACzB;AAED,MAAM,UAAU,YAAY,CAAC,KAAe,EAAY;IACvD,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAa,CAAC;AAAA,CAC9C;AAmBD,0DAA0D;AAC1D,MAAM,CAAC,MAAM,qBAAqB,GAA6B,IAAI,GAAG,CAAc,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC,CAAC","sourcesContent":["/**\n * Wire contracts for parallel-session coordination.\n *\n * Ported from the proposed `contracts.ts` of the 2026-09-20 coordination\n * design. These are new contracts, not pre-existing OMK exports.\n *\n * The central distinction the types encode: an authorization deadline is not a\n * termination proof. A grant whose deadline passed while an external effect was\n * live becomes `quarantined` — still holding its claims — rather than free.\n */\n\n/** Canonical nonnegative decimal string. Ordering is numeric, not lexical. */\nexport type Sequence = string & { readonly __sequence: unique symbol };\n\nconst SEQUENCE_PATTERN = /^(0|[1-9][0-9]*)$/;\nconst MAX_SEQUENCE_LENGTH = 40;\n\nexport function sequence(value: unknown): Sequence {\n\tif (typeof value !== \"string\" || !SEQUENCE_PATTERN.test(value)) {\n\t\tthrow new TypeError(\"sequence must be a canonical nonnegative decimal string\");\n\t}\n\tif (value.length > MAX_SEQUENCE_LENGTH) throw new RangeError(\"sequence too long\");\n\treturn value as Sequence;\n}\n\nexport function nextSequence(value: Sequence): Sequence {\n\treturn String(BigInt(value) + 1n) as Sequence;\n}\n\n/**\n * Lifecycle of an authorized effect.\n *\n * The in-process broker currently mints `reserved`, `running`, `quarantined`,\n * `terminated` and `cancelled`. `starting` and `terminating` are reserved for\n * the out-of-process supervisor that reports those transitions over the wire;\n * nothing emits them yet, and the broker must not infer them.\n */\nexport type EffectState =\n\t| \"reserved\"\n\t| \"starting\"\n\t| \"running\"\n\t| \"terminating\"\n\t| \"quarantined\"\n\t| \"terminated\"\n\t| \"cancelled\";\n\n/** States in which a grant no longer holds its claims. */\nexport const SETTLED_EFFECT_STATES: ReadonlySet<EffectState> = new Set<EffectState>([\"terminated\", \"cancelled\"]);\n\nexport type ClaimNamespace = \"filesystem\" | \"git-ref\" | \"contract\" | \"socket\" | \"database\" | \"host-budget\";\nexport type ClaimAccess = \"read\" | \"write\";\n\n/**\n * One declared resource claim.\n *\n * `canonicalKey` must already be normalized by the caller: the broker rejects\n * rather than guesses, because silently normalizing `a/../b` would let two\n * sessions believe they hold disjoint keys.\n */\nexport interface ResourceClaim {\n\treadonly namespace: ClaimNamespace;\n\treadonly instanceId: string;\n\treadonly canonicalKey: string;\n\treadonly access: ClaimAccess;\n\treadonly generation: Sequence;\n}\n\n/**\n * Proof of admission for exactly one operation of one session incarnation.\n *\n * `authorizationDeadline` bounds the authorization only. Termination is a\n * separate, supervisor-reported fact.\n */\nexport interface GrantToken {\n\treadonly authorityEpoch: Sequence;\n\treadonly grantSequence: Sequence;\n\treadonly sessionId: string;\n\treadonly sessionIncarnation: Sequence;\n\treadonly authorizationDeadline: number;\n}\n\nexport type AdmissionOutcome =\n\t| { readonly status: \"granted\"; readonly token: GrantToken }\n\t| { readonly status: \"blocked\"; readonly blockers: readonly Sequence[] }\n\t| { readonly status: \"over-capacity\"; readonly requestedWeight: number; readonly availableWeight: number };\n"]}

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

@@ -348,6 +348,7 @@ export declare class AgentSession {
     private readonly _resourceObservationJournals;
     private _latestResourcePromptRunId;
     private _lastResourceAdmission;
+    private _resourcePressureStabilizer;
     private _workloadPermitPool;
     private _pendingRuntimeTerminationCause;
     private _activeRunToolTermination;
@@ -550,6 +551,14 @@ export declare class AgentSession {
      * Extract the most recent user query text from conversation messages.
      * Returns undefined when no user message exists or content is empty.
      * Handles both string content and multimodal (array) content.
+     *
+     * The scan walks the whole transcript backwards and stops at the first user
+     * message. A fixed tail window cannot work here: tool results are their own
+     * messages, so a single turn that calls two tools already leaves
+     * `[user, assistant, toolResult, toolResult]` and buries the task four deep.
+     * Losing it mid-turn collapses every skill to the neutral relevance score and
+     * degrades ranking to catalogue order, precisely while tools are running and
+     * a matching skill matters most.
      */
     private _extractCurrentQuery;
     private _getContextBudgetOptions;
@@ -562,11 +571,24 @@ export declare class AgentSession {
     private _rebuildSystemPrompt;
     private _runAgentPrompt;
     private _beginResourceGovernedRun;
+    /**
+     * Feed one snapshot's raw pressure through the per-session stabilizer.
+     * Created lazily so sessions that never probe carry no state; the first
+     * observation installs its own level directly (no warmup lag).
+     */
+    private _stabilizeResourcePressure;
     private _openResourceObservations;
     /** §20.2: record the TUI-side completion sound result in its originating run journal. */
     recordCompletionSoundResult(promptRunId: string, result: import("./completion-sound.ts").CompletionSoundResult): void;
     /** §19.4 read-only SDK surface: the most recent resource admission decision, if any. */
     getCurrentResourceAdmission(): ResourceAdmissionDecision | null;
+    /**
+     * Spec 020 Req1 — canonical subagent lane authority bound to this session.
+     * Rebuilt on each call so it tracks the live admission decision, shared
+     * permit pool, and open prompt run. Extension tool contexts read it through
+     * `ctx.getSubagentLaneAuthority()`.
+     */
+    private _getSubagentLaneAuthority;
     /** §19.4 read-only SDK surface: capture a fresh host resource snapshot. */
     getHostResourceSnapshot(): Promise<HostResourceSnapshot>;
     /** §19.4 read-only SDK surface: shared workload permit pool state, if any. */
@@ -830,8 +852,13 @@ export declare class AgentSession {
     /**
      * Effective context window for the upcoming turn.
      * Image-bearing turns with a text-only session model are auto-routed to the
-     * vision model (gpt-5.6-luna, 1M) — that window is the real limit. Text-only
-     * turns keep the session model's (typically much larger) window.
+     * vision model (gpt-5.6-luna, 1M), so the request has to fit both windows and
+     * the binding limit is the smaller one. Session windows fall on both sides of
+     * 1M: most catalogued models are smaller (median near 300K) and keep their own
+     * window as the limit, while the larger-than-1M models are the ones the clamp
+     * exists for — without it their threshold is computed against a window the
+     * vision route will not honour, and the request overflows before compaction
+     * fires. Text-only turns keep the session model's window untouched.
      */
     private _effectiveTurnContextWindow;
     private _checkProjectedCompaction;