@aragon-agent/cli 0.6.46 → 0.6.48

package/dist/governance/tools/shared-tools.js

@@ -15,7 +15,7 @@
  * different agent.
  */
 import { textResult } from '@aragon-agent/core';
-import { GOV_LIMITS } from '../limits.js';
+import { GOV_LIMITS } from '@aragon-agent/tui/model/governance/limits';
 import { Issues, formatNotAccepted, isRecord, readBool, readInteger, withNotes, } from './normalize-util.js';
 const ARTIFACT_ID_CHARS = 120;
 const VIEW_TARGET_CHARS = 200;

package/dist/governance/tools/submit-normalizers.d.ts

@@ -15,7 +15,7 @@
  * finding, or an `ALL_PASS` next to a `gap` row, is not repairable: either the verdict or
  * the evidence is wrong and only the author knows which.
  */
-import type { ReviewSubmission, TestSubmission, WorkSubmission } from '../types.js';
+import type { ReviewSubmission, TestSubmission, WorkSubmission } from '@aragon-agent/tui/model/governance/types';
 import { type Normalized } from './normalize-util.js';
 export type WorkSubmissionInput = Pick<WorkSubmission, 'wpId' | 'summary' | 'filesChanged' | 'interfaceContracts' | 'verification'> & Partial<Pick<WorkSubmission, 'appeal' | 'escalate'>>;
 /** Validate and repair a `gov_submit_work` argument object. Pure. */

package/dist/governance/tools/submit-normalizers.js

@@ -15,7 +15,7 @@
  * finding, or an `ALL_PASS` next to a `gap` row, is not repairable: either the verdict or
  * the evidence is wrong and only the author knows which.
  */
