@bridge4dev/runner 0.35.0 → 0.36.0

package/dist/agent-prompt.d.ts

@@ -23,7 +23,26 @@
  * runner is the process that opens the file, and it is the only side that can
  * see what the path actually resolves to on this disk.
  */
-/** Big enough for a real process document; small enough to stay a prompt. */
+/**
+ * Big enough for a real process document; small enough to stay a prompt.
+ *
+ * Raised from 32 KB to 64 KB in 0.36.0 (ticket #192). 32 KB was picked when the
+ * only prompts in existence were 20–25 KB, and the number was never visible
+ * anywhere: a project whose file grew past it simply stopped having a system
+ * prompt, and said so once per session in a line nobody was watching. DevBridge's
+ * own `dev-prompt.md` had been over the line for two releases.
+ *
+ * It stays a real ceiling rather than becoming a setting, and the reason is the
+ * price. This text is not read once — it is in `system[]` on EVERY request the
+ * agent makes, for the whole life of the process, so a prompt is paid for by the
+ * turn. 64 KB is roughly 16k tokens, which is already a lot to carry for
+ * twenty turns; anything beyond it is a document the agent should be asked to
+ * read, not a rule it must never forget.
+ *
+ * The number is on the wire (`agent_prompt_state` announces it), so the settings
+ * card shows the ceiling of the runner that would actually read the file —
+ * never a copy of this constant that could be a version behind.
+ */
 export declare const AGENT_PROMPT_MAX_BYTES: number;
 export type AgentPromptResult = {
     ok: true;
@@ -33,10 +52,18 @@ export type AgentPromptResult = {
     bytes: number;
     sha: string;
 }
-/** Already phrased for a human and safe to show — no raw paths beyond the one they typed. */
+/**
+ * Already phrased for a human and safe to show — no raw paths beyond the one
+ * they typed.
+ *
+ * `bytes` is carried only by the one refusal where the size IS the answer: a
+ * file over the ceiling. «Too big» without the number leaves the person to
+ * guess how much has to go, which is how #192 sat unnoticed for two releases.
+ */
  | {
     ok: false;
     reason: string;
+    bytes?: number;
 };
 /**
  * Read the project's prompt file, or explain why it cannot be read.
@@ -62,6 +89,30 @@ export type AgentPromptResult = {
 export declare function readAgentPrompt(projectRoot: string, relPath: string): AgentPromptResult;
 /** How the prompt is announced in the session feed and in the journal. */
 export declare function agentPromptSizeLabel(bytes: number): string;
+/**
+ * What the settings card asks before anybody starts a session: would this file
+ * reach the agent, and how big is it right now (ticket #192).
+ *
+ * Deliberately the SAME function the launch uses rather than a second, lighter
+ * check. A settings screen that says «fine» over a file the launch would refuse
+ * is worse than a screen that says nothing — and the two would drift the first
+ * time a rule was added to only one of them.
+ *
+ * The text itself never leaves the machine: this answers about the file, and a
+ * project's standing rules are not something the dashboard needs a copy of.
+ */
+export interface AgentPromptState {
+    /** Would this file reach the agent's system prompt, as things stand now? */
+    loaded: boolean;
+    /** The ceiling THIS runner enforces — so the far side never assumes its own. */
+    limit: number;
+    /** Present whenever it is known: on success always, on refusal when size is the reason. */
+    bytes?: number;
+    sha?: string;
+    /** Already phrased for a human, when `loaded` is false. */
+    reason?: string;
+}
+export declare function inspectAgentPrompt(projectRoot: string, relPath: string): AgentPromptState;
 /**
  * A configured path, safe to put in a line a person reads.
  *

package/dist/agent-prompt.js

@@ -27,10 +27,29 @@ import { isGitInternalPath, isSecretPath } from './policy.js';
  * runner is the process that opens the file, and it is the only side that can
  * see what the path actually resolves to on this disk.
  */
-/** Big enough for a real process document; small enough to stay a prompt. */
-export const AGENT_PROMPT_MAX_BYTES = 32 * 1024;
-function deny(reason) {
-    return { ok: false, reason };
+/**
+ * Big enough for a real process document; small enough to stay a prompt.
+ *
+ * Raised from 32 KB to 64 KB in 0.36.0 (ticket #192). 32 KB was picked when the
+ * only prompts in existence were 20–25 KB, and the number was never visible
+ * anywhere: a project whose file grew past it simply stopped having a system
+ * prompt, and said so once per session in a line nobody was watching. DevBridge's
+ * own `dev-prompt.md` had been over the line for two releases.
+ *
+ * It stays a real ceiling rather than becoming a setting, and the reason is the
+ * price. This text is not read once — it is in `system[]` on EVERY request the
+ * agent makes, for the whole life of the process, so a prompt is paid for by the
+ * turn. 64 KB is roughly 16k tokens, which is already a lot to carry for
+ * twenty turns; anything beyond it is a document the agent should be asked to
+ * read, not a rule it must never forget.
+ *
+ * The number is on the wire (`agent_prompt_state` announces it), so the settings
+ * card shows the ceiling of the runner that would actually read the file —
+ * never a copy of this constant that could be a version behind.
+ */
+export const AGENT_PROMPT_MAX_BYTES = 64 * 1024;
+function deny(reason, bytes) {
+    return { ok: false, reason, ...(bytes === undefined ? {} : { bytes }) };
 }
 /**
  * Read the project's prompt file, or explain why it cannot be read.
@@ -140,17 +159,20 @@ export function readAgentPrompt(projectRoot, relPath) {
     //    this, `ln /etc/hostname docs/prompt.md` walks past both «inside the
     //    project folder» and «not on the protected list», because both were
     //    decided about the NAME.
-    let buffer;
+    let read;
     try {
-        buffer = readCapped(realPath, AGENT_PROMPT_MAX_BYTES + 1, link);
+        read = readCapped(realPath, AGENT_PROMPT_MAX_BYTES + 1, link);
     }
     catch (error) {
         if (error instanceof PromptFileRefused)
             return deny(error.reason);
         return deny(describeFsError(error));
     }
+    const buffer = read.buffer;
     if (buffer.length > AGENT_PROMPT_MAX_BYTES) {
-        return deny(`the file is larger than ${Math.floor(AGENT_PROMPT_MAX_BYTES / 1024)} KB`);
+        // The size comes off the descriptor that was just read, not off a second
+        // `stat` of the name — it is the size of the file this refusal is about.
+        return deny(`the file is larger than ${Math.floor(AGENT_PROMPT_MAX_BYTES / 1024)} KB`, read.size);
     }
     if (buffer.includes(0))
         return deny('the file is not text');
@@ -180,6 +202,9 @@ class PromptFileRefused extends Error {
  *
  * @param expected The `lstat` taken before the path checks — the identity every
  *   rule above was decided about.
+ * @returns The bytes actually read, capped at `limit`, and the file's own size
+ *   as the descriptor reports it. The two differ exactly when the file is over
+ *   the ceiling, which is the case that needs the real number to explain itself.
  */
 function readCapped(file, limit, expected) {
     const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
@@ -203,7 +228,7 @@ function readCapped(file, limit, expected) {
                 break;
             read += n;
         }
-        return buffer.subarray(0, read);
+        return { buffer: buffer.subarray(0, read), size: opened.size };
     }
     finally {
         fs.closeSync(fd);
@@ -234,6 +259,17 @@ function describeFsError(error) {
 export function agentPromptSizeLabel(bytes) {
     return bytes < 1024 ? `${bytes} B` : `${(bytes / 1024).toFixed(1)} KB`;
 }
+export function inspectAgentPrompt(projectRoot, relPath) {
+    const result = readAgentPrompt(projectRoot, relPath);
+    return result.ok
+        ? { loaded: true, limit: AGENT_PROMPT_MAX_BYTES, bytes: result.bytes, sha: result.sha }
+        : {
+            loaded: false,
+            limit: AGENT_PROMPT_MAX_BYTES,
+            reason: result.reason,
+            ...(result.bytes === undefined ? {} : { bytes: result.bytes }),
+        };
+}
 /**
  * A configured path, safe to put in a line a person reads.
  *

package/dist/index.js

@@ -261,6 +261,16 @@ function runnerCapabilities(apiUrlOverride) {
          */
         contextRewind: true,
         contextCompaction: true,
+        /**
+         * Ticket #196: understands `session_pause`, and therefore that a pause is a
+         * STATE rather than a single interrupt.
+         *
+         * Announced because the API has to know which of the two it is talking to:
+         * a runner without this drops the frame unread, and the pause has to fall
+         * back to the old best-effort interrupt rather than silently holding
+         * nothing at all.
+         */
+        sessionPause: true,
         /**
          * Reads the project's own prompt file and hands it to the agent as
          * SYSTEM-prompt text, for both Claude and Codex.
@@ -373,6 +383,10 @@ function runnerCapabilities(apiUrlOverride) {
             'git_pull',
             'git_merge_abort',
             'recipe_state',
+            // Ticket #192: the project settings card asks whether the prompt file
+            // would load and how big it is. Announced as a command rather than as a
+            // flag, because that is the list `runCommand` actually dispatches on.
+            'agent_prompt_state',
             'propose_commit_message',
             'recall_message',
             'compact_context',

package/dist/protocol.d.ts

@@ -14,6 +14,22 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
     epoch: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
     activeMsBase: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
     extraBudgetMinutes: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodNumber>>>;
+    /**
+     * The clock the session is held under, ISO — ticket #196.
+     *
+     * Carried in the descriptor and not only in the `session_pause` frame,
+     * because a one-off frame is a fact that expires: a runner restarted or
+     * reconnected mid-pause would come back knowing nothing and resume the work
+     * the pause exists to hold. `hello_ack` re-establishes it with everything
+     * else about the session.
+     *
+     * `.catch(undefined)` like its neighbours: this field rides inside
+     * `hello_ack`, which carries EVERY session of the server, so one malformed
+     * value must cost its own session at most (QA-100 MAJOR-1). Reading a broken
+     * pause as «not paused» is also the safer of the two failures — it is the
+     * behaviour every runner had before this release.
+     */
+    pausedUntil: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
     workspace: z.ZodObject<{
         id: z.ZodString;
         path: z.ZodString;
@@ -201,6 +217,7 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
         url: string;
         token: string;
     } | undefined;
+    pausedUntil?: string | null | undefined;
     skipAgentPrompt?: boolean | undefined;
     branchHint?: string | undefined;
     branchPlan?: {
@@ -248,6 +265,7 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
     costUsd?: number | undefined;
     activeMsBase?: number | undefined;
     extraBudgetMinutes?: number | null | undefined;
+    pausedUntil?: unknown;
     skipAgentPrompt?: unknown;
     branchHint?: unknown;
     branchPlan?: unknown;
@@ -274,6 +292,22 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         epoch: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
         activeMsBase: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
         extraBudgetMinutes: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodNumber>>>;
+        /**
+         * The clock the session is held under, ISO — ticket #196.
+         *
+         * Carried in the descriptor and not only in the `session_pause` frame,
+         * because a one-off frame is a fact that expires: a runner restarted or
+         * reconnected mid-pause would come back knowing nothing and resume the work
+         * the pause exists to hold. `hello_ack` re-establishes it with everything
+         * else about the session.
+         *
+         * `.catch(undefined)` like its neighbours: this field rides inside
+         * `hello_ack`, which carries EVERY session of the server, so one malformed
+         * value must cost its own session at most (QA-100 MAJOR-1). Reading a broken
+         * pause as «not paused» is also the safer of the two failures — it is the
+         * behaviour every runner had before this release.
+         */
+        pausedUntil: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
         workspace: z.ZodObject<{
             id: z.ZodString;
             path: z.ZodString;
@@ -461,6 +495,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             url: string;
             token: string;
         } | undefined;
+        pausedUntil?: string | null | undefined;
         skipAgentPrompt?: boolean | undefined;
         branchHint?: string | undefined;
         branchPlan?: {
@@ -508,6 +543,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         costUsd?: number | undefined;
         activeMsBase?: number | undefined;
         extraBudgetMinutes?: number | null | undefined;
+        pausedUntil?: unknown;
         skipAgentPrompt?: unknown;
         branchHint?: unknown;
         branchPlan?: unknown;
@@ -555,6 +591,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             url: string;
             token: string;
         } | undefined;
+        pausedUntil?: string | null | undefined;
         skipAgentPrompt?: boolean | undefined;
         branchHint?: string | undefined;
         branchPlan?: {
@@ -608,6 +645,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         costUsd?: number | undefined;
         activeMsBase?: number | undefined;
         extraBudgetMinutes?: number | null | undefined;
+        pausedUntil?: unknown;
         skipAgentPrompt?: unknown;
         branchHint?: unknown;
         branchPlan?: unknown;
@@ -658,6 +696,22 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         epoch: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
         activeMsBase: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
         extraBudgetMinutes: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodNumber>>>;
+        /**
+         * The clock the session is held under, ISO — ticket #196.
+         *
+         * Carried in the descriptor and not only in the `session_pause` frame,
+         * because a one-off frame is a fact that expires: a runner restarted or
+         * reconnected mid-pause would come back knowing nothing and resume the work
+         * the pause exists to hold. `hello_ack` re-establishes it with everything
+         * else about the session.
+         *
+         * `.catch(undefined)` like its neighbours: this field rides inside
+         * `hello_ack`, which carries EVERY session of the server, so one malformed
+         * value must cost its own session at most (QA-100 MAJOR-1). Reading a broken
+         * pause as «not paused» is also the safer of the two failures — it is the
+         * behaviour every runner had before this release.
+         */
+        pausedUntil: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
         workspace: z.ZodObject<{
             id: z.ZodString;
             path: z.ZodString;
@@ -845,6 +899,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             url: string;
             token: string;
         } | undefined;
+        pausedUntil?: string | null | undefined;
         skipAgentPrompt?: boolean | undefined;
         branchHint?: string | undefined;
         branchPlan?: {
@@ -892,6 +947,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         costUsd?: number | undefined;
         activeMsBase?: number | undefined;
         extraBudgetMinutes?: number | null | undefined;
+        pausedUntil?: unknown;
         skipAgentPrompt?: unknown;
         branchHint?: unknown;
         branchPlan?: unknown;
@@ -937,6 +993,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             url: string;
             token: string;
         } | undefined;
+        pausedUntil?: string | null | undefined;
         skipAgentPrompt?: boolean | undefined;
         branchHint?: string | undefined;
         branchPlan?: {
@@ -987,6 +1044,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         costUsd?: number | undefined;
         activeMsBase?: number | undefined;
         extraBudgetMinutes?: number | null | undefined;
+        pausedUntil?: unknown;
         skipAgentPrompt?: unknown;
         branchHint?: unknown;
         branchPlan?: unknown;
@@ -1109,6 +1167,18 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
 }, {
     sessionId: string;
     type: "session_interrupt";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"session_pause">;
+    sessionId: z.ZodString;
+    pausedUntil: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string;
+    type: "session_pause";
+    pausedUntil: string | null;
+}, {
+    sessionId: string;
+    type: "session_pause";
+    pausedUntil: string | null;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"server_settings">;
     maxSessions: z.ZodCatch<z.ZodOptional<z.ZodNumber>>;

package/dist/protocol.js

@@ -40,6 +40,22 @@ export const SessionDescriptorSchema = z.object({
     activeMsBase: z.number().int().min(0).optional().default(0),
     // Extra minutes granted by «Продолжить», on top of the workspace budget.
     extraBudgetMinutes: z.number().int().min(0).nullable().optional().default(null),
+    /**
+     * The clock the session is held under, ISO — ticket #196.
+     *
+     * Carried in the descriptor and not only in the `session_pause` frame,
+     * because a one-off frame is a fact that expires: a runner restarted or
+     * reconnected mid-pause would come back knowing nothing and resume the work
+     * the pause exists to hold. `hello_ack` re-establishes it with everything
+     * else about the session.
+     *
+     * `.catch(undefined)` like its neighbours: this field rides inside
+     * `hello_ack`, which carries EVERY session of the server, so one malformed
+     * value must cost its own session at most (QA-100 MAJOR-1). Reading a broken
+     * pause as «not paused» is also the safer of the two failures — it is the
+     * behaviour every runner had before this release.
+     */
+    pausedUntil: z.string().max(40).nullable().optional().catch(undefined),
     workspace: z.object({
         id: z.string().uuid(),
         path: z.string(),
@@ -237,6 +253,26 @@ export const GatewayFrameSchema = z.discriminatedUnion('type', [
     }),
     z.object({ type: z.literal('session_stop'), sessionId: z.string().uuid() }),
     z.object({ type: z.literal('session_interrupt'), sessionId: z.string().uuid() }),
+    /**
+     * The session is held under a clock, or the clock is off — ticket #196.
+     *
+     * ONE frame carrying the whole state, not a pause/resume pair: two frames are
+     * two ways for a runner to end up believing something the row does not say,
+     * and `pausedUntil: null` already IS «resumed». The API's own SSE frame is
+     * built the same way and for the same reason.
+     *
+     * Until this existed a pause was a single `session_interrupt` — and an
+     * interrupt is an event, not a state. It could arrive before the turn it was
+     * meant to stop (both agents drop an interrupt with no active turn), and it
+     * said nothing about the minutes that followed: queued messages flushed,
+     * auto-resume relaunched, and a background subagent's report woke a whole new
+     * turn, all while every screen said «На паузе».
+     */
+    z.object({
+        type: z.literal('session_pause'),
+        sessionId: z.string().uuid(),
+        pausedUntil: z.string().max(40).nullable(),
+    }),
     // Server-wide settings changed mid-connection (session 8) — today just the
     // parallel-session ceiling.
     z.object({

package/dist/supervisor.d.ts

@@ -371,8 +371,41 @@ export declare class Supervisor {
      * fire and forget — a failure here is logged, and the records stay on disk.
      */
     private flushPendingMessages;
-    /** Stop the current turn without ending the session (VS-Code-style Stop). */
+    /**
+     * Stop the current turn without ending the session (VS-Code-style Stop).
+     *
+     * @param reason `'pause'` when a clock did it rather than a person. Only the
+     *   words in the feed differ — «Turn interrupted by the user» over a turn the
+     *   user did not touch is the kind of small lie that costs an hour of
+     *   debugging later.
+     * @param announce Say it in the feed. The pause watchdog passes `false`: the
+     *   line was already written when the clock landed, and one per background
+     *   turn it stops would bury the feed under a fact nobody asked about.
+     */
     private interruptSession;
+    /** Is this session held under a clock right now (ticket #196)? */
+    private static isPaused;
+    /**
+     * Set or clear the clock this session is held under (ticket #196).
+     *
+     * `null` means the pause is over. Releasing does NOT start anything by
+     * itself: the API sends the messages that were waiting through the ordinary
+     * message path, and anything this runner was holding is flushed here.
+     */
+    private applyPause;
+    /**
+     * The turn started anyway — stop it (ticket #196).
+     *
+     * The last line of defence, and the only one that can catch a turn nobody
+     * outside the agent process asked for: a background subagent's report wakes a
+     * new turn inside the CLI (gotcha #244), and an interrupted Codex turn starts
+     * the next queued one by itself. Neither passes through any frame this runner
+     * could refuse, so the only place to notice them is the events they produce.
+     *
+     * Deliberately quiet: the notice was already written when the pause landed,
+     * and one per interrupted background turn would bury the feed.
+     */
+    private stopWorkUnderPause;
     /** Live model / interaction-mode switch (persisted for the next relaunch). */
     private applySettings;
     /** Is a turn (or a question the agent is parked on) in flight right now? */

package/dist/supervisor.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { log } from './log.js';
 import { claimAutoResume, clearAutoResume, pruneAutoResume } from './auto-resume.js';
 import { evaluateRecipeCommand, maskSecrets, maskString } from './policy.js';
-import { agentPromptSizeLabel, quotePath, readAgentPrompt } from './agent-prompt.js';
+import { agentPromptSizeLabel, inspectAgentPrompt, quotePath, readAgentPrompt, } from './agent-prompt.js';
 import { JournalStore } from './journal.js';
 import { deleteSessionBranch, ensurePreviewWorktree, ensureSessionWorktree, prepareDirectWorkspace, previewWorktreePath, removePreviewWorktree, removeSessionWorktree, repoKeyFor, sessionWorktreePath, validateWorkspacePath, } from './git.js';
 import { readRecipeProposal } from './recipe.js';
@@ -220,6 +220,9 @@ export class Supervisor {
             case 'session_interrupt':
                 await this.interruptSession(frame.sessionId);
                 break;
+            case 'session_pause':
+                await this.applyPause(frame.sessionId, frame.pausedUntil);
+                break;
             case 'session_settings':
                 await this.applySettings(frame.sessionId, frame.model, frame.mode, frame.effort);
                 break;
@@ -263,6 +266,11 @@ export class Supervisor {
                 existing.stopRequested = true;
                 existing.session?.stop('session_stopped');
             }
+            // The descriptor is newer than what this session was built from, so its
+            // clock is too (QA-149 MAJOR-1). Applied on the way out of every early
+            // return, not just the reconnect one — a descriptor re-sent for any
+            // reason is the freshest thing this runner will see about the pause.
+            await this.applyPause(descriptor.id, descriptor.pausedUntil ?? null);
             return;
         }
         // Up to `maxSessions` agents at once (session 8). Sessions idling after a
@@ -301,6 +309,11 @@ export class Supervisor {
             extraBudgetMinutes: descriptor.extraBudgetMinutes,
             epoch: descriptor.epoch,
             openQuestions: new Set(),
+            // 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
+            // work straight back up.
+            ...pausedUntilOf(descriptor),
             mode: descriptor.mode,
             ...(descriptor.model ? { model: descriptor.model } : {}),
             ...(descriptor.effort ? { effort: descriptor.effort } : {}),
@@ -512,6 +525,19 @@ export class Supervisor {
             branch: running.branch,
             worktreePath: running.worktreePath,
         });
+        // Ticket #196: a Stop or a pause that arrived while this process was coming
+        // up was dropped on the floor — `interruptSession` returns early when there
+        // is no adapter yet, and the window covers preparing the worktree and
+        // hashing the whole tree for a checkpoint. The turn it was aimed at is
+        // exactly the one starting now, so it is answered here, at the first moment
+        // there is something to answer it with.
+        if (running.interruptWhenReady || Supervisor.isPaused(running)) {
+            delete running.interruptWhenReady;
+            void this.interruptSession(descriptor.id, Supervisor.isPaused(running) ? 'pause' : 'user').catch((error) => log.warn('supervisor: could not honour an interrupt requested during startup', {
+                sessionId: descriptor.id,
+                error: String(error),
+            }));
+        }
         void this.pumpEvents(running);
         return true;
     }
@@ -959,6 +985,9 @@ export class Supervisor {
         for (const waiting of this.sessions.values()) {
             if (waiting.session || waiting.stopRequested || waiting.budgetSpent)
                 continue;
+            // A freed slot is not a reason to start work somebody put on hold (#196).
+            if (Supervisor.isPaused(waiting))
+                continue;
             if (waiting.pendingMessages.length === 0 || !waiting.worktreePath)
                 continue;
             if (this.liveSessionCount(waiting.descriptor.id) >= this.maxSessions)
@@ -1125,8 +1154,19 @@ export class Supervisor {
         // Anything below that is the agent talking means the agent is working. Read
         // before the switch so every such case gets it, including the ones added
         // after this line was written.
-        if (event.type === 'message' ? event.role === 'assistant' : AGENT_OUTPUT_EVENTS.has(event.type))
-            this.noteAgentIsWorking(running);
+        if (event.type === 'message' ? event.role === 'assistant' : AGENT_OUTPUT_EVENTS.has(event.type)) {
+            // Ticket #196. The same signal, read twice for opposite reasons: when the
+            // session is free it proves the agent is working (#185), and when the
+            // session is held under a clock it proves something started that should
+            // not have. The second is the ONLY way to catch a turn nobody outside the
+            // agent process asked for — a background subagent's report (gotcha #244)
+            // and Codex's own «interrupted, so start the next queued turn» both come
+            // through no frame this runner could refuse.
+            if (Supervisor.isPaused(running))
+                this.stopWorkUnderPause(running);
+            else
+                this.noteAgentIsWorking(running);
+        }
         switch (event.type) {
             case 'provider_session': {
                 running.descriptor = { ...descriptor, providerSessionId: event.providerSessionId };
@@ -1495,10 +1535,16 @@ export class Supervisor {
             ...(attachments?.length ? { attachments } : {}),
         });
         const originSeq = echoed.seq;
-        if (!running.worktreePath) {
+        if (!running.worktreePath || Supervisor.isPaused(running)) {
             // Session is still being prepared — deliver after launch (QA-96 F3).
             // Attachments travel as metadata and are downloaded at delivery time,
             // which is the first moment the worktree is guaranteed to exist.
+            //
+            // Or the session is held under a clock (#196). The API refuses live
+            // messages for a paused session, but not every path goes through that
+            // check — the outbox flushes on reconnect, and the git service posts its
+            // 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;
         }
@@ -1780,6 +1826,11 @@ export class Supervisor {
      * fire and forget — a failure here is logged, and the records stay on disk.
      */
     flushPendingMessages(running) {
+        // Ticket #196: six places call this — a launch, a mode relaunch, a freed
+        // slot, a delivery, and twice on reconnect — and none of them knew about a
+        // pause. Held work stays held until the clock is off.
+        if (Supervisor.isPaused(running))
+            return;
         const pending = running.pendingMessages.splice(0);
         if (pending.length === 0)
             return;
@@ -1816,11 +1867,29 @@ export class Supervisor {
             this.deliverMessage(running, parts.join('\n\n'), pending);
         });
     }
-    /** Stop the current turn without ending the session (VS-Code-style Stop). */
-    async interruptSession(sessionId) {
+    /**
+     * Stop the current turn without ending the session (VS-Code-style Stop).
+     *
+     * @param reason `'pause'` when a clock did it rather than a person. Only the
+     *   words in the feed differ — «Turn interrupted by the user» over a turn the
+     *   user did not touch is the kind of small lie that costs an hour of
+     *   debugging later.
+     * @param announce Say it in the feed. The pause watchdog passes `false`: the
+     *   line was already written when the clock landed, and one per background
+     *   turn it stops would bury the feed under a fact nobody asked about.
+     */
+    async interruptSession(sessionId, reason = 'user', announce = true) {
         const running = this.sessions.get(sessionId);
-        if (!running?.session)
+        if (!running)
+            return;
+        if (!running.session) {
+            // The process is still coming up. Remembered rather than dropped: the
+            // launch honours this the moment the adapter exists, so a Stop or a pause
+            // pressed during startup stops the turn it was aimed at instead of
+            // vanishing (#196).
+            running.interruptWhenReady = true;
             return;
+        }
         // The turn being interrupted is the turn the question belongs to — leaving
         // the ask parked would make the user's next message be swallowed as its
         // answer (QA-106 m7). The adapter reports each withdrawal itself; the local
@@ -1828,13 +1897,98 @@ export class Supervisor {
         running.session.cancelQuestions('turn_aborted');
         running.openQuestions.clear();
         await running.session.interrupt();
-        this.sendEvent(running, 'notice', { level: 'info', text: 'Turn interrupted by the user' });
+        if (announce) {
+            this.sendEvent(running, 'notice', {
+                level: 'info',
+                text: reason === 'pause'
+                    ? 'Paused — the turn was stopped. Nothing else will start until the clock runs out.'
+                    : 'Turn interrupted by the user',
+            });
+        }
         const next = running.descriptor.kind === 'CHAT' ? 'WAITING_INPUT' : 'REVIEW';
         this.reportStatus(sessionId, next, {
             costUsd: running.costUsd,
             activeMs: Supervisor.spentMs(running),
         });
     }
+    /** Is this session held under a clock right now (ticket #196)? */
+    static isPaused(running) {
+        return running.pausedUntil !== undefined && running.pausedUntil > Date.now();
+    }
+    /**
+     * Set or clear the clock this session is held under (ticket #196).
+     *
+     * `null` means the pause is over. Releasing does NOT start anything by
+     * itself: the API sends the messages that were waiting through the ordinary
+     * message path, and anything this runner was holding is flushed here.
+     */
+    async applyPause(sessionId, pausedUntil) {
+        const running = this.sessions.get(sessionId);
+        if (!running)
+            return;
+        const until = pausedUntil ? Date.parse(pausedUntil) : Number.NaN;
+        if (Number.isFinite(until) && until > Date.now()) {
+            const first = !Supervisor.isPaused(running);
+            running.pausedUntil = until;
+            // Interrupting on every pause frame, not only the first: the frame is
+            // also how a MOVED pause arrives, and a turn that slipped through in
+            // between has to be stopped too. `interruptSession` is idempotent — an
+            // adapter with nothing to interrupt does nothing.
+            if (first || running.lastReported === 'RUNNING' || running.lastReported === 'STARTING') {
+                await this.interruptSession(sessionId, 'pause');
+            }
+            return;
+        }
+        if (running.pausedUntil === undefined)
+            return; // already free
+        delete running.pausedUntil;
+        // Both of these belong to the clock and must go with it (QA-149 MINOR-1).
+        // A pause set while the process was still coming up and cancelled a second
+        // later used to leave `interruptWhenReady` standing — and the launch then
+        // killed the session's first turn and signed it «Turn interrupted by the
+        // user», over a turn the user never touched. Exactly the lie #196 removed.
+        delete running.interruptWhenReady;
+        delete running.pauseInterruptAt;
+        // Whatever was held while the clock ran goes now, in the order it arrived.
+        this.flushPendingMessages(running);
+    }
+    /**
+     * The turn started anyway — stop it (ticket #196).
+     *
+     * The last line of defence, and the only one that can catch a turn nobody
+     * outside the agent process asked for: a background subagent's report wakes a
+     * new turn inside the CLI (gotcha #244), and an interrupted Codex turn starts
+     * the next queued one by itself. Neither passes through any frame this runner
+     * could refuse, so the only place to notice them is the events they produce.
+     *
+     * Deliberately quiet: the notice was already written when the pause landed,
+     * and one per interrupted background turn would bury the feed.
+     */
+    stopWorkUnderPause(running) {
+        if (!Supervisor.isPaused(running) || !running.session)
+            return;
+        // One interrupt per burst, not per event. An abort is not instant: a turn
+        // being stopped still emits whatever was already in flight, and without
+        // this every one of those lines would fire another `interrupt()` — a
+        // hundred round trips into the CLI to stop something that is already
+        // stopping. Two seconds is far shorter than the gap before a genuinely NEW
+        // turn (a background subagent finishing), which still gets its own.
+        const now = Date.now();
+        if (running.pauseInterruptAt !== undefined && now - running.pauseInterruptAt < 2_000)
+            return;
+        running.pauseInterruptAt = now;
+        // Through the ordinary path rather than straight at the adapter (QA-149
+        // MAJOR-2): it also withdraws the cards this turn had opened. A turn killed
+        // with a question still parked leaves the person's next message to be
+        // swallowed as an answer to it — the QA-106 m7 trap, which the main
+        // interrupt path has guarded against since it was found.
+        void this.interruptSession(running.descriptor.id, 'pause', false).catch((error) => {
+            log.warn('supervisor: could not stop a turn that started under a pause', {
+                sessionId: running.descriptor.id,
+                error: String(error),
+            });
+        });
+    }
     /** Live model / interaction-mode switch (persisted for the next relaunch). */
     async applySettings(sessionId, model, mode, effort) {
         const running = this.sessions.get(sessionId);
@@ -2026,6 +2180,19 @@ export class Supervisor {
                     tracked.epoch = descriptor.epoch;
                     tracked.descriptor = { ...tracked.descriptor, epoch: descriptor.epoch };
                 }
+                // Ticket #196, QA-149 MAJOR-1. The pause is re-established HERE, and
+                // this is the case that matters most: a dropped socket leaves the agent
+                // process running, so «reconnect» is precisely when a session is
+                // `tracked`. The first cut of #196 read `pausedUntil` only in the two
+                // constructors of a NEW `RunningSession`, which meant it survived a
+                // runner RESTART and not a reconnect — and a pause set while the socket
+                // was down never arrived at all, because `session_pause` is
+                // fire-and-forget with no outbox behind it.
+                //
+                // Both directions matter: the row may have gained a clock (hold now) or
+                // lost one (release and send what was held). `applyPause` does both, and
+                // it runs BEFORE `flushSessionOutbox` arrives from the API side.
+                await this.applyPause(descriptor.id, descriptor.pausedUntil ?? null);
                 this.reportStatus(descriptor.id, statusForReport(tracked), {
                     costUsd: tracked.costUsd,
                     ...(tracked.branch ? { branch: tracked.branch } : {}),
@@ -2091,6 +2258,7 @@ export class Supervisor {
                     extraBudgetMinutes: descriptor.extraBudgetMinutes,
                     epoch: descriptor.epoch,
                     openQuestions: new Set(),
+                    ...pausedUntilOf(descriptor),
                     mode: descriptor.mode,
                     ...(descriptor.model ? { model: descriptor.model } : {}),
                     ...(descriptor.effort ? { effort: descriptor.effort } : {}),
@@ -2135,7 +2303,15 @@ export class Supervisor {
                 // middle of" — would be addressed to an agent that remembers none of
                 // it. A process killed before it reported its session id (the SIGABRT
                 // this ticket came from) leaves the row in exactly that state.
-                const willContinue = wasMidTurn && Boolean(resumeId) && claimAutoResume(descriptor.id);
+                // Ticket #196: a paused session is never continued automatically. The
+                // row still says RUNNING — a pause interrupts the turn but is not a
+                // status — so without this the reconnect would read «mid-turn» and
+                // relaunch the agent with «continue from where you stopped», which is
+                // the exact opposite of what the clock was set for.
+                const willContinue = wasMidTurn &&
+                    !Supervisor.isPaused(running) &&
+                    Boolean(resumeId) &&
+                    claimAutoResume(descriptor.id);
                 // The note stays either way (owner's call): an interruption is a fact
                 // about the session and must not disappear just because we recovered
                 // from it. Only the instruction at the end changes — telling someone to
@@ -2918,6 +3094,28 @@ export class Supervisor {
                         this.opts.onRestartRequested?.(outcome);
                     return;
                 }
+                /**
+                 * «Would this file reach the agent, and how big is it» (ticket #192).
+                 *
+                 * The settings card asks before a session exists, so the answer has to
+                 * come from the machine that would do the reading: the file is on this
+                 * disk, and the ceiling belongs to THIS build of the runner. A dashboard
+                 * carrying its own copy of either would be a screen that can be a
+                 * version wrong about a rule it is stating.
+                 *
+                 * Answers `ok: true` even when the file would be refused — «too large»
+                 * is an answer about the file, not a failure of the command, and the
+                 * card has to be able to draw it.
+                 */
+                case 'agent_prompt_state': {
+                    const root = str(frame.args?.['root']) ?? str(frame.args?.['workspacePath']);
+                    if (!root)
+                        return void reply({ ok: false, error: 'workspacePath is required' });
+                    const path = str(frame.args?.['path']);
+                    if (!path)
+                        return void reply({ ok: false, error: 'path argument is required' });
+                    return void reply({ ok: true, result: inspectAgentPrompt(root, path) });
+                }
                 // ─── Session 14: the project recipe ──────────────────────────
                 //
                 // Read-only, always available even when verification is switched off:
@@ -3297,6 +3495,20 @@ export class Supervisor {
         this.verify.shutdown();
     }
 }
+/**
+ * The pause carried by a descriptor, as a field that can be spread (#196).
+ *
+ * A clock already in the past is read as no clock at all: the API clears it on
+ * release, but a runner that was down when the release happened would otherwise
+ * hold the session for ever on a number nobody is going to update.
+ */
+function pausedUntilOf(descriptor) {
+    const raw = descriptor.pausedUntil;
+    if (!raw)
+        return {};
+    const until = Date.parse(raw);
+    return Number.isFinite(until) && until > Date.now() ? { pausedUntil: until } : {};
+}
 function str(value) {
     return typeof value === 'string' && value ? value : null;
 }

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const RUNNER_VERSION = "0.35.0";
+export declare const RUNNER_VERSION = "0.36.0";
 //# 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.35.0';
+export const RUNNER_VERSION = '0.36.0';
 //# sourceMappingURL=version.js.map

package/package.json

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