@bridge4dev/runner 0.47.0 → 0.49.0

package/dist/stop-cycle.d.ts

@@ -0,0 +1,148 @@
+import type { AgentEvent, AgentSession, InterruptOutcome } from './adapters/types.js';
+/**
+ * One managed stop of one agent process (#373).
+ *
+ * The defect this exists for: stopping a turn used to be a boolean and a hope.
+ * The Claude adapter armed a single `aborting` flag, EVERY result read and
+ * cleared it, and the second result of the same stop therefore arrived looking
+ * like a failure — `turn_end{ok:false}` → `settleTurnStatus` → FAILED, which is
+ * terminal. A session that had merely run out of plan limit was buried with a
+ * live clock still ticking on it, and nothing would ever wake it again.
+ *
+ * A cycle is bound to ONE process instance and to one reason. Everything that
+ * arrives from that instance while the cycle runs — a late result, the tail of
+ * a tool the CLI had already started, the ending our own `close()` produces —
+ * belongs to the stop and is not news about the session's health. Everything
+ * from any OTHER instance (the process we start after the pause is lifted) is
+ * outside it, which is what keeps a real failure after a resume visible.
+ *
+ * Deliberately a small module of plain rules: the decisions below are the ones
+ * a mistake is expensive in, and they are worth being able to test without a
+ * supervisor, a fake CLI and a socket.
+ */
+/**
+ * How far the stop has got.
+ *
+ *  - `interrupting` — the request is out; the process is still ours to lose.
+ *  - `parking`      — the turn has ended (or will not end), and we are closing
+ *                     the process ourselves. From here on its noises are ours.
+ *  - `parked`       — the event stream ended. Nothing else can arrive.
+ */
+export type StopPhase = 'interrupting' | 'parking' | 'parked';
+/**
+ * Who asked.
+ *
+ * `user` keeps the old contract exactly: one Stop, one ending, and the NEXT
+ * genuine failure still reaches the person. `pause` is the one that closes the
+ * process and therefore has to own what closing it produces.
+ */
+export type StopReason = 'user' | 'pause';
+export interface StopCycle {
+    /** The adapter session this cycle stops. Identity only — never called. */
+    readonly session: AgentSession;
+    /**
+     * Who asked — and it can be RAISED while the stop is in flight.
+     *
+     * A clock landing on a Stop the person pressed a second earlier is the same
+     * stop, not a second one: the CLI has one outstanding interrupt and will
+     * answer it once. But it is now a PAUSE, and a pause closes the process and
+     * owns what closing it produces. Left as `user` the cycle would step aside at
+     * the first ending and the second result would file the session FAILED —
+     * the incident, reached through a door the fix did not cover.
+     */
+    reason: StopReason;
+    /**
+     * Which clock this stop belongs to, for the log.
+     *
+     * Deliberately NOT a guard: what decides whether two stops are the same one
+     * is the process instance, and «a clock lifted and set again» is already
+     * answered by the release dropping a cycle that closed nothing. The number is
+     * here so a line in journald can be tied to the pause that caused it —
+     * reading two stops in one session and not knowing whether they answered one
+     * clock or two is how the incident took a day to reconstruct.
+     */
+    readonly epoch: number;
+    phase: StopPhase;
+    /** The single interrupt round-trip. Every later request joins this one. */
+    inFlight: Promise<void> | null;
+    /** What the CLI said about the request, once it said anything. */
+    outcome: InterruptOutcome | null;
+    /** The control channel refused while the process was still running. */
+    refused: boolean;
+    /**
+     * We closed this process ourselves.
+     *
+     * The line invariant 7 is drawn on. Everything a process says after we have
+     * closed it is the closing; everything it says before is still news about the
+     * session. `phase` alone cannot answer this — a stop that is refused parking
+     * (an open permission card) reaches `parking` with the process untouched.
+     */
+    closed: boolean;
+    /** The one `turn_end` this cycle publishes has gone out. */
+    turnEndSent: boolean;
+    /**
+     * The stop has run its course.
+     *
+     * It still OWNS this process's endings — a late result after a refused park
+     * is exactly the incident's second result — but it no longer stands in the way
+     * of a new stop: a turn that starts minutes later, from inside a CLI nobody
+     * closed, has to be stoppable in its own right.
+     */
+    settled: boolean;
+    /** There was a turn to stop — so an ending is owed to the feed. */
+    readonly hadTurn: boolean;
+    /**
+     * Tool calls already in flight when the stop began.
+     *
+     * The reason the incident fired a SECOND interrupt: the result of the
+     * question this runner had just withdrawn came back as an ordinary tool
+     * event, and «the agent is producing output» could not tell it from a turn
+     * starting up. Ownership answers it — a result for one of these ids is the
+     * tail of the work being stopped, not new work.
+     */
+    readonly toolsAtStop: ReadonlySet<string>;
+    /** Waiting for the result that should follow an accepted interrupt. */
+    settleTimer?: ReturnType<typeof setTimeout>;
+}
+/** Is this cycle the one that owns `session`, and is it still live? */
+export declare function ownsProcess(cycle: StopCycle | undefined, session: AgentSession | null): boolean;
+/**
+ * What to do with a `turn_end` that arrived inside a stop cycle.
+ *
+ *  - `ordinary` — nothing special: a manual Stop keeps the contract it has had
+ *    since QA-120, including the rule that the next real failure is not hidden.
+ *  - `stopped`  — the one ending this cycle publishes: `ok`, `aborted`, and the
+ *    facts the turn actually carried.
+ *  - `tail`     — a second (or third) ending of a turn that has already been
+ *    closed out. The incident's `error_during_execution`, 1.2 s late.
+ */
+export declare function turnEndVerdict(cycle: StopCycle): 'ordinary' | 'stopped' | 'tail';
+/**
+ * What to do with an `error` that arrived inside a stop cycle.
+ *
+ * The one place the difference between «the process fell over» and «the process
+ * was closed» has to be paid attention to, and the only honest source for it is
+ * the adapter's own `processGone` — never the sentence in the message, which is
+ * written by the CLI and changes with it.
+ */
+export declare function errorVerdict(cycle: StopCycle, processGone: boolean): 'failure' | 'tail';
+/**
+ * Is this event work STARTING, rather than the tail of what is being stopped?
+ *
+ * Only a genuinely new turn deserves a second stop. A tool result belonging to
+ * a call that was already running when the stop began is the first stop still
+ * finishing — firing another interrupt at it is what gave the incident two
+ * interrupts, two `aborting` arms and one result too few to spend them.
+ */
+export declare function isNewWork(event: AgentEvent, cycle: StopCycle | undefined): boolean;
+/**
+ * Is this the result of a tool call that was already running when we stopped?
+ *
+ * The incident's `tool_result` at seq 832 was exactly this: the withdrawn
+ * question's own refusal, arriving three seconds after the stop. Kept apart
+ * from «a result we never saw start» rather than lumping every result together
+ * — the two say different things about the process, and the diagnostic log has
+ * to be able to say which one happened.
+ */
+export declare function isStoppedToolTail(cycle: StopCycle, event: AgentEvent): boolean;
+//# sourceMappingURL=stop-cycle.d.ts.map

