@aragon-agent/cli 0.6.31 → 0.6.32

package/dist/config/cli-commands.d.ts

@@ -21,6 +21,19 @@ export declare const LOG_CONFIG_SET_KEYS: readonly ["log.level", "log.toFile", "
  * `Set team.enabled = false`.
  */
 export declare const TEAM_CONFIG_SET_KEYS: readonly ["team.enabled", "team.maxSubagents", "team.maxConcurrent", "team.subagentTimeoutMs", "team.dispatchTimeoutMs", "team.maxTurnsPerSubagent", "team.overseer", "team.overseerIntervalMs", "team.model", "team.modelProfileId"];
+/**
+ * Config keys under `jobs.` that `aragon config set` accepts
+ * (long-task-jobs §6.5).
+ *
+ * THE FIRST NESTED SECTION WHOSE KEYS ARE ALL WRITABLE, so it is also the first
+ * one where `JOBS_CONFIG_SET_KEYS ⊆ CONFIG_SET_KEYS` needs its own assertion:
+ * `__tests__/config.test.ts`'s static guard matches LITERAL keys in `cli.tsx`, so
+ * a set that is spread in is invisible to it (RV-P2-8).
+ *
+ * Every key is ONE level deep on purpose — `runConfigGet` splits on a single dot,
+ * so `jobs.waitSeconds` resolves and `jobs.mirror.enabled` would not.
+ */
+export declare const JOBS_CONFIG_SET_KEYS: readonly ["jobs.enabled", "jobs.waitSeconds", "jobs.stallSeconds", "jobs.persistLog", "jobs.noticeSteer"];
 /**
  * Config keys under `retry.` that `aragon config set` accepts
  * (llm-api-retry-backoff §8.2).
@@ -81,6 +94,20 @@ export declare const COMPACTION_CONFIG_SET_KEYS: readonly ["compaction.enabled",
  * included.
  */
 export declare function applyLogConfigSet(key: string, value: string): Partial<PersistedConfig> | null;
+/**
+ * Translate a `jobs.*` dotted key into a patch, or `null` for anything else.
+ *
+ * THE TEMPLATE IS `applyTeamConfigSet`, NOT an `applyBashConfigSet` — no such
+ * function exists, and `bash.*` is not `config set`-able to this day (RV-P2-8).
+ * Every numeric key routes through `clampJobsConfig` rather than a local
+ * coercion, so the caller echoes the STORED value and an out-of-range input is
+ * visible: `config set jobs.waitSeconds 1` prints `5`.
+ *
+ * The patch is a PARTIAL section, which is only safe because
+ * `updatePersistedConfig` deep-merges `jobs` — the sixth time that trap is
+ * recorded in `store.ts`.
+ */
+export declare function applyJobsConfigSet(key: string, value: string): Partial<PersistedConfig> | null;
 /**
  * Translate a `team.*` dotted key into a patch, or `null` for anything else.
  *

package/dist/config/cli-commands.js

@@ -14,7 +14,7 @@ import { getConfigBackupPath, getConfigPath, getHomeRoot, getLogsDir, getPromptH
 import { getHomeMigrationBreadcrumbPath } from './migrate-home.js';
 import { loadPersistedConfig, updatePersistedConfig } from './store.js';
 import { normalizeModelProfiles, validateModelProfiles } from './model-profiles.js';
-import { clampFastConfig, clampRetryConfig, clampCompactionConfig, clampTeamConfig, parseThresholdInput, clampUpdateConfig, coercePositiveInt, maskSecret, DEFAULT_FAST_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_TEAM_CONFIG, DEFAULT_COMPACTION_CONFIG, DEFAULT_UPDATE_CONFIG, } from './schema.js';
+import { clampFastConfig, clampRetryConfig, clampCompactionConfig, clampTeamConfig, parseThresholdInput, clampUpdateConfig, coercePositiveInt, maskSecret, DEFAULT_FAST_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_TEAM_CONFIG, DEFAULT_COMPACTION_CONFIG, DEFAULT_UPDATE_CONFIG, DEFAULT_JOBS_CONFIG, clampJobsConfig, } from './schema.js';
 import { clampLogLevel } from '../logging/levels.js';
 /** Config keys under `log.` that `aragon config set` accepts. */
 export const LOG_CONFIG_SET_KEYS = [
@@ -48,6 +48,25 @@ export const TEAM_CONFIG_SET_KEYS = [
     'team.model',
     'team.modelProfileId',
 ];
+/**
+ * Config keys under `jobs.` that `aragon config set` accepts
+ * (long-task-jobs §6.5).
+ *
+ * THE FIRST NESTED SECTION WHOSE KEYS ARE ALL WRITABLE, so it is also the first
+ * one where `JOBS_CONFIG_SET_KEYS ⊆ CONFIG_SET_KEYS` needs its own assertion:
+ * `__tests__/config.test.ts`'s static guard matches LITERAL keys in `cli.tsx`, so
+ * a set that is spread in is invisible to it (RV-P2-8).
+ *
+ * Every key is ONE level deep on purpose — `runConfigGet` splits on a single dot,
+ * so `jobs.waitSeconds` resolves and `jobs.mirror.enabled` would not.
+ */
+export const JOBS_CONFIG_SET_KEYS = [
+    'jobs.enabled',
+    'jobs.waitSeconds',
+    'jobs.stallSeconds',
+    'jobs.persistLog',
+    'jobs.noticeSteer',
+];
 /**
  * Config keys under `retry.` that `aragon config set` accepts
  * (llm-api-retry-backoff §8.2).
@@ -166,6 +185,40 @@ export function applyLogConfigSet(key, value) {
             return null;
     }
 }
+/**
+ * Translate a `jobs.*` dotted key into a patch, or `null` for anything else.
+ *
+ * THE TEMPLATE IS `applyTeamConfigSet`, NOT an `applyBashConfigSet` — no such
+ * function exists, and `bash.*` is not `config set`-able to this day (RV-P2-8).
+ * Every numeric key routes through `clampJobsConfig` rather than a local
+ * coercion, so the caller echoes the STORED value and an out-of-range input is
+ * visible: `config set jobs.waitSeconds 1` prints `5`.
+ *
+ * The patch is a PARTIAL section, which is only safe because
+ * `updatePersistedConfig` deep-merges `jobs` — the sixth time that trap is
+ * recorded in `store.ts`.
+ */
+export function applyJobsConfigSet(key, value) {
+    const patch = (jobs) => ({ jobs });
+    const clampOne = (field) => {
+        const merged = clampJobsConfig({ ...DEFAULT_JOBS_CONFIG, [field]: value });
+        return { [field]: merged[field] };
+    };
+    switch (key) {
+        case 'jobs.enabled':
+            return patch({ enabled: isTrue(value) });
+        case 'jobs.waitSeconds':
+            return patch(clampOne('waitSeconds'));
+        case 'jobs.stallSeconds':
+            return patch(clampOne('stallSeconds'));
+        case 'jobs.persistLog':
+            return patch({ persistLog: isTrue(value) });
+        case 'jobs.noticeSteer':
+            return patch({ noticeSteer: isTrue(value) });
+        default:
+            return null;
+    }
+}
 /**
  * Translate a `team.*` dotted key into a patch, or `null` for anything else.
  *

package/dist/config/env.js

@@ -254,6 +254,44 @@ export function readEnvConfig() {
         if (Object.keys(section).length > 0)
             partial.bash = section;
     }
+    const jobsEnabled = process.env.ARAGON_JOBS_ENABLED?.trim().toLowerCase();
+    const jobsWait = process.env.ARAGON_JOBS_WAIT_SECONDS?.trim();
+    const jobsStall = process.env.ARAGON_JOBS_STALL_SECONDS?.trim();
+    const jobsPersist = process.env.ARAGON_JOBS_PERSIST_LOG?.trim().toLowerCase();
+    const jobsSteer = process.env.ARAGON_JOBS_NOTICE_STEER?.trim().toLowerCase();
+    if ((jobsEnabled !== undefined && jobsEnabled.length > 0) ||
+        (jobsWait !== undefined && jobsWait.length > 0) ||
+        (jobsStall !== undefined && jobsStall.length > 0) ||
+        (jobsPersist !== undefined && jobsPersist.length > 0) ||
+        (jobsSteer !== undefined && jobsSteer.length > 0)) {
+        const section = {};
+        // ONE TRUTHINESS LADDER FOR ALL THREE BOOLEANS, because three slightly
+        // different spellings of "is this true" is how `ARAGON_JOBS_ENABLED=off`
+        // ends up enabling the feature.
+        const flag = (value) => value === '1' || value === 'true' || value === 'on' || value === 'yes';
+        if (jobsEnabled !== undefined && jobsEnabled.length > 0)
+            section.enabled = flag(jobsEnabled);
+        if (jobsPersist !== undefined && jobsPersist.length > 0)
+            section.persistLog = flag(jobsPersist);
+        if (jobsSteer !== undefined && jobsSteer.length > 0)
+            section.noticeSteer = flag(jobsSteer);
+        if (jobsWait !== undefined && jobsWait.length > 0) {
+            const parsed = Number.parseInt(jobsWait, 10);
+            // LEFT ABSENT WHEN UNPARSEABLE, so `clampJobsConfig` supplies the default
+            // rather than an env var that silently means 0.
+            if (Number.isFinite(parsed))
+                section.waitSeconds = parsed;
+        }
+        if (jobsStall !== undefined && jobsStall.length > 0) {
+            const parsed = Number.parseInt(jobsStall, 10);
+            if (Number.isFinite(parsed))
+                section.stallSeconds = parsed;
+        }
+        // A PARTIAL section, safe only because every consumer deep-merges it - the
+        // same contract `partial.skills` / `partial.log` / `partial.team` rely on.
+        if (Object.keys(section).length > 0)
+            partial.jobs = section;
+    }
     const retry = process.env.ARAGON_RETRY?.trim().toLowerCase();
     const retryMax = process.env.ARAGON_RETRY_MAX?.trim();
     if ((retry !== undefined && retry.length > 0) || (retryMax !== undefined && retryMax.length > 0)) {

package/dist/config/load.js

@@ -6,7 +6,8 @@
  * legitimately long single tool run can never be watchdog-killed.
  */
 import process from 'node:process';
-import { DEFAULT_CONFIG, DEFAULT_SCROLL_MODE, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampCompactionConfig, clampLogConfig, clampFastConfig, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampBashConfig, clampUpdateConfig, clampTheme, clampThinkingLevel, clampContextWindow, clampMaxTokens, clampMaxRenderInterval, clampScrollMode, clampScrollResumeMs, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAutoToken, isSkillsToolPolicyMode, legacyTeamCeilingPatch, parseThresholdInput, } from './schema.js';
+import { JOB_WAIT_MARGIN_MS } from '../proc/limits.js';
+import { DEFAULT_CONFIG, DEFAULT_SCROLL_MODE, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampCompactionConfig, clampLogConfig, clampFastConfig, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampBashConfig, clampJobsConfig, clampUpdateConfig, clampTheme, clampThinkingLevel, clampContextWindow, clampMaxTokens, clampMaxRenderInterval, clampScrollMode, clampScrollResumeMs, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAutoToken, isSkillsToolPolicyMode, legacyTeamCeilingPatch, parseThresholdInput, } from './schema.js';
 import { loadDotenv, readEnvConfig, readEnvDisabledSkills } from './env.js';
 import { readConfigFile, updatePersistedConfig } from './store.js';
 import { projectModelProfiles, resolveModelProfileState, resolveModelRoleKey, } from './model-profile-resolution.js';
@@ -182,6 +183,23 @@ function resolveBashConfig(env, file) {
         ...(env.bash ?? {}),
     });
 }
