@tokenfactory/acc-runner 0.40.23 → 0.40.24

package/dist/warm-session/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * CX-4 (WARM-SESSIONS): barrel export for the warm-session layer.
+ *
+ * A pre-spawned, resumable engine session per active conversation so chat turns
+ * reuse it (fast first token) instead of paying process spawn every prompt.
+ * These are injectable PRIMITIVES; a follow-up wires the pool into the companion
+ * (a `claude --session-id` warm factory + `capacityHeld()` folded into the
+ * chat-lane claim budget), exactly as the AS-3 resume primitives shipped ahead
+ * of their watch/companion wiring. Intentionally `dead-until-wired`.
+ */
+export * from "./types.js";
+export * from "./latency.js";
+export * from "./pool.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/warm-session/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/warm-session/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}

package/dist/warm-session/index.js

@@ -0,0 +1,14 @@
+/**
+ * CX-4 (WARM-SESSIONS): barrel export for the warm-session layer.
+ *
+ * A pre-spawned, resumable engine session per active conversation so chat turns
+ * reuse it (fast first token) instead of paying process spawn every prompt.
+ * These are injectable PRIMITIVES; a follow-up wires the pool into the companion
+ * (a `claude --session-id` warm factory + `capacityHeld()` folded into the
+ * chat-lane claim budget), exactly as the AS-3 resume primitives shipped ahead
+ * of their watch/companion wiring. Intentionally `dead-until-wired`.
+ */
+export * from "./types.js";
+export * from "./latency.js";
+export * from "./pool.js";
+//# sourceMappingURL=index.js.map

package/dist/warm-session/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/warm-session/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}

package/dist/warm-session/latency.d.ts

@@ -0,0 +1,72 @@
+/**
+ * CX-4 (WARM-SESSIONS): the first-token latency recorder.
+ *
+ * The default `OpsMetricsSink` the pool reports into. It keeps a bounded ring of
+ * recent first-token samples PER MODE (warm/cold) and computes p50/p95 with the
+ * nearest-rank method, so Pulse can render "warm p50 <= 1.5s / cold <= 4s" from
+ * one snapshot. No-token turns (an empty/failed reply, `firstTokenMs === null`)
+ * are counted but EXCLUDED from the percentile so a broken turn never flatters
+ * or poisons the latency picture. A follow-up wires an adapter over this that
+ * forwards each sample to the durable ops-metrics topic; this recorder is the
+ * pure, deterministic core the benchmark asserts against.
+ *
+ * STAGING: intentionally `dead-until-wired` — the ops-metrics/Pulse adapter over
+ * this recorder lands in a follow-up (see the task's Follow-ups).
+ */
+import { type FirstTokenMode, type FirstTokenSample, type OpsMetricsSink } from "./types.js";
+/** Percentile view of one mode's first-token samples (ms); null when empty. */
+export interface FirstTokenPercentiles {
+    /** Total samples recorded for the mode (includes no-token turns). */
+    count: number;
+    /** Samples that produced a visible token (the percentile population). */
+    tokenCount: number;
+    p50: number | null;
+    p95: number | null;
+    min: number | null;
+    max: number | null;
+    /** Simple arithmetic mean of the token-bearing samples (ms). */
+    mean: number | null;
+}
+/** A full warm-vs-cold snapshot plus the pass/fail against the plan targets. */
+export interface FirstTokenStats {
+    warm: FirstTokenPercentiles;
+    cold: FirstTokenPercentiles;
+    /** True when warm has ≥1 token sample and its p50 ≤ the warm target. */
+    warmP50WithinTarget: boolean;
+    /** True when cold has ≥1 token sample and its p95 ≤ the cold target. */
+    coldP95WithinTarget: boolean;
+    targets: {
+        warmP50Ms: number;
+        coldP95Ms: number;
+    };
+}
+/**
+ * Nearest-rank percentile over an ASCENDING-sorted array. `p` is 0..100. Returns
+ * null for an empty array. index = clamp(ceil(p/100 * n) - 1, 0, n-1).
+ */
+export declare function percentile(sortedAsc: readonly number[], p: number): number | null;
+export interface FirstTokenLatencyRecorderOptions {
+    /** Max samples retained per mode (ring buffer); older samples are evicted. */
+    maxSamplesPerMode?: number;
+    /** Warm p50 target (ms) — defaults to the plan's 1.5s. */
+    warmP50TargetMs?: number;
+    /** Cold p95 target (ms) — defaults to the plan's 4s. */
+    coldP95TargetMs?: number;
+}
+/** In-memory, bounded first-token recorder implementing `OpsMetricsSink`. */
+export declare class FirstTokenLatencyRecorder implements OpsMetricsSink {
+    private readonly byMode;
+    private readonly maxSamples;
+    private readonly warmP50TargetMs;
+    private readonly coldP95TargetMs;
+    constructor(opts?: FirstTokenLatencyRecorderOptions);
+    recordFirstToken(sample: FirstTokenSample): void;
+    /** All retained samples for a mode (stable copy). */
+    samples(mode: FirstTokenMode): readonly FirstTokenSample[];
+    private percentilesFor;
+    /** Current warm/cold percentiles plus pass/fail against the targets. */
+    snapshot(): FirstTokenStats;
+    /** Drop all retained samples (test/rig reset). */
+    reset(): void;
+}
+//# sourceMappingURL=latency.d.ts.map

