@cotal-ai/manager 0.16.0 → 0.18.0

package/dist/reconcile-gate.d.ts

@@ -0,0 +1,82 @@
+import type { KV } from "@nats-io/kv";
+/** Which guard refused. The command prints this verbatim, and the smoke asserts on it, so a refusal
+ *  can never be confused with a different refusal — the failure mode where an operator reads
+ *  "refused" and force-retries the wrong thing. */
+export type GateReconcileCondition = 
+/** No gate row at the coordinate — nothing to reconcile (a typo'd endpoint/instanceId). */
+"no-gate"
+/** The gate is `open` or `retired`: this repairs a frozen gate only. */
+ | "not-frozen"
+/** Frozen under a takeover/activation/retirement op — this completes a REGISTRATION's obligation. */
+ | "wrong-op-kind"
+/** The freeze-holder still holds a live connection. The freeze is protecting a live op. */
+ | "holder-alive"
+/** The sweep under-reported (no responder, truncation, unproven single-server mode). May be live. */
+ | "holder-unknown"
+/** The oracle could not be consulted at all, or answered unusably (unreachable, unprovisioned,
+ *  garbled, or a reply that did not echo the principal asked about). */
+ | "liveness-unestablishable"
+/** A holder's eviction was not VERIFIED gone — the barrier's own fail-closed step. */
+ | "eviction-unverified"
+/** The token-pinned reopen lost its CAS: a newer barrier moved the gate. Re-observe. */
+ | "raced";
+/** A refusal, carrying the condition as DATA rather than only as prose. */
+export declare class GateReconcileRefused extends Error {
+    readonly condition: GateReconcileCondition;
+    constructor(condition: GateReconcileCondition, message: string);
+}
+/** The freeze-holder liveness verdict as the reconciler consumes it. `unestablishable` is kept
+ *  DISTINCT from `unknown`: both refuse, but they tell the operator to fix different things (start
+ *  the daemon vs. re-observe a mesh that could not be swept completely). */
+export type HolderLiveness = {
+    state: "live";
+    detail: string;
+} | {
+    state: "gone";
+    detail: string;
+} | {
+    state: "unknown";
+    detail: string;
+} | {
+    state: "unestablishable";
+    detail: string;
+};
+/** What the reconciliation found and did — returned on success, and logged either way. */
+export interface GateReconcileReport {
+    endpoint: string;
+    instanceId: string;
+    holderPrincipal: string;
+    opId: string;
+    freezeToken: number;
+    /** The coordinate before the repair; the reopen advances `generation` by one and NOTHING else. */
+    before: {
+        generation: number;
+        processEpoch: number;
+        registrationRevision: number;
+        nameAuthorityRevision: number;
+    };
+    liveness: HolderLiveness;
+    familyRows: number;
+    revoked: string[];
+    evicted: string[];
+    reopenedAtGeneration: number;
+}
+/**
+ * Reconcile ONE frozen gate. Every seam the guard depends on is injected, so the command wires the
+ * real ones and the smoke drives the real barrier against an ephemeral broker.
+ *
+ * `probeHolder` is the AFFIRMATIVE check. It must return `gone` only on a proven-absent verdict;
+ * everything else — including any form of "we did not hear back" — must be `unknown` or
+ * `unestablishable`. It is a parameter and not an inlined call so that this ordering (probe, then
+ * refuse, THEN mutate) is structural: the barrier is not even constructed until the probe passed.
+ */
+export declare function reconcileEndpointGate(opts: {
+    kv: KV;
+    space: string;
+    endpoint: string;
+    instanceId: string;
+    probeHolder: (principal: string) => Promise<HolderLiveness>;
+    evict: (holderPrincipal: string) => Promise<boolean>;
+    log: (line: string) => void;
+}): Promise<GateReconcileReport>;
+//# sourceMappingURL=reconcile-gate.d.ts.map