+/**
+ * Merge the `jobs` section across the three layers that supply it
+ * (defaults > file > env), long-task-jobs §6.5.
+ *
+ * THREE LAYERS, NOT FOUR, and that is the same decision `resolveBashConfig`
+ * records: both switches this section carries are already reachable from
+ * `config.json` (a per-machine preference) and from the environment (the channel
+ * a container entrypoint has). A fourth spelling would be a fourth place for the
+ * answer to differ.
+ */
+function resolveJobsConfig(env, file) {
+    return clampJobsConfig({
+        ...DEFAULT_CONFIG.jobs,
+        ...(file.jobs ?? {}),
+        ...(env.jobs ?? {}),
+    });
+}
 /**
  * Merge the `retry` section across all four layers (defaults › file › env ›
  * flags), llm-api-retry-backoff §6.2.
@@ -554,10 +572,32 @@ export function loadConfig(flags = {}, options = {}) {
     const planModeMaxAskRounds = clampAskRounds(file.planModeMaxAskRounds, DEFAULT_CONFIG.planModeMaxAskRounds);
     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.
+    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 = {};
@@ -687,6 +727,10 @@ 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.
+        jobs,
         cwd,
         color,
         colorLevel,
@@ -730,6 +774,11 @@ function recordResolvedConfig(config) {
         // trace — so "why did my failing call sit there for three minutes" (or
         // "why did it not retry at all") has an answer after the fact.
         retry: config.retry.enabled ? config.retry.maxRetries : 'off',
+        // The CONVERGED value, not the configured one: after I-4 they can differ, and
+        // "my 30s wait became 10s" is answerable only if the resolved number is
+        // recorded rather than the one on disk.
+        jobWaitSeconds: config.jobs.waitSeconds,
+        jobsEnabled: config.jobs.enabled,
         hasApiKey: Boolean(config.apiKeys[config.provider]),
         configPath: getConfigPath(),
     });

package/dist/config/schema.d.ts

@@ -795,6 +795,62 @@ export declare const DEFAULT_BASH_CONFIG: BashConfig;
  * A garbage `startupSettleMs` resolves to 4000 and throws nothing.
  */
 export declare function clampBashConfig(raw: unknown): BashConfig;