package/dist/warm-session/latency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"latency.d.ts","sourceRoot":"","sources":["../../src/warm-session/latency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACpB,MAAM,YAAY,CAAC;AAEpB,+EAA+E;AAC/E,MAAM,WAAW,qBAAqB;IACpC,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,gEAAgE;IAChE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,gFAAgF;AAChF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,qBAAqB,CAAC;IAC5B,IAAI,EAAE,qBAAqB,CAAC;IAC5B,wEAAwE;IACxE,mBAAmB,EAAE,OAAO,CAAC;IAC7B,wEAAwE;IACxE,mBAAmB,EAAE,OAAO,CAAC;IAC7B,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CACnD;AAYD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMjF;AAED,MAAM,WAAW,gCAAgC;IAC/C,8EAA8E;IAC9E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,0DAA0D;IAC1D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,wDAAwD;IACxD,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAID,6EAA6E;AAC7E,qBAAa,yBAA0B,YAAW,cAAc;IAC9D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAGrB;IACF,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;gBAE7B,IAAI,GAAE,gCAAqC;IAMvD,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI;IAOhD,qDAAqD;IACrD,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,gBAAgB,EAAE;IAI1D,OAAO,CAAC,cAAc;IAoBtB,wEAAwE;IACxE,QAAQ,IAAI,eAAe;IAY3B,kDAAkD;IAClD,KAAK,IAAI,IAAI;CAId"}

package/dist/warm-session/latency.js

@@ -0,0 +1,102 @@
+/**
+ * CX-4 (WARM-SESSIONS): the first-token latency recorder.
+ *
+ * The default `OpsMetricsSink` the pool reports into. It keeps a bounded ring of
+ * recent first-token samples PER MODE (warm/cold) and computes p50/p95 with the
+ * nearest-rank method, so Pulse can render "warm p50 <= 1.5s / cold <= 4s" from
+ * one snapshot. No-token turns (an empty/failed reply, `firstTokenMs === null`)
+ * are counted but EXCLUDED from the percentile so a broken turn never flatters
+ * or poisons the latency picture. A follow-up wires an adapter over this that
+ * forwards each sample to the durable ops-metrics topic; this recorder is the
+ * pure, deterministic core the benchmark asserts against.
+ *
+ * STAGING: intentionally `dead-until-wired` — the ops-metrics/Pulse adapter over
+ * this recorder lands in a follow-up (see the task's Follow-ups).
+ */
+import { COLD_FIRST_TOKEN_TARGET_MS, WARM_FIRST_TOKEN_P50_TARGET_MS, } from "./types.js";
+const EMPTY_PERCENTILES = {
+    count: 0,
+    tokenCount: 0,
+    p50: null,
+    p95: null,
+    min: null,
+    max: null,
+    mean: null,
+};
+/**
+ * Nearest-rank percentile over an ASCENDING-sorted array. `p` is 0..100. Returns
+ * null for an empty array. index = clamp(ceil(p/100 * n) - 1, 0, n-1).
+ */
+export function percentile(sortedAsc, p) {
+    const n = sortedAsc.length;
+    if (n === 0)
+        return null;
+    const rank = Math.ceil((p / 100) * n);
+    const idx = Math.min(n - 1, Math.max(0, rank - 1));
+    return sortedAsc[idx] ?? null;
+}
+const DEFAULT_MAX_SAMPLES = 1_000;
+/** In-memory, bounded first-token recorder implementing `OpsMetricsSink`. */
+export class FirstTokenLatencyRecorder {
+    byMode = {
+        warm: [],
+        cold: [],
+    };
+    maxSamples;
+    warmP50TargetMs;
+    coldP95TargetMs;
+    constructor(opts = {}) {
+        this.maxSamples = Math.max(1, Math.floor(opts.maxSamplesPerMode ?? DEFAULT_MAX_SAMPLES));
+        this.warmP50TargetMs = opts.warmP50TargetMs ?? WARM_FIRST_TOKEN_P50_TARGET_MS;
+        this.coldP95TargetMs = opts.coldP95TargetMs ?? COLD_FIRST_TOKEN_TARGET_MS;
+    }
+    recordFirstToken(sample) {
+        const bucket = this.byMode[sample.mode];
+        bucket.push(sample);
+        // Ring: drop the oldest once past the cap so retention stays bounded.
+        if (bucket.length > this.maxSamples)
+            bucket.splice(0, bucket.length - this.maxSamples);
+    }
+    /** All retained samples for a mode (stable copy). */
+    samples(mode) {
+        return [...this.byMode[mode]];
+    }
+    percentilesFor(mode) {
+        const all = this.byMode[mode];
+        if (all.length === 0)
+            return { ...EMPTY_PERCENTILES };
+        const tokenMs = all
+            .filter((s) => s.sawToken && typeof s.firstTokenMs === "number")
+            .map((s) => s.firstTokenMs)
+            .sort((a, b) => a - b);
+        const tokenCount = tokenMs.length;
+        const sum = tokenMs.reduce((acc, v) => acc + v, 0);
+        return {
+            count: all.length,
+            tokenCount,
+            p50: percentile(tokenMs, 50),
+            p95: percentile(tokenMs, 95),
+            min: tokenCount > 0 ? tokenMs[0] : null,
+            max: tokenCount > 0 ? tokenMs[tokenCount - 1] : null,
+            mean: tokenCount > 0 ? sum / tokenCount : null,
+        };
+    }
+    /** Current warm/cold percentiles plus pass/fail against the targets. */
+    snapshot() {
+        const warm = this.percentilesFor("warm");
+        const cold = this.percentilesFor("cold");
+        return {
+            warm,
+            cold,
+            warmP50WithinTarget: warm.p50 !== null && warm.p50 <= this.warmP50TargetMs,
+            coldP95WithinTarget: cold.p95 !== null && cold.p95 <= this.coldP95TargetMs,
+            targets: { warmP50Ms: this.warmP50TargetMs, coldP95Ms: this.coldP95TargetMs },
+        };
+    }
+    /** Drop all retained samples (test/rig reset). */
+    reset() {
+        this.byMode.warm.length = 0;
+        this.byMode.cold.length = 0;
+    }
+}
+//# sourceMappingURL=latency.js.map