package/dist/reconcile-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile-gate.d.ts","sourceRoot":"","sources":["../src/reconcile-gate.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAEtC;;mDAEmD;AACnD,MAAM,MAAM,sBAAsB;AAChC,2FAA2F;AACzF,SAAS;AACX,wEAAwE;GACtE,YAAY;AACd,qGAAqG;GACnG,eAAe;AACjB,2FAA2F;GACzF,cAAc;AAChB,qGAAqG;GACnG,gBAAgB;AAClB;wEACwE;GACtE,0BAA0B;AAC5B,sFAAsF;GACpF,qBAAqB;AACvB,wFAAwF;GACtF,OAAO,CAAC;AAEZ,2EAA2E;AAC3E,qBAAa,oBAAqB,SAAQ,KAAK;IAE3C,QAAQ,CAAC,SAAS,EAAE,sBAAsB;gBAAjC,SAAS,EAAE,sBAAsB,EAC1C,OAAO,EAAE,MAAM;CAKlB;AAED;;4EAE4E;AAC5E,MAAM,MAAM,cAAc,GACtB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,KAAK,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjD,0FAA0F;AAC1F,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,kGAAkG;IAClG,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,oBAAoB,EAAE,MAAM,CAAC;QAAC,qBAAqB,EAAE,MAAM,CAAA;KAAE,CAAC;IAClH,QAAQ,EAAE,cAAc,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAChD,EAAE,EAAE,EAAE,CAAC;IACP,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAC5D,KAAK,EAAE,CAAC,eAAe,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACrD,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA4F/B"}

package/dist/reconcile-gate.js

