@aragon-agent/cli 0.6.46 → 0.6.47

package/CHANGELOG.md

@@ -8,6 +8,21 @@ were written.
 ## Unreleased
 
 ### Added
+- **Long waits: `job_wait` now waits up to 20 minutes, and the wait looks like it.**
+  `timeoutSeconds` takes any integer from 5 to 1200 (it used to stop at 60, and at 150 with the
+  default `toolTimeoutMs`, because the tool ceiling silently pulled it down). `job_wait` gets its own
+  executor ceiling (1230 s) and pauses the idle watchdog for the whole wait, so `toolTimeoutMs` no
+  longer limits it and `jobs.waitSeconds` accepts 5-1200. **Typing a message ends the wait at once**
+  (result line `[woke] ...`, the job keeps running, no `Esc` needed); reviewer notes and completion
+  notices do not. While waiting, the tool card is replaced by a fixed five-row card - a progress bar
+  (the job's own progress when it prints any, otherwise the wait window), both clocks, the job's
+  newest output with "N s ago", a calm "not a failure" note after `jobs.stallSeconds` of silence, and
+  a hint that a message ends the wait - and the status bar reads `Waiting on t3 4m12s/10m00s`. New:
+  `job: "any"` (return on the first job to end), a `[next]` suggestion with a `timeoutSeconds` (and the
+  job's ETA) so the model prefers one long wait to many short ones, and `[note]` when a request is
+  clamped to the ceiling. No new config keys; `jobs.enabled=false` is byte-identical to before.
+  Honest limit: while a wait runs the idle check is off, so a stuck wait is ended by its own 20-minute
+  bound, the executor backstop, or you.
 - **Governance mode - a multi-agent "legion" collaboration posture.** `Shift+Tab` (and `Ctrl+N`)
   now cycle `BUILD -> PLAN -> GOVERN -> PLAN+GOVERN -> BUILD`; `/gov` goes to any of them
   directly. In `GOVERN` the main agent becomes an **Orchestrator** that cannot write files or run

package/README.md

@@ -2068,13 +2068,60 @@ longer reads "not ready yet, still coming up" for its first minute.
 Two tools manage them:
 
 - `job_wait({ job, timeoutSeconds?, since? })` — block up to a bound (default 30s,
-  at most 60s) and return one status line, one progress line, at most six new
-  output rows and a cursor. It returns immediately if the job already finished.
-  This is the point of the feature: waiting 30 seconds used to cost six
-  `bash_output` calls, six model turns and six 200-row tails; it now costs one
-  call and about 150 tokens.
+  **at most 20 minutes**: `timeoutSeconds` takes any integer from 5 to 1200) and
+  return one status line, one progress line, at most six new output rows and a
+  cursor. It returns immediately if the job already finished, and it also ends
+  the moment **you send a message** (see below). `job` is an id, `"all"` (until
+  every live job ends) or `"any"` (until the first one ends). This is the point
+  of the feature: waiting 30 seconds used to cost six `bash_output` calls, six
+  model turns and six 200-row tails; it now costs one call and about 150 tokens,
+  and a 40-minute training run costs a handful of calls instead of dozens.
 - `job_list()` — one line per job: id, kind, status, elapsed, progress.
 
+### Long waits
+
+A wait can now last up to 20 minutes, so three things keep it safe and visible:
+
+- **You can always interrupt it by typing.** Send a message while the agent is
+  waiting and the wait ends at once; the result says `[woke] you sent a message...`,
+  your message is delivered next, and the job keeps running. You do not need
+  `Esc`, which would stop the whole run. (Automatic notes, such as a reviewer's
+  or a completion notice, do not end a wait. If the agent had queued more tool
+  calls in the same step, the engine skips them when your message arrives, as it
+  does for any message sent mid-step.)
+- **The wait is drawn as a five-row card** instead of a bare "running":
+
+  ```
+  ⠹ Waiting for t3  python train.py --epochs 10                 4m12s of 10m00s
+    │ ████████░░░░░░░░░░░░░░░░░░░░  30%  epoch 3/10  ETA 13m
+    │ job running 42m04s · this wait ends in 5m48s, or sooner if the job finishes
+    │ step 912/1000  loss 0.4098                                           3s ago
+    │ Send a message to end the wait early · Esc x2 stops the whole run
+  ```
+
+  The bar shows the job's own progress when it prints any, and otherwise the
+  wait window itself (the words say which). After `jobs.stallSeconds` of silence
+  the output row becomes a calm
+  `quiet for 6m02s - the job is still alive; this is not a failure`. The status
+  bar and activity line carry the same clock (`Waiting on t3 4m12s/10m00s`).
+  The card is always five rows, uses ASCII glyphs on terminals without Unicode,
+  and keeps its numbers moving under reduced motion. It disappears when the wait
+  ends and leaves the usual one-line history row.
+- **The idle watchdog is paused for the length of the wait**, and `toolTimeoutMs`
+  no longer limits it: `job_wait` gets its own executor ceiling (20 minutes plus
+  30 seconds). The honest cost is that a wait which is itself stuck is only
+  caught by that ceiling and by you (`Esc x2`), not by the 3.5-minute idle check.
+
+Results suggest the next wait: when the job reports an ETA or has been running for
+a while, the `[next]` line carries a `timeoutSeconds` worth using (for example
+`timeoutSeconds: 900 ... (ETA about 13m)`) so the agent prefers one long wait to
+many short ones. It is advice, never enforced. A request over 1200 seconds is
+clamped and says so (`[note] timeoutSeconds 3600 exceeds the 1200s ceiling`).
+
+Cost note: a wait longer than your provider's prompt-cache lifetime (often five
+minutes) means the next request re-reads the context uncached. That is still far
+cheaper than the dozens of model turns short polling would have spent.
+
 Nothing else tells the model a job finished. When one ends while it is busy, a
 `<job_notices>` block appears at the end of the next tool result:
 