package/dist/warm-session/latency.js.map

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

package/dist/warm-session/pool.d.ts

@@ -0,0 +1,153 @@
+/**
+ * CX-4 (WARM-SESSIONS): the warm-session pool.
+ *
+ * Holds at most one pre-spawned, resumable engine session per ACTIVE
+ * conversation and routes each turn through the fastest available path:
+ *
+ *   - WARM HIT  — a `ready`, alive session exists for the conversation → resume
+ *     it (fast first token). The session is marked `in_use` for the turn and
+ *     returned to `ready` on a CLEAN finish so the NEXT turn is warm too.
+ *   - COLD MISS — no warm session (never warmed, still warming, evicted, or
+ *     expired) → fall through to the injected `coldStream`, which is the
+ *     UNCHANGED per-turn spawn (an engine's `streamTurn`). A background
+ *     `prewarm` is kicked so the conversation's NEXT turn is warm. The cold path
+ *     is byte-for-byte the pre-warm behaviour, so cold latency is a strict
+ *     regression baseline.
+ *
+ * Every turn emits ONE first-token latency sample (tagged warm/cold) to the
+ * injected `OpsMetricsSink`. Idle sessions are swept after a TTL with clean
+ * teardown, and — critically — an IDLE warm session holds ZERO capacity:
+ * `capacityHeld()` counts only `in_use` sessions, so a warm-but-idle session is
+ * never mistaken for an in-flight turn by the chat-lane claim budget.
+ *
+ * Fully injectable (factory / cold path / clock / metrics / logger), so the
+ * whole lifecycle — warm/cold routing, latency tagging, idle sweep, teardown,
+ * capacity accounting — is exercised with a fake clock and scripted engine, no
+ * `claude` binary and no network.
+ *
+ * STAGING: intentionally `dead-until-wired` — the companion folds `capacityHeld()`
+ * into its chat-lane claim budget and routes turns through `runTurn` in a
+ * follow-up (see the task's Follow-ups).
+ */
+import type { EngineStreamChunk, EngineStreamTurnOptions } from "../engines/types.js";
+import { type FirstTokenMode, type OpsMetricsSink, type WarmSessionFactory, type WarmSpawnArgs, type WarmTeardownReason } from "./types.js";
+/** The unchanged cold path: an engine's per-turn `streamTurn`. */
+export type ColdStreamFn = (opts: EngineStreamTurnOptions) => AsyncIterable<EngineStreamChunk>;
+export interface WarmSessionPoolOptions {
+    /** Pre-spawns resumable sessions (the ONE engine seam). */
+    factory: WarmSessionFactory;
+    /** The unchanged per-turn spawn used when no warm session is ready. */
+    coldStream: ColdStreamFn;
+    /** Where first-token latency samples are reported. */
+    metrics: OpsMetricsSink;
+    /** Idle-expiry TTL (ms); a `ready` session idle longer than this is torn down. */
+    idleTtlMs?: number;
+    /** Max concurrent warm sessions; a cold miss past this does not prewarm. */
+    maxSessions?: number;
+    /** Idle-sweep cadence for `start()` (ms). */
+    sweepIntervalMs?: number;
+    /** Clock (test seam). */
+    now?: () => number;
+    /** Best-effort log sink. */
+    onLog?: (line: string) => void;
+}
+/** The result of routing one turn: the chosen mode + the measured stream. */
+export interface WarmTurnHandle {
+    /** Whether the turn is being served warm (reused session) or cold (fresh spawn). */
+    mode: FirstTokenMode;
+    /** The warm session id when `mode === "warm"`, else null. */
+    sessionId: string | null;
+    /**
+     * The turn's delta stream, instrumented for first-token latency. Iterating to
+     * completion (or breaking / throwing early) records exactly ONE latency sample
+     * and releases the warm session. The consumer drives it exactly as it would a
+     * bare `streamTurn`.
+     */
+    stream: AsyncGenerator<EngineStreamChunk, void, void>;
+}
+/** Observable pool sizes (for logging / the doctor surface). */
+export interface WarmPoolStats {
+    size: number;
+    ready: number;
+    warming: number;
+    inUse: number;
+    /** Capacity held right now — equals `inUse` (idle warm sessions hold none). */
+    capacityHeld: number;
+}
+export declare class WarmSessionPool {
+    private readonly opts;
+    private readonly entries;
+    private readonly idleTtlMs;
+    private readonly maxSessions;
+    private readonly sweepIntervalMs;
+    private readonly now;
+    private timer;
+    private stopped;
+    constructor(opts: WarmSessionPoolOptions);
+    /** Number of conversations with a warm-session slot (any phase). */
+    size(): number;
+    /** Conversations with a `ready`, reusable warm session. */
+    readyConversations(): string[];
+    /**
+     * Capacity held by the pool RIGHT NOW: the count of sessions with a turn
+     * actively streaming (`in_use`). An idle/warming warm session holds ZERO —
+     * this is the "idle != tokens" invariant the chat-lane claim budget relies on,
+     * so a wired companion adds THIS (not the warm-session count) to its in-flight
+     * accounting. A pre-warmed but idle conversation must never shrink the budget.
+     */
+    capacityHeld(): number;
+    stats(): WarmPoolStats;
+    /**
+     * Pre-spawn a resumable session for a conversation ahead of its next turn.
+     * Idempotent + deduped: a no-op when a `ready`/`warming`/`in_use` slot already
+     * exists, and concurrent calls share ONE warm-up. Returns true when a session
+     * is (or is already) warming/ready, false when the pool declined (stopped or
+     * at the `maxSessions` cap). Never throws — a failed warm logs and resolves
+     * false so the cold path still serves the turn.
+     */
+    prewarm(conversationId: string, args?: Omit<WarmSpawnArgs, "conversationId">): Promise<boolean>;
+    /** Run the factory warm-up, transitioning the entry to `ready` or evicting it. */
+    private doWarm;
+    /**
+     * Route one turn. Returns the chosen `mode`, the warm `sessionId` (or null),
+     * and an instrumented `stream` the caller drives exactly like a bare
+     * `streamTurn`. Consuming the stream to its end — or breaking/throwing early —
+     * records ONE first-token latency sample and releases the warm session.
+     */
+    runTurn(opts: EngineStreamTurnOptions): WarmTurnHandle;
+    /**
+     * Wrap a delta stream to (a) time the first VISIBLE token, (b) emit one latency
+     * sample on completion, and (c) release the warm session — back to `ready` on a
+     * clean finish, or torn down + evicted on abort/error (a resumed session left
+     * mid-turn is unsafe to reuse). A cold turn has no session to release.
+     */
+    private instrument;
+    /**
+     * Release a warm session after its turn. Clean finish → back to `ready` (the
+     * next turn reuses it, `lastUsedAt` reset so the idle clock restarts). Fault /
+     * abort → teardown + evict so a corrupt resumed session is never reused. If the
+     * pool stopped mid-turn, the session is torn down regardless.
+     */
+    private release;
+    /**
+     * Tear down every `ready` session idle longer than the TTL. `in_use` sessions
+     * (a turn is streaming) and `warming` slots are never expired. Returns the
+     * count torn down. Safe to call ad hoc or from the sweep interval.
+     */
+    sweepIdle(nowMs?: number): Promise<number>;
+    /**
+     * Explicitly evict one conversation's session (e.g. the conversation went
+     * inactive, or a dead handle was detected). No-op when absent or in_use.
+     */
+    evict(conversationId: string, reason?: WarmTeardownReason): Promise<boolean>;
+    /** Start the periodic idle sweep. Idempotent. */
+    start(): void;
+    /**
+     * Stop the pool: cancel the sweep and tear down EVERY session (including any
+     * in-flight one) so a shutdown leaves no orphaned process. Returns after all
+     * teardowns settle. Idempotent.
+     */
+    stop(): Promise<void>;
+    private log;
+}
+//# sourceMappingURL=pool.d.ts.map

