@cotal-ai/manager 0.90.1 → 0.91.0

package/dist/chat-session.d.ts

@@ -0,0 +1,165 @@
+import { type EpErrorCode, type StaticManagedSlotRow } from "@cotal-ai/core";
+/** Every static chat alias starts with this. An ordinary spawn refuses any name that does. */
+export declare const CHAT_ALIAS_PREFIX = "chat_";
+/** Draw a fresh `chat_<26 base32>` alias (130 random bits). 256 is a multiple of 32, so masking each
+ *  byte keeps every symbol uniform. */
+export declare function drawChatAlias(): string;
+/** Whether `name` has the exact shape {@link drawChatAlias} produces. */
+export declare function isChatAlias(name: string): boolean;
+/** A `chat-session-open` request, as {@link readChatOpenInput} reads it. */
+export interface ChatSessionOpenInput {
+    subscribe?: string[];
+    allowSubscribe?: string[];
+    allowPublish?: string[];
+    label: string;
+    ttl: number;
+    sealTo: string;
+}
+/** The bounds the served `chat-session-open` schema states. The pure smoke holds them equal. */
+export declare const CHAT_OPEN_BOUNDS: {
+    readonly listItems: 64;
+    readonly labelLength: 128;
+    readonly ttlSec: 900;
+};
+/** Read a `chat-session-open` request from its raw arguments, or the refusal. The ep door checks the
+ *  served schema first; this reads every field the handler uses again, so no unchecked value reaches
+ *  it. Channel validity, a blank label and the curve shape of `sealTo` are {@link chatOpenLists}'s. */
+export declare function readChatOpenInput(raw: unknown): ChatSessionOpenInput | {
+    error: string;
+};
+/** Read a `chat-session-retire` request from its raw arguments, or the refusal. The alias shape and
+ *  the slot's ownership are {@link chatRetireRefusal}'s and the handler's. */
+export declare function readChatRetireInput(raw: unknown): {
+    alias: string;
+    actor: string;
+    lifecycleUid: string;
+} | {
+    error: string;
+};
+/** The three lists of an open request under a spawn's own rules, or the refusal. Every entry must
+ *  be a valid channel, as the provisioner and the mint require; the initial channels must lie
+ *  within the read ceiling, which falls back to them when empty (`resolveReadAcl`); the post list
+ *  is default-deny. The foreign event-channel rule needs the drawn actor, so the handler applies
+ *  it. {@link readChatOpenInput} bounds the label, each list and the ttl first. */
+export declare function chatOpenLists(input: {
+    subscribe?: readonly string[];
+    allowSubscribe?: readonly string[];
+    allowPublish?: readonly string[];
+    label: string;
+    sealTo: string;
+}): {
+    subscribe: string[];
+    allowSubscribe: string[];
+    allowPublish: string[];
+} | {
+    error: string;
+};
+/** What `chat-session-open` seals to the caller's `sealTo`: the credential bound to the space,
+ *  the admitting manager instance and every field of the reply. The client refuses any other key
+ *  set and any field that differs from the reply or from what it asked. */
+export interface SealedChatAdmission {
+    readonly v: 1;
+    readonly space: string;
+    readonly managerInstanceId: string;
+    readonly alias: string;
+    readonly actor: string;
+    readonly lifecycleUid: string;
+    readonly expiresAt: number;
+    readonly sealTo: string;
+    readonly creds: string;
+}
+/** Seal one admission to its `sealTo` under a one-time sender key. */
+export declare function sealChatAdmission(admission: Omit<SealedChatAdmission, "v">): {
+    sealer: string;
+    sealed: string;
+};
+/** The ownership guard for `chat-session-retire`, or undefined when the slot may be retired. It
+ *  ends only a slot `chat-session-open` admitted on THIS logical manager instance, at the
+ *  requested incarnation: never an ordinary agent's slot, a sibling's, a legacy row with no
+ *  recorded owner, or another incarnation of the alias. */
+export declare function chatRetireRefusal(row: StaticManagedSlotRow | undefined, request: {
+    alias: string;
+    actor: string;
+    lifecycleUid: string;
+}, managerInstanceId: string): {
+    code: EpErrorCode;
+    message: string;
+} | undefined;
+/** How many chat retirements one manager process runs at once, at expiry and at stop. Each is a
+ *  full static terminal (KV round trips, a broker eviction scan and a deprovision), so a burst
+ *  waits its turn instead of opening that many terminals together. It bounds work in flight, not
+ *  sessions. */
+export declare const CHAT_EXPIRY_CONCURRENCY = 4;
+/** One session this manager process admitted, or is admitting, as its cleanup needs it. */
+export interface ExpiringChatSession {
+    readonly alias: string;
+    readonly actor: string;
+    readonly lifecycleUid: string;
+    /** Its resolved read ceiling; the concrete channels in it name its membership rows for the
+     *  teardown, and the delivery inventory finds the rest. */
+    readonly channels: readonly string[];
+    /** The leaf's expiry, epoch ms. */
+    readonly expiresAt: number;
+}
+/** The clock the tracker runs on. Production uses the process clock; a smoke drives its own. */
+export interface ChatExpiryTimers {
+    readonly now: () => number;
+    readonly set: (fn: () => void, ms: number) => unknown;
+    readonly clear: (handle: unknown) => void;
+}
+/**
+ * The chat sessions this manager process admitted, from before each one's first durable write
+ * until a retirement of it is confirmed. It retires each at its leaf's expiry, so a reply lost on
+ * the way back or a client that never retires still ends then, and it names to the manager's
+ * sweep and stop the exact alias, actor and UID of every session this process holds.
+ *
+ * It knows only what this process registered and never reads the slot store, so it cannot reach
+ * an ordinary agent's slot, a sibling's, a legacy row or a session another process admitted.
+ * `retire` runs the exact-owned retirement; a throw is a failure, retried after each of
+ * `retryDelaysMs`. A session whose retries are spent stays tracked as `held`, for a later retire
+ * or the stop.
+ */
+export declare class ChatSessionExpiry {
+    private readonly retire;
+    private readonly options;
+    private readonly sessions;
+    private readonly due;
+    private running;
+    private stopped;
+    private readonly timers;
+    constructor(retire: (session: ExpiringChatSession) => Promise<void>, options: {
+        readonly retryDelaysMs: readonly number[];
+        readonly concurrency: number;
+        readonly log: (line: string) => void;
+        readonly timers?: ChatExpiryTimers;
+    });
+    /** Register a session the open handler is about to write, before its first durable write. It is
+     *  not scheduled until {@link arm}. Throws once stopped and for a UID already registered. */
+    register(session: ExpiringChatSession): void;
+    /** Schedule a registered session's retirement at its expiry: once its opening succeeded, or once
+     *  a rollback of it did not complete. Throws once stopped, so an opening that finishes after a
+     *  stop began is rolled back instead of being handed out; the session stays registered for the
+     *  stop either way. */
+    arm(lifecycleUid: string): void;
+    /** Whether this process holds a session at this exact alias, actor and UID, in any state. */
+    holdsExact(slot: {
+        readonly alias: string;
+        readonly actor: string;
+        readonly lifecycleUid: string;
+    }): boolean;
+    /** The admitted channels of a tracked session, or undefined once it is not tracked. */
+    channels(lifecycleUid: string): readonly string[] | undefined;
+    /** Stop tracking a session whose retirement was confirmed. A retirement of it already running
+     *  finishes, and its outcome is dropped. */
+    forget(lifecycleUid: string): void;
+    /** Stop scheduling and refuse new sessions. Every tracked session stays tracked for the stop to
+     *  retire or report, and each one not running becomes `held`. */
+    stop(): void;
+    /** Every tracked session. One whose expiry retirement is still settling is included: the
+     *  manager runs one terminal per UID, so a second caller joins it rather than racing it. */
+    remaining(): ExpiringChatSession[];
+    private schedule;
+    private pump;
+    private failed;
+}
+//# sourceMappingURL=chat-session.d.ts.map

