@bridge4dev/runner 0.44.2 → 0.45.1

package/dist/adapters/claude.js

@@ -1983,8 +1983,9 @@ class ClaudeSession {
         // exit: the words reach the agent immediately and the turn continues.
         const openAsk = this.oldestOpenAsk();
         if (openAsk) {
-            this.answerQuestion({ askId: openAsk, action: 'discuss', text });
-            return;
+            // `answerQuestion` answers whether the ask took it; either way the words
+            // are now the card's business and not the queue's.
+            return this.answerQuestion({ askId: openAsk, action: 'discuss', text });
         }
         this.resumingTurn();
         const accepted = this.input.push({
@@ -1993,10 +1994,15 @@ class ClaudeSession {
             parent_tool_use_id: null,
         });
         if (!accepted) {
-            log.warn('claude: send after session ended — message dropped', {
+            // #231 F8: said out loud now instead of only here. The supervisor puts
+            // the message back on the queue — until this release the refusal reached
+            // nobody, and the browser was left showing a bubble for words the agent
+            // had already refused.
+            log.warn('claude: send after session ended — message refused', {
                 sessionId: this.spec.sessionId,
             });
         }
+        return accepted;
     }
     async interrupt() {
         this.aborting = true;
@@ -2296,6 +2302,13 @@ class ClaudeSession {
                                 // reads it to keep the streak counter honest — a turn that was
                                 // refused is not a turn that ran.
                                 ...(this.consumeLimitBlock() ? { limitBlocked: true } : {}),
+                                // #300: the same arithmetic as the failing branch below, on the
+                                // branch where it decides something else. A successful turn that
+                                // put nothing on the wire is usually a warm-up the person never
+                                // asked for — a resumed process closing a turn of its own — and
+                                // the supervisor holds it rather than announcing «your turn»
+                                // over an agent that has not spoken yet.
+                                ...(this.turnProduced ? { produced: true } : {}),
                             });
                             // #279: a turn just moved the plan, so the percentages are worth
                             // re-reading — throttled inside, and free either way.

package/dist/adapters/codex.js

@@ -552,10 +552,13 @@ class CodexSession {
     }
     send(text) {
         if (this.stopped) {
-            log.warn('codex: send after session ended — message dropped', {
+            // #231 F8: answered rather than swallowed. The supervisor puts the
+            // message back on the queue instead of leaving a bubble on screen for
+            // words this session already refused.
+            log.warn('codex: send after session ended — message refused', {
                 sessionId: this.spec.sessionId,
             });
-            return;
+            return false;
         }
         // A parked elicitation takes priority: the agent is blocked on it, and
         // starting a turn would deadlock behind the open request. Typing is a
@@ -572,7 +575,7 @@ class CodexSession {
                     custom: text,
                 })),
             });
-            return;
+            return true;
         }
         // Answering a plan card by typing instead of clicking is normal ("do it
         // differently"). Without this the held plan stayed forever and
@@ -592,13 +595,14 @@ class CodexSession {
         // Approving the plan is the moment the agent may actually work.
         if (!this.ready) {
             this.queuedInput.push(text);
-            return;
+            return true;
         }
         if (this.activeTurnId) {
             void this.steer(text);
-            return;
+            return true;
         }
         this.startTurn(text);
+        return true;
     }
     async steer(text) {
         if (!this.threadId || !this.activeTurnId)
@@ -1560,6 +1564,10 @@ class CodexSession {
             type: 'turn_end',
             ok: true,
             ...(status === 'interrupted' ? { aborted: true } : {}),
+            // #300, the twin of the failing branch above: a turn that ended well
+            // having produced nothing is usually no turn at all, and the supervisor
+            // holds it rather than saying «your turn» over a working agent.
+            ...(this.turnProduced ? { produced: true } : {}),
         });
         this.flushQueued();
     }

package/dist/adapters/types.d.ts