package/dist/warm-session/pool.d.ts.map

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

package/dist/warm-session/pool.js

@@ -0,0 +1,335 @@
+import { DEFAULT_MAX_WARM_SESSIONS, DEFAULT_WARM_IDLE_TTL_MS, DEFAULT_WARM_SWEEP_INTERVAL_MS, } from "./types.js";
+export class WarmSessionPool {
+    opts;
+    entries = new Map();
+    idleTtlMs;
+    maxSessions;
+    sweepIntervalMs;
+    now;
+    timer = null;
+    stopped = false;
+    constructor(opts) {
+        this.opts = opts;
+        this.idleTtlMs = Math.max(1_000, Math.floor(opts.idleTtlMs ?? DEFAULT_WARM_IDLE_TTL_MS));
+        this.maxSessions = Math.max(1, Math.floor(opts.maxSessions ?? DEFAULT_MAX_WARM_SESSIONS));
+        this.sweepIntervalMs = Math.max(1_000, Math.floor(opts.sweepIntervalMs ?? DEFAULT_WARM_SWEEP_INTERVAL_MS));
+        this.now = opts.now ?? Date.now;
+    }
+    /* ----------------------------- observability ---------------------------- */
+    /** Number of conversations with a warm-session slot (any phase). */
+    size() {
+        return this.entries.size;
+    }
+    /** Conversations with a `ready`, reusable warm session. */
+    readyConversations() {
+        return [...this.entries.values()].filter((e) => e.phase === "ready").map((e) => e.conversationId);
+    }
+    /**
+     * Capacity held by the pool RIGHT NOW: the count of sessions with a turn
+     * actively streaming (`in_use`). An idle/warming warm session holds ZERO —
+     * this is the "idle != tokens" invariant the chat-lane claim budget relies on,
+     * so a wired companion adds THIS (not the warm-session count) to its in-flight
+     * accounting. A pre-warmed but idle conversation must never shrink the budget.
+     */
+    capacityHeld() {
+        let n = 0;
+        for (const e of this.entries.values())
+            if (e.phase === "in_use")
+                n += 1;
+        return n;
+    }
+    stats() {
+        let ready = 0;
+        let warming = 0;
+        let inUse = 0;
+        for (const e of this.entries.values()) {
+            if (e.phase === "ready")
+                ready += 1;
+            else if (e.phase === "warming")
+                warming += 1;
+            else if (e.phase === "in_use")
+                inUse += 1;
+        }
+        return { size: this.entries.size, ready, warming, inUse, capacityHeld: inUse };
+    }
+    /* ------------------------------- warming -------------------------------- */
+    /**
+     * Pre-spawn a resumable session for a conversation ahead of its next turn.
+     * Idempotent + deduped: a no-op when a `ready`/`warming`/`in_use` slot already
+     * exists, and concurrent calls share ONE warm-up. Returns true when a session
+     * is (or is already) warming/ready, false when the pool declined (stopped or
+     * at the `maxSessions` cap). Never throws — a failed warm logs and resolves
+     * false so the cold path still serves the turn.
+     */
+    async prewarm(conversationId, args = {}) {
+        if (this.stopped)
+            return false;
+        const existing = this.entries.get(conversationId);
+        if (existing) {
+            // Already warming or holding a session — dedupe onto it.
+            if (existing.phase === "warming" && existing.warming) {
+                return (await existing.warming) !== null;
+            }
+            return existing.phase === "ready" || existing.phase === "in_use";
+        }
+        if (this.entries.size >= this.maxSessions) {
+            this.log(`prewarm(${conversationId}) declined: at maxSessions=${this.maxSessions}`);
+            return false;
+        }
+        const entry = {
+            conversationId,
+            phase: "warming",
+            handle: null,
+            warming: null,
+            warmedAt: 0,
+            lastUsedAt: this.now(),
+        };
+        this.entries.set(conversationId, entry);
+        const warming = this.doWarm(entry, args);
+        entry.warming = warming;
+        const handle = await warming;
+        return handle !== null;
+    }
+    /** Run the factory warm-up, transitioning the entry to `ready` or evicting it. */
+    async doWarm(entry, args) {
+        try {
+            const handle = await this.opts.factory.warm({ conversationId: entry.conversationId, ...args });
+            // The pool may have been stopped, or the slot evicted/superseded, while
+            // the warm-up was in flight — if so, tear the fresh handle down at once so
+            // it does not leak (its slot is gone).
+            if (this.stopped || this.entries.get(entry.conversationId) !== entry) {
+                await safeTeardown(handle, "replaced", this.opts.onLog);
+                return null;
+            }
+            entry.handle = handle;
+            entry.phase = "ready";
+            entry.warmedAt = this.now();
+            entry.lastUsedAt = this.now();
+            entry.warming = null;
+            this.log(`warmed ${entry.conversationId} (session ${handle.sessionId})`);
+            return handle;
+        }
+        catch (err) {
+            // Warm-up failed — drop the slot so the cold path serves and a later turn
+            // may retry warming.
+            if (this.entries.get(entry.conversationId) === entry)
+                this.entries.delete(entry.conversationId);
+            this.log(`warm(${entry.conversationId}) failed: ${errText(err)}`);
+            return null;
+        }
+    }
+    /* ------------------------------- driving -------------------------------- */
+    /**
+     * Route one turn. Returns the chosen `mode`, the warm `sessionId` (or null),
+     * and an instrumented `stream` the caller drives exactly like a bare
+     * `streamTurn`. Consuming the stream to its end — or breaking/throwing early —
+     * records ONE first-token latency sample and releases the warm session.
+     */
+    runTurn(opts) {
+        const conversationId = opts.conversationId;
+        const entry = this.entries.get(conversationId);
+        const warmUsable = !this.stopped &&
+            entry !== undefined &&
+            entry.phase === "ready" &&
+            entry.handle !== null &&
+            isHandleAlive(entry.handle);
+        if (warmUsable && entry && entry.handle) {
+            const handle = entry.handle;
+            entry.phase = "in_use";
+            const inner = handle.resumeStream(opts);
+            return {
+                mode: "warm",
+                sessionId: handle.sessionId,
+                stream: this.instrument("warm", opts, inner, entry, handle),
+            };
+        }
+        // Cold miss. If a stale/dead handle is sitting `ready`, evict it first so it
+        // does not leak and the conversation re-warms clean.
+        if (entry && entry.phase === "ready" && entry.handle && !isHandleAlive(entry.handle)) {
+            void this.evict(conversationId, "evicted_dead");
+        }
+        // Kick a background prewarm so the NEXT turn on this conversation is warm.
+        // Fire-and-forget and self-guarded (prewarm never rejects).
+        if (!this.stopped && !this.entries.has(conversationId))
+            void this.prewarm(conversationId, spawnArgsFrom(opts));
+        const inner = this.opts.coldStream(opts);
+        return {
+            mode: "cold",
+            sessionId: null,
+            stream: this.instrument("cold", opts, inner, null, null),
+        };
+    }
+    /**
+     * Wrap a delta stream to (a) time the first VISIBLE token, (b) emit one latency
+     * sample on completion, and (c) release the warm session — back to `ready` on a
+     * clean finish, or torn down + evicted on abort/error (a resumed session left
+     * mid-turn is unsafe to reuse). A cold turn has no session to release.
+     */
+    async *instrument(mode, opts, inner, entry, handle) {
+        const startedAt = this.now();
+        let firstTokenMs = null;
+        let sawToken = false;
+        let faulted = false;
+        try {
+            for await (const chunk of inner) {
+                if (!sawToken && chunk.delta && chunk.delta.length > 0) {
+                    sawToken = true;
+                    firstTokenMs = this.now() - startedAt;
+                }
+                yield chunk;
+            }
+        }
+        catch (err) {
+            faulted = true;
+            throw err;
+        }
+        finally {
+            // An abort counts as a fault for reuse purposes even without a throw.
+            if (opts.signal?.aborted)
+                faulted = true;
+            const totalMs = this.now() - startedAt;
+            this.opts.metrics.recordFirstToken({
+                conversationId: opts.conversationId,
+                turnId: opts.turnId,
+                mode,
+                firstTokenMs: sawToken ? firstTokenMs : null,
+                totalMs,
+                sawToken,
+                at: this.now(),
+            });
+            if (entry && handle)
+                await this.release(entry, handle, faulted);
+        }
+    }
+    /**
+     * Release a warm session after its turn. Clean finish → back to `ready` (the
+     * next turn reuses it, `lastUsedAt` reset so the idle clock restarts). Fault /
+     * abort → teardown + evict so a corrupt resumed session is never reused. If the
+     * pool stopped mid-turn, the session is torn down regardless.
+     */
+    async release(entry, handle, faulted) {
+        // The slot may have been superseded/evicted while the turn ran.
+        const current = this.entries.get(entry.conversationId);
+        if (current !== entry) {
+            await safeTeardown(handle, "replaced", this.opts.onLog);
+            return;
+        }
+        if (faulted || this.stopped || !isHandleAlive(handle)) {
+            const reason = this.stopped
+                ? "pool_shutdown"
+                : faulted
+                    ? "evicted_after_turn_fault"
+                    : "evicted_dead";
+            this.entries.delete(entry.conversationId);
+            entry.phase = "torn_down";
+            await safeTeardown(handle, reason, this.opts.onLog);
+            return;
+        }
+        entry.phase = "ready";
+        entry.lastUsedAt = this.now();
+    }
+    /* ------------------------------ expiry/stop ----------------------------- */
+    /**
+     * Tear down every `ready` session idle longer than the TTL. `in_use` sessions
+     * (a turn is streaming) and `warming` slots are never expired. Returns the
+     * count torn down. Safe to call ad hoc or from the sweep interval.
+     */
+    async sweepIdle(nowMs = this.now()) {
+        const expired = [];
+        for (const entry of this.entries.values()) {
+            if (entry.phase !== "ready" || entry.handle === null)
+                continue;
+            if (nowMs - entry.lastUsedAt >= this.idleTtlMs) {
+                expired.push({ conversationId: entry.conversationId, handle: entry.handle });
+                entry.phase = "torn_down";
+                this.entries.delete(entry.conversationId);
+            }
+        }
+        for (const { conversationId, handle } of expired) {
+            this.log(`idle-expiry teardown ${conversationId} (session ${handle.sessionId})`);
+            await safeTeardown(handle, "idle_expiry", this.opts.onLog);
+        }
+        return expired.length;
+    }
+    /**
+     * Explicitly evict one conversation's session (e.g. the conversation went
+     * inactive, or a dead handle was detected). No-op when absent or in_use.
+     */
+    async evict(conversationId, reason = "capacity_reclaim") {
+        const entry = this.entries.get(conversationId);
+        if (!entry || entry.phase === "in_use" || entry.handle === null)
+            return false;
+        this.entries.delete(conversationId);
+        entry.phase = "torn_down";
+        await safeTeardown(entry.handle, reason, this.opts.onLog);
+        return true;
+    }
+    /** Start the periodic idle sweep. Idempotent. */
+    start() {
+        if (this.timer || this.stopped)
+            return;
+        this.timer = setInterval(() => {
+            void this.sweepIdle();
+        }, this.sweepIntervalMs);
+        this.timer.unref?.();
+    }
+    /**
+     * Stop the pool: cancel the sweep and tear down EVERY session (including any
+     * in-flight one) so a shutdown leaves no orphaned process. Returns after all
+     * teardowns settle. Idempotent.
+     */
+    async stop() {
+        this.stopped = true;
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        const handles = [];
+        for (const entry of this.entries.values()) {
+            if (entry.handle)
+                handles.push({ conversationId: entry.conversationId, handle: entry.handle });
+            entry.phase = "torn_down";
+        }
+        this.entries.clear();
+        await Promise.all(handles.map(({ handle }) => safeTeardown(handle, "pool_shutdown", this.opts.onLog)));
+    }
+    log(line) {
+        this.opts.onLog?.(`[acc-runner] warm-session: ${line}`);
+    }
+}
+/* ------------------------------- helpers ---------------------------------- */
+/** A handle with no `isAlive` is assumed alive; a throwing probe is treated dead. */
+function isHandleAlive(handle) {
+    if (!handle.isAlive)
+        return true;
+    try {
+        return handle.isAlive();
+    }
+    catch {
+        return false;
+    }
+}
+/** Teardown that never rejects (a throwing teardown must not crash the pool). */
+async function safeTeardown(handle, reason, onLog) {
+    try {
+        await handle.teardown(reason);
+    }
+    catch (err) {
+        onLog?.(`[acc-runner] warm-session: teardown(${reason}) failed: ${errText(err)}`);
+    }
+}
+/** Carry the turn's cwd/model into the background prewarm for the next turn. */
+function spawnArgsFrom(opts) {
+    const out = {};
+    if (opts.cwd !== undefined)
+        out.cwd = opts.cwd;
+    if (opts.modelId !== undefined)
+        out.modelId = opts.modelId;
+    return out;
+}
+/** Best-effort, log-safe text of a thrown value. */
+function errText(err) {
+    const e = err;
+    return (e?.message ?? String(err ?? "")).slice(0, 300);
+}
+//# sourceMappingURL=pool.js.map