@@ -0,0 +1,118 @@
+/**
+ * GUARDED RECONCILIATION of an endpoint issuance gate left FROZEN by a crashed re-registration
+ * (Cotal #391; SPEC 13.1 "the gate is left frozen for reconciliation").
+ *
+ * THE STATE THIS REPAIRS, and the only one it accepts: a manager restart was killed between the
+ * barrier's freeze and the successor's completion. The gate is `frozen` under a `registration` op
+ * whose holder no longer exists, so the freeze token's owner can never resume. Fail-closed is
+ * correct and stays correct — but in THAT state the freeze protects nothing while blocking every
+ * restart, and before this the operator's only exits were hand-driving internals or discarding
+ * state.
+ *
+ * The repair itself is not new: it is the SHIPPED composition (`endpointRegistrationBarrier` +
+ * a verified evictor), driven in the §13.1 order, with no raw writes. What is new is the GUARD in
+ * front of it, which is the whole point of the command:
+ *
+ *   1. VERIFY THE HOLDER IS GONE, AFFIRMATIVELY. Not "the holder did not answer", not "a timeout
+ *      elapsed" — a COMPLETE, single-server-proven CONNZ sweep that PROVES no connection attributes
+ *      to the freeze-holder. Absence of evidence is `unknown`, and `unknown` REFUSES.
+ *   2. LOG WHAT WAS FOUND, before mutating anything.
+ *   3. REFUSE LOUD, NAMING WHICH CONDITION FAILED — an operator staring at a wedged mesh needs to
+ *      know whether the holder is alive, whether liveness could not be established, or whether the
+ *      gate simply is not in the state this repairs. "It refused" is not actionable.
+ *
+ * The probe sits ON TOP OF the barrier's own fail-closed eviction, never in place of it: BOTH must
+ * pass. There is deliberately NO force flag and no path that discards gate state — a recovery path
+ * whose failure mode is killing a live manager does not get an override.
+ */
+import { endpointRegistrationBarrier, parseEndpointGate, epgateKey, } from "@cotal-ai/core";
+/** A refusal, carrying the condition as DATA rather than only as prose. */
+export class GateReconcileRefused extends Error {
+    condition;
+    constructor(condition, message) {
+        super(message);
+        this.condition = condition;
+        this.name = "GateReconcileRefused";
+    }
+}
+/**
+ * Reconcile ONE frozen gate. Every seam the guard depends on is injected, so the command wires the
+ * real ones and the smoke drives the real barrier against an ephemeral broker.
+ *
+ * `probeHolder` is the AFFIRMATIVE check. It must return `gone` only on a proven-absent verdict;
+ * everything else — including any form of "we did not hear back" — must be `unknown` or
+ * `unestablishable`. It is a parameter and not an inlined call so that this ordering (probe, then
+ * refuse, THEN mutate) is structural: the barrier is not even constructed until the probe passed.
+ */
+export async function reconcileEndpointGate(opts) {
+    const { kv, space, endpoint, instanceId, log } = opts;
+    // ---- 1. Observe the gate RAW: the freeze token IS the row revision, and the dead op's opId is
+    // on the row. Both are needed to complete that op's obligation rather than start a new one.
+    const key = epgateKey(endpoint, instanceId);
+    const entry = await kv.get(key);
+    if (!entry || entry.operation !== "PUT")
+        throw new GateReconcileRefused("no-gate", `no endpoint gate at ${key} — nothing to reconcile (check the endpoint and instanceId)`);
+    const row = parseEndpointGate(entry.value, key);
+    const freezeToken = entry.revision;
+    log(`gate ${key}: state=${row.state} generation=${row.generation} processEpoch=${row.processEpoch} registrationRevision=${row.registrationRevision} nameAuthorityRevision=${row.nameAuthorityRevision} op=${JSON.stringify(row.op ?? null)} holder=${row.principal} revision=${freezeToken}`);
+    if (row.state !== "frozen")
+        throw new GateReconcileRefused("not-frozen", `the gate at ${key} is "${row.state}", not "frozen" — this reconciles a frozen gate only, and an open gate needs no repair`);
+    if (row.op?.kind !== "registration")
+        throw new GateReconcileRefused("wrong-op-kind", `the gate at ${key} is frozen under a "${row.op?.kind}" op, not a registration — this completes a crashed REGISTRATION's §13.1 obligation only; refusing to reinterpret another op's intent`);
+    const opId = row.op.opId;
+    // ---- 2. THE GUARD. Affirmative liveness, before anything is mutated.
+    const liveness = await opts.probeHolder(row.principal);
+    log(`freeze-holder ${row.principal}: ${liveness.state} — ${liveness.detail}`);
+    if (liveness.state === "live")
+        throw new GateReconcileRefused("holder-alive", `the freeze-holder "${row.principal}" is ALIVE (${liveness.detail}) — the freeze is protecting an op that is still running. Refusing: reconciling here would revoke and evict a live incarnation's credential family. Stop that process first, then re-run.`);
+    if (liveness.state === "unknown")
+        throw new GateReconcileRefused("holder-unknown", `the liveness of freeze-holder "${row.principal}" is UNKNOWN (${liveness.detail}) — the sweep could not prove it absent, and absence of evidence is not evidence of absence. Refusing: a holder that may still be live is treated as live.`);
+    if (liveness.state === "unestablishable")
+        throw new GateReconcileRefused("liveness-unestablishable", `liveness for freeze-holder "${row.principal}" CANNOT BE ESTABLISHED (${liveness.detail}) — without the oracle this repair has no affirmative check to stand on, and it will not infer death from silence.`);
+    // ---- 3. Only now: the shipped composition, in the §13.1 order, over the DEAD op's own id.
+    const barrier = endpointRegistrationBarrier(kv, space, { endpoint, instanceId, opId, evict: opts.evict });
+    const rows = await barrier.enumerate();
+    log(`family: ${rows.length} ledger row(s)`);
+    const revoked = [];
+    for (const r of rows) {
+        if (r.state === "active") {
+            await barrier.revoke(r); // deny-new BEFORE kill-live — the precondition eviction's name carries
+            revoked.push(r.credentialId);
+            log(`  revoked ${r.credentialId} (${r.holderPrincipal})`);
+        }
+        else
+            log(`  ${r.state}: ${r.credentialId} (${r.holderPrincipal})`);
+    }
+    // Evict every distinct family holder, and the freeze-holder itself even when it staged no rows —
+    // the probe proved it gone, and the barrier's verify is what makes that durable rather than a
+    // snapshot. An unverified eviction aborts and LEAVES THE GATE FROZEN (unchanged §13.1 posture).
+    const holders = [...new Set([row.principal, ...rows.map((r) => r.holderPrincipal)])];
+    const evicted = [];
+    for (const h of holders) {
+        if (!(await barrier.evict(h)))
+            throw new GateReconcileRefused("eviction-unverified", `eviction of "${h}" was NOT verified gone — the gate stays frozen (fail-closed, SPEC 13.1). Nothing was reopened; the revocations above are deny-new and safe to leave.`);
+        evicted.push(h);
+        log(`  verified evicted: ${h}`);
+    }
+    // ---- 4. Token-pinned abort-reopen at the UNCHANGED coordinate. The dead op wrote nothing
+    // forward, so only `generation` advances; the successor's normal takeover then runs end-to-end.
+    const reopenedAtGeneration = row.generation + 1;
+    const ok = await barrier.reopen(freezeToken, {
+        generation: reopenedAtGeneration,
+        processEpoch: row.processEpoch,
+        registrationRevision: row.registrationRevision,
+        nameAuthorityRevision: row.nameAuthorityRevision,
+    });
+    if (!ok)
+        throw new GateReconcileRefused("raced", `the token-pinned reopen of ${key} lost its CAS — a newer barrier moved the gate while this repair ran. Nothing was reopened; re-observe before retrying.`);
+    log(`✓ gate ${key} reopened at generation=${reopenedAtGeneration}, processEpoch unchanged (${row.processEpoch}); family revoked (${revoked.length}) and verify-evicted (${evicted.length} holder(s))`);
+    return {
+        endpoint, instanceId, holderPrincipal: row.principal, opId, freezeToken,
+        before: {
+            generation: row.generation, processEpoch: row.processEpoch,
+            registrationRevision: row.registrationRevision, nameAuthorityRevision: row.nameAuthorityRevision,
+        },
+        liveness, familyRows: rows.length, revoked, evicted, reopenedAtGeneration,
+    };
+}
+//# sourceMappingURL=reconcile-gate.js.map