+export interface JobsConfig {
+    /**
+     * Register `job_wait` / `job_list`, splice the `<background_jobs>` block,
+     * mirror job logs. Default TRUE.
+     *
+     * READ ONCE AT CONSTRUCTION, the `bash.background` / `team.enabled` rule. Its
+     * job is to be the single switch under which the tool array, the tool
+     * descriptions and the system prompt are BYTE-IDENTICAL to the pre-feature
+     * build (I-3) - which is why it is a registration switch and not a behaviour
+     * flag.
+     */
+    enabled: boolean;
+    /**
+     * Seconds one `job_wait` blocks by default. Default 30, range 5..60.
+     *
+     * 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.
+     */
+    waitSeconds: number;
+    /**
+     * Seconds without output before a job is reported `[stalled]`. Default 300,
+     * range 30..3600.
+     *
+     * A REPORT, NEVER AN ACTION: nothing kills or retries on this (R-13). The
+     * default is deliberately generous, because a training epoch that prints every
+     * five minutes is healthy.
+     */
+    stallSeconds: number;
+    /**
+     * Mirror each job's full output to `<home>/jobs/<session>/<id>.log`. Default
+     * TRUE; `false` creates no directory at all, for privacy- or IO-sensitive
+     * environments (D-6).
+     */
+    persistLog: boolean;
+    /**
+     * Whether a completion notice may STEER the running turn. Default TRUE.
+     *
+     * NOT A NOTICE SWITCH (§6.5). With this off, notices still arrive at the end of
+     * the next tool result and before the next user turn; only the active
+     * interruption stops. Turning notifications off entirely would require running
+     * no jobs.
+     */
+    noticeSteer: boolean;
+}
+export declare const DEFAULT_JOBS_CONFIG: JobsConfig;
+/**
+ * THE single gate for every `jobs` read AND write, mirroring `clampBashConfig`
+ * and the four sections before it.
+ *
+ * THE ELEVENTH SECTION, AND THE FIRST ONE THAT `config set` CAN REACH BY
+ * NESTED KEY (§6.5). Every key is a SCALAR and the section is ONE level deep,
+ * because `runConfigGet` splits on a single dot - a `jobs.mirror.enabled` would
+ * resolve to `undefined` and the setting would silently never apply.
+ */
+export declare function clampJobsConfig(raw: unknown): JobsConfig;
 /**
  * Parse `0.9`, `90%` or `90` into a ratio, or `null` when it is neither.
  *
@@ -955,6 +1011,8 @@ export interface PersistedConfig {
     compaction: CompactionConfig;
     /** Background services. The TENTH nested object; scalars only (see BashConfig). */
     bash: BashConfig;