package/dist/warm-session/pool.js.map

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

package/dist/warm-session/types.d.ts

@@ -0,0 +1,124 @@
+/**
+ * CX-4 (WARM-SESSIONS): the warm-session type surface.
+ *
+ * Per CHAT_UX_ENHANCEMENTS_PLAN.md §1: a chat turn's first-token latency is
+ * dominated by engine PROCESS SPAWN (node boot + acc-mcp handshake + auth
+ * resolution), not by the transport. The warm-session layer keeps a pre-spawned,
+ * resumable engine session per ACTIVE conversation on the serving runner so a
+ * turn REUSES it (fast first token) instead of paying spawn on every prompt.
+ *
+ * This module is deliberately self-contained and fully injectable: it names two
+ * seams — a `WarmSessionFactory` that pre-spawns/holds a resumable session, and
+ * a `coldStream` fallback that is the UNCHANGED per-turn spawn (an engine's
+ * `streamTurn`) — plus an `OpsMetricsSink` for first-token latency. The pool
+ * neither imports the companion nor a `claude` binary, so it is exercised
+ * deterministically (tests/unit/warm-session/*) and wired into the companion by
+ * a follow-up, mirroring how the AS-3 resume primitives shipped ahead of their
+ * watch/companion wiring.
+ *
+ * The `EngineStreamChunk` / `EngineStreamTurnOptions` shapes are reused verbatim
+ * from engines/types.ts so a warm turn is byte-identical to a cold one on the
+ * wire — a warm session is a latency optimisation, never a protocol change.
+ *
+ * STAGING: these exports are intentionally `dead-until-wired` — the companion +
+ * real-engine resume adapter that consume them land in a follow-up (see the
+ * task's Follow-ups), mirroring how the AS-3 resume primitives shipped first.
+ */
+import type { EngineStreamChunk, EngineStreamTurnOptions } from "../engines/types.js";
+/** Whether a turn's first token came from a reused warm session or a cold spawn. */
+export type FirstTokenMode = "warm" | "cold";
+/**
+ * Lifecycle phase of a warm session entry in the pool.
+ *   warming    — factory.warm() is in flight (the session is being pre-spawned).
+ *   ready      — pre-spawned and idle, holding NO capacity, awaiting a turn.
+ *   in_use     — a turn is actively streaming on it (this is the ONLY phase that
+ *                counts toward capacity — idle warm sessions never do).
+ *   torn_down  — teardown() has settled; the entry is being/has been evicted.
+ */
+export type WarmSessionPhase = "warming" | "ready" | "in_use" | "torn_down";
+/**
+ * Why a warm session was torn down. Carried into `WarmSessionHandle.teardown` so
+ * a wired factory can log/observe the disposal cause without the pool leaking a
+ * string convention.
+ */
+export type WarmTeardownReason = "idle_expiry" | "pool_shutdown" | "evicted_after_turn_fault" | "evicted_dead" | "replaced" | "capacity_reclaim";
+/**
+ * A pre-spawned, resumable engine session bound to ONE conversation. Produced by
+ * `WarmSessionFactory.warm`. `resumeStream` feeds a turn's prompt into the
+ * already-warm session and yields the same `EngineStreamChunk` deltas a cold
+ * `streamTurn` would — the first delta arrives fast because node/acc-mcp/auth
+ * were paid at warm time. `teardown` disposes the underlying process/handle
+ * cleanly (SIGTERM + reap) so an expired or faulted session leaves NO leak.
+ */
+export interface WarmSessionHandle {
+    /** The conversation this session is pinned to. */
+    readonly conversationId: string;
+    /** Opaque resumable-session id (engine's `--session-id`/resume token). */
+    readonly sessionId: string;
+    /** Run one turn by resuming this warm session; yields incremental deltas. */
+    resumeStream(opts: EngineStreamTurnOptions): AsyncIterable<EngineStreamChunk>;
+    /**
+     * Cheap liveness check for an IDLE session (default: assume alive). A wired
+     * factory backing the session with a long-lived child reports `false` once the
+     * child has exited so the pool evicts the dead handle instead of resuming into
+     * an error. Never throws.
+     */
+    isAlive?(): boolean;
+    /** Dispose the session cleanly (idempotent). Never rejects. */
+    teardown(reason: WarmTeardownReason): Promise<void>;
+}
+/** Arguments to pre-spawn a warm session for a conversation. */
+export interface WarmSpawnArgs {
+    conversationId: string;
+    /** Repo checkout the eventual turns run in (forwarded to the engine). */
+    cwd?: string;
+    /** Model to pin for the session; omitted/blank uses the operator default. */
+    modelId?: string | null;
+    /** Abort signal for the warm-up itself (pool shutdown mid-warm). */
+    signal?: AbortSignal;
+}
+/**
+ * Pre-spawns and hands back a resumable engine session. The ONE seam a follow-up
+ * wires to a real chat engine (a `claude --session-id` pre-spawn, or a long-lived
+ * stdin-streaming child). Kept as an interface so the pool has zero engine
+ * knowledge and the conformance tests inject a scripted fake.
+ */
+export interface WarmSessionFactory {
+    warm(args: WarmSpawnArgs): Promise<WarmSessionHandle>;
+}
+/**
+ * One first-token latency observation for a single turn. `firstTokenMs` is the
+ * ms from turn start to the first VISIBLE delta; it is `null` when the turn
+ * produced no visible token (an empty/failed reply) so a no-token turn never
+ * pollutes the p50/p95. `totalMs` is turn start → stream end regardless.
+ */
+export interface FirstTokenSample {
+    conversationId: string;
+    turnId: string;
+    mode: FirstTokenMode;
+    firstTokenMs: number | null;
+    totalMs: number;
+    sawToken: boolean;
+    /** Wall-clock stamp (via the injected clock) for ordering/retention. */
+    at: number;
+}
+/**
+ * Where the pool reports per-turn first-token latency. A follow-up wires this to
+ * the ops-metrics topic / activity events so Pulse can render warm/cold p50/p95;
+ * `FirstTokenLatencyRecorder` (latency.ts) is the default in-memory sink that
+ * also computes the percentiles.
+ */
+export interface OpsMetricsSink {
+    recordFirstToken(sample: FirstTokenSample): void;
+}
+/** Warm p50 first-token target on the rig (ms). */
+export declare const WARM_FIRST_TOKEN_P50_TARGET_MS = 1500;
+/** Cold first-token target on the rig (ms) — the unchanged spawn path ceiling. */
+export declare const COLD_FIRST_TOKEN_TARGET_MS = 4000;
+/** Default idle-expiry TTL for a warm session (~10 min per the plan). */
+export declare const DEFAULT_WARM_IDLE_TTL_MS = 600000;
+/** Default max warm sessions the pool holds concurrently. */
+export declare const DEFAULT_MAX_WARM_SESSIONS = 32;
+/** Default idle-sweep cadence. */
+export declare const DEFAULT_WARM_SWEEP_INTERVAL_MS = 60000;
+//# sourceMappingURL=types.d.ts.map