package/dist/chat-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-session.d.ts","sourceRoot":"","sources":["../src/chat-session.ts"],"names":[],"mappings":"AAWA,OAAO,EAAkE,KAAK,WAAW,EAAE,KAAK,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE7I,8FAA8F;AAC9F,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAKzC;uCACuC;AACvC,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,yEAAyE;AACzE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED,4EAA4E;AAC5E,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,gGAAgG;AAChG,eAAO,MAAM,gBAAgB;;;;CAA4D,CAAC;AAU1F;;uGAEuG;AACvG,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,oBAAoB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAqBxF;AAED;8EAC8E;AAC9E,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAW5H;AAED;;;;mFAImF;AACnF,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACnC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG;IAAE,SAAS,EAAE,MAAM,EAAE,CAAC;IAAC,cAAc,EAAE,MAAM,EAAE,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAWhG;AAED;;2EAE2E;AAC3E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC;IACd,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,sEAAsE;AACtE,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,IAAI,CAAC,mBAAmB,EAAE,GAAG,CAAC,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAG/G;AAED;;;2DAG2D;AAC3D,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,oBAAoB,GAAG,SAAS,EACrC,OAAO,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,EAC/D,iBAAiB,EAAE,MAAM,GACxB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAYpD;AAED;;;gBAGgB;AAChB,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,2FAA2F;AAC3F,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;+DAC2D;IAC3D,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,mCAAmC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,gGAAgG;AAChG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;IAC3B,QAAQ,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IACtD,QAAQ,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C;AA0BD;;;;;;;;;;;GAWG;AACH,qBAAa,iBAAiB;IAQ1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAR1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyC;IAClE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAgB;IACpC,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;gBAGvB,MAAM,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,EACvD,OAAO,EAAE;QAAE,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAA;KAAE;IAKjL;iGAC6F;IAC7F,QAAQ,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI;IAM5C;;;2BAGuB;IACvB,GAAG,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;IAQ/B,6FAA6F;IAC7F,UAAU,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO;IAK5G,uFAAuF;IACvF,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS;IAI7D;gDAC4C;IAC5C,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;IASlC;qEACiE;IACjE,IAAI,IAAI,IAAI;IAWZ;gGAC4F;IAC5F,SAAS,IAAI,mBAAmB,EAAE;IAIlC,OAAO,CAAC,QAAQ;IAYhB,OAAO,CAAC,IAAI;IAsBZ,OAAO,CAAC,MAAM;CAkBf"}

