@aragon-agent/cli 0.6.45 → 0.6.47

package/dist/config/schema.d.ts

@@ -878,11 +878,11 @@ export interface JobsConfig {
      */
     enabled: boolean;
     /**
-     * Seconds one `job_wait` blocks by default. Default 30, range 5..60.
+     * Seconds one `job_wait` blocks by default. Default 30, range 5..1200.
      *
-     * ALSO CONVERGED AGAINST THE TOOL CEILING at load time and again at call time
-     * (I-4): a wait that outlives the tool call hosting it would turn every long
-     * job into `Command timed out`, which is the defect this feature removes.
+     * NOT CONVERGED AGAINST `toolTimeoutMs` ANY MORE (extended-job-wait I-4'): the
+     * executor gives `job_wait` its own ceiling and the idle watchdog is paused for
+     * the whole wait, so a long default no longer risks `Command timed out`.
      */
     waitSeconds: number;
     /**

package/dist/config/schema.js

@@ -8,6 +8,7 @@
 import { isAbsolute } from 'node:path';
 import { ABSOLUTE_MAX_OUTPUT_TOKENS, DEFAULT_MAX_OUTPUT_TOKENS, DEFAULT_RETRY_POLICY, MIN_MAX_OUTPUT_TOKENS, RETRY_LIMITS, } from '@aragon-agent/core';
 import { clampLogLevel } from '../logging/levels.js';
+import { PROC_LIMITS } from '../proc/limits.js';
 import { TEAM_LIMITS } from '../team/limits.js';
 import { DEFAULT_GOVERNANCE_CONFIG } from './governance-config.js';
 // Governance mode (governance-mode 11.1): defined in its own file so this one does not grow.
@@ -1013,7 +1014,12 @@ export const DEFAULT_JOBS_CONFIG = {
     persistLog: true,
     noticeSteer: true,
 };
-const WAIT_SECONDS_RANGE = { min: 5, max: 60 };
+// DERIVED, NOT RESTATED (extended-job-wait I-2): a second copy of the ceiling is
+// how the config layer and the tool layer end up disagreeing without an error.
+const WAIT_SECONDS_RANGE = {
+    min: PROC_LIMITS.waitMinSeconds,
+    max: PROC_LIMITS.waitMaxSeconds,
+};
 const STALL_SECONDS_RANGE = { min: 30, max: 3600 };
 /**
  * THE single gate for every `jobs` read AND write, mirroring `clampBashConfig`

package/dist/proc/limits.d.ts

@@ -132,9 +132,26 @@ export declare const PROC_LIMITS: {
      * instead of a seventh `bash_output` poll.
      */
     readonly waitTailRows: 6;
-    /** Seconds a single wait may block, as a STRUCTURAL floor and ceiling (`jobs.waitSeconds` is clamped into this range). */
+    /**
+     * Seconds a single wait may block, as a STRUCTURAL floor and ceiling (`jobs.waitSeconds` is clamped into this range).
+     *
+     * THE ONE AUTHORITY FOR THE CEILING (extended-job-wait I-2): the executor
+     * override (`JOB_WAIT_TOOL_CEILING_MS`), `WAIT_SECONDS_RANGE.max`, the tool
+     * description and the prompt block all derive from, or are asserted equal to,
+     * `waitMaxSeconds`. Changing it here and missing another reader is how a wait
+     * is silently cut short by a layer nobody remembered.
+     */
     readonly waitMinSeconds: 5;
-    readonly waitMaxSeconds: 60;
+    readonly waitMaxSeconds: 1200;
+    /**
+     * Cadence of the in-wait heartbeat, in ms.
+     *
+     * ONE HZ because the reader needs "a few seconds ago" precision, not a stream:
+     * subscribing to the supervisor's 100 ms output coalescing would mean ~12000
+     * pointless view updates across a 20-minute wait. The same beat also carries the
+     * wall-clock deadline re-check (see `proc/wait.ts`).
+     */
+    readonly waitHeartbeatMs: 1000;
     /**
      * Characters one extracted progress line may occupy.
      *
@@ -183,18 +200,15 @@ export declare const BACKGROUND_SERVICES_BLOCK_VERSION = "v1";
  * (`bash.background` and `jobs.enabled`), so one version number covering both
  * would make "which block changed" unanswerable from a report.
  */
-export declare const JOBS_BLOCK_VERSION = "v1-2026-10";
+export declare const JOBS_BLOCK_VERSION = "v2-2026-10";
 /**
- * Head-room a single wait leaves below the tool ceiling (I-4).
- *
- * `jobs.waitSeconds * 1000 + JOB_WAIT_MARGIN_MS <= toolTimeoutMs` is the whole
- * reason a wait never needs to pause the idle watchdog (D-3): a 60 s wait inside
- * a 180 s tool call in a 210 s idle window cannot be mistaken for a hang.
+ * Head-room the executor's own `job_wait` timer leaves above the longest wait.
  *
- * IT LIVES HERE RATHER THAN IN `config/schema.ts`, where the design document put
- * it, because the TOOL layer needs the same number for its call-time convergence
- * (AC-14) and nothing in `tools/` may import `config/` - a tool takes its policy
- * through closures. One constant, two readers, no second copy to drift. Recorded
- * in `docs/plans/long-task-jobs/spec.md` under `## 实施过程发现的方案缺陷` (I-2).
+ * It is a SECOND, INDEPENDENT clock, not a coupling to `toolTimeoutMs`
+ * (extended-job-wait I-4'): the idle watchdog is paused for the whole wait, so
+ * when `waitForJob` itself misbehaves this is the only thing left that can end
+ * the call. `toolTimeoutMs` no longer constrains a wait at all.
  */
 export declare const JOB_WAIT_MARGIN_MS = 30000;
+/** The executor ceiling for `job_wait`: the longest wait plus its margin (1230 s). */
+export declare const JOB_WAIT_TOOL_CEILING_MS: number;

package/dist/proc/limits.js

@@ -139,9 +139,26 @@ export const PROC_LIMITS = {
      * instead of a seventh `bash_output` poll.
      */
     waitTailRows: 6,
-    /** Seconds a single wait may block, as a STRUCTURAL floor and ceiling (`jobs.waitSeconds` is clamped into this range). */
+    /**
+     * Seconds a single wait may block, as a STRUCTURAL floor and ceiling (`jobs.waitSeconds` is clamped into this range).
+     *
+     * THE ONE AUTHORITY FOR THE CEILING (extended-job-wait I-2): the executor
+     * override (`JOB_WAIT_TOOL_CEILING_MS`), `WAIT_SECONDS_RANGE.max`, the tool
+     * description and the prompt block all derive from, or are asserted equal to,
+     * `waitMaxSeconds`. Changing it here and missing another reader is how a wait
+     * is silently cut short by a layer nobody remembered.
+     */
     waitMinSeconds: 5,
-    waitMaxSeconds: 60,
+    waitMaxSeconds: 1200,
+    /**
+     * Cadence of the in-wait heartbeat, in ms.
+     *
+     * ONE HZ because the reader needs "a few seconds ago" precision, not a stream:
+     * subscribing to the supervisor's 100 ms output coalescing would mean ~12000
+     * pointless view updates across a 20-minute wait. The same beat also carries the
+     * wall-clock deadline re-check (see `proc/wait.ts`).
+     */
+    waitHeartbeatMs: 1000,
     /**
      * Characters one extracted progress line may occupy.
      *
@@ -190,18 +207,15 @@ export const BACKGROUND_SERVICES_BLOCK_VERSION = 'v1';
  * (`bash.background` and `jobs.enabled`), so one version number covering both
  * would make "which block changed" unanswerable from a report.
  */
-export const JOBS_BLOCK_VERSION = 'v1-2026-10';
+export const JOBS_BLOCK_VERSION = 'v2-2026-10';
 /**
- * Head-room a single wait leaves below the tool ceiling (I-4).
- *
- * `jobs.waitSeconds * 1000 + JOB_WAIT_MARGIN_MS <= toolTimeoutMs` is the whole
- * reason a wait never needs to pause the idle watchdog (D-3): a 60 s wait inside
- * a 180 s tool call in a 210 s idle window cannot be mistaken for a hang.
+ * Head-room the executor's own `job_wait` timer leaves above the longest wait.
  *
- * IT LIVES HERE RATHER THAN IN `config/schema.ts`, where the design document put
- * it, because the TOOL layer needs the same number for its call-time convergence
- * (AC-14) and nothing in `tools/` may import `config/` - a tool takes its policy
- * through closures. One constant, two readers, no second copy to drift. Recorded
- * in `docs/plans/long-task-jobs/spec.md` under `## 实施过程发现的方案缺陷` (I-2).
+ * It is a SECOND, INDEPENDENT clock, not a coupling to `toolTimeoutMs`
+ * (extended-job-wait I-4'): the idle watchdog is paused for the whole wait, so
+ * when `waitForJob` itself misbehaves this is the only thing left that can end
+ * the call. `toolTimeoutMs` no longer constrains a wait at all.
  */
 export const JOB_WAIT_MARGIN_MS = 30_000;
+/** The executor ceiling for `job_wait`: the longest wait plus its margin (1230 s). */
+export const JOB_WAIT_TOOL_CEILING_MS = PROC_LIMITS.waitMaxSeconds * 1000 + JOB_WAIT_MARGIN_MS;

package/dist/proc/progress.d.ts

@@ -27,6 +27,13 @@ export interface JobProgress {
     source: 'row' | 'carry';
     /** Index into the scanned window; `-1` for the carry line. Diagnostics and tests only. */
     rowIndex: number;
+    /**
+     * 0..1 completion when the text carries a usable ratio, else `null`.
+     *
+     * A REPORT FOR THE PROGRESS BAR ONLY (extended-job-wait I-12): it never decides
+     * `status`, `[done]` or the spin guard.
+     */
+    fraction: number | null;
 }
 /**
  * Extract one line of progress from the tail of a job's output.

package/dist/proc/progress.js

@@ -34,7 +34,7 @@ const PERCENT = /(\d{1,3}(?:\.\d+)?)\s*%/;
 const EPOCH_STEP = /\b(epoch|step)\s+(\d{1,7})\s*\/\s*(\d{1,7})/i;
 const BYTES = /(\d+(?:\.\d+)?)\s*(GiB|MiB|KiB|GB|MB|KB|gb|mb|kb|gib|mib)?\s*\/\s*(\d+(?:\.\d+)?)\s*(GiB|MiB|KiB|GB|MB|KB|gb|mb|kb|gib|mib)/;
 const RATIO = /[\[(]?\b(\d{1,7})\s*\/\s*(\d{1,7})\b[\])]?/;
-const ETA = /ETA[^0-9]{0,4}([0-9:]+[a-z]*)/i;
+const ETA = /ETA[^0-9]{0,4}([0-9][0-9a-z:]*)/i;
 /** A row that is decoration, not information: `...`, `|`, `-`, `===`, a bare path separator. */
 const NOISE = /^[\s.\-_=|\\/+*#>~]+$/;
 /** Clip to the one-line budget, ASCII ellipsis, never mid-surrogate. */
@@ -48,6 +48,12 @@ function clip(text, limit = PROC_LIMITS.waitProgressChars) {
         return flat;
     return `${flat.slice(0, Math.max(0, limit - 3)).trimEnd()}...`;
 }
+/** `cur / total` as a fraction, or `null` when the total says nothing (`0/0`). */
+function ratioFraction(current, total) {
+    if (!Number.isFinite(current) || !Number.isFinite(total) || total <= 0)
+        return null;
+    return Math.min(1, Math.max(0, current / total));
+}
 /**
  * The structured signals for one line, in table order.
  *
@@ -57,22 +63,42 @@ function clip(text, limit = PROC_LIMITS.waitProgressChars) {
  */
 function signalsOf(line) {
     const percent = PERCENT.exec(line);
-    if (percent?.[1])
-        return { text: `${percent[1]}%`, kind: 'percent' };
+    if (percent?.[1]) {
+        return {
+            text: `${percent[1]}%`,
+            kind: 'percent',
+            fraction: ratioFraction(Number(percent[1]), 100),
+        };
+    }
     const epoch = EPOCH_STEP.exec(line);
     if (epoch?.[1] && epoch[2] !== undefined && epoch[3] !== undefined) {
-        return { text: `${epoch[1].toLowerCase()} ${epoch[2]}/${epoch[3]}`, kind: 'epoch' };
+        return {
+            text: `${epoch[1].toLowerCase()} ${epoch[2]}/${epoch[3]}`,
+            kind: 'epoch',
+            fraction: ratioFraction(Number(epoch[2]), Number(epoch[3])),
+        };
     }
     const bytes = BYTES.exec(line);
     if (bytes?.[1] && bytes[3]) {
         // Normalised to the TOTAL's unit, which is the one the user's own command
         // printed: `1.2/3.4 GiB` reads, `1.2 GiB/3.4 GiB` is noise. The numerator's
         // unit is optional because the common form writes it once, at the end.
-        return { text: `${bytes[1]}/${bytes[3]} ${bytes[4]}`, kind: 'bytes' };
+        // TWO UNITS THAT DIFFER ARE NOT COMPARED (no unit conversion): `512 MiB/3 GiB`
+        // would need a table, and a wrong bar is worse than an honest absence.
+        const sameUnit = !bytes[2] || bytes[2].toLowerCase() === bytes[4]?.toLowerCase();
+        return {
+            text: `${bytes[1]}/${bytes[3]} ${bytes[4]}`,
+            kind: 'bytes',
+            fraction: sameUnit ? ratioFraction(Number(bytes[1]), Number(bytes[3])) : null,
+        };
     }
     const ratio = RATIO.exec(line);
     if (ratio?.[1] && ratio[2] !== undefined) {
-        return { text: `${ratio[1]}/${ratio[2]}`, kind: 'ratio' };
+        return {
+            text: `${ratio[1]}/${ratio[2]}`,
+            kind: 'ratio',
+            fraction: ratioFraction(Number(ratio[1]), Number(ratio[2])),
+        };
     }
     return undefined;
 }
@@ -83,7 +109,7 @@ function withEta(signal, window) {
     for (const line of window) {
         const eta = ETA.exec(line);
         if (eta?.[1])
-            return { text: `${signal.text}  ETA ${eta[1]}`, kind: signal.kind };
+            return { ...signal, text: `${signal.text}  ETA ${eta[1]}` };
     }
     return signal;
 }
@@ -120,6 +146,7 @@ export function extractProgress(rows, carry) {
             kind: signal.kind,
             source: candidate.source,
             rowIndex: candidate.rowIndex,
+            fraction: signal.fraction,
         };
     }
     // Fallback: the newest line that at least says something.
@@ -131,5 +158,6 @@ export function extractProgress(rows, carry) {
         kind: 'text',
         source: last.source,
         rowIndex: last.rowIndex,
+        fraction: null,
     };
 }

package/dist/proc/prompt.js

@@ -53,10 +53,13 @@ export function buildBackgroundJobsBlock() {
         '- 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.',
+        '- Wait with job_wait({ job: "t1" }). Every wait is bounded (default 30s, at most 20',
+        '  minutes = timeoutSeconds 1200) and returns one status line, one progress line, and',
+        '  only the output since your last cursor. Prefer ONE long wait over several short',
+        '  ones: follow the [next] suggestion or the job\'s ETA. A wait ends the moment the job',
+        '  finishes or the user sends a message. Use job "any" to wake on the first of several',
+        '  jobs, "all" for the last. 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.',

package/dist/proc/supervisor.js

@@ -590,7 +590,13 @@ export class ProcSupervisor {
             // covered by AC-26 / AC-38 instead.
             lastOutputAt: r.lastOutputAt,
             ...(r.progress
-                ? { progress: { text: r.progress.text, kind: r.progress.kind } }
+                ? {
+                    progress: {
+                        text: r.progress.text,
+                        kind: r.progress.kind,
+                        fraction: r.progress.fraction,
+                    },
+                }
                 : {}),
             ...(this.isStalled(r) ? { stalled: true } : {}),
             ...(r.logPath !== undefined ? { logPath: r.logPath } : {}),

package/dist/proc/types.d.ts

@@ -33,6 +33,12 @@ export type JobKind = 'service' | 'task';
 export interface ServiceSnapshotProgress {
     text: string;
     kind: ProgressKind;
+    /**
+     * 0..1 completion for the wait card's bar, or `null`. REQUIRED, not optional:
+     * `snapshot()` hand-copies this literal, and a required field turns a forgotten
+     * copy into a compile error instead of a silently missing bar.
+     */
+    fraction: number | null;
 }
 export type ServiceStatus = 
 /** Spawned, not yet ready, still alive. */

package/dist/proc/wait-plan.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Wait-length advice for `job_wait` (extended-job-wait §3.5).
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope.
+ *
+ * PURE: no IO, no clock. The output is TEXT for the model (the `[next]` line) and
+ * nothing else (I-13): the tool never refuses or rewrites a wait because it
+ * differs from the suggestion, for the reason `[guard]` only hints. The aim is
+ * fewer, longer waits - one 10-minute wait costs one LLM round trip, twenty
+ * 30-second waits cost twenty.
+ */
+/** Sizes a suggestion snaps UP to, so the model sees round numbers it can reuse. */
+export declare const NICE_WAIT_SECONDS: readonly number[];
+/** The raw token after `ETA` in a progress line (`13m`, `01:23:45`), if any. */
+export declare function extractEtaText(progressText: string | undefined): string | undefined;
+/**
+ * Remaining seconds from the text after `ETA` in a progress line.
+ *
+ * Accepts `13m`, `45s`, `2h`, `13m20s`, `1h02m`, `01:23:45`, `12:30`, `0:45`.
+ * Anything else - including no `ETA` at all - is `undefined`; never throws.
+ */
+export declare function parseEtaSeconds(progressText: string | undefined): number | undefined;
+export interface SuggestWaitInput {
+    jobAgeMs: number;
+    /** The clamped request of the previous wait (not the time it actually ran). */
+    lastWaitSeconds: number;
+    /** Consecutive waits with no new row and no progress change. */
+    quietWaits: number;
+    etaSeconds?: number | undefined;
+    /** `jobs.waitSeconds`. */
+    configuredSeconds: number;
+    minSeconds: number;
+    maxSeconds: number;
+}
+/**
+ * The wait length to suggest next, deterministic and always within
+ * `[minSeconds, maxSeconds]`.
+ */
+export declare function suggestWaitSeconds(input: SuggestWaitInput): number;

package/dist/proc/wait-plan.js

@@ -0,0 +1,77 @@
+/**
+ * Wait-length advice for `job_wait` (extended-job-wait §3.5).
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope.
+ *
+ * PURE: no IO, no clock. The output is TEXT for the model (the `[next]` line) and
+ * nothing else (I-13): the tool never refuses or rewrites a wait because it
+ * differs from the suggestion, for the reason `[guard]` only hints. The aim is
+ * fewer, longer waits - one 10-minute wait costs one LLM round trip, twenty
+ * 30-second waits cost twenty.
+ */
+/** Sizes a suggestion snaps UP to, so the model sees round numbers it can reuse. */
+export const NICE_WAIT_SECONDS = [30, 60, 120, 180, 300, 420, 600, 900, 1200];
+const UNIT_SECONDS = { h: 3600, m: 60, s: 1 };
+/** The raw token after `ETA` in a progress line (`13m`, `01:23:45`), if any. */
+export function extractEtaText(progressText) {
+    if (progressText === undefined)
+        return undefined;
+    return /ETA[^0-9]{0,4}([0-9][0-9a-z:]*)/i.exec(progressText)?.[1];
+}
+/**
+ * Remaining seconds from the text after `ETA` in a progress line.
+ *
+ * Accepts `13m`, `45s`, `2h`, `13m20s`, `1h02m`, `01:23:45`, `12:30`, `0:45`.
+ * Anything else - including no `ETA` at all - is `undefined`; never throws.
+ */
+export function parseEtaSeconds(progressText) {
+    const value = extractEtaText(progressText)?.toLowerCase();
+    if (value === undefined)
+        return undefined;
+    if (value.includes(':')) {
+        const parts = value.split(':');
+        if (parts.length < 2 || parts.length > 3 || !parts.every((p) => /^\d{1,3}$/.test(p))) {
+            return undefined;
+        }
+        const numbers = parts.map(Number);
+        return numbers.length === 3
+            ? numbers[0] * 3600 + numbers[1] * 60 + numbers[2]
+            : numbers[0] * 60 + numbers[1];
+    }
+    const units = /^(?:\d+[hms])+$/.exec(value);
+    if (!units)
+        return undefined;
+    let total = 0;
+    for (const part of value.matchAll(/(\d+)([hms])/g)) {
+        total += Number(part[1]) * (UNIT_SECONDS[part[2]] ?? 0);
+    }
+    return total > 0 ? total : undefined;
+}
+/** Age ladder: the older the job, the longer one wait should be. */
+function ladderSeconds(jobAgeMs) {
+    if (jobAgeMs < 2 * 60_000)
+        return 30;
+    if (jobAgeMs < 10 * 60_000)
+        return 120;
+    if (jobAgeMs < 30 * 60_000)
+        return 300;
+    return 600;
+}
+/**
+ * The wait length to suggest next, deterministic and always within
+ * `[minSeconds, maxSeconds]`.
+ */
+export function suggestWaitSeconds(input) {
+    const finite = (n, fallback) => (Number.isFinite(n) ? n : fallback);
+    const ladder = ladderSeconds(finite(input.jobAgeMs, 0));
+    const last = finite(input.lastWaitSeconds, 0);
+    let candidate = input.quietWaits >= 2 ? Math.max(ladder, last * 2) : ladder;
+    // The ETA outranks the ladder: wait until just after the job says it is done.
+    // Early ETAs swing wildly, which is fine - the next result re-suggests.
+    if (input.etaSeconds !== undefined && Number.isFinite(input.etaSeconds)) {
+        candidate = input.etaSeconds + 15;
+    }
+    candidate = Math.max(candidate, finite(input.configuredSeconds, 0));
+    const snapped = NICE_WAIT_SECONDS.find((n) => n >= candidate) ?? input.maxSeconds;
+    return Math.max(input.minSeconds, Math.min(snapped, input.maxSeconds));
+}

package/dist/proc/wait-view.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The view model behind the wait card (extended-job-wait §3.8.1).
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope.
+ *
+ * PURE: `buildWaitView` reads nothing but its arguments. The card and the status
+ * bar are projections of the object it returns, which is why every clock in the
+ * UI can be a subtraction between an epoch stamped here and the one `nowSec` the
+ * renderer already has (no second timer, no second spinner).
+ */
+import type { ProgressKind } from './progress.js';
+import type { ServiceSnapshot, ServiceStatus } from './types.js';
+export interface WaitView {
+    toolCallId: string;
+    /** `t3` for one job, `3 jobs` for several. */
+    jobLabel: string;
+    /** The single job's command, clipped; empty when several jobs are awaited. */
+    command: string;
+    /** Epoch ms the wait began. */
+    waitStartedAt: number;
+    /** The clamped budget of this wait, in ms. */
+    upToMs: number;
+    /** Epoch ms of the beat that produced this view; lets a pure consumer tell "how long" without a clock. */
+    beatAt: number;
+    mode: 'all' | 'any';
+    liveJobs: number;
+    /** Earliest `startedAt` among the targets (epoch ms). */
+    jobStartedAt: number;
+    /** The single job's status; `running` when several are awaited. */
+    status: ServiceStatus;
+    progress?: {
+        text: string;
+        kind: ProgressKind;
+        fraction: number | null;
+    };
+    /** Newest non-empty output row, sanitised and clipped. */
+    lastRow?: string;
+    /** Latest `lastOutputAt` among the targets (epoch ms). */
+    lastOutputAt: number;
+    stalled: boolean;
+    stallSeconds: number;
+}
+export type WaitEndReason = 'terminal' | 'timeout' | 'abort' | 'wake';
+export type WaitEvent = {
+    type: 'begin' | 'update';
+    toolCallId: string;
+    view: WaitView;
+} | {
+    type: 'end';
+    toolCallId: string;
+    reason: WaitEndReason;
+};
+export type WaitListener = (event: WaitEvent) => void;
+export interface BuildWaitViewInput {
+    toolCallId: string;
+    /** The awaited jobs' current snapshots. Empty yields `undefined`. */
+    snapshots: readonly ServiceSnapshot[];
+    mode: 'all' | 'any';
+    waitStartedAt: number;
+    upToMs: number;
+    nowMs: number;
+    stallSeconds: number;
+}
+/** Project the awaited jobs into one card-sized view; `undefined` when none remain. */
+export declare function buildWaitView(input: BuildWaitViewInput): WaitView | undefined;

package/dist/proc/wait-view.js

@@ -0,0 +1,66 @@
+/**
+ * The view model behind the wait card (extended-job-wait §3.8.1).
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope.
+ *
+ * PURE: `buildWaitView` reads nothing but its arguments. The card and the status
+ * bar are projections of the object it returns, which is why every clock in the
+ * UI can be a subtraction between an epoch stamped here and the one `nowSec` the
+ * renderer already has (no second timer, no second spinner).
+ */
+import { isTerminalStatus } from './types.js';
+const COMMAND_CHARS = 80;
+const LAST_ROW_CHARS = 200;
+function clip(text, limit) {
+    // Control characters become spaces so a stray escape can never reach the card.
+    const flat = text.replace(/[\u0000-\u001f\u007f]+/g, ' ').trim();
+    return flat.length <= limit ? flat : `${flat.slice(0, Math.max(0, limit - 3)).trimEnd()}...`;
+}
+function newestRow(rows) {
+    for (let i = rows.length - 1; i >= 0; i -= 1) {
+        const row = clip(rows[i] ?? '', LAST_ROW_CHARS);
+        if (row.length > 0)
+            return row;
+    }
+    return undefined;
+}
+/** Project the awaited jobs into one card-sized view; `undefined` when none remain. */
+export function buildWaitView(input) {
+    const { snapshots } = input;
+    const first = snapshots[0];
+    if (first === undefined)
+        return undefined;
+    const single = snapshots.length === 1;
+    // The job that spoke last supplies the "latest output" row of a multi-job wait.
+    const freshest = snapshots.reduce((a, b) => (b.lastOutputAt > a.lastOutputAt ? b : a), first);
+    const lastOutputAt = freshest.lastOutputAt;
+    const lastRow = newestRow(freshest.rows);
+    const live = snapshots.filter((job) => !isTerminalStatus(job.status));
+    const progress = single ? first.progress : undefined;
+    const quietMs = Math.max(0, input.nowMs - lastOutputAt);
+    return {
+        toolCallId: input.toolCallId,
+        jobLabel: single ? first.id : `${snapshots.length} jobs`,
+        command: single ? clip(first.command, COMMAND_CHARS) : '',
+        waitStartedAt: input.waitStartedAt,
+        upToMs: input.upToMs,
+        beatAt: input.nowMs,
+        mode: input.mode,
+        liveJobs: live.length,
+        jobStartedAt: Math.min(...snapshots.map((job) => job.startedAt)),
+        status: single ? first.status : 'running',
+        ...(progress
+            ? {
+                progress: {
+                    text: progress.text,
+                    kind: progress.kind,
+                    fraction: progress.fraction,
+                },
+            }
+            : {}),
+        ...(lastRow !== undefined ? { lastRow } : {}),
+        lastOutputAt,
+        stalled: live.length > 0 && quietMs > input.stallSeconds * 1000,
+        stallSeconds: input.stallSeconds,
+    };
+}

package/dist/proc/wait.d.ts

@@ -23,33 +23,66 @@
  *     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.
+ *  5. THE HEARTBEAT RE-CHECKS THE DEADLINE AGAINST `now()`, NOT AGAINST THE
+ *     TIMER (extended-job-wait). A 20-minute wait spans a laptop lid: Node's
+ *     monotonic `setTimeout` does not count the sleep, so a "10 minute" wait can
+ *     run 40 minutes of wall clock. Each beat compares `now() - startedAt` with
+ *     the budget and settles on the first beat after resume.
+ *
+ * THE WAKE SOURCE IS EDGE-TRIGGERED ONLY - there is no "is something pending"
+ * probe. The engine drains steering before EVERY tool execution
+ * (`core/src/engine/agent-loop.ts`), so input that arrived before this wait began
+ * has already been accepted; only input that arrives AFTER `subscribe()` needs to
+ * end the wait. Between the engine's decision to run `job_wait` and the
+ * `subscribe()` below there is no `await`, so no notification can fall into the
+ * gap. A level-triggered probe would add a stale-state hot loop (every wait
+ * returning at once) for no reachable gain.
  */
 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'>;
+/** Anything that can say "the user just spoke". Edge-triggered; see rule 5 above. */
+export interface WakeSource {
+    /** Calls `listener` once per new user input after this call; returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+}
 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`). */
+    /** Already clamped by the caller (`jobs.waitSeconds` 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;
+    /** 'all' (default): every target must end. 'any': the first terminal target ends the wait. */
+    mode?: 'all' | 'any';
+    /** User-input wake source; absent for a sub-agent, a test or an old caller. */
+    wakeOn?: WakeSource;
+    /** Beat that drives the live view and re-checks the deadline against `now()`. */
+    heartbeat?: {
+        everyMs: number;
+        onBeat: (nowMs: number) => void;
+    };
 }
 export interface JobWaitOutcome {
     /** One snapshot per target that still exists, in the requested order. */
     jobs: ServiceSnapshot[];
-    /** Every target reached a terminal status. */
+    /**
+     * `mode: 'all'` (default): every target reached a terminal status.
+     * `mode: 'any'`: at least one did.
+     */
     terminal: boolean;
     waitedMs: number;
     timedOut: boolean;
     aborted: boolean;
+    /** The wait ended because the user sent a message. */
+    woken: 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.
+ * Wait up to `timeoutMs` for the targets 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.