package/dist/warm-session/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/warm-session/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAEtF,oFAAoF;AACpF,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,CAAC;AAE7C;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE5E;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAC1B,aAAa,GACb,eAAe,GACf,0BAA0B,GAC1B,cAAc,GACd,UAAU,GACV,kBAAkB,CAAC;AAEvB;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6EAA6E;IAC7E,YAAY,CAAC,IAAI,EAAE,uBAAuB,GAAG,aAAa,CAAC,iBAAiB,CAAC,CAAC;IAC9E;;;;;OAKG;IACH,OAAO,CAAC,IAAI,OAAO,CAAC;IACpB,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD;AAED,gEAAgE;AAChE,MAAM,WAAW,aAAa;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,oEAAoE;IACpE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACvD;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,cAAc,CAAC;IACrB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,wEAAwE;IACxE,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAClD;AAED,mDAAmD;AACnD,eAAO,MAAM,8BAA8B,OAAQ,CAAC;AACpD,kFAAkF;AAClF,eAAO,MAAM,0BAA0B,OAAQ,CAAC;AAChD,yEAAyE;AACzE,eAAO,MAAM,wBAAwB,SAAU,CAAC;AAChD,6DAA6D;AAC7D,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAC5C,kCAAkC;AAClC,eAAO,MAAM,8BAA8B,QAAS,CAAC"}