package/dist/chat-session.js

@@ -0,0 +1,281 @@
+/**
+ * Static chat sessions (S mode): the manager-mediated admission for a live human or program
+ * session on a static-auth mesh. The manager draws the alias, mints the session's own leaf over the
+ * native static activation and provisioning, and retires it through the native static terminal.
+ * This module holds the pure rules those two handlers share, the sealed admission payload, and the
+ * tracker that retires a session nobody retired; it reads and writes no store itself.
+ *
+ * The wire authority of a session is its incarnation-unique nkey (`actor`). The `chat_` alias is
+ * routing only: it keys the durable slot row and is never a caller input at open.
+ */
+import { randomBytes } from "node:crypto";
+import { assertValidChannel, isCurvePublicKey, resolveReadAcl, sealJson } from "@cotal-ai/core";
+/** Every static chat alias starts with this. An ordinary spawn refuses any name that does. */
+export const CHAT_ALIAS_PREFIX = "chat_";
+const BASE32 = "abcdefghijklmnopqrstuvwxyz234567";
+const CHAT_ALIAS = /^chat_[a-z2-7]{26}$/;
+/** Draw a fresh `chat_<26 base32>` alias (130 random bits). 256 is a multiple of 32, so masking each
+ *  byte keeps every symbol uniform. */
+export function drawChatAlias() {
+    return CHAT_ALIAS_PREFIX + Array.from(randomBytes(26), (b) => BASE32[b & 31]).join("");
+}
+/** Whether `name` has the exact shape {@link drawChatAlias} produces. */
+export function isChatAlias(name) {
+    return CHAT_ALIAS.test(name);
+}
+/** The bounds the served `chat-session-open` schema states. The pure smoke holds them equal. */
+export const CHAT_OPEN_BOUNDS = { listItems: 64, labelLength: 128, ttlSec: 900 };
+const OPEN_FIELDS = ["subscribe", "allowSubscribe", "allowPublish", "label", "ttl", "sealTo"];
+const RETIRE_FIELDS = ["alias", "actor", "lifecycleUid"];
+/** The raw arguments as a plain object, or undefined. */
+function argObject(raw) {
+    return typeof raw === "object" && raw !== null && !Array.isArray(raw) ? raw : undefined;
+}
+/** Read a `chat-session-open` request from its raw arguments, or the refusal. The ep door checks the
+ *  served schema first; this reads every field the handler uses again, so no unchecked value reaches
+ *  it. Channel validity, a blank label and the curve shape of `sealTo` are {@link chatOpenLists}'s. */
+export function readChatOpenInput(raw) {
+    const bad = (why) => ({ error: `chat-session-open: ${why}` });
+    const a = argObject(raw);
+    if (!a)
+        return bad("the arguments must be an object");
+    const extra = Object.keys(a).find((key) => !OPEN_FIELDS.includes(key));
+    if (extra !== undefined)
+        return bad(`unknown field "${extra}"`);
+    const lists = {};
+    for (const key of ["subscribe", "allowSubscribe", "allowPublish"]) {
+        const list = a[key];
+        if (list === undefined)
+            continue;
+        if (!Array.isArray(list) || list.length > CHAT_OPEN_BOUNDS.listItems || !list.every((c) => typeof c === "string" && c.length > 0) || new Set(list).size !== list.length)
+            return bad(`${key} must be a list of at most ${CHAT_OPEN_BOUNDS.listItems} distinct, non-empty channel names`);
+        lists[key] = [...list];
+    }
+    const { label, ttl, sealTo } = a;
+    if (typeof label !== "string" || label.length === 0 || label.length > CHAT_OPEN_BOUNDS.labelLength)
+        return bad(`label must be a string of 1 to ${CHAT_OPEN_BOUNDS.labelLength} characters`);
+    if (typeof ttl !== "number" || !Number.isSafeInteger(ttl) || ttl < 1 || ttl > CHAT_OPEN_BOUNDS.ttlSec)
+        return bad(`ttl must be a whole number of seconds from 1 to ${CHAT_OPEN_BOUNDS.ttlSec}`);
+    if (typeof sealTo !== "string")
+        return bad("sealTo must be a string");
+    return { ...lists, label, ttl, sealTo };
+}
+/** Read a `chat-session-retire` request from its raw arguments, or the refusal. The alias shape and
+ *  the slot's ownership are {@link chatRetireRefusal}'s and the handler's. */
+export function readChatRetireInput(raw) {
+    const bad = (why) => ({ error: `chat-session-retire: ${why}` });
+    const a = argObject(raw);
+    if (!a)
+        return bad("the arguments must be an object");
+    const extra = Object.keys(a).find((key) => !RETIRE_FIELDS.includes(key));
+    if (extra !== undefined)
+        return bad(`unknown field "${extra}"`);
+    const { alias, actor, lifecycleUid } = a;
+    if (typeof alias !== "string" || alias.length === 0)
+        return bad("alias must be a non-empty string");
+    if (typeof actor !== "string" || actor.length === 0)
+        return bad("actor must be a non-empty string");
+    if (typeof lifecycleUid !== "string" || lifecycleUid.length === 0)
+        return bad("lifecycleUid must be a non-empty string");
+    return { alias, actor, lifecycleUid };
+}
+/** The three lists of an open request under a spawn's own rules, or the refusal. Every entry must
+ *  be a valid channel, as the provisioner and the mint require; the initial channels must lie
+ *  within the read ceiling, which falls back to them when empty (`resolveReadAcl`); the post list
+ *  is default-deny. The foreign event-channel rule needs the drawn actor, so the handler applies
+ *  it. {@link readChatOpenInput} bounds the label, each list and the ttl first. */
+export function chatOpenLists(input) {
+    if (!input.label.trim())
+        return { error: "chat-session-open: label must not be blank" };
+    if (!isCurvePublicKey(input.sealTo))
+        return { error: "chat-session-open: sealTo is not a curve public key" };
+    const subscribe = [...(input.subscribe ?? [])];
+    const allowPublish = [...(input.allowPublish ?? [])];
+    try {
+        for (const channel of [...subscribe, ...(input.allowSubscribe ?? []), ...allowPublish])
+            assertValidChannel(channel);
+        return { subscribe, allowSubscribe: resolveReadAcl(subscribe, [...(input.allowSubscribe ?? [])]), allowPublish };
+    }
+    catch (e) {
+        return { error: `chat-session-open: ${e.message}` };
+    }
+}
+/** Seal one admission to its `sealTo` under a one-time sender key. */
+export function sealChatAdmission(admission) {
+    const payload = { v: 1, ...admission };
+    return sealJson(payload, admission.sealTo);
+}
+/** The ownership guard for `chat-session-retire`, or undefined when the slot may be retired. It
+ *  ends only a slot `chat-session-open` admitted on THIS logical manager instance, at the
+ *  requested incarnation: never an ordinary agent's slot, a sibling's, a legacy row with no
+ *  recorded owner, or another incarnation of the alias. */
+export function chatRetireRefusal(row, request, managerInstanceId) {
+    if (!isChatAlias(request.alias))
+        return { code: "permission-denied", message: `"${request.alias}" is not a chat session alias; chat-session-retire ends only sessions chat-session-open admitted` };
+    if (row === undefined)
+        return { code: "not-found", message: `no chat session slot exists for "${request.alias}"` };
+    if (row.ownerInstanceId !== managerInstanceId)
+        return { code: "failed-precondition", message: `the chat session slot "${request.alias}" belongs to manager instance ${row.ownerInstanceId ?? "<unrecorded>"}, not ${managerInstanceId}; only the instance that admitted it retires it` };
+    if (row.lifecycleUid !== request.lifecycleUid)
+        return { code: "failed-precondition", message: `the chat session slot "${request.alias}" is at uid ${row.lifecycleUid}, not ${request.lifecycleUid}; a retirement never addresses another incarnation` };
+    if (row.actor !== request.actor)
+        return { code: "failed-precondition", message: `the chat session slot "${request.alias}" names actor ${row.actor}, not ${request.actor}` };
+    return undefined;
+}
+/** How many chat retirements one manager process runs at once, at expiry and at stop. Each is a
+ *  full static terminal (KV round trips, a broker eviction scan and a deprovision), so a burst
+ *  waits its turn instead of opening that many terminals together. It bounds work in flight, not
+ *  sessions. */
+export const CHAT_EXPIRY_CONCURRENCY = 4;
+const PROCESS_TIMERS = {
+    now: () => Date.now(),
+    set: (fn, ms) => {
+        const timer = setTimeout(fn, ms);
+        timer.unref?.();
+        return timer;
+    },
+    clear: (handle) => clearTimeout(handle),
+};
+/**
+ * The chat sessions this manager process admitted, from before each one's first durable write
+ * until a retirement of it is confirmed. It retires each at its leaf's expiry, so a reply lost on
+ * the way back or a client that never retires still ends then, and it names to the manager's
+ * sweep and stop the exact alias, actor and UID of every session this process holds.
+ *
+ * It knows only what this process registered and never reads the slot store, so it cannot reach
+ * an ordinary agent's slot, a sibling's, a legacy row or a session another process admitted.
+ * `retire` runs the exact-owned retirement; a throw is a failure, retried after each of
+ * `retryDelaysMs`. A session whose retries are spent stays tracked as `held`, for a later retire
+ * or the stop.
+ */
+export class ChatSessionExpiry {
+    retire;
+    options;
+    sessions = new Map();
+    due = [];
+    running = 0;
+    stopped = false;
+    timers;
+    constructor(retire, options) {
+        this.retire = retire;
+        this.options = options;
+        this.timers = options.timers ?? PROCESS_TIMERS;
+    }
+    /** Register a session the open handler is about to write, before its first durable write. It is
+     *  not scheduled until {@link arm}. Throws once stopped and for a UID already registered. */
+    register(session) {
+        if (this.stopped)
+            throw new Error(`this manager is stopping, so chat session ${session.alias} was not admitted`);
+        if (this.sessions.has(session.lifecycleUid))
+            throw new Error(`chat session uid ${session.lifecycleUid} is already registered`);
+        this.sessions.set(session.lifecycleUid, { session, state: "opening", failures: 0 });
+    }
+    /** Schedule a registered session's retirement at its expiry: once its opening succeeded, or once
+     *  a rollback of it did not complete. Throws once stopped, so an opening that finishes after a
+     *  stop began is rolled back instead of being handed out; the session stays registered for the
+     *  stop either way. */
+    arm(lifecycleUid) {
+        const entry = this.sessions.get(lifecycleUid);
+        if (!entry)
+            throw new Error(`chat session uid ${lifecycleUid} is not registered`);
+        if (this.stopped)
+            throw new Error(`this manager is stopping, so chat session ${entry.session.alias} is not scheduled for its expiry`);
+        if (entry.state !== "opening" && entry.state !== "held")
+            return;
+        this.schedule(entry, entry.session.expiresAt - this.timers.now());
+    }
+    /** Whether this process holds a session at this exact alias, actor and UID, in any state. */
+    holdsExact(slot) {
+        const entry = this.sessions.get(slot.lifecycleUid);
+        return entry !== undefined && entry.session.alias === slot.alias && entry.session.actor === slot.actor;
+    }
+    /** The admitted channels of a tracked session, or undefined once it is not tracked. */
+    channels(lifecycleUid) {
+        return this.sessions.get(lifecycleUid)?.session.channels;
+    }
+    /** Stop tracking a session whose retirement was confirmed. A retirement of it already running
+     *  finishes, and its outcome is dropped. */
+    forget(lifecycleUid) {
+        const entry = this.sessions.get(lifecycleUid);
+        if (!entry)
+            return;
+        if (entry.timer !== undefined)
+            this.timers.clear(entry.timer);
+        this.sessions.delete(lifecycleUid);
+        const queued = this.due.indexOf(lifecycleUid);
+        if (queued >= 0)
+            this.due.splice(queued, 1);
+    }
+    /** Stop scheduling and refuse new sessions. Every tracked session stays tracked for the stop to
+     *  retire or report, and each one not running becomes `held`. */
+    stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        this.due.length = 0;
+        for (const entry of this.sessions.values()) {
+            if (entry.timer !== undefined)
+                this.timers.clear(entry.timer);
+            entry.timer = undefined;
+            if (entry.state !== "running")
+                entry.state = "held";
+        }
+    }
+    /** Every tracked session. One whose expiry retirement is still settling is included: the
+     *  manager runs one terminal per UID, so a second caller joins it rather than racing it. */
+    remaining() {
+        return [...this.sessions.values()].map((entry) => entry.session);
+    }
+    schedule(entry, delayMs) {
+        entry.state = "armed";
+        const uid = entry.session.lifecycleUid;
+        entry.timer = this.timers.set(() => {
+            entry.timer = undefined;
+            if (this.stopped || this.sessions.get(uid) !== entry)
+                return;
+            entry.state = "due";
+            this.due.push(uid);
+            this.pump();
+        }, Math.max(0, delayMs));
+    }
+    pump() {
+        while (!this.stopped && this.running < this.options.concurrency && this.due.length > 0) {
+            const uid = this.due.shift();
+            const entry = this.sessions.get(uid);
+            if (!entry)
+                continue;
+            this.running++;
+            entry.state = "running";
+            void Promise.resolve()
+                .then(() => this.retire(entry.session))
+                .then(() => {
+                if (this.sessions.get(uid) === entry)
+                    this.sessions.delete(uid);
+            }, (e) => this.failed(entry, e))
+                .finally(() => {
+                this.running--;
+                this.pump();
+            });
+        }
+    }
+    failed(entry, e) {
+        const uid = entry.session.lifecycleUid;
+        if (this.sessions.get(uid) !== entry)
+            return;
+        if (this.stopped) {
+            entry.state = "held";
+            return;
+        }
+        const delayMs = this.options.retryDelaysMs[entry.failures];
+        entry.failures++;
+        const why = e instanceof Error ? e.message : String(e);
+        if (delayMs === undefined) {
+            entry.state = "held";
+            this.options.log(`! chat session ${entry.session.alias} (uid ${uid}) expired and its retirement failed ${entry.failures} time(s) (${why}); it stays held until a retire, this manager's stop, or the next start of this manager instance`);
+            return;
+        }
+        this.options.log(`! chat session ${entry.session.alias} (uid ${uid}) expiry retirement failed (${why}); retrying in ${delayMs} ms`);
+        this.schedule(entry, delayMs);
+    }
+}
+//# sourceMappingURL=chat-session.js.map