+    /** Background jobs and bounded waiting. The ELEVENTH; scalars only (see JobsConfig). */
+    jobs: JobsConfig;
 }
 export declare const DEFAULT_CONFIG: PersistedConfig;
 /**
@@ -1262,6 +1320,21 @@ export interface CliConfig {
      * either of them.
      */
     bash: BashConfig;
+    /**
+     * Background jobs and bounded waiting (long-task-jobs §6.5). The ELEVENTH
+     * nested object; five scalar keys, one level deep.
+     *
+     * ON `CliConfig` AS WELL AS `PersistedConfig`, for the reason every section
+     * above records: `AgentController` reads `config.jobs.waitSeconds` through a
+     * closure and `job_wait` reads it again at call time, so a key persisted and
+     * never projected would round-trip through `config set`, show up in
+     * `config list`, and change nothing.
+     *
+     * ONE LEVEL DEEP IS A HARD REQUIREMENT, NOT A PREFERENCE: `runConfigGet` splits
+     * `jobs.waitSeconds` on a single dot, so a nested sub-object would resolve to
+     * `undefined` and report an empty value for a setting that IS on disk.
+     */
+    jobs: JobsConfig;
     /**
      * Lifetime submit count driving the composer hint fade (`HINT_FADE_AFTER`).
      *

package/dist/config/schema.js

@@ -930,6 +930,34 @@ export function clampBashConfig(raw) {
         readyTimeoutMs: clampInt(src.readyTimeoutMs, DEFAULT_BASH_CONFIG.readyTimeoutMs, READY_TIMEOUT_RANGE),
     };
 }
+export const DEFAULT_JOBS_CONFIG = {
+    enabled: true,
+    waitSeconds: 30,
+    stallSeconds: 300,
+    persistLog: true,
+    noticeSteer: true,
+};
+const WAIT_SECONDS_RANGE = { min: 5, max: 60 };
+const STALL_SECONDS_RANGE = { min: 30, max: 3600 };
+/**
+ * THE single gate for every `jobs` read AND write, mirroring `clampBashConfig`
+ * and the four sections before it.
+ *
+ * THE ELEVENTH SECTION, AND THE FIRST ONE THAT `config set` CAN REACH BY
+ * NESTED KEY (§6.5). Every key is a SCALAR and the section is ONE level deep,
+ * because `runConfigGet` splits on a single dot - a `jobs.mirror.enabled` would
+ * resolve to `undefined` and the setting would silently never apply.
+ */
+export function clampJobsConfig(raw) {
+    const src = (raw && typeof raw === 'object' ? raw : {});
+    return {
+        enabled: bool(src.enabled, DEFAULT_JOBS_CONFIG.enabled),
+        waitSeconds: clampInt(src.waitSeconds, DEFAULT_JOBS_CONFIG.waitSeconds, WAIT_SECONDS_RANGE),
+        stallSeconds: clampInt(src.stallSeconds, DEFAULT_JOBS_CONFIG.stallSeconds, STALL_SECONDS_RANGE),
+        persistLog: bool(src.persistLog, DEFAULT_JOBS_CONFIG.persistLog),
+        noticeSteer: bool(src.noticeSteer, DEFAULT_JOBS_CONFIG.noticeSteer),
+    };
+}
 /**
  * Parse `0.9`, `90%` or `90` into a ratio, or `null` when it is neither.
  *
@@ -1028,6 +1056,12 @@ export const DEFAULT_CONFIG = {
     // `undefined` would arrive with background services OFF for every existing
     // user — the same direction the compaction line above must never fail in.
     bash: DEFAULT_BASH_CONFIG,
+    // And one section later again, for the sixth time, and this one would fail
+    // in the WORSE direction: every key in `jobs` is `true` or positive by
+    // default, so a `config.json` predating this feature resolving `config.jobs`
+    // to `undefined` would throw on `config.jobs.waitSeconds` at construction
+    // rather than quietly disabling something.
+    jobs: DEFAULT_JOBS_CONFIG,
 };
 /**
  * Runtime state that used to be stored in `config.json` by mistake

package/dist/config/store.js

@@ -17,7 +17,7 @@ import { getConfigPath, getSessionsDir } from './app-paths.js';
 import { registerProfileSecrets, registerSecretsFrom } from '../logging/secret-registry.js';
 import { adaptLegacyConnectionPatch, ModelProfileConfigError, readModelSettingsDisk } from './model-profile-store.js';
 import { normalizeModelProfiles } from './model-profiles.js';
-import { clampBashConfig, CONFIG_VERSION, DEFAULT_CONFIG, clampCompactionConfig, clampFastConfig, clampLogConfig, clampMaxTokens, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampContextWindow, clampUpdateConfig, isAutoToken, stripLegacyStateKeys, } from './schema.js';
+import { clampBashConfig, clampJobsConfig, CONFIG_VERSION, DEFAULT_CONFIG, clampCompactionConfig, clampFastConfig, clampLogConfig, clampMaxTokens, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampContextWindow, clampUpdateConfig, isAutoToken, stripLegacyStateKeys, } from './schema.js';
 /**
  * Normalize `maxTokens` for both directions of the config file.
  *
@@ -189,6 +189,12 @@ export function normalizePersistedConfig(input) {
         // and NOT merged over the defaults, which is verbatim the failure the
         // paragraph above says this line prevents.
         bash: clampBashConfig({ ...DEFAULT_CONFIG.bash, ...(partial.bash ?? {}) }),
+        // And the eleventh, on the same line and for the same reason. `jobs.enabled`
+        // is `true` by default, so a user whose `config.json` predates this feature
+        // must not resolve it to `undefined` — and `waitSeconds` would be `undefined`
+        // outright, which is a crash on the first `job_wait` rather than a silently
+        // wrong setting.
+        jobs: clampJobsConfig({ ...DEFAULT_CONFIG.jobs, ...(partial.jobs ?? {}) }),
     };
 }
 /**
@@ -289,6 +295,13 @@ export function mergePersistedConfig(current, patch) {
         // top level and write `background` absent, silently unregistering
         // `bash_output` / `bash_kill` from the next launch onward.
         bash: clampBashConfig({ ...current.bash, ...(patch.bash ?? {}) }),
+        // The eleventh section, and the sixth time this file records the same trap.
+        // `aragon config set jobs.waitSeconds 45` sends `{ jobs: { waitSeconds: 45 } }`;
+        // without this line the shallow top-level spread REPLACES the section and
+        // `persistLog` / `noticeSteer` / `enabled` / `stallSeconds` are written
+        // absent — with `noticeSteer`'s default masking it on the next load, so the
+        // user would never learn that their privacy switch had been turned back on.
+        jobs: clampJobsConfig({ ...current.jobs, ...(patch.jobs ?? {}) }),
     };
     return merged;
 }

package/dist/exec/events.d.ts

@@ -9,8 +9,11 @@
  *
  * PURE TYPES AND BUILDERS. No I/O, no process access, no imports outside
  * `node:`-free type space, so a consumer of this module cannot accidentally
- * evaluate the runner.
- *
+ * evaluate the runner. The one import below is a TYPE from `proc/types.ts` for
+ * the same reason: a shape, erased at compile time.
+ */
+import type { ServiceStatus } from '../proc/types.js';
+/**
  * `EXEC_SCHEMA_VERSION` appears on `system` and on `result` and NOWHERE ELSE.
  * ADDING A FIELD OR AN EVENT TYPE NEVER BUMPS IT; renaming or removing one does.
  * That rule only holds if consumers keep their side of it, so the README states
@@ -370,7 +373,30 @@ export interface ExecResultEvent {
     todos: ExecTodoCounts | null;
     error: ExecErrorInfo | null;
 }
-export type ExecEvent = ExecSystemInitEvent | ExecUserEvent | ExecTurnStateEvent | ExecProgressEvent | ExecTextDeltaEvent | ExecThinkingEvent | ExecAssistantEvent | ExecToolCallEvent | ExecToolResultEvent | ExecTodoEvent | ExecTeamEvent | ExecFastReviewEvent | ExecFastTierEvent | ExecCompactionEvent | ExecRetryEvent | ExecErrorEvent | ExecResultEvent;
+/**
+ * A background job's lifecycle (long-task-jobs §4.10).
+ *
+ * A PURE ADDITION to schema v1: a consumer that does not know this `type`
+ * ignores it, which is the forward-compatibility contract this file's header
+ * states. `progress` is emitted only when the extracted text CHANGES and at most
+ * once a second - a 40-minute training run would otherwise write thousands of
+ * lines to a machine consumer's stdout.
+ */
+export interface ExecJobEvent {
+    type: 'job';
+    schemaVersion: number;
+    sessionId: string;
+    subtype: 'started' | 'progress' | 'exited' | 'stalled';
+    /** `t3` / `s1`. */
+    jobId: string;
+    kind: 'service' | 'task';
+    status: ServiceStatus;
+    elapsedMs: number;
+    /** Only on `subtype === 'progress'`, and only when the text changed. */
+    progress?: string;
+    exitCode?: number | null;
+}
+export type ExecEvent = ExecSystemInitEvent | ExecUserEvent | ExecTurnStateEvent | ExecProgressEvent | ExecTextDeltaEvent | ExecThinkingEvent | ExecAssistantEvent | ExecToolCallEvent | ExecToolResultEvent | ExecTodoEvent | ExecTeamEvent | ExecFastReviewEvent | ExecFastTierEvent | ExecCompactionEvent | ExecRetryEvent | ExecJobEvent | ExecErrorEvent | ExecResultEvent;
 /** Everything `system/init` needs that the runner cannot derive for itself. */
 export interface ExecInitParams {
     sessionId: string;

package/dist/exec/events.js

@@ -1,16 +1,4 @@
 /**
- * THE CONTRACT (cli-integration-surface section 5.1).
- *
- * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope
- * (`glyphs.test.ts::inScope`, R-3 / AC-25). Every string here can reach a
- * consumer's terminal through `--output-format text` fallbacks or a stderr
- * warning, and the whole point of the scanner is that a legacy `cmd.exe` shows
- * mojibake for anything else.
- *
- * PURE TYPES AND BUILDERS. No I/O, no process access, no imports outside
- * `node:`-free type space, so a consumer of this module cannot accidentally
- * evaluate the runner.
- *
  * `EXEC_SCHEMA_VERSION` appears on `system` and on `result` and NOWHERE ELSE.
  * ADDING A FIELD OR AN EVENT TYPE NEVER BUMPS IT; renaming or removing one does.
  * That rule only holds if consumers keep their side of it, so the README states
@@ -53,6 +41,9 @@ export const EXEC_CAPABILITIES = [
     'session-file',
     'turn-lifecycle',
     'execution-progress',
+    // Background job lifecycle events (long-task-jobs §4.10). A consumer that does
+    // not know the `job` type ignores it; this string is how it asks first.
+    'background-jobs',
 ];
 export function buildInitEvent(params) {
     return {

package/dist/exec/runner.d.ts

@@ -20,6 +20,7 @@ import { type FollowThroughMode } from '../todo/follow-through.js';
 import type { ExecEmitter } from './emitter.js';
 import type { FastSnapshot } from '../fast/types.js';
 import type { ExecStopReason } from './events.js';
+import type { ProcEvent } from '../proc/types.js';
 /**
  * The controller surface the runner needs.
  *
@@ -45,6 +46,14 @@ export interface ExecRunnerController extends HeadlessController {
      * it simply emits no `fast_tier` events.
      */
     fastSnapshot?(): FastSnapshot | null;
+    /**
+     * The CLI-local process stream, when this session supervises processes.
+     *
+     * OPTIONAL AND CALLED WITH `?.()`, exactly like the three optional streams
+     * above: this interface is minimal so a test can satisfy it with an object
+     * literal, and a host with no supervisor has nothing to report.
+     */
+    subscribeProc?(listener: (event: ProcEvent) => void): () => void;
 }
 /** Where the caller's messages come from. One turn, or an NDJSON stdin stream. */
 export interface ExecPromptSource {
@@ -97,6 +106,10 @@ export declare class ExecRunner {
     private readonly progress;
     private controller;
     private unsubscribers;
+    /** Per-job progress throttle state: the last text emitted, and when. */
+    private readonly jobProgressAt;
+    /** Per-job `lastOutputAt` at which `stalled` was last reported. */
+    private readonly jobStalledAt;
     private turns;
     private readonly usage;
     private compactionBilling;
@@ -123,6 +136,17 @@ export declare class ExecRunner {
      * multiple subscribers.
      */
     attach(controller: ExecRunnerController): void;
+    /**
+     * Map a supervisor event onto the `job` channel.
+     *
+     * THROTTLING IS THE WHOLE DISCIPLINE HERE. `output` is already coalesced to
+     * <=10 Hz inside the supervisor, which is still far too fast for a machine
+     * consumer reading a 40-minute training run; `progress` is therefore emitted
+     * only when the extracted TEXT CHANGES and never more than once a second. The
+     * other three subtypes are one-shot per job, so they pass straight through.
+     */
+    private onProcEvent;
+    private emitJob;
     /**
      * Drop the subscriptions and the timer.
      *

package/dist/exec/runner.js

@@ -17,6 +17,7 @@
 import { formatStreamError } from '../agent/reducer.js';
 import { setSignalTerminator } from '../logging/install.js';
 import { advanceBudget, decideFollowThrough, emptyBudget, } from '../todo/follow-through.js';
+import { EXEC_SCHEMA_VERSION } from './events.js';
 import { ExecProgressReporter } from './progress-reporter.js';
 export function singlePrompt(text) {
     let served = false;
@@ -44,6 +45,10 @@ export class ExecRunner {
     progress;
     controller = null;
     unsubscribers = [];
+    /** Per-job progress throttle state: the last text emitted, and when. */
+    jobProgressAt = new Map();
+    /** Per-job `lastOutputAt` at which `stalled` was last reported. */
+    jobStalledAt = new Map();
     turns = 0;
     usage = { inputTokens: 0, outputTokens: 0 };
     compactionBilling;
@@ -218,8 +223,82 @@ export class ExecRunner {
         });
         if (compaction)
             this.unsubscribers.push(compaction);
+        // Background jobs (long-task-jobs §4.10). SUBSCRIBED HERE, IN `attach()`, NOT
+        // IN `start()`: the follow-through chain enters `run()` more than once, and a
+        // subscription made there would be re-made every time and never released —
+        // one leaked listener per turn for the life of the process.
+        //
+        // The four-stream shape is deliberate: `?:` optional call, `unsubscribers`
+        // push, `detach()` releases. Identical to `subscribeTeam` / `subscribeTodos` /
+        // `subscribeFast` / `subscribeCompaction`, so a host without a supervisor
+        // simply emits nothing.
+        const proc = controller.subscribeProc?.((event) => this.onProcEvent(event));
+        if (proc)
+            this.unsubscribers.push(proc);
         this.installTerminator();
     }
+    /**
+     * Map a supervisor event onto the `job` channel.
+     *
+     * THROTTLING IS THE WHOLE DISCIPLINE HERE. `output` is already coalesced to
+     * <=10 Hz inside the supervisor, which is still far too fast for a machine
+     * consumer reading a 40-minute training run; `progress` is therefore emitted
+     * only when the extracted TEXT CHANGES and never more than once a second. The
+     * other three subtypes are one-shot per job, so they pass straight through.
+     */
+    onProcEvent(event) {
+        const job = event.service;
+        if (event.type === 'started') {
+            this.emitJob(job, 'started');
+            return;
+        }
+        if (event.type === 'exited' || event.type === 'stopped') {
+            this.jobProgressAt.delete(job.id);
+            this.jobStalledAt.delete(job.id);
+            this.emitJob(job, 'exited');
+            return;
+        }
+        // `ready` is deliberately NOT mapped onto a second `started`: a service emits
+        // both, and a consumer that counted `started` events would see two. The
+        // readiness fact is already carried by `status` on any later event, and the
+        // four subtypes this channel publishes are one-shot per job.
+        if (event.type !== 'output')
+            return;
+        if (job.stalled === true) {
+            if (this.jobStalledAt.get(job.id) === job.lastOutputAt)
+                return;
+            this.jobStalledAt.set(job.id, job.lastOutputAt);
+            this.emitJob(job, 'stalled');
+            return;
+        }
+        const text = job.progress?.text;
+        if (text === undefined)
+            return;
+        if (this.jobProgressAt.get(job.id)?.text === text)
+            return;
+        const now = Date.now();
+        const last = this.jobProgressAt.get(job.id)?.at ?? 0;
+        // ONE SECOND IS THE FLOOR, and the first change of a job is always emitted
+        // (no previous entry), so a consumer sees the initial figure immediately.
+        if (last !== 0 && now - last < 1000)
+            return;
+        this.jobProgressAt.set(job.id, { text, at: now });
+        this.emitJob(job, 'progress', text);
+    }
+    emitJob(job, subtype, progress) {
+        this.emit({
+            type: 'job',
+            schemaVersion: EXEC_SCHEMA_VERSION,
+            sessionId: this.sessionId,
+            subtype,
+            jobId: job.id,
+            kind: job.kind,
+            status: job.status,
+            elapsedMs: Math.max(0, (job.endedAt ?? Date.now()) - job.startedAt),
+            ...(progress !== undefined ? { progress } : {}),
+            ...(subtype === 'exited' ? { exitCode: job.exitCode } : {}),
+        });
+    }
     /**
      * Drop the subscriptions and the timer.
      *