@@ -2114,7 +2161,7 @@ to use it — `grep` and `read_file` already exist.
 | Key | Default | Meaning |
 |---|---|---|
 | `jobs.enabled` | `true` | Register `job_wait`/`job_list`, splice the prompt block. `false` restores the pre-feature build byte for byte. |
-| `jobs.waitSeconds` | `30` | Default bound for one wait, 5–60. Also lowered automatically so a wait always fits inside the tool ceiling. |
+| `jobs.waitSeconds` | `30` | Default bound for one wait, 5–1200. No longer lowered by `toolTimeoutMs`. |
 | `jobs.stallSeconds` | `300` | Silence before `[stalled]`, 30–3600. |
 | `jobs.persistLog` | `true` | Mirror each job's output to disk. `false` creates no directory at all. |
 | `jobs.noticeSteer` | `true` | Whether a completion notice may interrupt a running turn. `false` keeps the notice for the next tool result or the next user turn — it is **not** a notification off switch. |

package/dist/agent/coalesce.d.ts

@@ -16,6 +16,10 @@
  * concatenating, and a differing id starts a new pending action because merging
  * across ids would paint one command's output onto another's card.
  *
+ * A FOURTH ARRIVED WITH THE LONG WAIT (extended-job-wait RV-6): `waitUpdate`
+ * carries the WHOLE view, so it merges exactly like the tool tail - same
+ * `toolCallId` keeps the last, a different id or any other action flushes first.
+ *
  * ONE PENDING SLOT, DISCRIMINATED, NEVER TWO (P1-5). A second, independent slot
  * for the object-shaped payload would let a chunk overtake a token and reorder
  * the two streams — exactly what I-L4-1 (`ui/render-governor.ts:14-19`) forbids:

package/dist/agent/coalesce.js

@@ -16,6 +16,10 @@
  * concatenating, and a differing id starts a new pending action because merging
  * across ids would paint one command's output onto another's card.
  *
+ * A FOURTH ARRIVED WITH THE LONG WAIT (extended-job-wait RV-6): `waitUpdate`
+ * carries the WHOLE view, so it merges exactly like the tool tail - same
+ * `toolCallId` keeps the last, a different id or any other action flushes first.
+ *
  * ONE PENDING SLOT, DISCRIMINATED, NEVER TWO (P1-5). A second, independent slot
  * for the object-shaped payload would let a chunk overtake a token and reorder
  * the two streams — exactly what I-L4-1 (`ui/render-governor.ts:14-19`) forbids:
@@ -28,6 +32,9 @@ function isTextDelta(action) {
 function isToolOutputDelta(action) {
     return action.type === 'toolOutputDelta';
 }
+function isWaitUpdate(action) {
+    return action.type === 'waitUpdate';
+}
 /** Merge consecutive same-kind deltas; flush on kind change or a non-delta. */
 export function mergeDeltas(actions) {
     const out = [];
@@ -70,6 +77,12 @@ export function mergeDeltas(actions) {
             // increment, so merging means replacing (D-30).
             pending = { kind: 'tool', action };
         }
+        else if (isWaitUpdate(action)) {
+            const merges = prev !== null && prev.kind === 'wait' && prev.action.toolCallId === action.toolCallId;
+            if (!merges)
+                flush();
+            pending = { kind: 'wait', action };
+        }
         else {
             flush();
             out.push(action);

package/dist/agent/controller.d.ts

@@ -28,6 +28,7 @@ import type { SubagentModelResolution } from '../team/model.js';
 import type { ForcedTeamState } from '../team/forced-mode.js';
 import type { TeamEvent, TeamSnapshot } from '../team/types.js';
 import { ProcSupervisor } from '../proc/supervisor.js';
+import type { WaitEvent } from '../proc/wait-view.js';
 import type { ProcEventListener, ServiceSnapshot } from '../proc/types.js';
 import { type FastStatus } from '../fast/wiring.js';
 import type { FastEventListener, FastSnapshot } from '../fast/types.js';
@@ -350,6 +351,10 @@ export declare class AgentController {
      */
     private readonly toolOutputs;
     private readonly outputListeners;
+    /** `job_wait` live-view listeners (extended-job-wait); see `subscribeWait`. */
+    private readonly waitListeners;
+    /** "The user just spoke": ends a running `job_wait` early. */
+    private readonly userAttention;
     private readonly fast;
     private readonly compaction;
     private settingsRevision;
@@ -768,6 +773,12 @@ export declare class AgentController {
      * rather than a counter, so a nested call's `finally` re-arms the watchdog
      * while the outer wait is still going. That is why a child's `--confirm`
      * dialog does NOT route through this (see the constructor's `humanQueue`).
+     *
+     * `job_wait` ALSO DEPENDS ON THAT (extended-job-wait I-3): it holds the pause for
+     * up to 20 minutes and is safe only because the engine runs a batch's tools
+     * one at a time. If tool execution ever becomes parallel, make this a COUNTER
+     * first - otherwise the first tool to finish re-arms the watchdog under a
+     * still-waiting sibling, which then kills the run at the idle timeout.
      */
     withPausedWatchdog<T>(fn: () => Promise<T>): Promise<T>;
     /** @see withPausedWatchdog — the name the plan tools and `--confirm` use. */
@@ -1026,6 +1037,16 @@ export declare class AgentController {
      * `warn` because a listener that throws once throws on every chunk.
      */
     private emitToolOutput;
+    /**
+     * Subscribe to `job_wait`'s live view (`begin` / 1 Hz `update` / `end`).
+     *
+     * NOT GATED ON `liveToolOutput` (extended-job-wait D-9): that switch bounds a
+     * high-frequency byte stream; this channel is capped at 1 Hz, and switching it
+     * off would bring back the 20-minute black box.
+     */
+    subscribeWait(listener: (event: WaitEvent) => void): () => void;
+    /** Fan out one wait event; a throwing listener is logged and skipped (I-6). */
+    private emitWait;
     /**
      * Subscribe to the CLI-local live tool-output stream (§3.1.3).
      *

package/dist/agent/controller.js

@@ -27,7 +27,8 @@ import { buildForcedTeamBlock } from '../team/forced-prompt.js';
 import { buildFastBlock } from '../fast/prompt.js';
 import { ProcSupervisor } from '../proc/supervisor.js';
 import { buildBackgroundJobsBlock, buildBackgroundServicesBlock } from '../proc/prompt.js';
-import { PROC_LIMITS } from '../proc/limits.js';
+import { JOB_WAIT_TOOL_CEILING_MS, PROC_LIMITS } from '../proc/limits.js';
+import { createUserAttention } from './user-attention.js';
 import { JobLogMirror } from '../proc/log-mirror.js';
 import { JobNoticeQueue } from '../proc/notices.js';
 import { makeBashKill, makeBashOutput } from '../tools/proc-tools.js';
@@ -261,6 +262,10 @@ export class AgentController {
      */
     toolOutputs;
     outputListeners = new Set();
+    /** `job_wait` live-view listeners (extended-job-wait); see `subscribeWait`. */
+    waitListeners = new Set();
+    /** "The user just spoke": ends a running `job_wait` early. */
+    userAttention = createUserAttention();
     // -----------------------------------------------------------------------
     // Fast model tier (fast-model-tier §3.1 / §3.3)
     //
@@ -735,15 +740,19 @@ export class AgentController {
                         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 THREE LONG-WAIT PORTS (extended-job-wait). `holdWatchdog` wraps the
+                        // WHOLE wait because tools run one at a time (I-3); `attention` is
+                        // subscribe-only (RV-1); the view listener never throws back (I-6).
+                        onWait: (event) => this.emitWait(event),
+                        holdWatchdog: (fn) => this.withPausedWatchdog(fn),
+                        attention: { subscribe: (listener) => this.userAttention.subscribe(listener) },
                     }),
                     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),
                     }),
@@ -961,6 +970,13 @@ export class AgentController {
                     // outlived a mid-session `Settings > Team` switch to the supervisor
                     // and killed the dispatch the supervisor was meant to look after.
                     ...(this.teamRegistered ? { task: 0 } : {}),
+                    // THE EXECUTOR'S OWN CLOCK FOR A LONG WAIT (extended-job-wait I-2 / I-4').
+                    // Without it `job_wait` falls onto `toolTimeoutMs` (180 s) and a 20-minute
+                    // wait dies at three; with `0` the wait would have no independent backstop
+                    // while the watchdog is paused. A finite value derived from the one
+                    // authority, `PROC_LIMITS.waitMaxSeconds`, is both. `jobsRegistered` is
+                    // assigned in the constructor before this table is built.
+                    ...(this.jobsRegistered ? { job_wait: JOB_WAIT_TOOL_CEILING_MS } : {}),
                     // P0 (governance-mode D-21 / RV-0): `gov_dispatch` runs a whole governed stage,
                     // routinely longer than `toolTimeoutMs`, and it listens to `ctx.signal` (it hands
                     // it to `TeamRuntime.dispatch`), which is what makes `0` safe. Registered in the SAME
@@ -1587,6 +1603,10 @@ export class AgentController {
                 this.pendingUserSteering.delete(id);
             throw error;
         }
+        // AFTER a successful steer, and ONLY for user input (I-7): a reviewer or a job
+        // notice must not cut short the wait the user chose.
+        if (user)
+            this.userAttention.notify();
         return id;
     }
     followUp(text) {
@@ -1948,6 +1968,12 @@ export class AgentController {
      * rather than a counter, so a nested call's `finally` re-arms the watchdog
      * while the outer wait is still going. That is why a child's `--confirm`
      * dialog does NOT route through this (see the constructor's `humanQueue`).
+     *
+     * `job_wait` ALSO DEPENDS ON THAT (extended-job-wait I-3): it holds the pause for
+     * up to 20 minutes and is safe only because the engine runs a batch's tools
+     * one at a time. If tool execution ever becomes parallel, make this a COUNTER
+     * first - otherwise the first tool to finish re-arms the watchdog under a
+     * still-waiting sibling, which then kills the run at the idle timeout.
      */
     async withPausedWatchdog(fn) {
         this.agent.pauseIdleWatchdog();
@@ -2501,6 +2527,33 @@ export class AgentController {
             }
         }
     }
+    /**
+     * Subscribe to `job_wait`'s live view (`begin` / 1 Hz `update` / `end`).
+     *
+     * NOT GATED ON `liveToolOutput` (extended-job-wait D-9): that switch bounds a
+     * high-frequency byte stream; this channel is capped at 1 Hz, and switching it
+     * off would bring back the 20-minute black box.
+     */
+    subscribeWait(listener) {
+        this.waitListeners.add(listener);
+        return () => {
+            this.waitListeners.delete(listener);
+        };
+    }
+    /** Fan out one wait event; a throwing listener is logged and skipped (I-6). */
+    emitWait(event) {
+        for (const listener of this.waitListeners) {
+            try {
+                listener(event);
+            }
+            catch (err) {
+                getLogger().debug('tool', 'wait_listener_threw', {
+                    toolCallId: event.toolCallId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+    }
     /**
      * Subscribe to the CLI-local live tool-output stream (§3.1.3).
      *

package/dist/agent/reducer.d.ts

@@ -19,6 +19,7 @@ import type { FastReview, FastSnapshot } from '../fast/types.js';
 import type { CompactionMode, CompactionPhase, CompactionRecord, CompactionSnapshot, CompactionUiTrigger, ContextUsageSnapshot } from '../compaction/types.js';
 import type { AcceptanceSnapshot, TodoItem, TodoSnapshot } from '../todo/types.js';
 import type { JobKind, ServiceSnapshot, ServiceStatus } from '../proc/types.js';
+import type { WaitView } from '../proc/wait-view.js';
 import type { RetryPhase } from './retry-view.js';
 import type { FilePatch } from '../tools/patch.js';
 import type { TaskSummaryView } from '../fast/task-summary-types.js';
@@ -140,6 +141,16 @@ export type Entry = {
     liveSeq?: number;
     /** Epoch ms of the last output row, for the stall row (§3.3.4). */
     lastOutputAt?: number;
+    /**
+     * The live view of a running `job_wait` (extended-job-wait §3.8.1), refreshed
+     * at 1 Hz. RUNTIME ONLY, and it lives and dies with `live` (I-9): cleared by
+     * `toolExecEnd` AND by every idle path through `releaseLiveTails`, and never
+     * persisted. `job_wait` never streams, so `live` is always empty for it - which
+     * is exactly why the idle clean-up cannot key off `live` alone.
+     */
+    wait?: WaitView;
+    /** Monotonic counter: the revision term that invalidates the render cache. */
+    waitSeq?: number;
 } | {
     id: string;
     kind: 'notice';
@@ -580,6 +591,15 @@ export type ViewAction = {
     toolCallId: string;
     rows: readonly string[];
     at: number;
+}
+/**
+ * `job_wait`'s 1 Hz view (extended-job-wait). Carries the WHOLE view, so the
+ * coalescer keeps only the last per `toolCallId`, like `toolOutputDelta`.
+ */
+ | {
+    type: 'waitUpdate';
+    toolCallId: string;
+    view: WaitView;
 } | {
     type: 'turnEnd';
     usage: TokenUsage;

package/dist/agent/reducer.js

@@ -400,12 +400,22 @@ function settleRetryCard(state, entries, phase) {
 function releaseLiveTails(entries) {
     let touched = false;
     const next = entries.map((e) => {
-        if (e.kind !== 'tool' || !e.live)
+        // `!e.live && !e.wait`, NOT `!e.live` (extended-job-wait RV-2): a `job_wait`
+        // never streams, so its `live` is always empty and the old guard would skip it,
+        // leaving a wait card that says "running" in the transcript forever.
+        if (e.kind !== 'tool' || (!e.live && !e.wait))
             return e;
         if (e.status !== 'running' && e.status !== 'pending')
             return e;
         touched = true;
-        return { ...e, live: undefined, lastOutputAt: undefined, liveSeq: (e.liveSeq ?? 0) + 1 };
+        return {
+            ...e,
+            live: undefined,
+            lastOutputAt: undefined,
+            liveSeq: (e.liveSeq ?? 0) + 1,
+            wait: undefined,
+            waitSeq: (e.waitSeq ?? 0) + 1,
+        };
     });
     return touched ? next : entries;
 }
@@ -669,6 +679,23 @@ export function viewReducer(state, action) {
                     : e),
             };
         }
+        /**
+         * ONLY A RUNNING, MATCHING ENTRY. `begin` travels from the controller and can
+         * beat `tool_execution_start` through the agent-event pipe, so a miss is
+         * normal and is dropped on purpose: the next 1 Hz beat repairs it (RV-5).
+         */
+        case 'waitUpdate': {
+            const id = findToolEntryId(state, action.toolCallId);
+            if (!id)
+                return state;
+            const target = state.entries.find((e) => e.id === id);
+            if (!target || target.kind !== 'tool' || target.status !== 'running')
+                return state;
+            return {
+                ...state,
+                entries: mapEntry(state.entries, id, (e) => e.kind === 'tool' ? { ...e, wait: action.view, waitSeq: (e.waitSeq ?? 0) + 1 } : e),
+            };
+        }
         case 'toolExecEnd': {
             const id = findToolEntryId(state, action.toolCallId);
             if (!id)
@@ -689,6 +716,8 @@ export function viewReducer(state, action) {
                         // `bashBadge`'s last-line parse (`ToolPreview.tsx:35-54`).
                         live: undefined,
                         lastOutputAt: undefined,
+                        wait: undefined,
+                        waitSeq: undefined,
                     }
                     : e),
             };

package/dist/agent/user-attention.d.ts

@@ -0,0 +1,17 @@
+/**
+ * "The user just spoke" as a subscribable edge (extended-job-wait §3.4).
+ *
+ * ASCII ONLY: `src/agent/**` is inside the glyph scanner's scope.
+ *
+ * EDGE-TRIGGERED ON PURPOSE: there is no "is anything pending" probe. A wait that
+ * could be woken by pre-existing state would return at once whenever that state
+ * went stale, and a model that gets an instant return from every `job_wait` burns
+ * tokens in a hot loop. Only a `notify()` that happens after `subscribe()` counts.
+ */
+export interface UserAttention {
+    /** Announce one new user input to every current subscriber. */
+    notify(): void;
+    /** Register a listener; returns its unsubscribe. */
+    subscribe(listener: () => void): () => void;
+}
+export declare function createUserAttention(): UserAttention;

package/dist/agent/user-attention.js

@@ -0,0 +1,32 @@
+/**
+ * "The user just spoke" as a subscribable edge (extended-job-wait §3.4).
+ *
+ * ASCII ONLY: `src/agent/**` is inside the glyph scanner's scope.
+ *
+ * EDGE-TRIGGERED ON PURPOSE: there is no "is anything pending" probe. A wait that
+ * could be woken by pre-existing state would return at once whenever that state
+ * went stale, and a model that gets an instant return from every `job_wait` burns
+ * tokens in a hot loop. Only a `notify()` that happens after `subscribe()` counts.
+ */
+export function createUserAttention() {
+    const listeners = new Set();
+    return {
+        notify() {
+            // Snapshot first: a listener may unsubscribe itself while we iterate.
+            for (const listener of [...listeners]) {
+                try {
+                    listener();
+                }
+                catch {
+                    // One broken listener must not deprive the others of the wake-up.
+                }
+            }
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+}

package/dist/cli.js

@@ -1765,9 +1765,8 @@ function runConfigSetValue(key, value) {
     const jobsPatch = applyJobsConfigSet(key, value);
     if (jobsPatch) {
         // Echoed from the STORED value, so `config set jobs.waitSeconds 1` prints 5
-        // and `jobs.waitSeconds 9999` prints 60 — the rule every section above
-        // states. It matters here too: `waitSeconds` is ALSO converged against the
-        // tool ceiling by I-4, so the stored value is the only honest answer.
+        // and `jobs.waitSeconds 9999` prints 1200 — the rule every section above
+        // states.
         const merged = updatePersistedConfig(jobsPatch);
         const field = key.slice('jobs.'.length);
         process.stdout.write(`Set ${key} = ${String(merged.jobs[field])}\n`);

package/dist/config/load.js

@@ -6,7 +6,6 @@
  * legitimately long single tool run can never be watchdog-killed.
  */
 import process from 'node:process';
-import { JOB_WAIT_MARGIN_MS } from '../proc/limits.js';
 import { DEFAULT_CONFIG, DEFAULT_SCROLL_MODE, IDLE_TIMEOUT_MARGIN_MS, clampDensity, clampHumanTimeout, clampCompactionConfig, clampLogConfig, clampFastConfig, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampBashConfig, clampJobsConfig, clampPromptsConfig, clampTaskSummaryConfig, clampUpdateConfig, clampTheme, clampThinkingLevel, clampContextWindow, clampMaxTokens, clampMaxRenderInterval, clampScrollMode, clampScrollResumeMs, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAutoToken, isSkillsToolPolicyMode, legacyTeamCeilingPatch, legacyTeamFanoutPatch, LEGACY_TEAM_FANOUT_DEFAULTS, parseThresholdInput, } from './schema.js';
 import { loadDotenv, readEnvConfig, readEnvDisabledSkills } from './env.js';
 import { readConfigFile, updatePersistedConfig } from './store.js';
@@ -622,32 +621,14 @@ export function loadConfig(flags = {}, options = {}) {
         DEFAULT_CONFIG.planModeDefault;
     const planModeHumanTimeoutMs = clampHumanTimeout(file.planModeHumanTimeoutMs, DEFAULT_CONFIG.planModeHumanTimeoutMs);
     const toolTimeoutMs = coercePositiveInt(pick(flags.toolTimeout, file.toolTimeoutMs), DEFAULT_CONFIG.toolTimeoutMs);
-    // THE `jobs` SECTION IS RESOLVED HERE, ABOVE THE TIMEOUT BLOCK, and the
-    // position is the whole of RV-P1-2. The design's first draft put the I-4 clamp
-    // next to the `idleTimeoutMs` invariant below, but `jobs` is parsed inside the
-    // big config literal a hundred lines further down — a reference to it here would
-    // be a use-before-declaration, and "resolve it later and patch the object" is
-    // how the invariant gets silently skipped. Resolving it first makes the clamp
-    // impossible to omit.
+    // `jobs.waitSeconds` is NOT converged against `toolTimeoutMs` (extended-job-wait
+    // I-4'): `job_wait` has its own executor ceiling and pauses the idle watchdog,
+    // so the section is resolved once, as-is.
     const jobs = resolveJobsConfig(env.partial, file);
     let idleTimeoutMs = coercePositiveInt(pick(flags.idleTimeout, file.idleTimeoutMs), DEFAULT_CONFIG.idleTimeoutMs);
     // Timeout invariant (R1): idle must be strictly greater than the tool ceiling
     // so a long single tool run is never aborted by the idle watchdog.
     idleTimeoutMs = Math.max(idleTimeoutMs, toolTimeoutMs + IDLE_TIMEOUT_MARGIN_MS);
-    // INVARIANT I-4 (long-task-jobs): a wait must fit inside the tool call that
-    // hosts it, `jobs.waitSeconds * 1000 + JOB_WAIT_MARGIN_MS <= toolTimeoutMs`.
-    //
-    // `Math.min`, AND THE DIRECTION IS THE POINT. The invariant above RAISES the
-    // idle window to accommodate the tool; this one LOWERS the wait to accommodate
-    // the tool. Copying `Math.max` here would produce a wait that outlives its own
-    // tool call — which is exactly the `Command timed out` failure the feature
-    // exists to remove, re-created by its own config check.
-    //
-    // With an operator-set ceiling below the margin the floor of 1s applies rather
-    // than a negative wait: the invariant wins over the minimum, because a wait
-    // longer than its host is worse than a short wait.
-    const waitCeilingSeconds = Math.floor((toolTimeoutMs - JOB_WAIT_MARGIN_MS) / 1000);
-    jobs.waitSeconds = Math.max(1, Math.min(jobs.waitSeconds, waitCeilingSeconds));
     // Resolve API keys: config-file key wins over the provider env var.
     const fileKeys = file.apiKeys ?? {};
     const apiKeys = {};
@@ -798,9 +779,7 @@ export function loadConfig(flags = {}, options = {}) {
         update: resolveUpdateConfig(flags, env.partial, file),
         compaction: resolveCompactionConfig(flags, env.partial, file),
         bash: resolveBashConfig(env.partial, file),
-        // The already-resolved-and-converged section from the timeout block above.
-        // NOT `resolveJobsConfig(...)` a second time: that would re-apply the
-        // un-converged `waitSeconds` and silently undo I-4.
+        // The already-resolved section from the top of this function.
         jobs,
         // The quick-prompt library's three policy scalars (quick-prompt-library D-19).
         // Resolved through the SAME clamp the read and write paths use, so an env-only

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;