@aragon-agent/cli 0.6.31 → 0.6.33

package/dist/proc/wait.js

@@ -0,0 +1,133 @@
+/**
+ * The bounded wait primitive (long-task-jobs §4.4.1).
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope.
+ *
+ * A FREE FUNCTION OVER THREE PORT METHODS, NOT A METHOD ON THE PORT (D-9).
+ * `Pick<ProcSupervisorPort, 'get' | 'read' | 'subscribe'>` is enough to answer
+ * "has it finished yet, and what did it print since my cursor", so no test double
+ * has to grow a `wait()` and the registry keeps owning exactly what it owns.
+ *
+ * FOUR RULES, and each one closes a way this turns into a hang:
+ *
+ *  1. TERMINAL FIRST, SUBSCRIBE SECOND. A job that already ended resolves
+ *     synchronously with `waitedMs: 0` and registers nothing - no listener, no
+ *     timer. `runBackground` carries the same defence for the same reason: a
+ *     1 ms crash is not hypothetical.
+ *  2. EVERY TIMER IS `unref`ed AND EVERY LISTENER IS REMOVED at every exit. A
+ *     wait that leaks a timer is a process that will not exit, which is the
+ *     failure mode this feature exists to remove.
+ *  3. ONE IDEMPOTENT `finish` FUNNEL. Terminal event, timeout and abort race, and
+ *     exactly one of them may win.
+ *  4. IT DOES NOT DEPEND ON A SINGLE WAKE SOURCE. `reapSync()` used to emit
+ *     nothing at all (the supervisor now emits `stopped` from it), and
+ *     `dispose()` clears its listener set without emitting; the self-timeout is
+ *     therefore a real second path, not belt-and-braces.
+ */
+import { isTerminalStatus } from './types.js';
+/** Read one bounded page per target; `read()` returns `undefined` for a vanished id. */
+function readPages(port, targets, since) {
+    const pages = new Map();
+    for (const id of targets) {
+        const page = port.read(id, since);
+        if (page)
+            pages.set(id, page);
+    }
+    return pages;
+}
+/**
+ * Does every target exist and sit in a terminal state?
+ *
+ * AN UNKNOWN ID COUNTS AS SETTLED. The supervisor evicts terminal records, so a
+ * job whose outcome the caller is asking about may have been reclaimed; waiting
+ * for it would burn the whole timeout to learn nothing. The caller distinguishes
+ * the two cases from `jobs.length` and the supervisor's own ledger.
+ */
+function allSettled(port, targets) {
+    return targets.every((id) => {
+        const snapshot = port.get(id);
+        return snapshot === undefined || isTerminalStatus(snapshot.status);
+    });
+}
+/**
+ * Wait up to `timeoutMs` for every target to reach a terminal status.
+ *
+ * Resolves - never rejects - and always after at most `timeoutMs`. `now` is
+ * injectable so a test can assert `waitedMs` without depending on wall clock.
+ */
+export async function waitForJob(port, req, now = Date.now) {
+    const { targets, signal } = req;
+    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)) {
+        return {
+            jobs: collect(port, targets),
+            terminal: true,
+            waitedMs: 0,
+            timedOut: false,
+            aborted: false,
+            pages: readPages(port, targets, req.since),
+        };
+    }
+    return new Promise((resolve) => {
+        let done = false;
+        // DECLARED BEFORE `finish` SO THE FUNNEL CANNOT READ A HALF-INITIALISED BINDING.
+        // `port.subscribe()` is free to call its listener synchronously (a test double
+        // is the obvious case), and a `finish` that closed over a `const` assigned
+        // later in the same block would then throw a temporal-dead-zone ReferenceError
+        // from inside the listener instead of resolving the wait.
+        let unsubscribe = () => { };
+        let timer;
+        /** 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
+        // resolving so a finished wait cannot hold the event loop open.
+        const finish = (reason) => {
+            if (done)
+                return;
+            done = true;
+            unsubscribe();
+            if (timer !== undefined)
+                clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            resolve({
+                jobs: collect(port, targets),
+                terminal: reason === 'terminal' || allSettled(port, targets),
+                waitedMs: now() - startedAt,
+                timedOut: reason === 'timeout',
+                aborted: reason === 'abort',
+                pages: readPages(port, targets, req.since),
+            });
+        };
+        unsubscribe = port.subscribe((event) => {
+            if (!isTerminalStatus(event.service.status))
+                return;
+            if (!targets.includes(event.service.id))
+                return;
+            if (allSettled(port, targets))
+                finish('terminal');
+        });
+        // RULE 2: `unref`, so a pending wait never keeps a quitting process alive.
+        timer = setTimeout(() => finish('timeout'), Math.max(0, req.timeoutMs));
+        timer.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.
+        if (signal?.aborted === true) {
+            finish('abort');
+            return;
+        }
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/** Snapshots for the targets that still exist, in the requested order. */
+function collect(port, targets) {
+    const jobs = [];
+    for (const id of targets) {
+        const snapshot = port.get(id);
+        if (snapshot)
+            jobs.push(snapshot);
+    }
+    return jobs;
+}

package/dist/session/persist.js

@@ -201,7 +201,9 @@ export function normalizeLoadedEntries(entries) {
         // may also carry is already terminal and is left alone.
         if (entry.kind === 'service' &&
             (entry.status === 'starting' || entry.status === 'ready' || entry.status === 'running')) {
-            return { ...entry, status: 'stopped', rows: [] };
+            // `stalled: false` for the same reason: nothing is running, so a silence
+            // badge restored from disk would describe a process that no longer exists.
+            return { ...entry, status: 'stopped', rows: [], stalled: false };
         }
         // THE SEVENTH CLAUSE (tui-shift-enter-copy-queue 5.2.5). Core's steering
         // queue is memory-only, so a `queued` entry on disk is a promise this

package/dist/session/validate-session.js

@@ -190,6 +190,23 @@ const ENTRY_FIELDS = {
             number(value, path); },
         startedAt: number, readyAt: optional(number), endedAt: optional(number), rows: array(string),
         rowsSeen: number, terminal: optional(boolean), killIncomplete: optional(boolean),
+        // THE FOUR FIELDS long-task-jobs adds (AC-38), and the reason this validator
+        // has to learn them: it is STRICT — an unknown field fails the whole load — so
+        // a session saved with a task in it would refuse to resume, which is a P0 in
+        // R-8's terms.
+        //
+        // ALL FOUR ARE OPTIONAL HERE, DELIBERATELY, and that is a correction to the
+        // design. The reducer always writes `jobKind` and `lastOutputAt` for a NEW
+        // save, so they are required on `ServiceSnapshot` (that is what turns a
+        // forgotten field into a compile error). But a session file written by any
+        // build BEFORE this feature has neither, and a strict validator that demanded
+        // them would make every existing session unresumable — a far worse failure
+        // than a missing progress line. Recorded in the spec's implementation notes.
+        jobKind: optional(enumeration('service', 'task')),
+        progress: optional(string),
+        lastOutputAt: optional(number),
+        stalled: optional(boolean),
+        logPath: optional(string),
     },
 };
 function validateEntries(value) {

package/dist/tools/bash-tool.d.ts

@@ -30,7 +30,7 @@
  * `bash` assertions meaningful rather than rewritten.
  */
 import { type AgentTool } from '@aragon-agent/core';
-import type { ProcSupervisorPort } from '../proc/types.js';
+import { type ProcSupervisorPort } from '../proc/types.js';
 import type { ToolDeps } from './fs-tools.js';
 export interface BashToolOptions {
     /**
@@ -57,5 +57,16 @@ export interface BashToolOptions {
      * `/bg`, no event and nothing in the result saying so.
      */
     interactive?: boolean;
+    /**
+     * `cfg.jobs.enabled`, read LIVE: whether `job_wait` / `job_list` exist in this
+     * session (long-task-jobs §4.3).
+     *
+     * TWO DECISIONS DEPEND ON IT AND NEITHER IS COSMETIC: the tool description only
+     * advertises tasks when the tools that manage them are registered, and a
+     * `[note]` telling the model to call `job_wait` is only printed when
+     * `job_wait` is callable. A workaround the model cannot execute reads as a
+     * broken tool.
+     */
+    jobsAvailable?: () => boolean;
 }
 export declare function makeBash(deps: ToolDeps, options?: BashToolOptions): AgentTool;

package/dist/tools/bash-tool.js

@@ -35,6 +35,7 @@ import { defineTool, errorResult, textResult, } from '@aragon-agent/core';
 import { looksLongRunning } from '../proc/classify.js';
 import { killTree } from '../proc/kill-tree.js';
 import { PROC_LIMITS } from '../proc/limits.js';
+import { isTerminalStatus } from '../proc/types.js';
 /**
  * The two sentences appended to the tool description when background launches
  * are available.
@@ -50,6 +51,17 @@ const BACKGROUND_DESCRIPTION = ' Set `background: true` for anything that does n
     '`nohup` or `screen` to detach a command yourself; the runtime supervises ' +
     'background commands, and a self-detached process cannot be reported on or ' +
     'stopped.';
+/**
+ * The task half, appended only when the job tools are registered.
+ *
+ * APPENDED CONDITIONALLY FOR THE SAME REASON AS THE BLOCK ABOVE: with
+ * `jobs.enabled: false` this sentence would describe a `task` id and a
+ * `job_wait` the model does not have, which is worse than saying nothing.
+ */
+const TASK_DESCRIPTION = ' For a command that DOES finish but takes far longer than one tool call - a ' +
+    'training run, a model download, a release build - `background: true` returns a ' +
+    'task id (`t1`, `t2`) instead of a service id, and you wait for it with ' +
+    '`job_wait` instead of polling `bash_output`.';
 /**
  * The settle window used when a supervisor is supplied WITHOUT one.
  *
@@ -70,22 +82,63 @@ const FALLBACK_STARTUP_SETTLE_MS = 4000;
 function trackForeground(supervisor, pid) {
     return supervisor ? supervisor.trackForeground(pid) : () => { };
 }
-/** Render a background launch's result block for the model (§3.5). */
+/**
+ * The sentence appended to a timed-out `bash` result when backgrounding is
+ * available.
+ *
+ * THE HIGHEST-VALUE LINE IN THIS FEATURE. Today a long job dies with
+ * `Command timed out after 120000ms` and nothing else: no pid, no handle, no way
+ * to continue - so the model reaches for a way to detach the process by hand,
+ * which is what produced the self-detached, unreportable children this runtime
+ * spent a whole feature removing. Naming the exact re-run command turns that into
+ * a plan the model can execute with tools it already has.
+ */
+function backgroundRetryNote(command, cwd) {
+    return [
+        '[note] this command does not finish within the tool ceiling. If it is a long',
+        'job, re-run it in the background:',
+        `  bash({ command: ${JSON.stringify(command)}, background: true, cwd: ${JSON.stringify(cwd)} })`,
+        'then wait with job_wait({ job: "t1" }).',
+    ].join('\n');
+}
+/**
+ * Render a background launch's result block for the model (§3.5, long-task-jobs
+ * §4.2.1).
+ *
+ * THE STATUS WORDS TELL THE TRUTH ABOUT THE KIND. A `task` is `running` from the
+ * spawn, so "still alive, nothing to connect to (a watcher, most likely)" would
+ * describe a training run as if it were a watcher; and a job that WE stopped is
+ * neither `starting` nor "still coming up". Both sentences cost the model a
+ * wrong decision rather than a word.
+ */
 function renderServiceResult(service, opts) {
+    const noun = service.kind === 'task' ? 'task' : 'service';
     const lines = [`$ ${service.command}`];
-    lines.push(`[background] service ${service.id} started (pid ${service.pid ?? '?'})`);
+    lines.push(`[background] ${noun} ${service.id} started (pid ${service.pid ?? '?'})`);
     const elapsed = ((service.readyAt ?? service.endedAt ?? Date.now()) - service.startedAt) / 1000;
+    let terminal = false;
     if (service.status === 'ready') {
         const how = service.detectedBy === 'probe' ? 'port probe' : 'output';
         const where = service.url ?? (service.port ? `port ${service.port}` : '');
         lines.push(`[ready] ${where}  (detected from ${how} after ${elapsed.toFixed(1)}s)`);
     }
     else if (service.status === 'running') {
-        lines.push(`[running] still alive, nothing to connect to (a watcher, most likely)`);
+        lines.push(service.kind === 'task'
+            ? `[running] still running after ${elapsed.toFixed(1)}s - it has not finished yet`
+            : '[running] still alive, nothing to connect to (a watcher, most likely)');
     }
     else if (service.status === 'exited' || service.status === 'failed') {
         const code = service.exitCode === null ? `signal ${service.signal}` : `code ${service.exitCode}`;
         lines.push(`[exited] ${code} after ${elapsed.toFixed(1)}s`);
+        terminal = true;
+    }
+    else if (service.status === 'stopped') {
+        // BEFORE long-task-jobs this fell into the `else` below and told the model
+        // "[starting] not ready yet - still coming up" about a job that had already
+        // been killed or reaped. That is a false statement in the one field the model
+        // reads first.
+        lines.push(`[stopped] before it finished, after ${elapsed.toFixed(1)}s`);
+        terminal = true;
     }
     else {
         lines.push(`[starting] not ready yet after ${elapsed.toFixed(1)}s - still coming up`);
@@ -93,6 +146,8 @@ function renderServiceResult(service, opts) {
     if (service.portPreoccupied && service.port !== undefined) {
         lines.push(`[note] port ${service.port} was already in use before start`);
     }
+    if (service.progress)
+        lines.push(`[progress] ${service.progress.text}`);
     if (service.rows.length > 0) {
         lines.push('[log tail]');
         for (const row of service.rows)
@@ -101,7 +156,13 @@ function renderServiceResult(service, opts) {
     if (opts.ephemeral) {
         // D-15 / P1-8: headless has no user who could keep it alive, and saying so
         // is the difference between a surprise and a documented behaviour.
-        lines.push('[note] this service will be stopped when the run ends.');
+        lines.push(`[note] this ${noun} will be stopped when the run ends.`);
+    }
+    // A FINISHED JOB EARNS NO ADVICE TO WAIT FOR IT (AC-5). Suggesting `job_wait`
+    // for something that already exited is how a model learns to poll.
+    if (!terminal && opts.jobsAvailable && service.kind === 'task') {
+        lines.push(`[note] wait for it with job_wait({ job: "${service.id}" }) - a bounded wait ` +
+            'returns its status and only the output since your cursor.');
     }
     lines.push(`Read more with bash_output({ service: "${service.id}" }); ` +
         `stop it with bash_kill({ service: "${service.id}" }).`);
@@ -118,6 +179,7 @@ function renderServiceResult(service, opts) {
 export function makeBash(deps, options = {}) {
     const supervisor = options.supervisor;
     const backgroundAvailable = supervisor !== undefined;
+    const taskAvailable = backgroundAvailable && options.jobsAvailable?.() === true;
     return defineTool({
         name: 'bash',
         label: 'Shell',
@@ -125,7 +187,8 @@ export function makeBash(deps, options = {}) {
             'stdout+stderr and exit code. `timeout` (ms) may only shrink within the ' +
             'agent tool-timeout ceiling; `cwd` defaults to the working directory. ' +
             'Emit shell syntax compatible with the OS/shell stated in the system prompt.' +
-            (backgroundAvailable ? BACKGROUND_DESCRIPTION : ''),
+            (backgroundAvailable ? BACKGROUND_DESCRIPTION : '') +
+            (taskAvailable ? TASK_DESCRIPTION : ''),
         parameters: {
             type: 'object',
             properties: {
@@ -160,16 +223,23 @@ export function makeBash(deps, options = {}) {
             // `false` -> foreground, always. The escape hatch; nothing overrides it.
             // absent  -> the classifier, and only where a card can be rendered.
             if (supervisor && params.background !== false) {
+                const longRunning = looksLongRunning(command);
                 const auto = options.interactive !== false &&
                     options.autoBackground?.() !== false &&
-                    looksLongRunning(command);
+                    longRunning;
                 if (params.background === true || auto) {
+                    // THE KIND IS DECIDED HERE, ONCE (long-task-jobs §4.3). An explicit
+                    // `background: true` on a command the classifier does not recognise is
+                    // a TASK; the automatic path can only ever produce a service, because
+                    // the classifier firing is what set it in motion.
                     return runBackground(supervisor, {
                         command,
                         cwd,
                         toolCallId: id,
+                        kind: longRunning ? 'service' : 'task',
                         settleMs: options.startupSettleMs?.() ?? FALLBACK_STARTUP_SETTLE_MS,
                         ephemeral: options.interactive === false,
+                        jobsAvailable: taskAvailable,
                     });
                 }
             }
@@ -225,8 +295,13 @@ export function makeBash(deps, options = {}) {
                 const buildBody = (opts) => {
                     const body = captured();
                     if (killReason === 'timeout') {
-                        // BYTE-IDENTICAL TO THE PRE-CHANGE BUILD for the `timeout` param.
-                        return errorResult(`Command timed out after ${params.timeout}ms.\n${body}`);
+                        // BYTE-IDENTICAL TO THE PRE-CHANGE BUILD when background launches are
+                        // unavailable; with them available the note below is the single
+                        // highest-value sentence in this feature, because it is what turns
+                        // "the tool ceiling killed my training run" into "re-run it in the
+                        // background, then wait for it".
+                        const timedOut = `Command timed out after ${params.timeout}ms.\n${body}`;
+                        return errorResult(backgroundAvailable ? `${timedOut}\n${backgroundRetryNote(command, cwd)}` : timedOut);
                     }
                     if (killReason === 'abort') {
                         // P1-5. The captured output is the evidence the model needs, and
@@ -383,9 +458,10 @@ async function runBackground(supervisor, args) {
         command: args.command,
         cwd: args.cwd,
         toolCallId: args.toolCallId,
+        kind: args.kind,
     });
     if (!started.ok || !started.service) {
-        return errorResult(started.error ?? 'Could not start the background service.');
+        return errorResult(started.error ?? 'Could not start the background job.');
     }
     const id = started.service.id;
     const settled = await new Promise((resolve) => {
@@ -407,11 +483,22 @@ async function runBackground(supervisor, args) {
         });
         const timer = setTimeout(() => finish(supervisor.get(id) ?? started.service), args.settleMs);
         timer.unref?.();
-        // A service that finished between `start()` and this subscription (a crash
-        // inside 1 ms is not hypothetical) would otherwise wait out the whole window.
+        // A job that finished between `start()` and this subscription (a crash inside
+        // 1 ms is not hypothetical) would otherwise wait out the whole window.
+        //
+        // THE PREDICATE IS TERMINAL, NOT `!== 'starting'` (long-task-jobs RV-P0-1 /
+        // I-12). For a service the two happened to agree, because `starting` was its
+        // only non-terminal state on this path. A `task` is `running` from the spawn,
+        // so `!== 'starting'` was true on the FIRST tick: `bash` returned `[running]`
+        // in ~0 ms, the settle window never applied, and a training script that
+        // crashed in 300 ms was reported as still running with no output and no exit
+        // code - the exact defect this feature exists to remove.
         const now = supervisor.get(id);
-        if (now && now.status !== 'starting')
+        if (now && isTerminalStatus(now.status))
             finish(now);
     });
-    return renderServiceResult(settled, { ephemeral: args.ephemeral });
+    return renderServiceResult(settled, {
+        ephemeral: args.ephemeral,
+        jobsAvailable: args.jobsAvailable,
+    });
 }

package/dist/tools/index.d.ts

@@ -13,6 +13,7 @@ import type { AgentMode } from '../agent/agent-mode.js';
 import type { ToolPermission } from '../exec/permission.js';
 import type { FilePatch } from './patch.js';
 import type { ProcSupervisorPort } from '../proc/types.js';
+import type { JobNotice } from '../proc/notices.js';
 export interface ConfirmRequest {
     tool: string;
     summary: string;
@@ -179,6 +180,29 @@ export interface BuiltinToolsOptions {
      * exactly as `--no-skills` and `--no-team` are.
      */
     procTools?: AgentTool[];
+    /**
+     * `job_wait` / `job_list`, appended verbatim (long-task-jobs §4.3 / D-10).
+     *
+     * THROUGH THE FACTORY FOR THE REASON `teamTools`, `todoTools` AND `procTools`
+     * EACH RECORD IN CAPITALS: `tools.test.ts::C7` asserts `HOST_TOOL_NAMES` equals
+     * what this factory PRODUCES, so appending them in `AgentController` after the
+     * factory returned would turn that test red with a message about two lists of
+     * names. An empty array (`jobs.enabled: false`) leaves the array byte-identical
+     * to the pre-feature build.
+     */
+    jobTools?: AgentTool[];
+    /**
+     * The completion-notice queue's read side, for the PULL channel (§4.6).
+     *
+     * A PORT, NOT THE CLASS: this file may not import `proc/notices.ts` at runtime
+     * (the same rule `procs` follows), and all the wrapper needs is "take
+     * everything and give it to me". Omitting it leaves every tool object
+     * untouched, provable by identity, which is how `-p`, the TUI and every
+     * subagent are shown to be unchanged.
+     */
+    jobNotices?: {
+        drain(): JobNotice[];
+    };
     /**
      * `cfg.bash.autoBackground`, READ AT CALL TIME.
      *
@@ -252,7 +276,7 @@ export interface BuiltinToolsOptions {
  * is the whole of what this mechanism is worth, and saying so plainly beats
  * implying it covers more.
  */
-export declare const SKILL_TOOL_FLOOR: readonly ["read_file", "list_dir", "glob", "grep", "skill", "skill_find", "ask_user", "submit_plan", "task", "todo_write", "bash_output"];
+export declare const SKILL_TOOL_FLOOR: readonly ["read_file", "list_dir", "glob", "grep", "skill", "skill_find", "ask_user", "submit_plan", "task", "todo_write", "bash_output", "job_wait", "job_list"];
 /**
  * The five tools plan mode refuses: exactly the complement of `SKILL_TOOL_FLOOR`
  * within `HOST_TOOL_NAMES` — "the five that change something", the set this file
@@ -285,5 +309,5 @@ export declare const PLAN_MODE_BLOCKED_TOOLS: ReadonlySet<string>;
  * declaration MEANS, and that reading must not change with how the CLI was
  * started.
  */
-export declare const HOST_TOOL_NAMES: readonly ["read_file", "write_file", "edit_file", "list_dir", "glob", "grep", "bash", "skill", "skill_find", "skill_install", "skill_create", "ask_user", "submit_plan", "todo_write", "bash_output", "bash_kill", "task"];
+export declare const HOST_TOOL_NAMES: readonly ["read_file", "write_file", "edit_file", "list_dir", "glob", "grep", "bash", "skill", "skill_find", "skill_install", "skill_create", "ask_user", "submit_plan", "todo_write", "bash_output", "bash_kill", "job_wait", "job_list", "task"];
 export declare function createBuiltinTools(options: BuiltinToolsOptions): AgentTool[];

package/dist/tools/index.js

@@ -13,6 +13,7 @@ import { planRefusal, submitPlanRefusal } from '../agent/agent-mode.js';
 import { makeReadFile, makeWriteFile, makeEditFile, makeListDir } from './fs-tools.js';
 import { makeGlob, makeGrep } from './search-tools.js';
 import { makeBash } from './bash-tool.js';
+import { withJobNoticeTail } from './job-tools.js';
 const MUTATING_TOOLS = new Set(['write_file', 'edit_file', 'bash']);
 /**
  * Tools the ceiling always permits (D-G6). The ONLY place that knows which of
@@ -65,6 +66,14 @@ export const SKILL_TOOL_FLOOR = [
     // membership test. Blocking it in plan mode would also let the agent start a
     // service it then could not read — the dead end the floor exists to prevent.
     'bash_output',
+    // `job_wait` / `job_list` join the FLOOR for the same reason, one feature
+    // later (long-task-jobs D-12). Waiting is READING: neither can start, stop or
+    // mutate anything, and plan mode's whole purpose - read the code, ask, then
+    // propose - is served by being able to wait for a job that was already
+    // running. Blocking them would also make a running job unreachable from the
+    // mode the user is actually in.
+    'job_wait',
+    'job_list',
 ];
 /**
  * The five tools plan mode refuses: exactly the complement of `SKILL_TOOL_FLOOR`
@@ -131,6 +140,12 @@ export const HOST_TOOL_NAMES = [
     // `skills doctor` already has with `--no-skills`.
     'bash_output',
     'bash_kill',
+    // The two job names join the SUPERSET for exactly the reason the two above
+    // did: a skill's `allowed-tools: [job_wait]` must be answerable by `doctor`
+    // even in a session where `jobs.enabled` is false and neither is registered
+    // (long-task-jobs §4.3).
+    'job_wait',
+    'job_list',
     // `team_send` / `team_wait` are DELIBERATELY ABSENT (P2-5). This constant
     // answers "can a skill's `allowed-tools` declaration ever take effect?", and
     // those two are never registered on a lead — so a skill naming them genuinely
@@ -261,6 +276,10 @@ export function createBuiltinTools(options) {
                 ...(options.autoBackground ? { autoBackground: options.autoBackground } : {}),
                 ...(options.startupSettleMs ? { startupSettleMs: options.startupSettleMs } : {}),
                 ...(options.interactive !== undefined ? { interactive: options.interactive } : {}),
+                // `jobs.enabled`, spread conditionally: with the job tools off the
+                // description and the `[note]` are the ones the pre-feature build
+                // produced, byte for byte (I-3).
+                ...(options.jobTools && options.jobTools.length > 0 ? { jobsAvailable: () => true } : {}),
             }
             : {}),
     ];
@@ -284,6 +303,12 @@ export function createBuiltinTools(options) {
     if (options.procTools && options.procTools.length > 0) {
         tools = [...tools, ...options.procTools];
     }
+    // AFTER `procTools` (long-task-jobs §5.2): the job tools are the third group of
+    // server-side handles and belong with the two they extend. A lead's `task` is
+    // still last.
+    if (options.jobTools && options.jobTools.length > 0) {
+        tools = [...tools, ...options.jobTools];
+    }
     // BEFORE both wrappers, so the lead's `task` is covered by the plan gate and
     // the ceiling like everything else, and a child's comm tools are covered by
     // everything except the ceiling (see `policyExempt`).
@@ -345,8 +370,24 @@ export function createBuiltinTools(options) {
     //
     // The plan gate is applied LAST, which makes it OUTERMOST at call time: it
     // needs no I/O and no state, so it must not sit behind a human wait.
+    //
+    // THE NOTICE TAIL IS THE ONE EXCEPTION TO "both tail returns are identical",
+    // and it is deliberately the OUTERMOST wrapper of all (long-task-jobs §4.6):
+    // whatever a tool did - succeeded, errored, or was refused by the plan gate -
+    // its result is a delivery opportunity for a `<job_notices>` block, so the
+    // wrapper has to run after every other decision has been made.
+    //
+    // `withJobNotices` RETURNS ITS ARGUMENT when no queue was supplied, so the
+    // identity claim the `AC-G17` tests make about `--no-skills` and about every
+    // headless and subagent toolset survives verbatim.
+    const withJobNotices = (list) => {
+        const queue = options.jobNotices;
+        if (!queue)
+            return list;
+        return list.map((tool) => withJobNoticeTail(tool, () => queue.drain()));
+    };
     if (!options.agentMode)
-        return tools;
+        return withJobNotices(tools);
     const getMode = options.agentMode;
-    return tools.map((t) => withPlanModeGate(t, getMode));
+    return withJobNotices(tools.map((t) => withPlanModeGate(t, getMode)));
 }

package/dist/tools/job-tools.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `job_wait` and `job_list`, plus the notice tail every tool result carries
+ * (long-task-jobs §4.4.2 / §4.4.3 / §4.6).
+ *
+ * ASCII ONLY: `src/tools/**` is inside the glyph scanner's scope.
+ *
+ * WHY TWO NEW TOOLS RATHER THAN A `block` PARAMETER ON `bash_output` (D-10):
+ * the tool list IS the discoverable capability surface. A model that can SEE
+ * `job_wait` knows that waiting is a legal step in a plan; a hidden `block: 30`
+ * parameter is a feature it will never use, and extending `bash_output`'s output
+ * would also rewrite assertions that pin its current grammar word for word.
+ *
+ * EVERY RESULT IS A FIXED GRAMMAR OF AT MOST TWELVE LINES. That is not tidiness:
+ * the entire economic argument for this feature is that one wait costs ~150
+ * tokens instead of a 200-row tail, so an unbounded result would delete the
+ * reason the feature exists.
+ */
+import { type AgentTool } from '@aragon-agent/core';
+import { type JobNotice } from '../proc/notices.js';
+import type { JobKind, ProcSupervisorPort, ServiceStatus } from '../proc/types.js';
+export interface JobToolDeps {
+    supervisor: ProcSupervisorPort;
+    /** `cfg.jobs.waitSeconds`, read LIVE (same rule as `startupSettleMs`). */
+    waitSeconds: () => number;
+    /** `cfg.jobs.stallSeconds`, read LIVE; only the `[stalled]` sentence uses it. */
+    stallSeconds: () => number;
+    /** `cfg.toolTimeoutMs`, read LIVE: I-4's second convergence. */
+    toolTimeoutMs: () => number;
+    /** `PROC_LIMITS.maxConsecutiveWaits`. */
+    maxConsecutiveWaits: number;
+    /**
+     * The terminal record for an id this session has already reported and then
+     * lost to `evictTerminal()` (RV-P2-7).
+     *
+     * WITHOUT IT "reclaimed" and "never existed" are the same message, and a model
+     * told `No job "t9"` about a 40-minute training run that finished successfully
+     * will start it again.
+     */
+    terminalRecord?: (id: string) => {
+        kind: JobKind;
+        status: ServiceStatus;
+    } | undefined;
+}
+export declare function makeJobWait(deps: JobToolDeps): AgentTool;
+export declare function makeJobList(deps: JobToolDeps): AgentTool;
+/**
+ * Append pending `<job_notices>` to every tool result (the PULL channel).
+ *
+ * SAME SHAPE AS `withMailboxTail`, AND FOR THE SAME REASON: the engine is told
+ * nothing, the wrapper rides `{...tool, execute}`, and the notice is delivered on
+ * the next tool call whatever that call is. The queue is drained EVEN WHEN the
+ * wrapped tool errored - a refused `bash` is still a delivery opportunity.
+ */
+export declare function withJobNoticeTail(tool: AgentTool, drain: () => JobNotice[]): AgentTool;