@aragon-agent/cli 0.6.29 → 0.6.32

package/dist/agent/controller.d.ts

@@ -246,6 +246,31 @@ export declare class AgentController {
     /** Session changes must not make a delayed receipt match a new message. */
     private readonly steeringPrefix;
     private steeringSequence;
+    /**
+     * OPEN TOOL CALLS IN THIS BATCH (long-task-jobs D-5).
+     *
+     * COUNTED HERE, NOT BORROWED FROM `FastWiring`'s `TurnFrameRing`: `fast` can be
+     * switched off entirely, and a completion notice must not go quiet with it. The
+     * cost is a second counter over the same two events, which AC-19 pins with a
+     * replay rather than with trust.
+     */
+    private activeToolCalls;
+    /** The completion-notice queue both the push and the pull channel take from. */
+    private readonly jobNotices;
+    /** The optional on-disk log mirror; `undefined` when `jobs.persistLog` is false. */
+    private jobMirror;
+    /** The relay: terminal events in, ledger across `steering_accepted`, safe-point push. */
+    private jobRelay;
+    /** `cfg.jobs.enabled` AND `cfg.bash.background`, fixed at construction. */
+    private jobsRegistered;
+    /**
+     * One mirror directory per PROCESS.
+     *
+     * The logs are a debugging aid, not a record with an identity: two sessions
+     * writing to one directory would interleave the tails of two different runs, and
+     * the retention sweep in `log-mirror.ts` keeps the newest few directories.
+     */
+    private readonly jobSessionTag;
     constructor(config: CliConfig, deps?: ControllerDeps);
     private resolveKey;
     /**
@@ -308,6 +333,16 @@ export declare class AgentController {
     private waitForEngineIdle;
     /** Prepare before clearing the plan, then enter the engine without yielding. */
     private startPrompt;
+    /**
+     * Deliver undelivered job notices, if any and if it is safe to steer.
+     *
+     * ONE METHOD, TWO CALL SITES, AND NOT INSIDE `prepareUserTurn` (RV-P1-7).
+     * `prepareUserTurn` is called from `startPrompt` AND from `continue` (with the
+     * CONCATENATED queued text), and it does three specific things for the engine's
+     * benefit. Hanging a delivery path off it would make `fast.setGoal`'s input
+     * semantics depend on whether a notice happened to be pending.
+     */
+    private flushPendingNotices;
     private prepareUserTurn;
     /** Cancel pending startup as well as any engine run already in progress. */
     abort(): void;
@@ -403,6 +438,17 @@ export declare class AgentController {
     hasPendingUserMessages(): boolean;
     private compactionBusyOutcome;
     isRunning(): boolean;
+    /**
+     * The one condition under which automated text may be injected (I-5).
+     *
+     * `activeToolCalls === 0` is the whole safety argument: `steer()` has exactly
+     * one safe checkpoint - the top of the loop, before the LLM call - so injecting
+     * text in the middle of a tool batch replaces the remaining `tool_use` blocks
+     * with "skipped due to steering interrupt" and the next request is malformed.
+     */
+    private isAtSafeSteerPoint;
+    /** How many completion notices are waiting for the model. */
+    pendingJobNotices(): number;
     getAgentMode(): AgentMode;
     /**
      * Request a mode change and return what was ACTUALLY ADOPTED.

package/dist/agent/controller.js

@@ -1,5 +1,6 @@
 import { createModelSettingsDraft, saveModelSettings, reloadModelSettings, } from './model-profile-settings.js';
 import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
 import { verifyCompactionIdentity } from '../compaction/memory-identity.js';
 import { COMPACTION_LIMITS } from '../compaction/limits.js';
 import { Agent, initProviders, ModelRegistry, } from '@aragon-agent/core';
@@ -20,9 +21,14 @@ import { resolveSubagentModel } from '../team/model.js';
 import { buildTeamBlock } from '../team/prompt.js';
 import { buildFastBlock } from '../fast/prompt.js';
 import { ProcSupervisor } from '../proc/supervisor.js';
-import { buildBackgroundServicesBlock } from '../proc/prompt.js';
+import { buildBackgroundJobsBlock, buildBackgroundServicesBlock } from '../proc/prompt.js';
 import { PROC_LIMITS } from '../proc/limits.js';
+import { JobLogMirror } from '../proc/log-mirror.js';
+import { JobNoticeQueue } from '../proc/notices.js';
 import { makeBashKill, makeBashOutput } from '../tools/proc-tools.js';
+import { makeJobList, makeJobWait } from '../tools/job-tools.js';
+import { JobNoticeRelay } from './job-notices.js';
+import { getHomeRoot } from '../config/app-paths.js';
 import { addSignalHook } from '../logging/install.js';
 import { describeFastTierProblem, fastProviderOf, resolveFastTier } from '../fast/resolve.js';
 import { FastWiring, offFastStatus } from '../fast/wiring.js';
@@ -271,6 +277,31 @@ export class AgentController {
     /** Session changes must not make a delayed receipt match a new message. */
     steeringPrefix = randomUUID();
     steeringSequence = 0;
+    /**
+     * OPEN TOOL CALLS IN THIS BATCH (long-task-jobs D-5).
+     *
+     * COUNTED HERE, NOT BORROWED FROM `FastWiring`'s `TurnFrameRing`: `fast` can be
+     * switched off entirely, and a completion notice must not go quiet with it. The
+     * cost is a second counter over the same two events, which AC-19 pins with a
+     * replay rather than with trust.
+     */
+    activeToolCalls = 0;
+    /** The completion-notice queue both the push and the pull channel take from. */
+    jobNotices = new JobNoticeQueue();
+    /** The optional on-disk log mirror; `undefined` when `jobs.persistLog` is false. */
+    jobMirror;
+    /** The relay: terminal events in, ledger across `steering_accepted`, safe-point push. */
+    jobRelay;
+    /** `cfg.jobs.enabled` AND `cfg.bash.background`, fixed at construction. */
+    jobsRegistered = false;
+    /**
+     * One mirror directory per PROCESS.
+     *
+     * The logs are a debugging aid, not a record with an identity: two sessions
+     * writing to one directory would interleave the tails of two different runs, and
+     * the retention sweep in `log-mirror.ts` keeps the newest few directories.
+     */
+    jobSessionTag = Date.now().toString(36);
     constructor(config, deps = {}) {
         this.config = config;
         this.cwd = config.cwd;
@@ -411,7 +442,22 @@ export class AgentController {
         // comment. `readyTimeoutMs` is read through a closure rather than captured,
         // so a live config change reaches the next service rather than the next
         // launch of the CLI.
-        this.procs = new ProcSupervisor({ readyTimeoutMs: () => this.config.bash.readyTimeoutMs });
+        // `jobs` is the FIRST section whose registration depends on two keys: the
+        // tools need a supervisor to talk to (`bash.background`) and their own switch.
+        // With either off, no `job_*` tool, no prompt block, no mirror - which is what
+        // makes I-3 (byte-identical when off) measurable rather than asserted.
+        this.jobsRegistered = config.jobs.enabled && config.bash.background;
+        this.jobMirror =
+            this.jobsRegistered && config.jobs.persistLog
+                ? new JobLogMirror({ root: () => join(getHomeRoot(), 'jobs', this.jobSessionTag) })
+                : undefined;
+        this.procs = new ProcSupervisor({
+            readyTimeoutMs: () => this.config.bash.readyTimeoutMs,
+            // Live closures, not captured values: a `config set` must reach the card of
+            // the job already running.
+            stallMs: () => this.config.jobs.stallSeconds * 1000,
+            ...(this.jobMirror ? { mirror: this.jobMirror } : {}),
+        });
         this.notifyHostFn = deps.notify;
         this.bashBackgroundRegistered = config.bash.background;
         // THE EXIT REAPER (G5 / P1-2 / R-10). An APPEND-ONLY hook rather than a
@@ -420,6 +466,22 @@ export class AgentController {
         // that leaves the user staring at a blank alternate screen. `reapSync` is
         // the only entry point it calls, and it is synchronous end to end (I-9).
         this.releaseSignalHook = addSignalHook(() => this.procs.reapSync());
+        // THE RELAY IS BUILT HERE, BEFORE THE TOOLS, because the tools take its
+        // `drain` as the PULL port and the supervisor's stream as their source. Its
+        // `steer` is the same receipt-less path `FastWiring` already uses, and its
+        // safe-point test is this class's own batch counter (D-5).
+        this.jobRelay = new JobNoticeRelay({
+            queue: this.jobNotices,
+            steer: (text) => this.enqueueSteering(text, false),
+            isAtSafeSteerPoint: () => this.isAtSafeSteerPoint(),
+            // The FILL channel precondition: no tool batch open, nothing being aborted -
+            // and deliberately no isRunning(), because this path runs just BEFORE
+            // agent.prompt() / agent.continue(), where the engine is idle by contract.
+            // The dep documents why that one missing clause is the whole difference.
+            canSteerBeforeTurn: () => this.activeToolCalls === 0 && !this.abortRequested,
+            steerEnabled: () => this.config.jobs.noticeSteer,
+        });
+        this.jobRelay.attach((listener) => this.procs.subscribe(listener));
         this.tools = createBuiltinTools({
             getCwd: () => this.cwd,
             // OWNED HERE, NOT IN `cli.tsx` (D-18): `createBuiltinTools` is called from
@@ -503,6 +565,35 @@ export class AgentController {
             procTools: this.bashBackgroundRegistered
                 ? [makeBashOutput({ supervisor: this.procs }), makeBashKill({ supervisor: this.procs })]
                 : [],
+            // THROUGH THE FACTORY for the reason above, and GATED ON BOTH KEYS:
+            // `job_wait` with no supervisor to read is a tool that can only say "no
+            // jobs", and `jobs.enabled: false` must leave the array byte-identical to
+            // the baseline (I-3).
+            jobTools: this.jobsRegistered
+                ? [
+                    makeJobWait({
+                        supervisor: this.procs,
+                        waitSeconds: () => this.config.jobs.waitSeconds,
+                        stallSeconds: () => this.config.jobs.stallSeconds,
+                        toolTimeoutMs: () => this.config.toolTimeoutMs,
+                        maxConsecutiveWaits: PROC_LIMITS.maxConsecutiveWaits,
+                        terminalRecord: (id) => this.jobRelay?.terminalRecord(id),
+                    }),
+                    makeJobList({
+                        supervisor: this.procs,
+                        waitSeconds: () => this.config.jobs.waitSeconds,
+                        stallSeconds: () => this.config.jobs.stallSeconds,
+                        toolTimeoutMs: () => this.config.toolTimeoutMs,
+                        maxConsecutiveWaits: PROC_LIMITS.maxConsecutiveWaits,
+                        terminalRecord: (id) => this.jobRelay?.terminalRecord(id),
+                    }),
+                ]
+                : [],
+            // The PULL port. Absent when jobs are off, which leaves every tool object
+            // untouched and provable by identity.
+            ...(this.jobsRegistered
+                ? { jobNotices: { drain: () => this.jobRelay?.drainForTail() ?? [] } }
+                : {}),
             // THROUGH THE FACTORY, NEVER APPENDED AFTERWARDS (D-15 / P0-1).
             // `tools.test.ts::C7` asserts `HOST_TOOL_NAMES` equals what
             // `createBuiltinTools` produces, so appending `task` here would turn that
@@ -720,13 +811,32 @@ export class AgentController {
             if (event.type === 'steering_accepted') {
                 for (const id of event.ids)
                     this.pendingUserSteering.delete(id);
+                // A receipt means Core took a batch out of the queue, which is the only
+                // proof a steered notice has that it was not discarded (§4.6.1).
+                this.jobRelay?.onSteeringAccepted();
             }
-            // The authoritative result arrives with this event, so from this instant
-            // the tail is superseded and its slot must be released (§3.1.1). Clearing
-            // HERE rather than on read is what keeps the store's size a function of
-            // CONCURRENT calls instead of total calls.
+            // THE BATCH COUNTER (D-5 / I-5). Decremented BEFORE the push attempt below,
+            // because "the batch is empty" is only true after the last one has ended.
+            if (event.type === 'tool_execution_start')
+                this.activeToolCalls += 1;
             if (event.type === 'tool_execution_end') {
-                this.toolOutputs?.clear('lead', event.toolCallId);
+                this.activeToolCalls = Math.max(0, this.activeToolCalls - 1);
+                // THE ONE PUSH SITE. A notice that could not be pushed here is picked up
+                // by the next tool result (the pull channel) or by the next user turn
+                // (the fill channel), so nothing is lost by declining.
+                this.jobRelay?.tryPush();
+            }
+            if (event.type === 'turn_start') {
+                // A new turn's first checkpoint is a safe point, and anything still
+                // steered-but-unproven must go back in the queue first: `fast`'s
+                // `recoverStranded()` may have wiped it at the end of the last run.
+                this.jobRelay?.requeueUndelivered();
+            }
+            if (event.type === 'agent_end') {
+                // The same reconciliation at the other end of a run. Both ends are
+                // required: `turn_start` covers the next turn of the same run, and this
+                // covers a run that ended with a notice stranded in the queue.
+                this.jobRelay?.requeueUndelivered();
             }
         });
         if (this.fast) {
@@ -818,6 +928,11 @@ export class AgentController {
             // `todo.enabled` rule). So the block is present exactly when the tools are,
             // and can never advertise a capability the model does not have.
             backgroundBlock: this.bashBackgroundRegistered ? buildBackgroundServicesBlock() : '',
+            // ONE FLAG, like `backgroundBlock` and for the same reason: `jobs.enabled`
+            // is read once at construction, so the block is present exactly when the
+            // tools that make its promises achievable are registered. With the flag off
+            // the prompt is byte-identical to the pre-feature text (I-3).
+            jobsBlock: this.jobsRegistered ? buildBackgroundJobsBlock() : '',
             // Read from the FIELD on every rebuild, for the reason the field's own
             // comment gives. Empty everywhere but `aragon exec`, and `buildSystemPrompt`
             // splices it conditionally, so every existing prompt is byte-identical.
@@ -977,9 +1092,30 @@ export class AgentController {
             return { status: 'not-started', reason: 'cancelled' };
         }
         this.todos?.beginUserTurn(options.todoPolicy);
+        // BEFORE the engine is entered, so the loop's first checkpoint (the top of
+        // the loop, before any LLM call) merges them into history. Anything left over
+        // from the previous run - a notice `fast` wiped, or one the model never saw
+        // because it answered and stopped - is delivered here (RV-P1-7).
+        this.flushPendingNotices();
         await this.agent.prompt(text);
         return { status: 'finished' };
     }
+    /**
+     * Deliver undelivered job notices, if any and if it is safe to steer.
+     *
+     * ONE METHOD, TWO CALL SITES, AND NOT INSIDE `prepareUserTurn` (RV-P1-7).
+     * `prepareUserTurn` is called from `startPrompt` AND from `continue` (with the
+     * CONCATENATED queued text), and it does three specific things for the engine's
+     * benefit. Hanging a delivery path off it would make `fast.setGoal`'s input
+     * semantics depend on whether a notice happened to be pending.
+     */
+    flushPendingNotices() {
+        // FLUSH, NOT PUSH. The push channel requires `isRunning()`, and the engine is
+        // idle on this path by contract - reusing it here would leave every stranded
+        // notice waiting for a tool batch that may never come, which is exactly the
+        // failure AC-25 exists to prevent.
+        this.jobRelay?.flushForTurn();
+    }
     prepareUserTurn(text) {
         if (this.skillsEnabled)
             this.skills.beginUserTurn();
@@ -1167,6 +1303,10 @@ export class AgentController {
             }
             this.todos?.beginUserTurn('new-task');
         }
+        // The `continue()` path needs its own delivery for the reason RV-P1-7 gives:
+        // a run that ended with a notice still queued resumes through here, and this
+        // is the most common way a stranded notice gets its second chance.
+        this.flushPendingNotices();
         await this.agent.continue();
         return { status: 'finished' };
     }
@@ -1179,6 +1319,21 @@ export class AgentController {
     isRunning() {
         return this.agent.state.isRunning;
     }
+    /**
+     * The one condition under which automated text may be injected (I-5).
+     *
+     * `activeToolCalls === 0` is the whole safety argument: `steer()` has exactly
+     * one safe checkpoint - the top of the loop, before the LLM call - so injecting
+     * text in the middle of a tool batch replaces the remaining `tool_use` blocks
+     * with "skipped due to steering interrupt" and the next request is malformed.
+     */
+    isAtSafeSteerPoint() {
+        return this.activeToolCalls === 0 && this.isRunning() && !this.abortRequested;
+    }
+    /** How many completion notices are waiting for the model. */
+    pendingJobNotices() {
+        return this.jobNotices.pending();
+    }
     // -----------------------------------------------------------------------
     // Plan mode (§3.1 / §3.2)
     // -----------------------------------------------------------------------
@@ -1373,6 +1528,12 @@ export class AgentController {
         this.procs.reapSync();
         this.releaseSignalHook();
         this.procs.dispose();
+        // THE MIRROR FLUSHES BEFORE THE RELAY DETACHES: whatever the last job wrote is
+        // already on disk in the ring, and the file is the only copy that survives
+        // this process.
+        this.jobRelay?.detach();
+        this.jobMirror?.dispose();
+        this.jobNotices.clear();
     }
     // -----------------------------------------------------------------------
     // Todo planning (todo-plan-execution §3.6a)
@@ -1840,6 +2001,13 @@ export class AgentController {
     clearAllQueues() {
         this.agent.clearAllQueues();
         this.pendingUserSteering.clear();
+        // A WIPE OF THE STEERING QUEUE MUST NOT TAKE A NOTICE WITH IT (I-11).
+        // `fast/reviewer.ts` clears this queue when `userSteerCount() === 0`, on the
+        // stated premise that `AgentController.steer()` is the only other writer - and
+        // a steered job notice is invisible to that counter because it carries no
+        // receipt id. Anything still unproven goes straight back into the notice
+        // queue, so the wipe costs a delay instead of a fact the model never learns.
+        this.jobRelay?.requeueUndelivered();
     }
     // -----------------------------------------------------------------------
     // Model / provider info

package/dist/agent/job-notices.d.ts

@@ -0,0 +1,143 @@
+/**
+ * JobNoticeRelay — the controller-side owner of "a job finished, and the model
+ * has to be told exactly once" (long-task-jobs §4.6 / §4.6.1).
+ *
+ * ASCII ONLY: `src/agent/**` is inside the glyph scanner's scope.
+ *
+ * THREE CHANNELS, ONE QUEUE, AND A LEDGER. The queue guarantees "at most once"
+ * because every channel takes from it with `drain()`. That alone is NOT enough,
+ * and this file exists because of the exception: Core's steering queue has a
+ * fourth consumer that DESTROYS rather than drains.
+ *
+ *   `fast/reviewer.ts` calls `clearAllQueues()` when `userSteerCount() === 0`,
+ *   and its stated safety argument is "`AgentController.steer()` is the only
+ *   other writer in the package". A job notice queued through
+ *   `enqueueSteering(text, false)` returns no receipt id, never enters
+ *   `pendingUserSteering`, and is therefore INVISIBLE to that counter. With
+ *   `fast` on, the last notice of a run could be wiped with no log line, no UI
+ *   change and no failing test.
+ *
+ * THE FIX IS A LEDGER, NOT A COUPLING. A notice that has been steered is held in
+ * `pendingSteered` until a `steering_accepted` receipt proves the queue was
+ * drained; anything still held at `turn_start` or at the end of a run is pushed
+ * back into the queue. `JobNoticeQueue.push` is idempotent by id, so a re-queue
+ * can only ever cause a DELAY, never a duplicate.
+ *
+ * NOTHING HERE IS PUSHED WHILE A TOOL BATCH IS OPEN. The controller owns the
+ * batch count and calls `tryPush()` only from the one safe point; this class
+ * re-checks the same condition so a future call site cannot forget it (I-5).
+ */
+import { type JobNotice, type JobNoticeQueue } from '../proc/notices.js';
+import { type JobKind, type ProcEvent, type ServiceStatus } from '../proc/types.js';
+export interface JobNoticeRelayDeps {
+    queue: JobNoticeQueue;
+    /** `enqueueSteering(text, false)` - the existing receipt-less path (§4.6). */
+    steer: (text: string) => void;
+    /** `activeToolCalls === 0 && isRunning() && !abortRequested` (I-5). */
+    isAtSafeSteerPoint: () => boolean;
+    /**
+     * `activeToolCalls === 0 && !abortRequested` - the FILL channel's precondition.
+     *
+     * DELIBERATELY NOT `isAtSafeSteerPoint()`, and the difference is one clause.
+     * The fill channel runs immediately BEFORE `agent.prompt()` / `agent.continue()`,
+     * where `isRunning()` is FALSE by contract (Core throws
+     * `Agent is already running` if it were true), so reusing the push predicate
+     * would make this channel dead - every stranded notice would wait for the next
+     * tool batch instead of going out with the user's message.
+     *
+     * What I-5 protects is "never inject text while a tool batch is open", and
+     * `activeToolCalls === 0` is exactly that clause; the `isRunning()` half of the
+     * push predicate exists for a different reason (a push is worthless if no run
+     * will ever drain it). Steering just before a run starts is the case the
+     * `steering_accepted` receipt was designed for: the loop's first checkpoint is
+     * the top of the loop, before any `tool_use` exists, so the text is merged into
+     * history structurally safely.
+     */
+    canSteerBeforeTurn: () => boolean;
+    /** `cfg.jobs.noticeSteer`, read LIVE: `false` disables the PUSH channel only. */
+    steerEnabled: () => boolean;
+}
+/** A terminal id this session has already reported (RV-P2-7's third state). */
+interface RecalledJob {
+    kind: JobKind;
+    status: ServiceStatus;
+}
+export declare class JobNoticeRelay {
+    private readonly deps;
+    /**
+     * Notices that have been steered but not yet proven delivered, keyed by
+     * `${id}:${status}:${at}` - the same identity `JobNoticeQueue` uses.
+     */
+    private readonly pendingSteered;
+    /**
+     * Terminal ids this session has seen, so `job_wait` can answer "it finished and
+     * was reclaimed, do not re-run it" instead of "no such job".
+     *
+     * Bounded by `maxNotices`, oldest out: it answers a question about the recent
+     * past, and an unbounded map in a long session is a leak with a helpful name.
+     */
+    private readonly recalled;
+    private unsubscribe;
+    constructor(deps: JobNoticeRelayDeps);
+    /** Subscribe to the supervisor's stream. Returns the release function. */
+    attach(subscribe: (listener: (event: ProcEvent) => void) => () => void): void;
+    detach(): void;
+    /** Terminal ids this session has already reported, for `job_wait`'s message. */
+    terminalRecord(id: string): RecalledJob | undefined;
+    /**
+     * Move everything queued into the steering queue, if this is a safe moment.
+     *
+     * Returns whether anything was pushed. Called from exactly one place in the
+     * controller - the `tool_execution_end` listener, after the batch count reaches
+     * zero.
+     */
+    tryPush(): boolean;
+    /**
+     * Deliver the queue just BEFORE a run starts (the FILL channel, §4.6).
+     *
+     * TWO DIFFERENCES FROM `tryPush()`, both deliberate:
+     *
+     *  - the precondition is `canSteerBeforeTurn()` (no `isRunning()` term), because
+     *    this runs before `agent.prompt()` / `agent.continue()`, where the engine is
+     *    not running yet - see the dep's own comment;
+     *  - `noticeSteer` does NOT gate it. That key switches the PUSH channel only
+     *    ("noticeSteer=false is not a notification off switch", §6.5), so a user who
+     *    declines mid-turn interruptions must still learn that the job finished
+     *    before their next message is sent.
+     */
+    flushForTurn(): boolean;
+    /** The shared half: take the queue, record the ledger, steer one block. */
+    private steerQueued;
+    /**
+     * A receipt means Core accepted a batch of steering text, which means the queue
+     * it came from has been drained.
+     *
+     * Notices carry no receipt id (`steer(text, id?)`'s `id` is optional and the
+     * receipt-less path passes none), so an arriving receipt is the only available
+     * proof. Treating "a receipt arrived" as "everything we steered was delivered"
+     * is correct in the only direction that matters: an over-eager release costs a
+     * MISSING notice, so the release is deferred to the next `steering_accepted`
+     * cycle rather than assumed at `steer()` time.
+     */
+    onSteeringAccepted(): void;
+    /**
+     * Put undelivered notices back at `turn_start` and at the end of a run.
+     *
+     * THIS IS WHAT TURNS "swallowed by clearAllQueues()" INTO "delivered one turn
+     * later". `push` deduplicates by id, so a notice that WAS delivered and is also
+     * re-queued can only be re-rendered once - and it is not re-queued at all,
+     * because a delivered notice was released by its receipt.
+     */
+    requeueUndelivered(): void;
+    /**
+     * Drain for the PULL channel.
+     *
+     * NOTHING IS RECORDED HERE, and that is the point: `drain()` hands ownership to
+     * the tool result that is about to carry the block, so there is no pending
+     * state to reconcile - the text is in the conversation as soon as the result
+     * returns.
+     */
+    drainForTail(): JobNotice[];
+    private onProcEvent;
+}
+export {};

package/dist/agent/job-notices.js

@@ -0,0 +1,182 @@
+/**
+ * JobNoticeRelay — the controller-side owner of "a job finished, and the model
+ * has to be told exactly once" (long-task-jobs §4.6 / §4.6.1).
+ *
+ * ASCII ONLY: `src/agent/**` is inside the glyph scanner's scope.
+ *
+ * THREE CHANNELS, ONE QUEUE, AND A LEDGER. The queue guarantees "at most once"
+ * because every channel takes from it with `drain()`. That alone is NOT enough,
+ * and this file exists because of the exception: Core's steering queue has a
+ * fourth consumer that DESTROYS rather than drains.
+ *
+ *   `fast/reviewer.ts` calls `clearAllQueues()` when `userSteerCount() === 0`,
+ *   and its stated safety argument is "`AgentController.steer()` is the only
+ *   other writer in the package". A job notice queued through
+ *   `enqueueSteering(text, false)` returns no receipt id, never enters
+ *   `pendingUserSteering`, and is therefore INVISIBLE to that counter. With
+ *   `fast` on, the last notice of a run could be wiped with no log line, no UI
+ *   change and no failing test.
+ *
+ * THE FIX IS A LEDGER, NOT A COUPLING. A notice that has been steered is held in
+ * `pendingSteered` until a `steering_accepted` receipt proves the queue was
+ * drained; anything still held at `turn_start` or at the end of a run is pushed
+ * back into the queue. `JobNoticeQueue.push` is idempotent by id, so a re-queue
+ * can only ever cause a DELAY, never a duplicate.
+ *
+ * NOTHING HERE IS PUSHED WHILE A TOOL BATCH IS OPEN. The controller owns the
+ * batch count and calls `tryPush()` only from the one safe point; this class
+ * re-checks the same condition so a future call site cannot forget it (I-5).
+ */
+import { renderJobNotices } from '../proc/notices.js';
+import { isTerminalStatus } from '../proc/types.js';
+export class JobNoticeRelay {
+    deps;
+    /**
+     * Notices that have been steered but not yet proven delivered, keyed by
+     * `${id}:${status}:${at}` - the same identity `JobNoticeQueue` uses.
+     */
+    pendingSteered = new Map();
+    /**
+     * Terminal ids this session has seen, so `job_wait` can answer "it finished and
+     * was reclaimed, do not re-run it" instead of "no such job".
+     *
+     * Bounded by `maxNotices`, oldest out: it answers a question about the recent
+     * past, and an unbounded map in a long session is a leak with a helpful name.
+     */
+    recalled = new Map();
+    unsubscribe;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Subscribe to the supervisor's stream. Returns the release function. */
+    attach(subscribe) {
+        this.unsubscribe?.();
+        this.unsubscribe = subscribe((event) => this.onProcEvent(event));
+    }
+    detach() {
+        this.unsubscribe?.();
+        this.unsubscribe = undefined;
+    }
+    /** Terminal ids this session has already reported, for `job_wait`'s message. */
+    terminalRecord(id) {
+        return this.recalled.get(id);
+    }
+    /**
+     * Move everything queued into the steering queue, if this is a safe moment.
+     *
+     * Returns whether anything was pushed. Called from exactly one place in the
+     * controller - the `tool_execution_end` listener, after the batch count reaches
+     * zero.
+     */
+    tryPush() {
+        if (!this.deps.steerEnabled())
+            return false;
+        if (!this.deps.isAtSafeSteerPoint())
+            return false;
+        return this.steerQueued();
+    }
+    /**
+     * Deliver the queue just BEFORE a run starts (the FILL channel, §4.6).
+     *
+     * TWO DIFFERENCES FROM `tryPush()`, both deliberate:
+     *
+     *  - the precondition is `canSteerBeforeTurn()` (no `isRunning()` term), because
+     *    this runs before `agent.prompt()` / `agent.continue()`, where the engine is
+     *    not running yet - see the dep's own comment;
+     *  - `noticeSteer` does NOT gate it. That key switches the PUSH channel only
+     *    ("noticeSteer=false is not a notification off switch", §6.5), so a user who
+     *    declines mid-turn interruptions must still learn that the job finished
+     *    before their next message is sent.
+     */
+    flushForTurn() {
+        if (!this.deps.canSteerBeforeTurn())
+            return false;
+        return this.steerQueued();
+    }
+    /** The shared half: take the queue, record the ledger, steer one block. */
+    steerQueued() {
+        const notices = this.deps.queue.drain();
+        if (notices.length === 0)
+            return false;
+        for (const notice of notices)
+            this.pendingSteered.set(noticeKey(notice), notice);
+        this.deps.steer(renderJobNotices(notices));
+        return true;
+    }
+    /**
+     * A receipt means Core accepted a batch of steering text, which means the queue
+     * it came from has been drained.
+     *
+     * Notices carry no receipt id (`steer(text, id?)`'s `id` is optional and the
+     * receipt-less path passes none), so an arriving receipt is the only available
+     * proof. Treating "a receipt arrived" as "everything we steered was delivered"
+     * is correct in the only direction that matters: an over-eager release costs a
+     * MISSING notice, so the release is deferred to the next `steering_accepted`
+     * cycle rather than assumed at `steer()` time.
+     */
+    onSteeringAccepted() {
+        this.pendingSteered.clear();
+    }
+    /**
+     * Put undelivered notices back at `turn_start` and at the end of a run.
+     *
+     * THIS IS WHAT TURNS "swallowed by clearAllQueues()" INTO "delivered one turn
+     * later". `push` deduplicates by id, so a notice that WAS delivered and is also
+     * re-queued can only be re-rendered once - and it is not re-queued at all,
+     * because a delivered notice was released by its receipt.
+     */
+    requeueUndelivered() {
+        if (this.pendingSteered.size === 0)
+            return;
+        const stranded = [...this.pendingSteered.values()];
+        this.pendingSteered.clear();
+        for (const notice of stranded)
+            this.deps.queue.push(notice);
+    }
+    /**
+     * Drain for the PULL channel.
+     *
+     * NOTHING IS RECORDED HERE, and that is the point: `drain()` hands ownership to
+     * the tool result that is about to carry the block, so there is no pending
+     * state to reconcile - the text is in the conversation as soon as the result
+     * returns.
+     */
+    drainForTail() {
+        return this.deps.queue.drain();
+    }
+    onProcEvent(event) {
+        const job = event.service;
+        if (!isTerminalStatus(job.status))
+            return;
+        const kind = job.kind;
+        this.recalled.set(job.id, { kind, status: job.status });
+        while (this.recalled.size > 32) {
+            const oldest = this.recalled.keys().next();
+            if (oldest.done === true)
+                break;
+            this.recalled.delete(oldest.value);
+        }
+        // One notice per terminal transition. `exited`/`stopped` are single events per
+        // job (the supervisor's own guards enforce that), so no de-duplication is
+        // needed here beyond the queue's own.
+        if (job.status !== 'exited' && job.status !== 'failed' && job.status !== 'stopped')
+            return;
+        this.deps.queue.push({
+            id: job.id,
+            kind,
+            status: job.status,
+            exitCode: job.exitCode,
+            signal: job.signal,
+            elapsedMs: (job.endedAt ?? Date.now()) - job.startedAt,
+            ...(job.progress?.text ? { progressText: job.progress.text } : {}),
+            // A FAILURE EARNS A TAIL; a clean exit does not (the block stays bounded).
+            tailRows: job.status === 'failed' || (job.exitCode !== null && job.exitCode !== 0)
+                ? job.rows.slice(-2)
+                : [],
+            at: Date.now(),
+        });
+    }
+}
+function noticeKey(notice) {
+    return `${notice.id}:${notice.status}:${notice.at}`;
+}