@@ -502,6 +502,13 @@ export type AgentEvent = {
      * The discriminator #257 turns on. `false` means the turn is safe to send
      * again; `true` means files may already be written and commands already
      * run, so it may only be RESUMED.
+     *
+     * Since ticket #300 it is reported on a SUCCESSFUL turn too, where it
+     * answers a different question with the same arithmetic: a turn that ends
+     * `ok` having produced nothing is, as often as not, no turn at all — a
+     * resumed process closing a warm-up the person never asked for. The
+     * supervisor holds such an ending briefly rather than announcing «your
+     * turn» over an agent that has not started speaking yet.
      */
     produced?: boolean;
     /**
@@ -553,8 +560,16 @@ export interface AgentSession {
      * make the NEXT message be consumed as the answer to a turn that is gone.
      */
     cancelQuestions(reason: QuestionInvalidationReason): void;
-    /** Follow-up user input into the live session. */
-    send(text: string): void;
+    /**
+     * Follow-up user input into the live session.
+     *
+     * Answers whether the session TOOK it (#231 F8). It used to return nothing,
+     * and a message pushed into a queue that had already ended was written to the
+     * log and forgotten — while the browser was showing that very sentence as a
+     * bubble with the session marked «working». The supervisor now puts a refusal
+     * back on the queue and says so in the feed.
+     */
+    send(text: string): boolean;
     /** Switch model mid-session (VS-Code-extension parity). */
     setModel(model: string): Promise<void>;
     /** Switch reasoning effort mid-session; null = the model's own default. */

package/dist/index.js

@@ -404,6 +404,11 @@ function runnerCapabilities(apiUrlOverride) {
             // this list is what `runCommand` actually dispatches on, and the API
             // falls back to the old frame for runners that do not name it.
             'answer_question',
+            // Ticket #299: and an ordinary message the same way. Same reasoning as
+            // the line above, on the path people use every minute — until this
+            // release the API called a socket write a delivery, and a message written
+            // into a socket that still read OPEN could simply cease to exist.
+            'deliver_message',
             'compact_context',
             ...(checkpointsEnabled
                 ? [

package/dist/protocol.d.ts

@@ -344,6 +344,47 @@ export declare const QuestionAnswerArgsSchema: z.ZodObject<{
         notes?: string | undefined;
     }[] | undefined;
 }>;
+/**
+ * The body of a `deliver_message` command — ticket #299.
+ *
+ * The same three fields the frame carries, with `messageId` required rather
+ * than optional: an API old enough to omit it is also too old to send this
+ * command at all, and the id is the entire reason a redelivery can be
+ * recognised instead of duplicated.
+ */
+export declare const DeliverMessageArgsSchema: z.ZodObject<{
+    messageId: z.ZodString;
+    text: z.ZodString;
+    attachments: z.ZodCatch<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        fileName: z.ZodString;
+        mimeType: z.ZodString;
+        fileSize: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        fileName: string;
+        mimeType: string;
+        fileSize: number;
+    }, {
+        id: string;
+        fileName: string;
+        mimeType: string;
+        fileSize: number;
+    }>, "many">>>;
+}, "strip", z.ZodTypeAny, {
+    text: string;
+    messageId: string;
+    attachments?: {
+        id: string;
+        fileName: string;
+        mimeType: string;
+        fileSize: number;
+    }[] | undefined;
+}, {
+    text: string;
+    messageId: string;
+    attachments?: unknown;
+}>;
 export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     type: z.ZodLiteral<"hello_ack">;
     serverId: z.ZodString;
@@ -1126,6 +1167,12 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
     type: z.ZodLiteral<"session_message">;
     sessionId: z.ZodString;
     text: z.ZodString;
+    /**
+     * The API's name for this message (#299). Optional: an API deployed before
+     * that ticket sends none, and a message without a name is still a message —
+     * it just cannot be recognised if it is sent a second time.
+     */
+    messageId: z.ZodCatch<z.ZodOptional<z.ZodString>>;
     attachments: z.ZodCatch<z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         fileName: z.ZodString;
@@ -1152,11 +1199,13 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         mimeType: string;
         fileSize: number;
     }[] | undefined;
+    messageId?: string | undefined;
 }, {
     text: string;
     sessionId: string;
     type: "session_message";
     attachments?: unknown;
+    messageId?: unknown;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"permission_answer">;
     sessionId: z.ZodString;
@@ -1401,6 +1450,20 @@ export type RunnerFrame = {
      * land on the session that has already been picked back up.
      */
     epoch?: number;
+    /**
+     * Subagents still running as this status is reported (ticket #236).
+     *
+     * `WAITING_INPUT` with live background work is not «your turn»: the agent
+     * comes back by itself when the subagent reports. The API stores this and
+     * two readers use it — the notification gate, so nobody is called to a
+     * conversation with nothing to answer, and the status strip, which had no
+     * way to know at all on a page opened after the last `agent_tasks` frame.
+     *
+     * Reported on every status, including the one whose only news is that the
+     * number reached zero — that report IS the moment the turn became the
+     * human's.
+     */
+    backgroundTasks?: number;
 } | {
     type: 'session_unknown';
     sessionId: string;

package/dist/protocol.js

@@ -208,6 +208,36 @@ export const QuestionAnswerShape = {
 };
 /** The `answer_question` command's arguments — the shape above on its own. */
 export const QuestionAnswerArgsSchema = z.object(QuestionAnswerShape);
+/**
+ * Attachment metadata, named once because two shapes now carry it: the legacy
+ * `session_message` frame and the `deliver_message` command that replaces it.
+ *
+ * `.catch(undefined)` is load-bearing and pre-dates both: one malformed entry
+ * must cost the attachments, never the sentence the person typed.
+ */
+const MessageAttachmentsSchema = z
+    .array(z.object({
+    id: z.string().uuid(),
+    fileName: z.string().max(500),
+    mimeType: z.string().max(200),
+    fileSize: z.number().int().min(0),
+}))
+    .max(10)
+    .optional()
+    .catch(undefined);
+/**
+ * The body of a `deliver_message` command — ticket #299.
+ *
+ * The same three fields the frame carries, with `messageId` required rather
+ * than optional: an API old enough to omit it is also too old to send this
+ * command at all, and the id is the entire reason a redelivery can be
+ * recognised instead of duplicated.
+ */
+export const DeliverMessageArgsSchema = z.object({
+    messageId: z.string().min(1).max(120),
+    text: z.string(),
+    attachments: MessageAttachmentsSchema,
+});
 export const GatewayFrameSchema = z.discriminatedUnion('type', [
     z.object({
         type: z.literal('hello_ack'),
@@ -236,19 +266,16 @@ export const GatewayFrameSchema = z.discriminatedUnion('type', [
         type: z.literal('session_message'),
         sessionId: z.string().uuid(),
         text: z.string(),
+        /**
+         * The API's name for this message (#299). Optional: an API deployed before
+         * that ticket sends none, and a message without a name is still a message —
+         * it just cannot be recognised if it is sent a second time.
+         */
+        messageId: z.string().max(120).optional().catch(undefined),
         // Files the user attached (session 10) — metadata only; the bytes are
         // fetched with the runner's own token. `.catch` so a malformed entry costs
         // the attachments, never the message the user typed.
-        attachments: z
-            .array(z.object({
-            id: z.string().uuid(),
-            fileName: z.string().max(500),
-            mimeType: z.string().max(200),
-            fileSize: z.number().int().min(0),
-        }))
-            .max(10)
-            .optional()
-            .catch(undefined),
+        attachments: MessageAttachmentsSchema,
     }),
     z.object({
         type: z.literal('permission_answer'),

package/dist/supervisor.d.ts

@@ -53,11 +53,42 @@ export interface SupervisorOptions {
      * announced and no rewind can be started.
      */
     checkpointsEnabled?: boolean;
+    /**
+     * How long a turn that produced nothing is held before it counts (#300).
+     *
+     * A test seam, like `proposeCommitMessage` above: the real window is 25
+     * seconds and no suite can wait that out, so the behaviour would go
+     * unverified — which is exactly how the independent review found the hold
+     * firing over a working agent (QA-2026-08-16 M-4). Never set in production.
+     */
+    emptyTurnSettleMs?: number;
 }
 export declare class Supervisor {
     private readonly ws;
     private readonly opts;
     private static readonly ORPHAN_MESSAGE_CAP;
+    /**
+     * How many delivered message ids one session remembers (#299).
+     *
+     * Only ever consulted for a REDELIVERY, and the API redelivers on a `hello`
+     * — within a reconnect of the original, not a day later. A hundred is far
+     * more than that window can hold and still nothing next to a session's own
+     * journal.
+     */
+    private static readonly DELIVERED_MESSAGE_CAP;
+    /**
+     * How long a turn that produced nothing is held before it counts (#300).
+     *
+     * Long enough to cover the gap the owner watched — a resumed process closed
+     * a phantom turn and the real answer landed twenty-one seconds later — and
+     * short enough that a genuinely silent turn is not left looking busy. The
+     * cost of being wrong is asymmetric on purpose: a late «your turn» is a
+     * cosmetic delay, an early one is a lie that invites someone to interrupt an
+     * agent mid-thought.
+     */
+    private static readonly EMPTY_TURN_SETTLE_MS;
+    /** The window actually used — the constant, or a test's own shorter one. */
+    private readonly emptyTurnSettleMs;
     /** 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. */
@@ -298,6 +329,54 @@ export declare class Supervisor {
      * card the user was about to answer — the moment another session wanted a
      * slot.
      */
+    /**
+     * Do what the end of a turn does — send it, and move the status.
+     *
+     * Extracted from `case 'turn_end'` because ticket #300 gave the same work a
+     * second caller: a turn held back as a possible phantom finishes here when
+     * 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.
+     */
+    private completeTurn;
+    /**
+     * Move the session to the status a finished turn leaves it in.
+     *
+     * Split out of `completeTurn` because ticket #300 gave it a second caller: a
+     * turn held as a possible phantom settles here when its timer runs out, and
+     * it has to land in exactly the status it would have landed in immediately.
+     */
+    private settleTurnStatus;
+    /**
+     * Hold a turn that produced nothing, in case it was never a turn (#300).
+     *
+     * Returns true when the turn has been parked and the caller must stop. False
+     * means «treat it as a real ending»: a session already on its way out, or one
+     * that is not running an agent, has nothing to wait for.
+     */
+    private holdEmptyTurn;
+    /**
+     * Drop a held turn: the agent spoke, so the turn it «ended» was a phantom.
+     *
+     * Called from `noteAgentIsWorking` — the one place that already knows the
+     * agent has produced something — and from the real turn ending, so a held
+     * phantom can never fire after the turn it belonged to has closed properly.
+     */
+    private clearEmptyTurn;
+    /**
+     * Record how many subagents are alive, and say so when it matters (#236).
+     *
+     * One place, because there are now two callers with opposite news — a frame
+     * from the adapter, and the process going away — and «is it the human's turn»
+     * must be answered the same way by both.
+     *
+     * The report on reaching zero is the whole point: the agent is already
+     * sitting in a resting status, so nothing else will ever tell the API that
+     * the session finally became the person's. `REVIEW` counts as well as
+     * `WAITING_INPUT` — a TICKET session waiting on its own subagent is in the
+     * same position, and leaving it out was how one of the two statuses kept its
+     * notification suppressed for good (QA-2026-08-16 M-5).
+     */
+    private setBackgroundTasks;
     private isParkable;
     /**
      * Stop the agent process but keep the session resumable.
@@ -342,7 +421,22 @@ export declare class Supervisor {
      * somebody says so.
      */
     private onQuestionAnswer;
-    private onUserMessage;
+    /**
+     * Take a message, and say what happened to it — synchronously (#299).
+     *
+     * NOT A SINGLE `await` FROM HERE TO THE RETURN. Frames are handled
+     * concurrently (gotcha #68), so a yield between «is this a duplicate» and
+     * «record it» would let the retry of a message overtake the original and be
+     * delivered twice. The same rule the question answer next door obeys, and for
+     * the same reason: this value becomes a `command_result` the API believes.
+     *
+     * Everything here was already synchronous — the delivery itself rides on
+     * `enqueueDelivery`, which registers work on a chain rather than awaiting it.
+     * The only change is that the outcome is now spoken out loud instead of being
+     * thrown away, because «I wrote it into a socket» was never an answer to
+     * «did the runner get it».
+     */
+    private acceptUserMessage;
     /**
      * Queue a message that no agent can take yet, and say so in the feed
      * (ticket #125).

package/dist/supervisor.js

@@ -19,7 +19,7 @@ import { selfUpdate } from './self-update.js';
 import { rememberWorkspacePath } from './environment.js';
 import { composeMessageWithAttachments, saveAttachments, } from './attachments.js';
 import { applyRewind, createCheckpoint, dropCheckpoints, listCheckpoints, previewRewind, pruneCheckpoints, } from './checkpoints.js';
-import { QuestionAnswerArgsSchema } from './protocol.js';
+import { DeliverMessageArgsSchema, QuestionAnswerArgsSchema } from './protocol.js';
 import { availableModes, MODE_REFUSED_TEXT } from './adapters/types.js';
 /** Refusals shared by every checkpoint command (ticket #126). */
 const CHECKPOINTS_OFF = 'Restore points are switched off on this server ([checkpoints] enabled = false)';
@@ -57,6 +57,28 @@ export class Supervisor {
     ws;
     opts;
     static ORPHAN_MESSAGE_CAP = 10;
+    /**
+     * How many delivered message ids one session remembers (#299).
+     *
+     * Only ever consulted for a REDELIVERY, and the API redelivers on a `hello`
+     * — within a reconnect of the original, not a day later. A hundred is far
+     * more than that window can hold and still nothing next to a session's own
+     * journal.
+     */
+    static DELIVERED_MESSAGE_CAP = 100;
+    /**
+     * How long a turn that produced nothing is held before it counts (#300).
+     *
+     * Long enough to cover the gap the owner watched — a resumed process closed
+     * a phantom turn and the real answer landed twenty-one seconds later — and
+     * short enough that a genuinely silent turn is not left looking busy. The
+     * cost of being wrong is asymmetric on purpose: a late «your turn» is a
+     * cosmetic delay, an early one is a lie that invites someone to interrupt an
+     * agent mid-thought.
+     */
+    static EMPTY_TURN_SETTLE_MS = 25_000;
+    /** The window actually used — the constant, or a test's own shorter one. */
+    emptyTurnSettleMs;
     /** A finished session's journal is kept this long for a late reconnect. */
     static JOURNAL_TTL_MS = 72 * 3_600_000;
     /** Backstop: events the API will never accept must not pile up forever. */
@@ -94,6 +116,7 @@ export class Supervisor {
         this.ws = ws;
         this.opts = opts;
         this.journals = opts.journals ?? new JournalStore();
+        this.emptyTurnSettleMs = opts.emptyTurnSettleMs ?? Supervisor.EMPTY_TURN_SETTLE_MS;
         this.verify = new VerifyRunner({
             enabled: opts.verifyEnabled !== false,
             onReport: (report) => {
@@ -207,7 +230,11 @@ export class Supervisor {
                 await this.startSession(frame.session);
                 break;
             case 'session_message':
-                await this.onUserMessage(frame.sessionId, frame.text, frame.attachments);
+                // The legacy door, still open for an API that has not learned the
+                // command yet. Its outcome goes nowhere because nobody is listening —
+                // which is the whole defect ticket #299 is about, and why the command
+                // below exists.
+                this.acceptUserMessage(frame.sessionId, frame.text, frame.attachments, frame.messageId ?? undefined);
                 break;
             case 'permission_answer': {
                 const running = this.sessions.get(frame.sessionId);
@@ -313,6 +340,8 @@ export class Supervisor {
             epoch: descriptor.epoch,
             openQuestions: new Set(),
             answeredAsks: new Set(),
+            deliveredMessageIds: new Set(),
+            backgroundTasks: 0,
             // Ticket #196: a pause is part of what a session IS, so it is read off
             // the descriptor rather than waiting for a frame. Without this a runner
             // that restarted mid-pause would come back knowing nothing and pick the
@@ -332,12 +361,25 @@ export class Supervisor {
         // exist (session 9).
         running.pendingMessages.push(...running.journal.pending());
         this.sessions.set(descriptor.id, running);
-        // Messages that arrived for a session this runner did not know yet.
+        /**
+         * Messages that arrived for a session this runner did not know yet.
+         *
+         * They go in through the ORDINARY door now (#231 F4). They used to be
+         * pushed straight onto `pendingMessages` with `appendPending` and no
+         * `originSeq` — which meant no echo and no `message_queued`, so the words
+         * reached the agent and never appeared in the conversation at all. The
+         * person saw an empty composer, an empty feed, and then an answer to
+         * something they could not see themselves having asked.
+         *
+         * `queueMessage` is skipped in favour of the full `acceptUserMessage` so
+         * that a session which is ready by now delivers immediately rather than
+         * sitting in a queue nothing flushes.
+         */
         const orphaned = this.orphanMessages.get(descriptor.id);
         if (orphaned) {
             this.orphanMessages.delete(descriptor.id);
             for (const message of orphaned) {
-                running.pendingMessages.push(running.journal.appendPending(message.text, message.attachments));
+                this.acceptUserMessage(descriptor.id, message.text, message.attachments, message.messageId);
             }
         }
         try {
@@ -1024,6 +1066,20 @@ export class Supervisor {
             // Idle process ended (parked or died between turns) — stay resumable.
             running.session = null;
             running.parkRequested = false;
+            /**
+             * The subagents died with it (QA-2026-08-16 M-5).
+             *
+             * Here rather than in `park()`, because parking only ASKS the process to
+             * stop and this is where it actually went. The adapter stops publishing
+             * the moment it is told to stop, so without this the last frame's count
+             * stands for ever: the strip says «Working in background» over a parked
+             * session and — far worse — the API goes on suppressing that session's
+             * «your turn» notification for the rest of its life, because the number
+             * it stored never reaches zero again.
+             *
+             * Before the `reportStatus` just below, so the zero rides out on it.
+             */
+            running.backgroundTasks = 0;
             running.costBaseUsd = running.costUsd; // next process starts from here
             // Persist the clock: a parked session can sit for hours and the runner
             // may be restarted before it ever runs again.
@@ -1217,6 +1273,176 @@ export class Supervisor {
      * card the user was about to answer — the moment another session wanted a
      * slot.
      */
+    /**
+     * Do what the end of a turn does — send it, and move the status.
+     *
+     * Extracted from `case 'turn_end'` because ticket #300 gave the same work a
+     * second caller: a turn held back as a possible phantom finishes here when
+     * 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.
+     */
+    completeTurn(running, descriptor, event) {
+        this.sendEvent(running, 'turn_end', {
+            ok: event.ok,
+            errorMessage: event.errorMessage,
+            ...(event.aborted ? { aborted: true } : {}),
+        });
+        // The session is already on its way out with a status that MEANS
+        // something — a spent budget, a Stop, a teardown. A turn ending inside
+        // that window is a consequence of it, and letting the line below
+        // overwrite `STOPPED / TIME_BUDGET` with `FAILED` (or with a cheerful
+        // WAITING_INPUT) replaces a true, actionable ending with a wrong one.
+        if (running.stopRequested || running.budgetSpent)
+            return;
+        // A finished turn is the last instant this conversation is BOTH
+        // complete and readable: the process can be parked or lose its slot at
+        // any point after it, and `conversationAnchor()` needs a live one.
+        this.currentAnchor(running);
+        /**
+         * A turn that produced NOTHING does not get to say «your turn» yet (#300).
+         *
+         * Only the STATUS waits. The `turn_end` event above has already gone out,
+         * because the feed's own readers depend on it — the task tray reads it to
+         * retire a finished turn's counters — and because holding it would make two
+         * facts disagree about one moment.
+         *
+         * The status is the whole symptom: `WAITING_INPUT` is what the dashboard
+         * prints as «Your turn», and a resumed agent process closes a turn it never
+         * ran — no text, no thinking, no tool call — twenty-one seconds before the
+         * real answer arrives. The product spent those seconds claiming to wait for
+         * a person who was, in fact, waiting for it.
+         *
+         * `produced` is the adapter's own arithmetic from 0.44.1 (#252/#257),
+         * reused rather than reinvented.
+         */
+        if (event.ok && event.produced !== true && this.holdEmptyTurn(running, descriptor, event)) {
+            return;
+        }
+        // Not held — so any phantom still waiting from an earlier turn is stale and
+        // must not outlive this ending. Cleared HERE and not before the decision
+        // above, or `holdEmptyTurn`'s «two in a row is a quiet agent, not two
+        // phantoms» rule could never see the first one (QA-2026-08-16 M-6).
+        this.clearEmptyTurn(running);
+        this.settleTurnStatus(running, descriptor, event);
+    }
+    /**
+     * Move the session to the status a finished turn leaves it in.
+     *
+     * Split out of `completeTurn` because ticket #300 gave it a second caller: a
+     * turn held as a possible phantom settles here when its timer runs out, and
+     * it has to land in exactly the status it would have landed in immediately.
+     */
+    settleTurnStatus(running, descriptor, event) {
+        // Turn end is the natural checkpoint for the budget clock: the slice
+        // just closed, so this is the moment the API can persist it. Without a
+        // report here `agentActiveMs` stayed 0 and every restart or resume
+        // silently handed the session a full fresh budget.
+        if (event.ok) {
+            const next = descriptor.kind === 'CHAT' ? 'WAITING_INPUT' : 'REVIEW';
+            this.reportStatus(descriptor.id, next, {
+                costUsd: running.costUsd,
+                activeMs: Supervisor.spentMs(running),
+            });
+        }
+        else if (event.limitBlocked) {
+            // #258. The plan refused this turn — it never ran, so the session has
+            // not failed at anything: it is waiting for a window to open, and the
+            // API has just armed a clock to wake it. FAILED is terminal, and a
+            // terminal session cannot be woken — the pause would ring into a dead
+            // row and cancel the words the person queued behind it.
+            this.reportStatus(descriptor.id, descriptor.kind === 'CHAT' ? 'WAITING_INPUT' : 'REVIEW', {
+                costUsd: running.costUsd,
+                activeMs: Supervisor.spentMs(running),
+            });
+        }
+        else {
+            this.reportStatus(descriptor.id, 'FAILED', {
+                costUsd: running.costUsd,
+                activeMs: Supervisor.spentMs(running),
+                errorMessage: event.errorMessage ?? 'Agent turn failed',
+            });
+        }
+    }
+    /**
+     * Hold a turn that produced nothing, in case it was never a turn (#300).
+     *
+     * Returns true when the turn has been parked and the caller must stop. False
+     * means «treat it as a real ending»: a session already on its way out, or one
+     * that is not running an agent, has nothing to wait for.
+     */
+    holdEmptyTurn(running, descriptor, event) {
+        // An aborted turn produced nothing BY DEFINITION — the human pressed Stop,
+        // and making them wait 25 seconds to be told the turn is over would be a
+        // new bug in place of the old one.
+        if (event.aborted)
+            return false;
+        // The session is winding down: a status is already on its way that means
+        // something, and holding this would only delay a truthful ending.
+        if (running.stopRequested || running.budgetSpent)
+            return false;
+        // Two of these in a row is not two phantoms — it is a quiet agent. The
+        // second one ends the turn for real.
+        if (running.emptyTurnTimer)
+            return false;
+        log.info('supervisor: holding a turn that produced nothing', {
+            sessionId: descriptor.id,
+            settleMs: this.emptyTurnSettleMs,
+        });
+        const timer = setTimeout(() => {
+            running.emptyTurnTimer = undefined;
+            // The session may have ended, been resumed or been replaced while we
+            // waited — `isStale` is the same guard every other delayed path uses.
+            if (this.isStale(running))
+                return;
+            log.info('supervisor: the empty turn was real after all', { sessionId: descriptor.id });
+            this.settleTurnStatus(running, descriptor, event);
+        }, this.emptyTurnSettleMs);
+        timer.unref();
+        running.emptyTurnTimer = timer;
+        return true;
+    }
+    /**
+     * Drop a held turn: the agent spoke, so the turn it «ended» was a phantom.
+     *
+     * Called from `noteAgentIsWorking` — the one place that already knows the
+     * agent has produced something — and from the real turn ending, so a held
+     * phantom can never fire after the turn it belonged to has closed properly.
+     */
+    clearEmptyTurn(running) {
+        if (!running.emptyTurnTimer)
+            return;
+        clearTimeout(running.emptyTurnTimer);
+        running.emptyTurnTimer = undefined;
+    }
+    /**
+     * Record how many subagents are alive, and say so when it matters (#236).
+     *
+     * One place, because there are now two callers with opposite news — a frame
+     * from the adapter, and the process going away — and «is it the human's turn»
+     * must be answered the same way by both.
+     *
+     * The report on reaching zero is the whole point: the agent is already
+     * sitting in a resting status, so nothing else will ever tell the API that
+     * the session finally became the person's. `REVIEW` counts as well as
+     * `WAITING_INPUT` — a TICKET session waiting on its own subagent is in the
+     * same position, and leaving it out was how one of the two statuses kept its
+     * notification suppressed for good (QA-2026-08-16 M-5).
+     */
+    setBackgroundTasks(running, live) {
+        if (live === running.backgroundTasks)
+            return;
+        const finished = running.backgroundTasks > 0 && live === 0;
+        running.backgroundTasks = live;
+        const resting = running.lastReported === 'WAITING_INPUT' || running.lastReported === 'REVIEW'
+            ? running.lastReported
+            : null;
+        if (finished && resting) {
+            this.reportStatus(running.descriptor.id, resting, {
+                costUsd: running.costUsd,
+                activeMs: Supervisor.spentMs(running),
+            });
+        }
+    }
     isParkable(running) {
         return ((running.lastReported === 'REVIEW' || running.lastReported === 'WAITING_INPUT') &&
             running.openQuestions.size === 0 &&
@@ -1274,6 +1500,12 @@ export class Supervisor {
      * own question must not take the card off the screen.
      */
     noteAgentIsWorking(running) {
+        // Ticket #300: the agent is producing, so a turn held back as a possible
+        // phantom was one. Dropped BEFORE the guards below, because those are about
+        // whether the STATUS may move — and a phantom must be cancelled even when
+        // the status is already right, or it fires later and ends a turn that is
+        // still going.
+        this.clearEmptyTurn(running);
         if (running.openQuestions.size > 0)
             return;
         if (running.stopRequested || running.parkRequested || running.budgetSpent)
@@ -1341,51 +1573,7 @@ export class Supervisor {
                 // when it finally succeeds or finally gives up.
                 if (!event.ok && this.armApiRetry(running, descriptor, event))
                     return;
-                this.sendEvent(running, 'turn_end', {
-                    ok: event.ok,
-                    errorMessage: event.errorMessage,
-                    ...(event.aborted ? { aborted: true } : {}),
-                });
-                // The session is already on its way out with a status that MEANS
-                // something — a spent budget, a Stop, a teardown. A turn ending inside
-                // that window is a consequence of it, and letting the line below
-                // overwrite `STOPPED / TIME_BUDGET` with `FAILED` (or with a cheerful
-                // WAITING_INPUT) replaces a true, actionable ending with a wrong one.
-                if (running.stopRequested || running.budgetSpent)
-                    return;
-                // A finished turn is the last instant this conversation is BOTH
-                // complete and readable: the process can be parked or lose its slot at
-                // any point after it, and `conversationAnchor()` needs a live one.
-                this.currentAnchor(running);
-                // Turn end is the natural checkpoint for the budget clock: the slice
-                // just closed, so this is the moment the API can persist it. Without a
-                // report here `agentActiveMs` stayed 0 and every restart or resume
-                // silently handed the session a full fresh budget.
-                if (event.ok) {
-                    const next = descriptor.kind === 'CHAT' ? 'WAITING_INPUT' : 'REVIEW';
-                    this.reportStatus(descriptor.id, next, {
-                        costUsd: running.costUsd,
-                        activeMs: Supervisor.spentMs(running),
-                    });
-                }
-                else if (event.limitBlocked) {
-                    // #258. The plan refused this turn — it never ran, so the session has
-                    // not failed at anything: it is waiting for a window to open, and the
-                    // API has just armed a clock to wake it. FAILED is terminal, and a
-                    // terminal session cannot be woken — the pause would ring into a dead
-                    // row and cancel the words the person queued behind it.
-                    this.reportStatus(descriptor.id, descriptor.kind === 'CHAT' ? 'WAITING_INPUT' : 'REVIEW', {
-                        costUsd: running.costUsd,
-                        activeMs: Supervisor.spentMs(running),
-                    });
-                }
-                else {
-                    this.reportStatus(descriptor.id, 'FAILED', {
-                        costUsd: running.costUsd,
-                        activeMs: Supervisor.spentMs(running),
-                        errorMessage: event.errorMessage ?? 'Agent turn failed',
-                    });
-                }
+                this.completeTurn(running, descriptor, event);
                 return;
             }
             case 'error':
@@ -1592,7 +1780,7 @@ export class Supervisor {
             case 'rate_limits':
                 this.sendEvent(running, 'rate_limits', { ...event.limits });
                 return;
-            case 'agent_tasks':
+            case 'agent_tasks': {
                 // Ticket #113. A LEVEL signal: every frame carries the whole live set,
                 // so the dashboard replaces rather than reconciles and a dropped frame
                 // cannot leave a finished subagent spinning in the tray forever.
@@ -1601,7 +1789,23 @@ export class Supervisor {
                     done: event.done,
                     total: event.total,
                 });
+                /**
+                 * ...and keep the count where a DECISION can read it (ticket #236).
+                 *
+                 * Until now this frame only ever flew past on its way to the browser,
+                 * and the one place that had to know — «is the turn the human's now» —
+                 * was taken without it. Two symptoms, one cause: a status strip reading
+                 * «Your turn» a centimetre above a live subagent, and a notification
+                 * calling someone to a conversation with nothing to answer.
+                 *
+                 * Counted from `tasks` rather than from `total`/`done`: those are the
+                 * turn's arithmetic and a background task deliberately outlives its own
+                 * turn (`endTaskTurn` keeps the live set).
+                 */
+                const live = event.tasks.filter((task) => task.status === 'running').length;
+                this.setBackgroundTasks(running, live);
                 return;
+            }
             case 'notice': {
                 // Only adapter notices are de-duplicated here. The supervisor's own
                 // notices (turn interrupted, session parked, budget warnings) go
@@ -1678,12 +1882,9 @@ export class Supervisor {
         // The words must not be eaten. This is the ordinary case after a runner
         // restart: the card in the browser outlived the process that asked, and
         // showing the user's own message in the feed while nothing receives it is
-        // the exact failure `onUserMessage` was hardened against (QA-106 M2).
+        // the exact failure `acceptUserMessage` was hardened against (QA-106 M2).
         if (typed) {
-            void this.onUserMessage(frame.sessionId, typed).catch((error) => log.error('supervisor: could not deliver a reply to a closed question', {
-                sessionId: frame.sessionId,
-                error: String(error),
-            }));
+            this.acceptUserMessage(frame.sessionId, typed);
             return 'not_open';
         }
         // Nothing to deliver — but the API optimistically flipped the session to
@@ -1691,7 +1892,22 @@ export class Supervisor {
         this.reportStatus(frame.sessionId, statusForReport(running), {});
         return 'not_open';
     }
-    async onUserMessage(sessionId, text, attachments) {
+    /**
+     * Take a message, and say what happened to it — synchronously (#299).
+     *
+     * NOT A SINGLE `await` FROM HERE TO THE RETURN. Frames are handled
+     * concurrently (gotcha #68), so a yield between «is this a duplicate» and
+     * «record it» would let the retry of a message overtake the original and be
+     * delivered twice. The same rule the question answer next door obeys, and for
+     * the same reason: this value becomes a `command_result` the API believes.
+     *
+     * Everything here was already synchronous — the delivery itself rides on
+     * `enqueueDelivery`, which registers work on a chain rather than awaiting it.
+     * The only change is that the outcome is now spoken out loud instead of being
+     * thrown away, because «I wrote it into a socket» was never an answer to
+     * «did the runner get it».
+     */
+    acceptUserMessage(sessionId, text, attachments, messageId) {
         const running = this.sessions.get(sessionId);
         if (!running) {
             // The API believes this session lives here but the runner lost track of
@@ -1700,10 +1916,47 @@ export class Supervisor {
             // instead of dropping it silently.
             log.warn('supervisor: message for unknown session — requesting descriptor', { sessionId });
             const queued = this.orphanMessages.get(sessionId) ?? [];
-            queued.push({ text, ...(attachments?.length ? { attachments } : {}) });
+            /**
+             * The name travels with the words (QA-2026-08-16 M-2).
+             *
+             * Without it the replay below took the message a SECOND time under no
+             * name, and the API's redelivery of the row it queued for the same
+             * `unknown_session` then looked brand new to `deliveredMessageIds` — the
+             * agent got one instruction twice, in the one scenario that reliably
+             * produces both copies.
+             */
+            queued.push({
+                text,
+                ...(attachments?.length ? { attachments } : {}),
+                ...(messageId ? { messageId } : {}),
+            });
             this.orphanMessages.set(sessionId, queued.slice(-Supervisor.ORPHAN_MESSAGE_CAP));
             this.ws.send({ type: 'session_unknown', sessionId });
-            return;
+            return 'unknown_session';
+        }
+        /**
+         * Already taken (#299).
+         *
+         * The API queues a message it could not get confirmed and re-sends it on
+         * the next `hello`. «Not confirmed» is not «not delivered»: the socket can
+         * die between this runner accepting the words and the answer reaching the
+         * API. Without this set the retry would hand the agent the same sentence a
+         * second time — the very failure the queue was built to avoid.
+         *
+         * In memory, so a runner that RESTARTED between the two attempts will take
+         * it twice. That is the deliberate side of the trade: after a restart the
+         * first copy almost certainly never reached the agent, and a duplicate is a
+         * far smaller injury than a message that silently does not exist.
+         */
+        if (messageId) {
+            if (running.deliveredMessageIds.has(messageId))
+                return 'duplicate';
+            running.deliveredMessageIds.add(messageId);
+            if (running.deliveredMessageIds.size > Supervisor.DELIVERED_MESSAGE_CAP) {
+                const oldest = running.deliveredMessageIds.values().next().value;
+                if (oldest !== undefined)
+                    running.deliveredMessageIds.delete(oldest);
+            }
         }
         // The feed shows what the USER wrote plus the files they picked — not the
         // composed prompt with workspace paths, which is an implementation detail.
@@ -1712,6 +1965,12 @@ export class Supervisor {
         const echoed = this.sendEvent(running, 'message', {
             role: 'user',
             text,
+            // The API's name for this message, echoed back so the browser can match
+            // the bubble it drew itself the moment Send was pressed (#299). Matching
+            // on text alone works right up until somebody sends the same sentence
+            // twice, which is exactly what a person does when they think the first
+            // one was lost.
+            ...(messageId ? { messageId } : {}),
             ...(attachments?.length ? { attachments } : {}),
         });
         const originSeq = echoed.seq;
@@ -1726,7 +1985,7 @@ export class Supervisor {
             // own conflict tasks. Held here rather than delivered, so «на паузе»
             // means the same thing whichever door the words came through.
             this.queueMessage(running, running.journal.appendPending(text, attachments, originSeq));
-            return;
+            return 'accepted';
         }
         this.enqueueDelivery(running, async () => {
             const composed = await this.materializeAttachments(running, text, attachments);
@@ -1751,6 +2010,7 @@ export class Supervisor {
                 return;
             this.deliverMessage(running, composed, [], originSeq);
         });
+        return 'accepted';
     }
     /**
      * Queue a message that no agent can take yet, and say so in the feed
@@ -1987,13 +2247,41 @@ export class Supervisor {
                 this.sendEvent(running, 'message_delivered', { targetSeqs: delivered });
             }
         };
+        // M-4 (QA-2026-08-16): a new turn is starting, so a phantom held from the
+        // previous one must not fire 25 seconds from now and report WAITING_INPUT
+        // over an agent that is working — the very lie #300 is about, and this time
+        // with an irreversible notification behind it.
+        this.clearEmptyTurn(running);
         if (running.session && !running.parkRequested) {
             // #252: the words this turn is actually running. `lastPrompt` deliberately
             // stays put — three older latches relaunch a PROCESS with it, and handing
             // them a follow-up line instead of the task would start a fresh
             // conversation with «продолжай».
             running.lastTurnPrompt = text;
-            running.session.send(text);
+            /**
+             * The process can refuse — and used to refuse in silence (#231 F8).
+             *
+             * `AsyncQueue.push` answers false once the queue has ended, which happens
+             * when the agent's own iterator finished between the check above and this
+             * line. The adapter wrote a line to its log and returned; from here the
+             * message looked delivered, so `settle()` retired it from the queue and
+             * the status went to RUNNING. On screen: the person's bubble, the word
+             * «working», and an agent that had already stopped and would never answer.
+             *
+             * Now it goes back in the queue, exactly like a parked process below, and
+             * the feed says why.
+             */
+            if (!running.session.send(text)) {
+                log.warn('supervisor: the agent process refused the message — requeued', {
+                    sessionId: running.descriptor.id,
+                });
+                this.sendEvent(running, 'system_note', {
+                    code: 'agent_gone',
+                    text: 'The agent process ended before it could take this message. It is queued and will be delivered when the session continues.',
+                });
+                this.requeue(running, held, text, originSeq);
+                return;
+            }
             settle();
             this.reportStatus(running.descriptor.id, 'RUNNING', {});
             return;
@@ -2599,6 +2887,8 @@ export class Supervisor {
                         epoch: descriptor.epoch,
                         openQuestions: new Set(),
                         answeredAsks: new Set(),
+                        deliveredMessageIds: new Set(),
+                        backgroundTasks: 0,
                         ...pausedUntilOf(descriptor),
                         mode: descriptor.mode,
                         ...(descriptor.model ? { model: descriptor.model } : {}),
@@ -2864,6 +3154,35 @@ export class Supervisor {
                         ? { ok: false, error: 'Unknown session', result: { outcome } }
                         : { ok: true, result: { outcome } });
                 }
+                case 'deliver_message': {
+                    // Ticket #299 — the same treatment as `answer_question` above, for
+                    // the door people use every minute. The `session_message` frame it
+                    // replaces is fire-and-forget, so the API counted a write into a
+                    // socket as a delivery; on 16.08.2026 a message written into a socket
+                    // that still read OPEN simply ceased to exist, with the queue empty
+                    // and the composer cleared.
+                    //
+                    // No `await` before the reply. `acceptUserMessage` is synchronous
+                    // precisely so this stays true: a yield between «is this a duplicate»
+                    // and «write it down» would let a redelivery overtake the original.
+                    const sessionId = frame.sessionId;
+                    if (!sessionId)
+                        return void reply({ ok: false, error: 'sessionId is required' });
+                    const parsed = DeliverMessageArgsSchema.safeParse(frame.args ?? {});
+                    if (!parsed.success) {
+                        return void reply({
+                            ok: false,
+                            error: parsed.error.issues[0]?.message ?? 'malformed message',
+                        });
+                    }
+                    const outcome = this.acceptUserMessage(sessionId, parsed.data.text, parsed.data.attachments, parsed.data.messageId);
+                    // `ok` is about the RELAY, like the answer above: `unknown_session` is
+                    // the one case the API can fix by asking again after it has re-sent
+                    // the descriptor, so it is the one case reported as a failure.
+                    return void reply(outcome === 'unknown_session'
+                        ? { ok: false, error: 'Unknown session', result: { outcome } }
+                        : { ok: true, result: { outcome } });
+                }
                 case 'recall_message': {
                     // Ticket #125: take a queued message back before any agent sees it.
                     const sessionId = frame.sessionId;
@@ -3868,6 +4187,11 @@ export class Supervisor {
             status,
             ...compact,
             ...(running ? { epoch: running.epoch } : {}),
+            // Ticket #236: on EVERY status, not only the interesting ones. The API
+            // stores the number, and a status frame that carries none leaves the last
+            // one standing — which for a session whose subagents have just finished
+            // would mean it goes on claiming background work forever.
+            ...(running ? { backgroundTasks: running.backgroundTasks } : {}),
         });
     }
     /** Graceful daemon shutdown: kill agents, keep sessions resumable server-side. */

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const RUNNER_VERSION = "0.44.2";
+export declare const RUNNER_VERSION = "0.45.1";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,3 +1,3 @@
 // Kept in sync with package.json by the release script (manual for now).
-export const RUNNER_VERSION = '0.44.2';
+export const RUNNER_VERSION = '0.45.1';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge4dev/runner",
-  "version": "0.44.2",
+  "version": "0.45.1",
   "description": "DevBridge dev runner — connects a dev server to DevBridge and runs agent sessions (Claude Code / Codex)",
   "homepage": "https://bridge4.dev",
   "license": "MIT",