package/dist/warm-session/types.js

@@ -0,0 +1,11 @@
+/** Warm p50 first-token target on the rig (ms). */
+export const WARM_FIRST_TOKEN_P50_TARGET_MS = 1_500;
+/** Cold first-token target on the rig (ms) — the unchanged spawn path ceiling. */
+export const COLD_FIRST_TOKEN_TARGET_MS = 4_000;
+/** Default idle-expiry TTL for a warm session (~10 min per the plan). */
+export const DEFAULT_WARM_IDLE_TTL_MS = 600_000;
+/** Default max warm sessions the pool holds concurrently. */
+export const DEFAULT_MAX_WARM_SESSIONS = 32;
+/** Default idle-sweep cadence. */
+export const DEFAULT_WARM_SWEEP_INTERVAL_MS = 60_000;
+//# sourceMappingURL=types.js.map

package/dist/warm-session/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/warm-session/types.ts"],"names":[],"mappings":"AAgIA,mDAAmD;AACnD,MAAM,CAAC,MAAM,8BAA8B,GAAG,KAAK,CAAC;AACpD,kFAAkF;AAClF,MAAM,CAAC,MAAM,0BAA0B,GAAG,KAAK,CAAC;AAChD,yEAAyE;AACzE,MAAM,CAAC,MAAM,wBAAwB,GAAG,OAAO,CAAC;AAChD,6DAA6D;AAC7D,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,CAAC;AAC5C,kCAAkC;AAClC,MAAM,CAAC,MAAM,8BAA8B,GAAG,MAAM,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenfactory/acc-runner",
-  "version": "0.40.23",
+  "version": "0.40.24",
   "description": "Agent Control Center local runner. Spawns Claude Code sessions assigned via ACC.",
   "license": "UNLICENSED",
   "private": false,