@aragon-agent/cli 0.6.29 → 0.6.32

package/dist/proc/prompt.js

@@ -19,8 +19,57 @@
  * `BACKGROUND_SERVICES_BLOCK_VERSION` exists so a change to this wording is
  * greppable from a behaviour report.
  */
-import { BACKGROUND_SERVICES_BLOCK_VERSION } from './limits.js';
-export { BACKGROUND_SERVICES_BLOCK_VERSION };
+/**
+ * The `<background_jobs>` system-prompt block (long-task-jobs §12).
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope, and this string
+ * also reaches a model running in a `cmd.exe` terminal.
+ *
+ * SPLICED CONDITIONALLY by `buildSystemPrompt`, which is what preserves I-3: with
+ * `jobs.enabled: false` the prompt is BYTE-IDENTICAL to the pre-feature output.
+ *
+ * EVERY SENTENCE HERE ANSWERS A DECISION THE MODEL ACTUALLY HAS TO MAKE:
+ *  - "do not poll" is the behaviour this feature exists to replace (six
+ *    `bash_output` calls per 30 seconds, six LLM turns, six 200-row tails);
+ *  - "a bounded wait is the only thing that tells you it finished" prevents the
+ *    opposite failure, a model that starts a job and then guesses;
+ *  - "`<job_notices>` is the notification, not an error" stops it apologising for
+ *    a block that is good news;
+ *  - "`[stalled]` is not a failure" stops it killing a job that is merely quiet.
+ *
+ * `JOBS_BLOCK_VERSION` exists so a change to this wording is greppable from a
+ * behaviour report.
+ */
+import { JOBS_BLOCK_VERSION } from './limits.js';
+export { JOBS_BLOCK_VERSION };
+export function buildBackgroundJobsBlock() {
+    return [
+        '<background_jobs>',
+        'Some commands finish on their own but take far longer than one tool call:',
+        'training runs, model downloads, big installs, release builds. Do not poll them',
+        'and do not let the tool ceiling kill them.',
+        '',
+        'Rules:',
+        '- Start one with bash({ command, background: true }). You get a job id: `t1` for a',
+        '  task (it will finish) or `s1` for a service (it will not). The call returns in a',
+        '  few seconds with the first lines of output.',
+        '- Wait with job_wait({ job: "t1" }). Every wait is bounded (default 30s, at most',
+        '  60s) and returns one status line, one progress line, and only the output since',
+        '  your last cursor. Call it again only after deciding something; do other work in',
+        '  between if you have any.',
+        '- Nothing but a bounded wait tells you a job finished. When one finishes while you',
+        '  are busy, a <job_notices> block appears at the end of a tool result - that is the',
+        '  notification, not an error.',
+        '- `[stalled]` means the job has printed nothing for a while. It has not failed.',
+        '  Choose: keep waiting, stop it, or read the tail.',
+        '- Full output lives in the service log (`bash_output`) and, past the ring, in a',
+        '  file whose path the truncation note names. Read that file with grep/read_file',
+        '  instead of asking for the whole log.',
+        '- Stop a job with bash_kill({ service: "t1" }) when you are done with it, unless the',
+        '  user asked for it to stay up. Jobs do not survive this session.',
+        '</background_jobs>',
+    ].join('\n');
+}
 export function buildBackgroundServicesBlock() {
     return [
         '<background_services>',

package/dist/proc/supervisor.d.ts

@@ -18,10 +18,23 @@
  * unconditionally. With the flag off this object holds foreground pids, nothing
  * else, and allocates no timers.
  */
-import { type ProcEventListener, type ProcSupervisorPort, type ServiceLogPage, type ServiceSnapshot, type ServiceStartRequest, type ServiceStartResult } from './types.js';
+import { type JobLogMirrorPort, type ProcEventListener, type ProcSupervisorPort, type ServiceLogPage, type ServiceSnapshot, type ServiceStartRequest, type ServiceStartResult } from './types.js';
 export interface ProcSupervisorOptions {
     /** `cfg.bash.readyTimeoutMs`, read once per service at spawn. */
     readyTimeoutMs: () => number;
+    /**
+     * `cfg.jobs.stallSeconds * 1000`, read per snapshot.
+     *
+     * A CLOSURE RATHER THAN A NUMBER, exactly like `readyTimeoutMs`: a
+     * `config set jobs.stallSeconds` has to reach the card of the job already
+     * running, and a value captured at construction would not.
+     */
+    stallMs?: () => number;
+    /**
+     * The optional write-through log mirror. `undefined` when `jobs.persistLog` is
+     * false, and in every test that does not care about disk.
+     */
+    mirror?: JobLogMirrorPort;
     /** Injected by the tests; production uses a real TCP connect. */
     probe?: (port: number) => Promise<boolean>;
 }
@@ -37,7 +50,15 @@ export declare class ProcSupervisor implements ProcSupervisorPort {
      */
     private readonly foreground;
     private readonly listeners;
-    private nextId;
+    /**
+     * TWO COUNTERS, NEVER ONE (long-task-jobs §4.2 / I-2).
+     *
+     * `s1` and `t1` are separate id spaces so a `bash_kill({ service: "s1" })` can
+     * never reach a task, and so the model can tell "this will finish" from "this
+     * will not" from the id alone. Ids are never reused - see `evictTerminal`.
+     */
+    private nextServiceId;
+    private nextTaskId;
     private disposed;
     constructor(opts: ProcSupervisorOptions);
     trackForeground(pid: number | undefined): () => void;
@@ -89,6 +110,18 @@ export declare class ProcSupervisor implements ProcSupervisorPort {
     private emit;
     /** Coalesce `output` at the SOURCE — `/bg` and `bash_output` read it too. */
     private scheduleOutput;
+    /**
+     * Recompute the extracted progress line from the tail of the ring.
+     *
+     * The scan window is `tail(progressScanRows)` SPLIT AROUND THE CARRY: `tail()`
+     * appends the not-yet-terminated line as its last element, and
+     * `extractProgress` needs to know which one that is, because `source: 'carry'`
+     * is how the caller knows a `\r`-rewritten bar (a download, a tqdm run) is
+     * moving rather than silent.
+     */
+    private refreshProgress;
+    /** `now - lastOutputAt` past `jobs.stallSeconds`, on a job that has not ended. */
+    private isStalled;
     /** Release every timer, wake every waiter, and announce the terminal state. */
     private finish;
     /**

package/dist/proc/supervisor.js

@@ -25,6 +25,7 @@ import { extractPortHint } from './classify.js';
 import { isAlive, killTree, killTreeSync } from './kill-tree.js';
 import { PROC_LIMITS } from './limits.js';
 import { LogRing } from './log-ring.js';
+import { extractProgress } from './progress.js';
 import { probePort, ReadinessWatcher } from './readiness.js';
 import { isTerminalStatus, } from './types.js';
 export class ProcSupervisor {
@@ -39,7 +40,15 @@ export class ProcSupervisor {
      */
     foreground = new Set();
     listeners = new Set();
-    nextId = 1;
+    /**
+     * TWO COUNTERS, NEVER ONE (long-task-jobs §4.2 / I-2).
+     *
+     * `s1` and `t1` are separate id spaces so a `bash_kill({ service: "s1" })` can
+     * never reach a task, and so the model can tell "this will finish" from "this
+     * will not" from the id alone. Ids are never reused - see `evictTerminal`.
+     */
+    nextServiceId = 1;
+    nextTaskId = 1;
     disposed = false;
     constructor(opts) {
         this.opts = opts;
@@ -80,7 +89,7 @@ export class ProcSupervisor {
         if (this.disposed)
             return { ok: false, error: 'The process supervisor is shut down.' };
         this.evictTerminal();
-        if (this.services.size >= PROC_LIMITS.maxServices) {
+        if (this.services.size >= PROC_LIMITS.maxJobs) {
             // NO EVICTION AND NO SILENT FOREGROUNDING (P2-8). Every record is live, so
             // dropping the oldest would orphan a running server that nothing can any
             // longer name or stop. Naming the ids is what makes the error actionable.
@@ -91,32 +100,44 @@ export class ProcSupervisor {
                 .join(', ');
             return {
                 ok: false,
-                error: `Too many background services (${PROC_LIMITS.maxServices}). ` +
+                error: `Too many background jobs (${PROC_LIMITS.maxJobs}). ` +
                     `Stop one first with bash_kill({ service: "<id>" }) - oldest live: ${live}.`,
             };
         }
-        const id = `s${this.nextId}`;
-        this.nextId += 1;
-        // THE PRE-FLIGHT PROBE RUNS BEFORE THE SPAWN (R-3). An unrelated process
-        // already answering on 3000 would otherwise make every launch instantly and
-        // falsely ready; finding it there disables the probe detector for this
-        // service and annotates the card, leaving the URL detector to do the work.
-        const hint = extractPortHint(req.command);
+        const kind = req.kind ?? 'service';
+        const id = kind === 'task' ? `t${this.nextTaskId++}` : `s${this.nextServiceId++}`;
+        // THE PRE-FLIGHT PROBE RUNS ONLY FOR A SERVICE (R-3), and the reason is the
+        // kind itself: a `task` connects to nothing, so probing its (usually
+        // non-existent) port hint would spend a socket timeout per launch to learn
+        // nothing. For a service, an unrelated process already answering on 3000
+        // would make every launch instantly and falsely ready; finding it there
+        // disables the probe detector and annotates the card, leaving the URL
+        // detector to do the work.
+        const hint = kind === 'service' ? extractPortHint(req.command) : undefined;
         const preoccupied = hint === undefined ? false : await (this.opts.probe ?? probePort)(hint).catch(() => false);
+        const startedAt = Date.now();
         const ring = new LogRing();
         const record = {
             id,
+            kind,
             toolCallId: req.toolCallId,
             command: req.command,
             cwd: req.cwd,
             pid: undefined,
-            status: 'starting',
-            startedAt: Date.now(),
+            // A TASK IS `running` FROM THE SPAWN (D-14). It has no readiness to wait
+            // for: the old behaviour left it `starting` for `readyTimeoutMs` (60s) and
+            // told the model "not ready yet - still coming up" about a job that was
+            // already training. Note that this changes the STATUS only - the settle
+            // window in `runBackground` still applies, via a TERMINAL predicate rather
+            // than a `!== 'starting'` one (I-12).
+            status: kind === 'task' ? 'running' : 'starting',
+            startedAt,
             exitCode: null,
             signal: null,
             rows: [],
             rowsSeen: 0,
             truncated: false,
+            lastOutputAt: startedAt,
             ...(hint !== undefined ? { port: hint } : {}),
             ...(preoccupied ? { portPreoccupied: true } : {}),
         };
@@ -167,12 +188,24 @@ export class ProcSupervisor {
         entry.child = child;
         record.pid = child.pid;
         const onChunk = (chunk) => {
-            const rows = ring.append(typeof chunk === 'string' ? chunk : chunk.toString());
+            const text = typeof chunk === 'string' ? chunk : chunk.toString();
+            const rows = ring.append(text);
+            // EVERY CHUNK, NOT EVERY COMPLETED ROW. A `\r`-rewritten progress bar
+            // moves continuously while completing no row at all, so a row-based clock
+            // would call a healthy download stalled after `jobs.stallSeconds`.
+            record.lastOutputAt = Date.now();
             record.rowsSeen = ring.rowsSeen;
             record.truncated = ring.truncated;
             record.rows = ring.tail(PROC_LIMITS.cardTailRows);
             if (rows.length > 0)
                 entry.watcher?.offerRows(rows);
+            if (this.opts.mirror) {
+                this.opts.mirror.write(id, text);
+                // The path exists only once the mirror has actually opened a file, and
+                // `bash_output`'s truncation note is useful when it names a real one - so
+                // it is read back rather than assumed.
+                record.logPath ??= this.opts.mirror.pathOf(id);
+            }
             this.scheduleOutput(entry);
         };
         child.stdout?.on('data', onChunk);
@@ -204,34 +237,41 @@ export class ProcSupervisor {
             record.endedAt = Date.now();
             this.finish(entry, asked ? 'stopped' : 'exited');
         });
-        const watcher = new ReadinessWatcher({
-            // The hint is dropped when the port was ALREADY answering: probing it
-            // would report ready in the first 40 ms for somebody else's server.
-            ...(hint !== undefined && !preoccupied ? { portHint: hint } : {}),
-            readyTimeoutMs: this.opts.readyTimeoutMs(),
-            ...(this.opts.probe ? { probe: this.opts.probe } : {}),
-            onReady: (result) => {
-                if (isTerminalStatus(record.status) || record.status === 'ready')
-                    return;
-                record.status = 'ready';
-                record.readyAt = Date.now();
-                if (result.url)
-                    record.url = result.url;
-                if (result.port !== undefined)
-                    record.port = result.port;
-                record.detectedBy = result.detectedBy;
-                this.emit({ type: 'ready', service: this.snapshot(entry) });
-            },
-            onTimeout: () => {
-                if (isTerminalStatus(record.status) || record.status === 'ready')
-                    return;
-                // AN HONEST THIRD STATE (D-4). It is alive and it listens on nothing.
-                record.status = 'running';
-                this.emit({ type: 'ready', service: this.snapshot(entry) });
-            },
-        });
-        entry.watcher = watcher;
-        watcher.start();
+        // A TASK HAS NO READINESS TO DETECT (AC-4), and starting a watcher for it
+        // would be actively wrong: the watcher's `onTimeout` path would later flip
+        // `running` -> `running` and emit a `ready` event for a job that has no
+        // address, and a 60s timer would keep firing for the whole life of a task
+        // that is already `running`.
+        if (kind === 'service') {
+            const watcher = new ReadinessWatcher({
+                // The hint is dropped when the port was ALREADY answering: probing it
+                // would report ready in the first 40 ms for somebody else's server.
+                ...(hint !== undefined && !preoccupied ? { portHint: hint } : {}),
+                readyTimeoutMs: this.opts.readyTimeoutMs(),
+                ...(this.opts.probe ? { probe: this.opts.probe } : {}),
+                onReady: (result) => {
+                    if (isTerminalStatus(record.status) || record.status === 'ready')
+                        return;
+                    record.status = 'ready';
+                    record.readyAt = Date.now();
+                    if (result.url)
+                        record.url = result.url;
+                    if (result.port !== undefined)
+                        record.port = result.port;
+                    record.detectedBy = result.detectedBy;
+                    this.emit({ type: 'ready', service: this.snapshot(entry) });
+                },
+                onTimeout: () => {
+                    if (isTerminalStatus(record.status) || record.status === 'ready')
+                        return;
+                    // AN HONEST THIRD STATE (D-4). It is alive and it listens on nothing.
+                    record.status = 'running';
+                    this.emit({ type: 'ready', service: this.snapshot(entry) });
+                },
+            });
+            entry.watcher = watcher;
+            watcher.start();
+        }
         this.emit({ type: 'started', service: this.snapshot(entry) });
         return { ok: true, service: this.snapshot(entry) };
     }
@@ -346,6 +386,15 @@ export class ProcSupervisor {
                 clearTimeout(entry.escalation);
             entry.outputTimer = undefined;
             entry.escalation = undefined;
+            // THE ONE EMIT THIS METHOD IS ALLOWED (long-task-jobs RV-P1-4). Without it a
+            // waiter that subscribed to `ProcEvent` is never woken here: this method
+            // sets a terminal status, and `child.on('exit')` then returns EARLY because
+            // the status is already terminal - so it does not emit either. A `job_wait`
+            // would sleep out its full timeout and only then learn the job was stopped.
+            //
+            // Safe on a signal-hook path: `emit` wraps every listener in try/catch, so
+            // this cannot throw, and it neither awaits nor spawns anything (I-9).
+            this.emit({ type: 'stopped', service: this.snapshot(entry) });
             for (const wake of entry.waiters.splice(0))
                 wake();
         }
@@ -399,10 +448,44 @@ export class ProcSupervisor {
             return;
         entry.outputTimer = setTimeout(() => {
             entry.outputTimer = undefined;
+            // PROGRESS IS COMPUTED HERE, NOT PER CHUNK (long-task-jobs §4.5): a
+            // 10 kHz stream of chunks would otherwise run the extraction table 10,000
+            // times a second to publish the same `47%`. At most 10 times a second, from
+            // the coalesced tick, is also what makes the result a stable value two
+            // waits in a row can be compared against.
+            this.refreshProgress(entry);
             this.emit({ type: 'output', service: this.snapshot(entry) });
         }, PROC_LIMITS.outputCoalesceMs);
         entry.outputTimer.unref?.();
     }
+    /**
+     * Recompute the extracted progress line from the tail of the ring.
+     *
+     * The scan window is `tail(progressScanRows)` SPLIT AROUND THE CARRY: `tail()`
+     * appends the not-yet-terminated line as its last element, and
+     * `extractProgress` needs to know which one that is, because `source: 'carry'`
+     * is how the caller knows a `\r`-rewritten bar (a download, a tqdm run) is
+     * moving rather than silent.
+     */
+    refreshProgress(entry) {
+        const tail = entry.ring.tail(PROC_LIMITS.progressScanRows);
+        const carry = entry.ring.carryRow;
+        const rows = carry.length > 0 ? tail.slice(0, -1) : tail;
+        const progress = extractProgress(rows, carry);
+        if (progress)
+            entry.record.progress = progress;
+        else
+            delete entry.record.progress;
+    }
+    /** `now - lastOutputAt` past `jobs.stallSeconds`, on a job that has not ended. */
+    isStalled(record) {
+        if (isTerminalStatus(record.status))
+            return false;
+        const ms = this.opts.stallMs?.();
+        if (ms === undefined || ms <= 0)
+            return false;
+        return Date.now() - record.lastOutputAt > ms;
+    }
     /** Release every timer, wake every waiter, and announce the terminal state. */
     finish(entry, type) {
         entry.watcher?.stop();
@@ -417,6 +500,10 @@ export class ProcSupervisor {
         entry.record.rows = entry.ring.tail(PROC_LIMITS.cardTailRows);
         entry.record.rowsSeen = entry.ring.rowsSeen;
         entry.record.truncated = entry.ring.truncated;
+        // ONE LAST EXTRACTION, so a job that printed `100%` and exited carries that
+        // line into its card, its notice and its `job_wait` result rather than the
+        // value from the last coalesced tick 100 ms earlier.
+        this.refreshProgress(entry);
         this.emit({ type, service: this.snapshot(entry) });
         for (const wake of entry.waiters.splice(0))
             wake();
@@ -429,10 +516,10 @@ export class ProcSupervisor {
      * something else.
      */
     evictTerminal() {
-        if (this.services.size < PROC_LIMITS.maxServices)
+        if (this.services.size < PROC_LIMITS.maxJobs)
             return;
         for (const [id, entry] of this.services) {
-            if (this.services.size < PROC_LIMITS.maxServices)
+            if (this.services.size < PROC_LIMITS.maxJobs)
                 break;
             if (isTerminalStatus(entry.record.status))
                 this.services.delete(id);
@@ -442,6 +529,7 @@ export class ProcSupervisor {
         const r = entry.record;
         return Object.freeze({
             id: r.id,
+            kind: r.kind,
             toolCallId: r.toolCallId,
             command: r.command,
             cwd: r.cwd,
@@ -460,6 +548,17 @@ export class ProcSupervisor {
             rowsSeen: r.rowsSeen,
             truncated: r.truncated,
             ...(r.killIncomplete ? { killIncomplete: true } : {}),
+            // THE THREE FIELDS THIS HAND-COPIED LITERAL WOULD OTHERWISE LOSE
+            // (long-task-jobs RV-P1-8). `kind` and `lastOutputAt` are REQUIRED on
+            // `ServiceSnapshot`, so forgetting one is a compile error; `progress` and
+            // `logPath` cannot be required (they genuinely may not exist) and are
+            // covered by AC-26 / AC-38 instead.
+            lastOutputAt: r.lastOutputAt,
+            ...(r.progress
+                ? { progress: { text: r.progress.text, kind: r.progress.kind } }
+                : {}),
+            ...(this.isStalled(r) ? { stalled: true } : {}),
+            ...(r.logPath !== undefined ? { logPath: r.logPath } : {}),
         });
     }
 }

package/dist/proc/types.d.ts

@@ -9,6 +9,31 @@
  * coupling (`no-host-coupling.test.ts`), so a new event member would break the
  * first and teach core about a host shape it has no business defining.
  */
+import type { JobProgress, ProgressKind } from './progress.js';
+/**
+ * WHICH KIND OF JOB A RECORD DESCRIBES (long-task-jobs §4.2, D-1).
+ *
+ *  - `service` never exits on its own and owes the caller a readiness signal;
+ *  - `task` always exits and is `running` from the spawn.
+ *
+ * The distinction is not cosmetic. Before it existed, an explicitly backgrounded
+ * `python train.py` sat in `starting` for `readyTimeoutMs` (60s) and `bash` told
+ * the model "not ready yet - still coming up" about a job that was already
+ * working - which is what pushed it into starting a second copy or giving up.
+ */
+export type JobKind = 'service' | 'task';
+/**
+ * The progress subset a SNAPSHOT carries: the rendered line and its shape.
+ *
+ * `source` and `rowIndex` stay on the record. They exist for tests and debugging
+ * (which row won, and did it come from a `\r` carry), and a card or a tool result
+ * that started depending on them would be depending on an implementation detail
+ * of the extraction table.
+ */
+export interface ServiceSnapshotProgress {
+    text: string;
+    kind: ProgressKind;
+}
 export type ServiceStatus = 
 /** Spawned, not yet ready, still alive. */
 'starting'
@@ -32,8 +57,18 @@ export type ServiceStatus =
 /** A status from which nothing further will happen. */
 export declare function isTerminalStatus(status: ServiceStatus): boolean;
 export interface ServiceRecord {
-    /** `s1`, `s2`, ... Short because the model has to quote it back. */
+    /** `s1` (a service), `t3` (a task). Short because the model has to quote it back. */
     id: string;
+    /**
+     * WHICH KIND OF JOB THIS IS (long-task-jobs §4.2, D-1).
+     *
+     * A `service` never exits on its own and owes the caller a readiness signal; a
+     * `task` always exits and is `running` from the spawn. The distinction is not
+     * cosmetic: before it existed, an explicitly backgrounded `python train.py` sat
+     * in `starting` for `readyTimeoutMs` (60s) and `bash` told the model "not ready
+     * yet - still coming up" about a job that was already working.
+     */
+    kind: JobKind;
     /** The `bash` call that started it. */
     toolCallId: string;
     command: string;
@@ -67,15 +102,35 @@ export interface ServiceRecord {
     truncated: boolean;
     /** A stop reported the pid still alive afterwards (R-2 / P2-6). */
     killIncomplete?: boolean;
+    /**
+     * When output last arrived, updated on EVERY CHUNK rather than per completed
+     * row (long-task-jobs §4.5).
+     *
+     * THE DISTINCTION IS LOAD-BEARING: a `\r`-rewritten progress bar (every
+     * download tool there is) moves continuously while completing no row at all,
+     * so a "last completed row" clock would declare a healthy download stalled
+     * after `jobs.stallSeconds`.
+     */
+    lastOutputAt: number;
+    /** Latest extracted progress line, recomputed on the coalesced output tick. */
+    progress?: JobProgress;
+    /** Where the optional on-disk mirror is writing this job's full log. */
+    logPath?: string;
 }
 /**
  * The frozen, JSON-serialisable projection listeners receive.
  *
  * LISTENERS GET SNAPSHOTS, NEVER THE RECORD, so a render-side bug cannot mutate
  * supervisor state. `rows` carries only the last `PROC_LIMITS.cardTailRows`.
+ *
+ * `kind` AND `lastOutputAt` ARE REQUIRED ON PURPOSE (long-task-jobs RV-P1-8).
+ * `snapshot()` is a hand-copied object literal, so a new optional field that is
+ * forgotten there fails silently in five consumers at once. Required fields turn
+ * that omission into a compile error instead.
  */
 export interface ServiceSnapshot {
     id: string;
+    kind: JobKind;
     toolCallId: string;
     command: string;
     cwd: string;
@@ -94,6 +149,17 @@ export interface ServiceSnapshot {
     rowsSeen: number;
     truncated: boolean;
     killIncomplete?: boolean;
+    lastOutputAt: number;
+    progress?: ServiceSnapshotProgress;
+    /**
+     * DERIVED, NOT STORED: `now - lastOutputAt > jobs.stallSeconds * 1000` on a
+     * job that has not ended.
+     *
+     * A stored flag would need a timer to flip it, and the whole point is that any
+     * render refreshes the judgement for free.
+     */
+    stalled?: boolean;
+    logPath?: string;
 }
 export type ProcEvent = {
     type: 'started';
@@ -118,6 +184,11 @@ export interface ServiceStartRequest {
     command: string;
     cwd: string;
     toolCallId: string;
+    /**
+     * Absent means `'service'`, which is what every pre-existing caller means and
+     * what keeps `start()` backward compatible without a second method.
+     */
+    kind?: JobKind;
 }
 export interface ServiceStartResult {
     ok: boolean;
@@ -133,6 +204,23 @@ export interface ServiceLogPage {
     cursor: number;
     /** Rows were evicted between `since` and what is returned. */
     truncated: boolean;
+    /**
+     * The not-yet-terminated line among `rows` (empty when the last chunk ended
+     * with a newline).
+     *
+     * THE ONLY WAY TO TELL A REDRAWING PROGRESS BAR FROM A FINISHED ROW: `rows`
+     * always ends with the carry line when one exists, so `job_wait` uses this to
+     * keep an unchanged carriage-return-rewritten bar out of its incremental row
+     * budget (RV-P1-5). Optional so a test double - and `bash_output`, which does
+     * not care - can leave it out.
+     */
+    carryRow?: string;
+}
+/** What `job_wait` and the supervisor need from a log mirror; no filesystem here. */
+export interface JobLogMirrorPort {
+    open(jobId: string): void;
+    write(jobId: string, chunk: string): void;
+    pathOf(jobId: string): string | undefined;
 }
 /**
  * The port `bash`, the tools, the controller and `/bg` see.

package/dist/proc/wait.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The bounded wait primitive (long-task-jobs §4.4.1).
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope.
+ *
+ * A FREE FUNCTION OVER THREE PORT METHODS, NOT A METHOD ON THE PORT (D-9).
+ * `Pick<ProcSupervisorPort, 'get' | 'read' | 'subscribe'>` is enough to answer
+ * "has it finished yet, and what did it print since my cursor", so no test double
+ * has to grow a `wait()` and the registry keeps owning exactly what it owns.
+ *
+ * FOUR RULES, and each one closes a way this turns into a hang:
+ *
+ *  1. TERMINAL FIRST, SUBSCRIBE SECOND. A job that already ended resolves
+ *     synchronously with `waitedMs: 0` and registers nothing - no listener, no
+ *     timer. `runBackground` carries the same defence for the same reason: a
+ *     1 ms crash is not hypothetical.
+ *  2. EVERY TIMER IS `unref`ed AND EVERY LISTENER IS REMOVED at every exit. A
+ *     wait that leaks a timer is a process that will not exit, which is the
+ *     failure mode this feature exists to remove.
+ *  3. ONE IDEMPOTENT `finish` FUNNEL. Terminal event, timeout and abort race, and
+ *     exactly one of them may win.
+ *  4. IT DOES NOT DEPEND ON A SINGLE WAKE SOURCE. `reapSync()` used to emit
+ *     nothing at all (the supervisor now emits `stopped` from it), and
+ *     `dispose()` clears its listener set without emitting; the self-timeout is
+ *     therefore a real second path, not belt-and-braces.
+ */
+import type { ProcSupervisorPort, ServiceLogPage, ServiceSnapshot } from './types.js';
+/** The port surface this module needs. Deliberately narrower than the full port. */
+export type WaitPort = Pick<ProcSupervisorPort, 'get' | 'read' | 'subscribe'>;
+export interface WaitForJobsRequest {
+    /** Ids already resolved by the caller. An empty list returns immediately. */
+    targets: readonly string[];
+    /** Already clamped by the caller (`jobs.waitSeconds`, I-4 and `WAIT_SECONDS_RANGE`). */
+    timeoutMs: number;
+    /** The tool call's `ctx.signal`. Aborting resolves the wait with `aborted: true`. */
+    signal?: AbortSignal;
+    /** Cursor from a previous `job_wait` / `bash_output`; omit for the whole tail. */
+    since?: number;
+}
+export interface JobWaitOutcome {
+    /** One snapshot per target that still exists, in the requested order. */
+    jobs: ServiceSnapshot[];
+    /** Every target reached a terminal status. */
+    terminal: boolean;
+    waitedMs: number;
+    timedOut: boolean;
+    aborted: boolean;
+    /** Incremental page per target, read at settle time. */
+    pages: ReadonlyMap<string, ServiceLogPage>;
+}
+/**
+ * Wait up to `timeoutMs` for every target to reach a terminal status.
+ *
+ * Resolves - never rejects - and always after at most `timeoutMs`. `now` is
+ * injectable so a test can assert `waitedMs` without depending on wall clock.
+ */
+export declare function waitForJob(port: WaitPort, req: WaitForJobsRequest, now?: () => number): Promise<JobWaitOutcome>;