-import { GOV_LIMITS } from '../limits.js';
+import { GOV_LIMITS } from '@aragon-agent/tui/model/governance/limits';
 import { Issues, SUBMIT_LIMITS as L, isRecord, readBool, readInteger, } from './normalize-util.js';
 const VERDICTS = ['PASS', 'PASS_WITH_FIXES', 'NEEDS_REWORK'];
 const TEST_VERDICTS = [

package/dist/governance/tools/submit-tools.d.ts

@@ -15,7 +15,7 @@
  * fields they know and the engine call receives the bound identity.
  */
 import { type AgentTool } from '@aragon-agent/core';
-import type { GovernanceEngineApi, Identity } from '../types.js';
+import type { GovernanceEngineApi, Identity } from '@aragon-agent/tui/model/governance/types';
 export * from './normalize-util.js';
 export * from './submit-normalizers.js';
 /** `gov_submit_work`: DEV (and the FIX developer). */

package/dist/logging/cli-commands.js

@@ -20,7 +20,7 @@ import { getLogsDir } from '../config/app-paths.js';
 import { loadConfig } from '../config/load.js';
 import { isLogFileName } from './file-sink.js';
 import { getLogger } from './logger.js';
-import { LOG_LEVELS, isLogLevel } from './levels.js';
+import { LOG_LEVELS, isLogLevel } from '@aragon-agent/tui/model/logging/levels';
 const EXIT_OK = 0;
 const EXIT_RUNTIME = 1;
 const EXIT_USAGE = 2;

package/dist/logging/install.d.ts

@@ -36,7 +36,7 @@
  *       subcommand; the full-screen branch swaps in one that restores first.
  * ══════════════════════════════════════════════════════════════════════════
  */
-import { type LogConfig } from '../config/schema.js';
+import { type LogConfig } from '@aragon-agent/tui/model/config/schema';
 import { Logger, type LogScope } from './logger.js';
 /**
  * Hand the screen-restore duty to whoever actually owns the screen.

package/dist/logging/install.js

@@ -39,10 +39,10 @@
 import process from 'node:process';
 import { getHomeResolutionWarning } from '../config/app-paths.js';
 import { readConfigFile } from '../config/store.js';
-import { clampLogConfig } from '../config/schema.js';
-import { clampLogLevel } from './levels.js';
+import { clampLogConfig } from '@aragon-agent/tui/model/config/schema';
+import { clampLogLevel } from '@aragon-agent/tui/model/logging/levels';
 import { Logger, setActiveLogger } from './logger.js';
-import { registerProfileSecrets, registerSecretsFrom } from './secret-registry.js';
+import { registerProfileSecrets, registerSecretsFrom } from '@aragon-agent/tui/model/logging/secret-registry';
 /** POSIX signal numbers for the `128 + signo` exit-code convention. */
 const SIGNAL_NUMBERS = { SIGINT: 2, SIGTERM: 15, SIGHUP: 1 };
 let screenRestore = () => { };

package/dist/logging/logger.d.ts

@@ -20,8 +20,8 @@
  * same day's file: `sid` separates their interleaved lines, and `pid` is what
  * still matches up with what the OS recorded after a crash.
  */
-import type { LogConfig } from '../config/schema.js';
-import { type LogLevelName } from './levels.js';
+import type { LogConfig } from '@aragon-agent/tui/model/config/schema';
+import { type LogLevelName } from '@aragon-agent/tui/model/logging/levels';
 /** Closed set, not free text: a typo'd scope is a record nobody can filter on. */
 export type LogScope = 'cli' | 'config' | 'agent' | 'tool' | 'skills' | 'llm' | 'migrate' | 'log' | 'fast' | 'history' | 'update' | 'compaction' | 'session' | 'branch' | 'bridge';
 export interface LogRecord {

package/dist/logging/logger.js

@@ -25,9 +25,10 @@ import { join } from 'node:path';
 import process from 'node:process';
 import { getLogsDir } from '../config/app-paths.js';
 import { FileSink, currentLogFileName } from './file-sink.js';
-import { isLevelEnabled } from './levels.js';
+import { isLevelEnabled } from '@aragon-agent/tui/model/logging/levels';
+import { setTuiLogger } from '@aragon-agent/tui/model/logging/log-port';
 import { redactRecord } from './redact.js';
-import { getSecrets } from './secret-registry.js';
+import { getSecrets } from '@aragon-agent/tui/model/logging/secret-registry';
 const DISABLED_CONFIG = {
     level: 'silent',
     toFile: false,
@@ -235,3 +236,31 @@ export function resetLoggerForTest() {
     active?.closeSink();
     active = null;
 }
+/**
+ * Connects the terminal-UI log port to this logger (tui-package-split S1).
+ *
+ * Four view-model / renderer modules log through `log-port` instead of importing this file,
+ * because they live in another package. The wiring is HERE, as an import side effect, and not
+ * in `installLogging()` or a test setup file, for two reasons that each cost a failed run:
+ *
+ *  - Anything that can observe those records imports this module (`getLogger()` is how a test
+ *    spies on them, `installLogging()` is how the executable gets a real one), so the port is
+ *    connected in exactly the processes where it matters and nowhere else.
+ *  - A vitest `setupFiles` entry cannot do it: setup runs before the test file, and importing
+ *    this module's dependency `config/app-paths` from there captures the home directory BEFORE
+ *    a test that sets `ARAGON_HOME` at the top of its file gets to - 66 cases then read and
+ *    write the wrong directory.
+ *
+ * LAZY: every call re-reads `getLogger()`. `installLogging()` replaces the singleton and
+ * `resetLoggerForTest()` discards it; a forwarder that captured the instance would keep writing
+ * to a closed logger and drop every record after the swap. No cast is needed: `Logger` accepts
+ * every `TuiLogScope` because that union is a subset of `LogScope`, so widening the port without
+ * widening `LogScope` is a compile error right here.
+ */
+setTuiLogger({
+    error: (scope, msg, data) => getLogger().error(scope, msg, data),
+    warn: (scope, msg, data) => getLogger().warn(scope, msg, data),
+    info: (scope, msg, data) => getLogger().info(scope, msg, data),
+    debug: (scope, msg, data) => getLogger().debug(scope, msg, data),
+    child: (scope) => getLogger().child(scope),
+});

package/dist/proc/kill-tree.js

@@ -24,7 +24,7 @@
  */
 import { spawn, spawnSync } from 'node:child_process';
 import process from 'node:process';
-import { PROC_LIMITS } from './limits.js';
+import { PROC_LIMITS } from '@aragon-agent/tui/model/proc/limits';
 /** Is the pid still there? `signal 0` tests for existence without delivering. */
 export function isAlive(pid) {
     if (pid === undefined || !Number.isFinite(pid) || pid <= 0)

package/dist/proc/log-mirror.js

@@ -28,7 +28,7 @@ import { appendFile, appendFileSync, mkdirSync, readdirSync, rmSync, statSync }
 import { existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { getLogger } from '../logging/logger.js';
-import { PROC_LIMITS } from './limits.js';
+import { PROC_LIMITS } from '@aragon-agent/tui/model/proc/limits';
 /**
  * True when `path` holds nothing but `<jobId>.log` files, or nothing at all.
  *

package/dist/proc/log-ring.js

@@ -18,8 +18,8 @@
  * is "terminal-safe rows", and no consumer can forget — and it follows the same
  * "two bounds are two different literals" rule.
  */
-import { sanitizeChunk, toDisplayRow } from '../tools/terminal-output.js';
-import { PROC_LIMITS } from './limits.js';
+import { sanitizeChunk, toDisplayRow } from '@aragon-agent/tui/model/tools/terminal-output';
+import { PROC_LIMITS } from '@aragon-agent/tui/model/proc/limits';
 /**
  * A per-service ring.
  *

package/dist/proc/notices.d.ts

@@ -15,7 +15,7 @@
  * second notice for the same id is always the same fact restated - which is what
  * makes the relay's re-queueing after a queue wipe idempotent (I-11).
  */
-import type { JobKind, ServiceStatus } from './types.js';
+import type { JobKind, ServiceStatus } from '@aragon-agent/tui/model/proc/types';
 export interface JobNotice {
     /** The job: `t3` / `s1`. */
     id: string;

package/dist/proc/notices.js

@@ -15,8 +15,8 @@
  * second notice for the same id is always the same fact restated - which is what
  * makes the relay's re-queueing after a queue wipe idempotent (I-11).
  */
-import { formatDuration } from '../agent/usage.js';
-import { PROC_LIMITS } from './limits.js';
+import { formatDuration } from '@aragon-agent/tui/model/agent/usage';
+import { PROC_LIMITS } from '@aragon-agent/tui/model/proc/limits';
 /**
  * Insertion-ordered, deduplicated by id, bounded by `PROC_LIMITS.maxNotices`.
  *

package/dist/proc/prompt.d.ts

@@ -40,7 +40,7 @@
  * `JOBS_BLOCK_VERSION` exists so a change to this wording is greppable from a
  * behaviour report.
  */
-import { JOBS_BLOCK_VERSION } from './limits.js';
+import { JOBS_BLOCK_VERSION } from '@aragon-agent/tui/model/proc/limits';
 export { JOBS_BLOCK_VERSION };
 export declare function buildBackgroundJobsBlock(): string;
 export declare function buildBackgroundServicesBlock(): string;

package/dist/proc/prompt.js

@@ -40,7 +40,7 @@
  * `JOBS_BLOCK_VERSION` exists so a change to this wording is greppable from a
  * behaviour report.
  */
-import { JOBS_BLOCK_VERSION } from './limits.js';
+import { JOBS_BLOCK_VERSION } from '@aragon-agent/tui/model/proc/limits';
 export { JOBS_BLOCK_VERSION };
 export function buildBackgroundJobsBlock() {
     return [
@@ -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/readiness.js

@@ -14,7 +14,7 @@
  * hold the loop open, and they are reaped on exit.
  */
 import net from 'node:net';
-import { PROC_LIMITS } from './limits.js';
+import { PROC_LIMITS } from '@aragon-agent/tui/model/proc/limits';
 /**
  * A loopback/wildcard `http(s)` URL, with an optional port and path.
  *

package/dist/proc/supervisor.d.ts

@@ -18,7 +18,7 @@
  * unconditionally. With the flag off this object holds foreground pids, nothing
  * else, and allocates no timers.
  */
-import { type JobLogMirrorPort, 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 '@aragon-agent/tui/model/proc/types';
 export interface ProcSupervisorOptions {
     /** `cfg.bash.readyTimeoutMs`, read once per service at spawn. */
     readyTimeoutMs: () => number;

package/dist/proc/supervisor.js

@@ -23,11 +23,11 @@ import process from 'node:process';
 import { getLogger } from '../logging/logger.js';
 import { extractPortHint } from './classify.js';
 import { isAlive, killTree, killTreeSync } from './kill-tree.js';
-import { PROC_LIMITS } from './limits.js';
+import { PROC_LIMITS } from '@aragon-agent/tui/model/proc/limits';
 import { LogRing } from './log-ring.js';
-import { extractProgress } from './progress.js';
+import { extractProgress } from '@aragon-agent/tui/model/proc/progress';
 import { probePort, ReadinessWatcher } from './readiness.js';
-import { isTerminalStatus, } from './types.js';
+import { isTerminalStatus, } from '@aragon-agent/tui/model/proc/types';
 export class ProcSupervisor {
     opts;
     services = new Map();
@@ -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/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.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';
+import type { ProcSupervisorPort, ServiceLogPage, ServiceSnapshot } from '@aragon-agent/tui/model/proc/types';
 /** 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.

package/dist/proc/wait.js

@@ -23,8 +23,22 @@
  *     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 { isTerminalStatus } from './types.js';
+import { isTerminalStatus } from '@aragon-agent/tui/model/proc/types';
 /** Read one bounded page per target; `read()` returns `undefined` for a vanished id. */
 function readPages(port, targets, since) {
     const pages = new Map();
@@ -49,24 +63,41 @@ function allSettled(port, targets) {
         return snapshot === undefined || isTerminalStatus(snapshot.status);
     });
 }
+/** Has any target ended? Same unknown-id rule as `allSettled`. */
+function anySettled(port, targets) {
+    return targets.some((id) => {
+        const snapshot = port.get(id);
+        return snapshot === undefined || isTerminalStatus(snapshot.status);
+    });
+}
 /**
- * Wait up to `timeoutMs` for every target to reach a terminal status.
+ * THE ONE PREDICATE for "is this wait over", shared by the entry fast path and the
+ * `finish` funnel. Using it in only one of them makes `mode: 'any'` subscribe and
+ * burn the whole timeout when a target had already ended.
+ */
+function isDone(port, targets, mode) {
+    return mode === 'any' ? anySettled(port, targets) : allSettled(port, targets);
+}
+/**
+ * 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.
  */
 export async function waitForJob(port, req, now = Date.now) {
     const { targets, signal } = req;
+    const mode = req.mode ?? 'all';
     const startedAt = now();
     // RULE 1. Nothing to wait for at all, or everything already ended: no
     // subscription, no timer, `waitedMs: 0`.
-    if (targets.length === 0 || allSettled(port, targets)) {
+    if (targets.length === 0 || isDone(port, targets, mode)) {
         return {
             jobs: collect(port, targets),
             terminal: true,
             waitedMs: 0,
             timedOut: false,
             aborted: false,
+            woken: false,
             pages: readPages(port, targets, req.since),
         };
     }
@@ -79,6 +110,8 @@ export async function waitForJob(port, req, now = Date.now) {
         // from inside the listener instead of resolving the wait.
         let unsubscribe = () => { };
         let timer;
+        let beat;
+        let unwake = () => { };
         /** Assigned below; declared here so `finish` never reads an uninitialised binding. */
         let onAbort = () => { };
         // RULE 3: the one funnel. Idempotent, and it releases every reference before
@@ -88,15 +121,19 @@ export async function waitForJob(port, req, now = Date.now) {
                 return;
             done = true;
             unsubscribe();
+            unwake();
             if (timer !== undefined)
                 clearTimeout(timer);
+            if (beat !== undefined)
+                clearInterval(beat);
             signal?.removeEventListener('abort', onAbort);
             resolve({
                 jobs: collect(port, targets),
-                terminal: reason === 'terminal' || allSettled(port, targets),
+                terminal: reason === 'terminal' || isDone(port, targets, mode),
                 waitedMs: now() - startedAt,
                 timedOut: reason === 'timeout',
                 aborted: reason === 'abort',
+                woken: reason === 'wake',
                 pages: readPages(port, targets, req.since),
             });
         };
@@ -105,12 +142,38 @@ export async function waitForJob(port, req, now = Date.now) {
                 return;
             if (!targets.includes(event.service.id))
                 return;
-            if (allSettled(port, targets))
+            if (isDone(port, targets, mode))
                 finish('terminal');
         });
+        // The user spoke. Edge-triggered: only a notification after this line counts.
+        unwake = req.wakeOn?.subscribe(() => finish('wake')) ?? (() => { });
+        if (done) {
+            // A source that notifies synchronously inside `subscribe` already settled us.
+            unwake();
+            return;
+        }
         // RULE 2: `unref`, so a pending wait never keeps a quitting process alive.
         timer = setTimeout(() => finish('timeout'), Math.max(0, req.timeoutMs));
         timer.unref?.();
+        // RULE 5. Also the view's 1 Hz clock. A throwing `onBeat` is a renderer bug and
+        // must never kill a 20-minute wait.
+        if (req.heartbeat) {
+            const { everyMs, onBeat } = req.heartbeat;
+            beat = setInterval(() => {
+                const current = now();
+                if (current - startedAt >= req.timeoutMs) {
+                    finish('timeout');
+                    return;
+                }
+                try {
+                    onBeat(current);
+                }
+                catch {
+                    // Deliberately swallowed: see above.
+                }
+            }, Math.max(1, everyMs));
+            beat.unref?.();
+        }
         onAbort = () => finish('abort');
         // `{ once: true }` AND the explicit removal in `finish`: the option alone
         // leaves the listener registered on a signal that outlives this wait.

package/dist/prompts/command.d.ts

@@ -21,7 +21,7 @@
  * with candidates rather than a guess (D-22).
  */
 import type { CommandContext, CommandRegistry } from '../commands/registry.js';
-import type { QuickPrompt } from './types.js';
+import type { QuickPrompt } from '@aragon-agent/tui/model/prompts/types';
 export declare function registerPromptCommands(registry: CommandRegistry): void;
 /** `1. title  [fav]  #tag  12 uses` - no body, ever (D-17). */
 export declare function promptListLine(prompt: QuickPrompt, at: number): string;

package/dist/prompts/command.js

@@ -20,7 +20,7 @@
  * repeat, and `rm` has no recycle bin, so an ambiguous reference is a NAMED failure
  * with candidates rather than a guess (D-22).
  */
-import { PROMPT_DISABLED_COPY, PROMPT_HISTORY_REMINDER_COPY, PROMPT_LIST_EMPTY_COPY, PROMPT_SHOW_WARNING_COPY, PROMPT_UNKNOWN_SUBCOMMAND_COPY, PROMPT_UNAVAILABLE_COPY, promptAmbiguousCopy, promptDeletedCopy, promptErrorCopy, promptFavoriteCopy, promptInvalidSortCopy, promptListFooterCopy, promptMovedCopy, promptMoveRangeCopy, promptNotFoundCopy, promptRmConfirmCopy, promptSavedCopy, promptSortedCopy, } from './copy.js';
+import { PROMPT_DISABLED_COPY, PROMPT_HISTORY_REMINDER_COPY, PROMPT_LIST_EMPTY_COPY, PROMPT_SHOW_WARNING_COPY, PROMPT_UNKNOWN_SUBCOMMAND_COPY, PROMPT_UNAVAILABLE_COPY, promptAmbiguousCopy, promptDeletedCopy, promptErrorCopy, promptFavoriteCopy, promptInvalidSortCopy, promptListFooterCopy, promptMovedCopy, promptMoveRangeCopy, promptNotFoundCopy, promptRmConfirmCopy, promptSavedCopy, promptSortedCopy, } from '@aragon-agent/tui/model/prompts/copy';
 import { promptIndexOf } from './resolve.js';
 import { createPrompt, deletePrompt, loadPromptLibrary, reorderPrompt, reorderPrompts, setPromptFavorite, sortPromptIds, } from './store.js';
 /**

package/dist/prompts/normalize.d.ts

@@ -16,7 +16,7 @@
  * because by then the text is the only copy and dropping the entry to protect a
  * ceiling would delete the user's work to keep a number tidy.
  */
-import type { PromptLibrary, QuickPrompt } from './types.js';
+import type { PromptLibrary, QuickPrompt } from '@aragon-agent/tui/model/prompts/types';
 /**
  * One entry, or `null` when it cannot be salvaged.
  *