package/dist/stop-cycle.js

@@ -0,0 +1,86 @@
+/** Is this cycle the one that owns `session`, and is it still live? */
+export function ownsProcess(cycle, session) {
+    return cycle !== undefined && session !== null && cycle.session === session;
+}
+/**
+ * What to do with a `turn_end` that arrived inside a stop cycle.
+ *
+ *  - `ordinary` — nothing special: a manual Stop keeps the contract it has had
+ *    since QA-120, including the rule that the next real failure is not hidden.
+ *  - `stopped`  — the one ending this cycle publishes: `ok`, `aborted`, and the
+ *    facts the turn actually carried.
+ *  - `tail`     — a second (or third) ending of a turn that has already been
+ *    closed out. The incident's `error_during_execution`, 1.2 s late.
+ */
+export function turnEndVerdict(cycle) {
+    if (cycle.reason === 'user')
+        return 'ordinary';
+    if (cycle.turnEndSent)
+        return 'tail';
+    return 'stopped';
+}
+/**
+ * What to do with an `error` that arrived inside a stop cycle.
+ *
+ * The one place the difference between «the process fell over» and «the process
+ * was closed» has to be paid attention to, and the only honest source for it is
+ * the adapter's own `processGone` — never the sentence in the message, which is
+ * written by the CLI and changes with it.
+ */
+export function errorVerdict(cycle, processGone) {
+    // A manual Stop does not close anything, so nothing here is ours.
+    if (cycle.reason === 'user')
+        return 'failure';
+    // We have not closed it: a process dying on its own is a real failure, and
+    // burying it under the pause would be the original defect wearing the fix's
+    // clothes. Everything else from a process we asked to stop is the stopping.
+    if (!cycle.closed)
+        return processGone ? 'failure' : 'tail';
+    // We closed it. Whatever it says on the way out is the closing.
+    return 'tail';
+}
+/**
+ * Is this event work STARTING, rather than the tail of what is being stopped?
+ *
+ * Only a genuinely new turn deserves a second stop. A tool result belonging to
+ * a call that was already running when the stop began is the first stop still
+ * finishing — firing another interrupt at it is what gave the incident two
+ * interrupts, two `aborting` arms and one result too few to spend them.
+ */
+export function isNewWork(event, cycle) {
+    if (event.type !== 'tool')
+        return true;
+    if (event.phase === 'use')
+        return true;
+    // A result is always the tail of something, and the only question is whose.
+    // The tail of a call that was ALREADY RUNNING when we stopped is the stop
+    // finishing — the incident's seq 832, which fired a second interrupt. A
+    // result for a call we did not see start, on a process we asked to stop, is
+    // the opposite: something began after the stop and has now finished.
+    //
+    // Without a cycle there is no ownership to read, and a result on its own is
+    // no evidence of a turn beginning — a turn begins with a call, a thought or a
+    // sentence. Excluding every result regardless of whose it is is what the plan
+    // forbids, and this is the distinction it asks for.
+    if (!cycle)
+        return false;
+    if (event.toolUseId === undefined)
+        return false;
+    return !cycle.toolsAtStop.has(event.toolUseId);
+}
+/**
+ * Is this the result of a tool call that was already running when we stopped?
+ *
+ * The incident's `tool_result` at seq 832 was exactly this: the withdrawn
+ * question's own refusal, arriving three seconds after the stop. Kept apart
+ * from «a result we never saw start» rather than lumping every result together
+ * — the two say different things about the process, and the diagnostic log has
+ * to be able to say which one happened.
+ */
+export function isStoppedToolTail(cycle, event) {
+    return (event.type === 'tool' &&
+        event.phase === 'result' &&
+        event.toolUseId !== undefined &&
+        cycle.toolsAtStop.has(event.toolUseId));
+}
+//# sourceMappingURL=stop-cycle.js.map