package/dist/reconcile-gate.js.map

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

package/dist/runtime/pty.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pty.d.ts","sourceRoot":"","sources":["../../src/runtime/pty.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAiB,UAAU,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAoBtF;;;;;GAKG;AACH,qBAAa,UAAW,YAAW,OAAO;IACxC,QAAQ,CAAC,IAAI,EAAG,KAAK,CAAU;IAE/B,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW;CAsJhE"}
+{"version":3,"file":"pty.d.ts","sourceRoot":"","sources":["../../src/runtime/pty.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAiB,UAAU,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAoBtF;;;;;GAKG;AACH,qBAAa,UAAW,YAAW,OAAO;IACxC,QAAQ,CAAC,IAAI,EAAG,KAAK,CAAU;IAE/B,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW;CAgKhE"}

package/dist/runtime/pty.js

@@ -163,6 +163,14 @@ export class PtyRuntime {
                     return () => dataSubs.delete(fn);
                 },
                 onExit: (fn) => {
+                    // Already exited (a session attaching over a just-dead pty): fire on the next tick so the
+                    // bridge surfaces a `process-exit` end frame instead of a silent zombie. proc.onExit fired
+                    // ONCE before this listener existed, so a late subscriber would otherwise never hear it
+                    // (waitForExit carries the same already-dead guard).
+                    if (!alive) {
+                        queueMicrotask(fn);
+                        return () => { };
+                    }
                     exitSubs.add(fn);
                     return () => exitSubs.delete(fn);
                 },
@@ -171,10 +179,15 @@ export class PtyRuntime {
                         proc.write(data);
                 },
                 resize: (c, r) => {
+                    // node-pty REJECTS a non-positive dimension (throws), and a console fitting BEFORE its pane
+                    // is laid out can send a 0. Guard BOTH the mirror and the pty resize so a degenerate geometry
+                    // is a safe no-op — never a throw that would propagate into and wedge the serving frame
+                    // handler (the live-e2e "zombie session" class).
+                    if (c <= 0 || r <= 0)
+                        return;
                     cols = c;
                     rows = r;
-                    if (c > 0 && r > 0)
-                        term.resize(c, r); // keep the mirror in step so snapshots reconstruct at size
+                    term.resize(c, r); // keep the mirror in step so snapshots reconstruct at size
                     if (alive)
                         proc.resize(c, r);
                 },

package/dist/runtime/pty.js.map

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

package/dist/session/bridge.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The serving-side PTY ↔ session-rail bridge (P2 item 6). Given an authenticated §13.6 session
+ * (its verified grant + a connection scoped to the two eps rails) and a live pty {@link
+ * AttachSession}, it speaks the {@link TerminalFrame} framing over `openSessionRail(role:"serving")`:
+ *
+ *  - the RECONSTRUCTION handshake (PR #158 preserved over the mesh): the caller opens its rail,
+ *    then sends `ready`; the bridge replays the pty's byte-exact backlog snapshot (which can rebuild
+ *    a full-screen TUI's alternate-screen buffer) and only then streams live output — so a late or
+ *    third attach paints correctly without the child having to repaint. Live output that arrives
+ *    while the snapshot is being built is buffered and flushed after it, in order (no chunk slips
+ *    ahead of, or is lost before, the image);
+ *  - duplex byte flow: pty output → `b` frames (serving → caller); caller `b` frames → pty
+ *    keystrokes; `resize` frames → pty geometry;
+ *  - BACKPRESSURE (item-6 pin: never silent loss): the core rail's window is bounded and refuses
+ *    (`resource-exhausted`) rather than buffer; on refusal the bridge DROPS the chunk, accumulates
+ *    the dropped-byte count, and prepends an explicit `drop` notice to the next frame the reopened
+ *    window accepts — the caller always learns output was lost;
+ *  - TERMINATION (item-6 pin 4): every teardown surfaces a DISTINCT end reason (`process-exit` /
+ *    `closed` / `expired` / `target-despawn` / `manager-restart`) as an `end` frame before the rail
+ *    closes, so the client can tell "the agent exited" from "you were detached" from "the manager
+ *    restarted".
+ */
+import type { NatsConnection } from "@nats-io/transport-node";
+import { type SessionGrant, type AttachSession } from "@cotal-ai/core";
+/** The reference manager's terminal-cause vocabulary (the `end.reason` tokens it surfaces — a
+ *  bounded subset of the generic §13.6 terminal-session `end` reason). `process-exit` = the child
+ *  exited; `closed` = a party closed the rail; `expired` = the offer/session TTL elapsed;
+ *  `target-despawn` = the attached agent was despawned; `manager-restart` = the serving manager
+ *  incarnation advanced its epoch (the successor refuses old-epoch sessions, §13.6). */
+export type AttachEndReason = "process-exit" | "closed" | "expired" | "target-despawn" | "manager-restart";
+export interface ServeSessionBridgeOpts {
+    /** A connection scoped to this session's two eps rails (the serving side's per-session credential,
+     *  or — static mode — the manager's instrument connection whose rows cover the subtree). */
+    nc: NatsConnection;
+    /** The VERIFIED session grant (subjects/window/epoch); the bridge grants nothing, it only frames. */
+    grant: SessionGrant;
+    /** The live pty to bridge. */
+    session: AttachSession;
+    /** Fires once with the distinct end reason when the session tears down (either side). */
+    onEnd?(reason: AttachEndReason): void;
+    /** Passthrough rail timer knobs (testability). */
+    idleCreditMs?: number;
+    stallTimeoutMs?: number;
+}
+export interface SessionBridge {
+    /** Terminate the session with a distinct reason (target despawn / manager restart / expiry): the
+     *  `end` frame is sent best-effort, then the rail closes and the pty is unsubscribed. Idempotent. */
+    end(reason: AttachEndReason): void;
+    /** In-memory observability (smoke assertions): the rail's window stats, the dropped-byte count
+     *  (backpressure), the dropped-FRAME count (caller frames the codec rejected), and whether the
+     *  reconstruction handshake has gone live. */
+    stats(): {
+        sent: number;
+        ackedThrough: number;
+        delivered: number;
+        inFlight: number;
+        droppedBytes: number;
+        droppedFrames: number;
+        live: boolean;
+    };
+}
+export declare function serveSessionBridge(opts: ServeSessionBridgeOpts): SessionBridge;
+//# sourceMappingURL=bridge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../../src/session/bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAEL,KAAK,YAAY,EAAoB,KAAK,aAAa,EACxD,MAAM,gBAAgB,CAAC;AAExB;;;;wFAIwF;AACxF,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,QAAQ,GAAG,SAAS,GAAG,gBAAgB,GAAG,iBAAiB,CAAC;AAE3G,MAAM,WAAW,sBAAsB;IACrC;gGAC4F;IAC5F,EAAE,EAAE,cAAc,CAAC;IACnB,qGAAqG;IACrG,KAAK,EAAE,YAAY,CAAC;IACpB,8BAA8B;IAC9B,OAAO,EAAE,aAAa,CAAC;IACvB,yFAAyF;IACzF,KAAK,CAAC,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC;IACtC,kDAAkD;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B;yGACqG;IACrG,GAAG,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC;IACnC;;kDAE8C;IAC9C,KAAK,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC;CAClJ;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,sBAAsB,GAAG,aAAa,CAsI9E"}

package/dist/session/bridge.js

@@ -0,0 +1,157 @@
+import { EpEnvelopeError, openSessionRail, encodeTerminalData, terminalFrameBytes, decodeTerminalFrame, } from "@cotal-ai/core";
+export function serveSessionBridge(opts) {
+    const { session } = opts;
+    let live = false; // has `ready` been received (backlog replayed, streaming live)?
+    let ended = false;
+    let droppedBytes = 0;
+    let droppedFrames = 0; // caller frames the codec rejected (observability; NOT a silent black hole)
+    const preReadyBuffer = [];
+    let rail;
+    // Send an application payload down the serving rail. Returns true on success; false when the
+    // window is FULL (`resource-exhausted`, the caller-must-drop signal); any OTHER failure
+    // (broken/closed rail) terminates the session — a broken transport is a distinct `closed` end.
+    const railSend = (p) => {
+        try {
+            rail.send(p);
+            return true;
+        }
+        catch (e) {
+            if (e instanceof EpEnvelopeError && e.code === "resource-exhausted")
+                return false;
+            end("closed");
+            return false;
+        }
+    };
+    // Forward one pty output chunk, honoring backpressure with an explicit drop-notice. A pending
+    // drop count is flushed FIRST (the caller must learn output was lost before the resumed stream),
+    // and only if that notice lands does the actual chunk go — otherwise the chunk's bytes join the
+    // drop count. Nothing is ever buffered unboundedly: a chunk the window can't take is DROPPED,
+    // counted, and surfaced, never queued.
+    const forwardOutput = (chunk) => {
+        if (ended)
+            return;
+        if (droppedBytes > 0) {
+            if (railSend({ k: "drop", bytes: droppedBytes }))
+                droppedBytes = 0;
+            else {
+                droppedBytes += chunk.length;
+                return;
+            }
+        }
+        if (!railSend(encodeTerminalData(chunk)))
+            droppedBytes += chunk.length;
+    };
+    const offData = session.onData((chunk) => {
+        if (ended)
+            return;
+        if (live)
+            forwardOutput(chunk);
+        else
+            preReadyBuffer.push(chunk); // hold until the snapshot is replayed, then flush in order
+    });
+    // The pty exit surfaces `process-exit` — but DEFERRED until the caller is live if it exits before
+    // the `ready` handshake (a session established over an already-dead, or a just-dying, pty): EPS is
+    // at-most-once, so an `end` frame sent before the caller subscribed to `.out` is lost. goLive sends
+    // the deferred exit AFTER the backlog, so the caller always learns the agent exited.
+    let pendingExit = false;
+    const offExit = session.onExit(() => { if (live)
+        end("process-exit");
+    else
+        pendingExit = true; });
+    // The reconstruction handshake: replay the byte-exact backlog snapshot, then flush anything the
+    // pty emitted while we built it, then stream live. Subscribing to output BEFORE this (above)
+    // means no chunk is lost between the snapshot and going live. A repeat `ready` (an explicit
+    // repaint) re-sends a fresh snapshot without re-flushing the already-drained pre-ready buffer.
+    const goLive = async () => {
+        let snapshot;
+        try {
+            snapshot = await session.backlog();
+        }
+        catch (e) {
+            end("closed");
+            void e;
+            return;
+        }
+        if (ended)
+            return;
+        if (snapshot.length)
+            forwardOutput(snapshot);
+        if (!live) {
+            for (const chunk of preReadyBuffer.splice(0))
+                forwardOutput(chunk);
+            live = true;
+        }
+        // The pty exited before we went live (established over a dead/dying pty): surface `process-exit`
+        // NOW, after the backlog reconstruction, so the caller sees the final screen AND the honest end.
+        if (pendingExit)
+            end("process-exit");
+    };
+    const onCallerFrame = (data) => {
+        // A caller frame must NEVER wedge the serving rail. A GARBLED or DEGENERATE frame — e.g. a console
+        // fitting before its pane is laid out sends a 0-dim resize, which the §13.6 codec rejects — is
+        // dropped, and each pty side effect is best-effort. One bad frame crashing this handler is exactly
+        // the live-e2e "zombie session" class (rail open, no echo, no honest end) that violates pin 4.
+        // But a drop is NEVER a black hole: it is COUNTED + LOGGED so a silent inbound failure (a caller
+        // whose frames all decode-reject) is diagnosable, not invisible.
+        let p;
+        try {
+            p = decodeTerminalFrame(data);
+        }
+        catch (e) {
+            droppedFrames++;
+            console.error(`! session ${opts.grant.sessionId}: dropped an undecodable caller frame #${droppedFrames} (${e.message})`);
+            return;
+        }
+        switch (p.k) {
+            case "ready":
+                void goLive();
+                return;
+            case "data":
+                try {
+                    session.write(new TextDecoder().decode(terminalFrameBytes(p)));
+                }
+                catch { /* pty gone/degenerate; never wedge the rail */ }
+                return;
+            case "resize":
+                try {
+                    session.resize(p.cols, p.rows);
+                }
+                catch { /* degenerate geometry; ignore, never wedge */ }
+                return;
+            // `end`/`drop` are serving → caller only; a caller sending one is out of protocol — ignore it.
+            case "end":
+            case "drop":
+                return;
+        }
+    };
+    function end(reason) {
+        if (ended)
+            return;
+        ended = true;
+        offData();
+        offExit();
+        try {
+            rail.send({ k: "end", reason }); // best-effort distinct end-state notice (advisory; may window out)
+        }
+        catch {
+            /* the ledger close/expiry is the authority; the notice is advisory (§13.6) */
+        }
+        rail.close();
+        opts.onEnd?.(reason);
+    }
+    rail = openSessionRail({
+        nc: opts.nc,
+        grant: opts.grant,
+        role: "serving",
+        onData: onCallerFrame,
+        onClose: () => end("closed"),
+        onProtocolError: () => end("closed"),
+        ...(opts.idleCreditMs !== undefined ? { idleCreditMs: opts.idleCreditMs } : {}),
+        ...(opts.stallTimeoutMs !== undefined ? { stallTimeoutMs: opts.stallTimeoutMs } : {}),
+    });
+    return {
+        end,
+        stats: () => ({ ...rail.stats(), droppedBytes, droppedFrames, live }),
+    };
+}
+//# sourceMappingURL=bridge.js.map

package/dist/session/bridge.js.map

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