package/dist/chat-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-session.js","sourceRoot":"","sources":["../src/chat-session.ts"],"names":[],"mappings":"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"}

package/dist/commands.d.ts

@@ -1,5 +1,8 @@
 import { type MeshEntry } from "@cotal-ai/workspace";
 type Values = Record<string, string | undefined>;
+/** Read the resume commit token from its protected handoff file once, check it against the
+ *  digest named on argv, then unlink it. Errors name the field only; the value is never echoed. */
+export declare function readResumeCommitFile(path: string, sha256: string): string;
 /**
  * RECORD THIS PROCESS as the running manager, and un-record it on a clean exit.
  *

package/dist/commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAwBA,OAAO,EAIL,KAAK,SAAS,EACf,MAAM,qBAAqB,CAAC;AAgB7B,KAAK,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAEjD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,IAAI,CA+BxE;AAQD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,SAAkB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,OAAO,CAAC;IAAC,cAAc,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;IAAC,sBAAsB,CAAC,EAAE,MAAM,CAAA;CAAE,CAuDvO"}
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AA2BA,OAAO,EAKkB,KAAK,SAAS,EACtC,MAAM,qBAAqB,CAAC;AAiB7B,KAAK,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAEjD;mGACmG;AACnG,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CASzE;AAaD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,IAAI,CAgCxE;AAQD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,SAAkB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,OAAO,CAAC;IAAC,cAAc,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;IAAC,sBAAsB,CAAC,EAAE,MAAM,CAAA;CAAE,CAuDvO"}