package/dist/supervisor.d.ts

@@ -109,6 +109,19 @@ export interface SupervisorOptions {
      * firing over a working agent (QA-2026-08-16 M-4). Never set in production.
      */
     emptyTurnSettleMs?: number;
+    /**
+     * How long an unchanged plan-usage snapshot is held before it is re-sent
+     * (#366) – a test seam over `RATE_LIMITS_RESEND_INTERVAL_MS`, for the same
+     * reason `emptyTurnSettleMs` exists: the real floor is three minutes and this
+     * suite runs on real timers. Never set in production.
+     */
+    rateLimitsResendMs?: number;
+    /**
+     * How long a stop waits for the ending it asked for (#373) – a test seam over
+     * `STOP_SETTLE_MS`, for the same reason `emptyTurnSettleMs` exists. Never set
+     * in production.
+     */
+    stopSettleMs?: number;
 }
 export declare class Supervisor {
     private readonly ws;
@@ -136,6 +149,9 @@ export declare class Supervisor {
     private static readonly EMPTY_TURN_SETTLE_MS;
     /** The window actually used — the constant, or a test's own shorter one. */
     private readonly emptyTurnSettleMs;
+    private readonly rateLimitsResendMs;
+    /** The stop-settle window actually used — the constant, or a test's own. */
+    private readonly stopSettleMs;
     /** A finished session's journal is kept this long for a late reconnect. */
     private static readonly JOURNAL_TTL_MS;
     /** Backstop: events the API will never accept must not pile up forever. */
@@ -525,6 +541,29 @@ export declare class Supervisor {
      * its timer runs out, and it must end in exactly the way it would have
      * ended immediately. A copy would be two behaviours one edit apart.
      */
+    /**
+     * The level gate for the context meter (#366).
+     *
+     * While a turn is open, a frame goes out only when the meter moved by at
+     * least one of the shared thresholds or the window itself changed; the
+     * newest held-back value is flushed right before `turn_end`, so the ring at
+     * rest is exact. Outside a turn every frame passes – there are only a handful
+     * (process start, a model change, and the Claude adapter's own measurement,
+     * which resolves AFTER `turn_end`), and each one is news.
+     */
+    private forwardContextUsage;
+    /** Send the value the gate was holding, if any – strictly before `turn_end`. */
+    private flushHeldContextUsage;
+    /**
+     * The level gate for plan usage (#366).
+     *
+     * A snapshot goes out when it is the first, when anything but `measuredAt`
+     * changed, when it carries a refusal (#258 – always, even twice in a row), or
+     * when the one last sent is older than the resend floor. The fingerprint is
+     * the whole payload minus the clock, so a field an adapter adds tomorrow is
+     * part of it without anybody remembering to list it here.
+     */
+    private forwardRateLimits;
     private completeTurn;
     /**
      * Move the session to the status a finished turn leaves it in.
@@ -729,6 +768,90 @@ export declare class Supervisor {
      *   turn it stops would bury the feed under a fact nobody asked about.
      */
     private interruptSession;
+    /**
+     * How long a stop waits for the ending that should follow it (#373).
+     *
+     * The transition out of `interrupting` is the first result, not the
+     * acknowledgement — an ACK only says the request was heard, and the incident
+     * shows an ACK and a result are different events that arrive in either order.
+     * This is the backstop for the case where no result comes at all: an idle
+     * session had no turn to end, and a CLI can always simply not answer.
+     */
+    private static readonly STOP_SETTLE_MS;
+    /**
+     * How long after one stop the next output is still read as its tail (#196).
+     *
+     * The floor under the stop cycle rather than a substitute for it: while a
+     * cycle is open every event joins it, and this is what keeps a burst from
+     * opening a NEW cycle per line in the window after one closed without closing
+     * its process. Far shorter than the gap before a genuinely new turn — a
+     * background subagent finishing — which still gets its own stop.
+     */
+    private static readonly PAUSE_BURST_MS;
+    /**
+     * Stop one agent process once, and own what stopping it produces (#373).
+     *
+     * The shape is deliberate: the interrupt is a round trip that can take half a
+     * minute (a CLI sitting out a provider retry answers only when it comes back
+     * — 28.5 seconds, measured in #357), so nothing here may be on the path the
+     * event pump takes. The cycle is stored before the request goes out, which is
+     * what makes every later request join this one instead of starting a second.
+     */
+    private beginStopCycle;
+    /**
+     * Wait a bounded time for the ending an accepted interrupt should produce.
+     *
+     * «Bounded» rather than «for ever» because two real cases produce no ending
+     * at all: a pause landing between turns (there was nothing to stop), and a
+     * CLI that takes the request and then says nothing. Leaving the cycle open
+     * there would hold the seat and the clock indefinitely.
+     */
+    private armStopSettle;
+    private clearStopSettleTimer;
+    /**
+     * The turn is over — close the process, keeping the session resumable.
+     *
+     * This is the change the whole plan is about. A pause used to leave a live
+     * CLI standing for up to five hours, which is where the second result came
+     * from; now the runner takes the ending it asked for and parks, and the next
+     * message (or the clock's own «continue») starts a process that resumes the
+     * same conversation.
+     */
+    private settleStopCycle;
+    /**
+     * The agent never said yes — say so, and say only what actually happened.
+     *
+     * Invariant 5: a stop the CLI refused must not read as a clean cancellation.
+     * Which sentence is true depends on what came next, so it is written here and
+     * not where the refusal was noticed — a line promising «its process was
+     * closed» over a manual Stop, which closes nothing, is the same class of lie
+     * as the one this ticket is about (gotcha 324).
+     */
+    private sayIfTheStopWasRefused;
+    /**
+     * Why this paused process must NOT be closed, or null when it may be.
+     *
+     * Invariant 8 lives here. `park()` calls the adapter's `stop()`, and `stop()`
+     * answers every pending permission «denied» in the RUNNER's name — a decision
+     * nobody made, in a place that keeps decisions for ninety days. Worse, the API
+     * sends nothing when the clock is lifted over an open card
+     * (`pauseInterruptedTurn` is false while `openAsks > 0`), so the session would
+     * simply stand there, silent, with the card gone.
+     *
+     * A conversation the CLI has not named yet is the other refusal: parking
+     * promises the context is saved, and there is nothing to resume from.
+     */
+    private parkRefusalUnderPause;
+    /**
+     * The one ending a stop cycle publishes (#373).
+     *
+     * `ok` unconditionally: a turn this runner stopped is not a turn that failed,
+     * and `turn_end{ok:false}` is what put a paused session into the terminal
+     * status it could never be woken out of. The facts the turn actually carried
+     * ride along — `limitBlocked` because the API counts refusals with it, and
+     * `produced` because it is what keeps the refusal counter honest (#300).
+     */
+    private publishStoppedTurn;
     /** Is this session held under a clock right now (ticket #196)? */
     private static isPaused;
     /**