@qodeca/xezar 0.11.2 → 0.13.0

package/dist/workflows/run.d.ts

@@ -4,7 +4,15 @@ import { type Skill } from '../skills.ts';
 import type { QueuedMessage, RunRecord, RunStore } from '../runs/store.ts';
 import { WorkspaceSemaphore, type AccountHolds } from '../workspace/semaphore.ts';
 import { type WorkflowDef } from './types.ts';
-/** An interactive session that hears nothing from the user closes itself. */
+/**
+ * An interactive session that hears nothing from the user closes itself.
+ *
+ * Kept as the module default so `stepTimeoutMs`-style callers and old imports still
+ * resolve, but enforcement no longer reads it directly: `armIdleTimer` asks the shared
+ * `WorkspaceSemaphore`, so `resources.idleTimeoutMinutes` takes effect on the next park
+ * without a restart. This constant IS that setting's default, via
+ * `DEFAULT_IDLE_TIMEOUT_MINUTES`.
+ */
 export declare const IDLE_TIMEOUT_MS: number;
 /**
  * Preserve boundaries between complete assistant text blocks while a turn is
@@ -28,6 +36,9 @@ export declare function periodicAutosaveEnabled(env?: NodeJS.ProcessEnv): boolea
  * files or Git state. Isolated worktree runs are unaffected.
  */
 export declare function repositoryRootLockDisabled(env?: NodeJS.ProcessEnv): boolean;
+/** Safety cap on autonomous auto-continues per run — stops a stuck agent from nudging forever.
+ *  Exported so the regression suite pins the bound against the real number instead of a copy. */
+export declare const MAX_AUTO_CONTINUES = 40;
 /**
  * Auto-resume after a provider usage limit (spec 2026-08-03-auto-resume-after-usage-limit).
  *
@@ -254,6 +265,15 @@ export declare class RunManager {
     private readonly offUsage;
     /** The stalled-queue watchdog (see `rescueStalledQueue`). */
     private readonly queueWatchdog;
+    /** The rescue sweeps that have STARTED and not settled yet (#125). `clearInterval` cancels the
+     *  next tick; it cannot cancel the tick already running, and a sweep is async — it awaits
+     *  `reviveWorkflow` before appending NDJSON. dispose() settles these so a torn-down manager is
+     *  provably finished writing before its caller removes the data root under it. */
+    private readonly rescuesInFlight;
+    /** Set by dispose(): this manager makes no further moves. Re-checked at every await boundary a
+     *  rescue crosses, because a sweep that was already past its first check when dispose() landed
+     *  would otherwise write an event — and re-populate the queue dispose() had just emptied. */
+    private disposed;
     /** Set by the watchdog for exactly one sweep: ignore the usage-limit hold and make progress. */
     private forceNextPump;
     /** Runs the watchdog started despite the hold. The spawn-time gate (`requeueWhileHeld`) would
@@ -278,8 +298,19 @@ export declare class RunManager {
      * repo-root locks, and empties the queued state so nothing fires later.
      * Live sessions are NOT ended here: run lifecycle stays the caller's policy;
      * dispose only guarantees the manager makes no further moves on its own.
+     *
+     * Every side effect below is SYNCHRONOUS, so a caller that ignores the return value behaves
+     * exactly as it did before #125. The returned promise settles the one thing dispose cannot do
+     * synchronously: a queue-watchdog rescue that had already started. `clearInterval` stops the
+     * next tick, never the running one — the same discipline `AGENTS.md` records for the e2e
+     * fixture servers, where `kill()` only delivers the signal and the helper awaits the exit.
+     * Await it whenever the data root is about to be removed; a test that deletes its temp
+     * directory without awaiting is the ENOENT in #125.
+     *
+     * It never rejects: a sweep that fails still belongs to whoever started it (the watchdog floats
+     * it exactly as before), and teardown must not become a second place that error surfaces.
      */
-    dispose(): void;
+    dispose(): Promise<void>;
     /**
      * Pause any active run whose whole process tree exceeds the WORKSPACE
      * `resources.memoryLimitMb`, freeing its slot so the queue advances
@@ -384,6 +415,11 @@ export declare class RunManager {
      * `continue-N` step and the session before it are durable, which is enough. Otherwise the
      * workflow is revived from the record. A run that can be neither is failed loudly rather than
      * left in the queue as a ghost.
+     *
+     * Both effects here — an NDJSON append and a queue push — must not outlive dispose(), so the
+     * flag is re-read after `reviveWorkflow`, the one await this method crosses (#125). Bailing
+     * leaves the record `queued`, which is exactly what it was: re-adoption is what boot recovery
+     * does for the next owner of this data directory.
      */
     private reviveQueuedRun;
     /**
@@ -466,8 +502,14 @@ export declare class RunManager {
      * honest hold, with a real deadline behind it this time.
      *
      * Public so a test can drive the wedge directly instead of waiting out the interval.
+     *
+     * The sweep itself is `sweepStalledQueue`; this wrapper only publishes it to `rescuesInFlight`
+     * so dispose() can settle it (#125). Every entry point goes through here — the interval and the
+     * tests alike — so nothing can start a sweep that teardown cannot see. The schedule, the
+     * conditions and the effects are untouched.
      */
     rescueStalledQueue(now?: number): Promise<void>;
+    private sweepStalledQueue;
     /**
      * The accounts this project is currently holding: one key per run parked on a usage-limit
      * resume that has not come due yet (spec 2026-08-03-auto-resume-after-usage-limit).
@@ -639,6 +681,21 @@ export declare class RunManager {
         error?: string;
     };
     private runContinuation;
+    /**
+     * Autonomous turn end (#489): never hand the ball back to the user — nudge the agent to keep
+     * going and report whether the ball stayed with it. `false` means "park normally", which is
+     * every non-autonomous run, a run whose pause cleared `autonomous` (the memory-limit
+     * suppression above), a cancelled one, a closed session that cannot take the message, and a
+     * run that has spent its `MAX_AUTO_CONTINUES` budget.
+     *
+     * ONE helper, called from BOTH turn-end handlers, because the split is exactly what broke:
+     * `execute` set `autonomous` on its `ActiveRun` and its handler never read it, while
+     * `runContinuation`'s handler read it and its `ActiveRun` never set it — so the nudge fired
+     * nowhere and every autonomous run parked after one turn (#141). AGENTS.md names both traps:
+     * grep the TYPE at every construction site, and treat the two near-identical turn-end handlers
+     * as one place. Keep this the only sender of `AUTONOMOUS_NUDGE`.
+     */
+    private autoContinueTurn;
     private execute;
     /** Returns an error message, or null on success. */
     private runAgentStep;
@@ -747,6 +804,14 @@ export declare class RunManager {
      * shows the tool result's `[screenshot]` placeholder (or the image count).
      */
     private persistAttachment;
+    /**
+     * Arm the idle wall clock for a session that just parked at `waiting`.
+     *
+     * The duration comes from the shared semaphore's cached `resources.idleTimeoutMinutes`,
+     * so a change made in Settings applies to the next park with no restart. `null` means
+     * the operator chose "never close on idle": no timer is armed, and the only exits left
+     * are a user message and Cancel — both of which a `waiting` run already advertises.
+     */
     private armIdleTimer;
     private clearIdleTimer;
     private reconcileMonitoringWakeTimers;

package/dist/workflows/run.js

@@ -9,7 +9,7 @@ import { createRunner } from '../core/runner-factory.js';
 import { modelConflictsWithRunner } from '../core/model-presets.js';
 import { AGENT_MODELS_LOCKED_ERROR, agentModelsLocked } from '../core/agent-model-policy.js';
 import { ModelIdentityError, formatModelIdentity, normalizeModelForBackend, } from '../core/model-identity.js';
-import { HANDOFF_ONLY_INSTRUCTIONS, HANDOFF_INSTRUCTIONS, appendHandoffHeartbeat, followupsEnabled, handoffPath, seedHandoffFile, } from '../handoff.js';
+import { HANDOFF_ONLY_INSTRUCTIONS, HANDOFF_INSTRUCTIONS, appendHandoffHeartbeat, handoffPath, seedHandoffFile, } from '../handoff.js';
 import { todosPath } from '../todos.js';
 // Contract VALUES, like `workspaceUiStateSchema` in workspace/migrations.ts: the attachment
 // vocabulary the routes validate with is the same one the engine stores and re-reads by, so the
@@ -31,15 +31,24 @@ import { autoNamingActive, generateRunName, liveTitleUpdatesEnabled, postValidat
 import { reviewGateEnabled } from '../runs/review-gate.js';
 import { resolveProfileEnvForRoot } from '../workspace/agent-profiles.js';
 import { DEFAULT_AGENT_ACCOUNT_ID } from '../workspace/agent-accounts.js';
+import { DEFAULT_IDLE_TIMEOUT_MINUTES } from '../workspace/config.js';
 import { WorkspaceSemaphore } from '../workspace/semaphore.js';
 import { UiEventSink } from '../runs/ui-event-sink.js';
-import { chainStepNote, DEFAULT_ALLOWED_TOOLS, stepKind } from './types.js';
+import { chainStepNote, DEFAULT_ALLOWED_TOOLS, stepKind, stepTimeoutMs, } from './types.js';
 const CHECK_OUTPUT_CAP = 20_000;
 async function configuredModelProvider(backend, repoRoot) {
     return readAgentModelProvider(backend, repoRoot).catch(() => undefined);
 }
-/** An interactive session that hears nothing from the user closes itself. */
-export const IDLE_TIMEOUT_MS = 15 * 60_000;
+/**
+ * An interactive session that hears nothing from the user closes itself.
+ *
+ * Kept as the module default so `stepTimeoutMs`-style callers and old imports still
+ * resolve, but enforcement no longer reads it directly: `armIdleTimer` asks the shared
+ * `WorkspaceSemaphore`, so `resources.idleTimeoutMinutes` takes effect on the next park
+ * without a restart. This constant IS that setting's default, via
+ * `DEFAULT_IDLE_TIMEOUT_MINUTES`.
+ */
+export const IDLE_TIMEOUT_MS = DEFAULT_IDLE_TIMEOUT_MINUTES * 60_000;
 /**
  * Task-completion marker from the agent contract (HANDOFF_INSTRUCTIONS): a
  * turn whose text ends with `XEZ:DONE` means "goal achieved, nothing to ask" —
@@ -157,8 +166,9 @@ export function repositoryRootLockDisabled(env = process.env) {
     return env.XEZ_DISABLE_REPO_LOCK === '1';
 }
 const REPOSITORY_ROOT_LOCK_DISABLED_NOTE = 'repository-root lock disabled by XEZ_DISABLE_REPO_LOCK=1 (shared checkout is unsafe)';
-/** Safety cap on autonomous auto-continues per run — stops a stuck agent from nudging forever. */
-const MAX_AUTO_CONTINUES = 40;
+/** Safety cap on autonomous auto-continues per run — stops a stuck agent from nudging forever.
+ *  Exported so the regression suite pins the bound against the real number instead of a copy. */
+export const MAX_AUTO_CONTINUES = 40;
 const AUTONOMOUS_NUDGE = 'Continue working autonomously until the task is fully complete. Do not ask me for confirmation or clarification — make reasonable assumptions and proceed. When everything is done, end the session with your done signal.';
 const MONITORING_WAKE_NUDGE = 'Re-check the downstream work you were monitoring. Continue toward the task goal; emit XEZ:MONITORING again only if it is still pending.';
 /**
@@ -428,6 +438,15 @@ export class RunManager {
     offUsage;
     /** The stalled-queue watchdog (see `rescueStalledQueue`). */
     queueWatchdog;
+    /** The rescue sweeps that have STARTED and not settled yet (#125). `clearInterval` cancels the
+     *  next tick; it cannot cancel the tick already running, and a sweep is async — it awaits
+     *  `reviveWorkflow` before appending NDJSON. dispose() settles these so a torn-down manager is
+     *  provably finished writing before its caller removes the data root under it. */
+    rescuesInFlight = new Set();
+    /** Set by dispose(): this manager makes no further moves. Re-checked at every await boundary a
+     *  rescue crosses, because a sweep that was already past its first check when dispose() landed
+     *  would otherwise write an event — and re-populate the queue dispose() had just emptied. */
+    disposed = false;
     /** Set by the watchdog for exactly one sweep: ignore the usage-limit hold and make progress. */
     forceNextPump = false;
     /** Runs the watchdog started despite the hold. The spawn-time gate (`requeueWhileHeld`) would
@@ -466,8 +485,20 @@ export class RunManager {
      * repo-root locks, and empties the queued state so nothing fires later.
      * Live sessions are NOT ended here: run lifecycle stays the caller's policy;
      * dispose only guarantees the manager makes no further moves on its own.
+     *
+     * Every side effect below is SYNCHRONOUS, so a caller that ignores the return value behaves
+     * exactly as it did before #125. The returned promise settles the one thing dispose cannot do
+     * synchronously: a queue-watchdog rescue that had already started. `clearInterval` stops the
+     * next tick, never the running one — the same discipline `AGENTS.md` records for the e2e
+     * fixture servers, where `kill()` only delivers the signal and the helper awaits the exit.
+     * Await it whenever the data root is about to be removed; a test that deletes its temp
+     * directory without awaiting is the ENOENT in #125.
+     *
+     * It never rejects: a sweep that fails still belongs to whoever started it (the watchdog floats
+     * it exactly as before), and teardown must not become a second place that error surfaces.
      */
     dispose() {
+        this.disposed = true;
         this.offUsage();
         this.offSemaphore();
         clearInterval(this.queueWatchdog);
@@ -489,6 +520,7 @@ export class RunManager {
         this.pendingContinuations.clear();
         this.memoryPausing.clear();
         this.lastNamerKey.clear();
+        return Promise.allSettled([...this.rescuesInFlight]).then(() => undefined);
     }
     /**
      * Pause any active run whose whole process tree exceeds the WORKSPACE
@@ -504,11 +536,12 @@ export class RunManager {
         const runIds = Object.keys(snapshot).filter((runId) => this.active.has(runId));
         if (runIds.length === 0)
             return;
-        // Workspace limit from the shared semaphore's in-memory cache (step 2.5:
-        // refreshed at boot and on PUT /api/workspace/config — never N per-tick
-        // file reads across N projects). Legacy per-repo `memoryLimitMb` keys are
-        // ignored post-migration.
-        const limitMb = this.semaphore.memoryLimitMb();
+        // Limit from the shared semaphore's in-memory cache (step 2.5: refreshed at boot and
+        // on a config PUT — never N per-tick file reads across N projects). This repo's OWN
+        // `.xezar/config.json` `memoryLimitMb` wins when it sets one and the workspace ceiling
+        // applies otherwise (B2) — the same more-specific-wins rule `projectMaxParallel`
+        // follows. Before B2 the per-repo key saved successfully and was then ignored here.
+        const limitMb = this.semaphore.projectMemoryLimitMb(this.repoRoot);
         if (!limitMb || limitMb <= 0)
             return;
         const limitBytes = limitMb * 1024 * 1024;
@@ -558,6 +591,14 @@ export class RunManager {
             XEZ_HANDOFF_FILE: handoffPath(this.dataDir, runId),
             XEZ_TASK_ID: runId,
             XEZ_TODOS_FILE: generateFollowups ? todosPath(this.dataDir) : '',
+            // The stored env-passthrough list (F), carried on the per-run env so it reaches EVERY
+            // backend through the one path they all share (`buildChildEnv(spec.env)`) — no runner
+            // seam change, and it is live because the semaphore refreshes on a config PUT. Set to
+            // `''` rather than omitted when the list is empty, for the same reason
+            // `XEZ_TODOS_FILE` is: the child inherits `process.env`, so an omitted key would let
+            // this process's own `XEZ_ENV_PASSTHROUGH` shine through and quietly override the
+            // stored "forward nothing" choice.
+            XEZ_ENV_PASSTHROUGH: this.semaphore.agentEnvPassthrough().join(','),
             ...agentTmpEnv(this.dataDir, runId),
         };
     }
@@ -607,7 +648,7 @@ export class RunManager {
             // The global inbox is the ceiling on the per-run flag (#471). Enforced here rather than
             // at the HTTP route because `xezar run`, the inbox's own "▶ Run" and variants all reach
             // startRun directly — a route-level gate would leave those writing todos.json.
-            generateFollowups: followupsEnabled() ? input.generateFollowups : false,
+            generateFollowups: this.semaphore.followupsEnabled() ? input.generateFollowups : false,
             // Persist autonomy on the record (#489) so the terminal review gate
             // (`settleSuccess`) and the group-pick winner-park can honor it — mid-run
             // auto-nudge reads `input.autonomous` (`execute`), but the record is the
@@ -846,8 +887,15 @@ export class RunManager {
      * `continue-N` step and the session before it are durable, which is enough. Otherwise the
      * workflow is revived from the record. A run that can be neither is failed loudly rather than
      * left in the queue as a ghost.
+     *
+     * Both effects here — an NDJSON append and a queue push — must not outlive dispose(), so the
+     * flag is re-read after `reviveWorkflow`, the one await this method crosses (#125). Bailing
+     * leaves the record `queued`, which is exactly what it was: re-adoption is what boot recovery
+     * does for the next owner of this data directory.
      */
     async reviveQueuedRun(run, reason) {
+        if (this.disposed)
+            return;
         const queuedContinuation = [...run.steps]
             .reverse()
             .find((step) => step.status === 'pending' && step.id.startsWith('continue-'));
@@ -872,6 +920,8 @@ export class RunManager {
             return;
         }
         const workflow = await this.reviveWorkflow(run);
+        if (this.disposed)
+            return;
         if (!workflow) {
             this.store.updateRun(run.id, {
                 status: 'failed',
@@ -888,7 +938,7 @@ export class RunManager {
         // safe either way — but a run queued while the inbox was on and recovered after it was
         // switched off would otherwise keep echoing `generateFollowups: true` on a run that
         // demonstrably produced none. Normalize the record, the way startRun does.
-        const generateFollowups = followupsEnabled() ? run.generateFollowups : false;
+        const generateFollowups = this.semaphore.followupsEnabled() ? run.generateFollowups : false;
         if (generateFollowups !== run.generateFollowups) {
             this.store.updateRun(run.id, { generateFollowups });
         }
@@ -1248,13 +1298,32 @@ export class RunManager {
      * honest hold, with a real deadline behind it this time.
      *
      * Public so a test can drive the wedge directly instead of waiting out the interval.
+     *
+     * The sweep itself is `sweepStalledQueue`; this wrapper only publishes it to `rescuesInFlight`
+     * so dispose() can settle it (#125). Every entry point goes through here — the interval and the
+     * tests alike — so nothing can start a sweep that teardown cannot see. The schedule, the
+     * conditions and the effects are untouched.
      */
     async rescueStalledQueue(now = Date.now()) {
+        if (this.disposed)
+            return;
+        const sweep = this.sweepStalledQueue(now);
+        this.rescuesInFlight.add(sweep);
+        try {
+            await sweep;
+        }
+        finally {
+            this.rescuesInFlight.delete(sweep);
+        }
+    }
+    async sweepStalledQueue(now) {
         // First, the worst shape: a record that says `queued` while the engine holds no job, no
         // continuation and no queue entry for it. `pump()` cannot see such a run — it iterates the
         // queue, and this one is not in it — so nothing will ever start it. Re-adopt it through the
         // same path boot recovery uses.
         for (const run of this.store.listRuns()) {
+            if (this.disposed)
+                return;
             if (run.status !== 'queued')
                 continue;
             if (this.active.has(run.id) || this.starting.has(run.id))
@@ -1266,6 +1335,8 @@ export class RunManager {
             console.warn(`[xez] queue watchdog: re-adopting queued run ${run.id} the engine had lost`);
             await this.reviveQueuedRun(run, 'queue watchdog');
         }
+        if (this.disposed)
+            return;
         if (this.queue.length === 0)
             return;
         if (this.busySlots() > 0 || this.starting.size > 0)
@@ -1963,11 +2034,23 @@ export class RunManager {
         const record = this.store.getRun(runId);
         // The env is a live ceiling: a run created while the inbox was on must not keep writing
         // follow-ups after it is switched off.
-        const generateFollowups = followupsEnabled() && record?.generateFollowups !== false;
+        const generateFollowups = this.semaphore.followupsEnabled() && record?.generateFollowups !== false;
         const cwd = record?.worktreePath && existsSync(record.worktreePath)
             ? record.worktreePath
             : this.repoRoot;
-        const state = { cancelled: false, interrupt: () => undefined, cwd };
+        // Autonomy is re-read from the RECORD, the way restart recovery re-threads it into
+        // `execute`'s input: a continuation builds its OWN `ActiveRun`, and omitting the field here
+        // is what made every Continue and every recovered resume silently non-autonomous while the
+        // record still said otherwise (#141) — the same construction-site asymmetry `state.skills`
+        // hit in #811. `autoContinues` starts at 0 rather than `undefined` so `MAX_AUTO_CONTINUES`
+        // bounds this path too; the budget is per `ActiveRun`, so a Continue starts a fresh one.
+        const state = {
+            cancelled: false,
+            interrupt: () => undefined,
+            cwd,
+            autonomous: record?.autonomous === true,
+            autoContinues: 0,
+        };
         this.active.set(runId, state);
         this.starting.delete(runId);
         if (state.cwd === this.repoRoot) {
@@ -2091,23 +2174,12 @@ export class RunManager {
                     state.session?.end();
                     return;
                 }
+                let autoContinued = false;
                 if (sessionOpen) {
                     // Autonomous (#autonomous): never hand the ball back to the user. Nudge the agent to
-                    // keep going (bounded by MAX_AUTO_CONTINUES) instead of parking at `waiting`.
-                    const autoContinued = state.autonomous &&
-                        (state.autoContinues ?? 0) < MAX_AUTO_CONTINUES &&
-                        !state.cancelled &&
-                        (() => {
-                            const sent = state.session?.sendMessage([{ type: 'text', text: AUTONOMOUS_NUDGE }]);
-                            if (!sent)
-                                return false;
-                            state.autoContinues = (state.autoContinues ?? 0) + 1;
-                            this.store.appendEvent(runId, {
-                                type: 'note',
-                                message: `autonomous — continuing without pausing (${state.autoContinues}/${MAX_AUTO_CONTINUES})`,
-                            });
-                            return true;
-                        })();
+                    // keep going (bounded by MAX_AUTO_CONTINUES) instead of parking at `waiting`. Shared
+                    // with `execute`'s turn-end handler — one sender, both sites (#141).
+                    autoContinued = this.autoContinueTurn(runId, state);
                     if (!autoContinued) {
                         // `XEZ:ASK` → park `waiting` (attention) AND surface the structured
                         // question as an ask card (#473). `XEZ:MONITORING` → non-attention
@@ -2143,7 +2215,10 @@ export class RunManager {
                 if (this.store.getRun(runId)?.autoResumeAttempts !== undefined) {
                     this.store.updateRun(runId, { autoResumeAttempts: undefined });
                 }
-                appendHandoffHeartbeat(this.dataDir, runId, `turn complete — status=${monitoring ? 'monitoring' : sessionOpen ? 'waiting' : 'running'}`);
+                appendHandoffHeartbeat(this.dataDir, runId, 
+                // A nudged turn did NOT park — the agent is working again, so the heartbeat must not
+                // read `waiting` (#141; before the fix this branch was unreachable).
+                `turn complete — status=${autoContinued ? 'running' : monitoring ? 'monitoring' : sessionOpen ? 'waiting' : 'running'}`);
             }
         };
         // Backend + model come off the record: the run's current backend by default, or the
@@ -2264,11 +2339,37 @@ export class RunManager {
         if (session.pid !== undefined)
             registerRunProcess(runId, session.pid);
         const finishedAt = () => new Date().toISOString();
+        /**
+         * The turn's teardown — usage peaks, timers, and the turn-end autosave commit — runs
+         * BEFORE this turn's terminal status is published, which is the order `execute` already
+         * uses on the workflow path (`run finalize`, then `settleSuccess`, then `dropActive`,
+         * with no await between the last two). The continuation path had it the other way round,
+         * and that asymmetry is the second half of #155: `settleSuccess` published `review` and
+         * only then did the `finally` spawn git for `autosaveCommit`, so for the whole width of
+         * that commit the run advertised the review gate while still sitting in `active`.
+         * `finish()` refuses to accept a `review` run while `isActive(runId)` holds — the guard
+         * that stops a Finish from racing a send-back continuation into `done` — so a ✓ Accept
+         * arriving in that window answered `409 no open session` and the accept was lost, with
+         * the run left parked at `review` forever. Idempotent, because the terminal paths call it
+         * explicitly and `finally` calls it again for a throw that never reached one.
+         */
+        let turnTornDown = false;
+        const endTurn = async () => {
+            if (turnTornDown)
+                return;
+            turnTornDown = true;
+            this.recordUsagePeaks(runId);
+            this.clearIdleTimer(state);
+            this.clearAutosaveTimer(state);
+            if (state.cwd !== this.repoRoot)
+                await autosaveCommit(state.cwd, 'turn end');
+        };
         try {
             await session.result;
             if (sessionError)
                 throw new Error(sessionError);
             sink.sessionEnded(state.cancelled ? 'cancelled' : 'end_turn');
+            await endTurn();
             if (state.cancelled) {
                 this.store.updateStep(runId, stepId, { status: 'cancelled', finishedAt: finishedAt() });
                 this.store.updateRun(runId, { status: 'cancelled', finishedAt: finishedAt(), currentStepId: undefined });
@@ -2285,6 +2386,7 @@ export class RunManager {
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
             sink.sessionEnded('error', message);
+            await endTurn();
             this.store.updateStep(runId, stepId, { status: 'failed', error: message, finishedAt: finishedAt() });
             appendHandoffHeartbeat(this.dataDir, runId, `step "${stepId}" complete — status=failed`);
             this.store.updateRun(runId, {
@@ -2296,14 +2398,38 @@ export class RunManager {
             this.store.appendEvent(runId, { type: 'lifecycle', message: `continue failed — ${message}` });
         }
         finally {
-            this.recordUsagePeaks(runId);
-            this.clearIdleTimer(state);
-            this.clearAutosaveTimer(state);
-            if (state.cwd !== this.repoRoot)
-                await autosaveCommit(state.cwd, 'turn end');
+            await endTurn();
             this.dropActive(runId);
         }
     }
+    /**
+     * Autonomous turn end (#489): never hand the ball back to the user — nudge the agent to keep
+     * going and report whether the ball stayed with it. `false` means "park normally", which is
+     * every non-autonomous run, a run whose pause cleared `autonomous` (the memory-limit
+     * suppression above), a cancelled one, a closed session that cannot take the message, and a
+     * run that has spent its `MAX_AUTO_CONTINUES` budget.
+     *
+     * ONE helper, called from BOTH turn-end handlers, because the split is exactly what broke:
+     * `execute` set `autonomous` on its `ActiveRun` and its handler never read it, while
+     * `runContinuation`'s handler read it and its `ActiveRun` never set it — so the nudge fired
+     * nowhere and every autonomous run parked after one turn (#141). AGENTS.md names both traps:
+     * grep the TYPE at every construction site, and treat the two near-identical turn-end handlers
+     * as one place. Keep this the only sender of `AUTONOMOUS_NUDGE`.
+     */
+    autoContinueTurn(runId, state) {
+        if (!state.autonomous || state.cancelled)
+            return false;
+        if ((state.autoContinues ?? 0) >= MAX_AUTO_CONTINUES)
+            return false;
+        if (!state.session?.sendMessage([{ type: 'text', text: AUTONOMOUS_NUDGE }]))
+            return false;
+        state.autoContinues = (state.autoContinues ?? 0) + 1;
+        this.store.appendEvent(runId, {
+            type: 'note',
+            message: `autonomous — continuing without pausing (${state.autoContinues}/${MAX_AUTO_CONTINUES})`,
+        });
+        return true;
+    }
     // ---- execution -----------------------------------------------------------
     async execute(runId, workflow, input) {
         const state = {
@@ -2730,7 +2856,13 @@ export class RunManager {
                     return;
                 }
                 const waiting = interactive && sessionOpen;
-                if (waiting) {
+                // Autonomous (#autonomous): the turn is over and the session is open, which is exactly
+                // the moment this run must NOT park. Same helper, same bound, same note as
+                // `runContinuation`'s handler (#141) — the field `execute` has always set is finally
+                // read here. `interactive` still gates it: a mid-workflow step ends its own session and
+                // the next step follows, so there is no ball to hand back and nothing to nudge.
+                const autoContinued = waiting ? this.autoContinueTurn(runId, state) : false;
+                if (waiting && !autoContinued) {
                     // Turn over, session open. Either the ball is in the user's court
                     // (`waiting`) — optionally with a structured `XEZ:ASK` question the
                     // cockpit renders as an ask card (#473) — or the agent declared it is
@@ -2764,7 +2896,7 @@ export class RunManager {
                 }
                 // Xez's own heartbeat — the handoff stays current even when the
                 // agent forgets to write (spec 007).
-                appendHandoffHeartbeat(this.dataDir, runId, `turn complete — status=${monitoring ? 'monitoring' : waiting ? 'waiting' : 'running'}`);
+                appendHandoffHeartbeat(this.dataDir, runId, `turn complete — status=${autoContinued ? 'running' : monitoring ? 'monitoring' : waiting ? 'waiting' : 'running'}`);
             }
         };
         const stepBackend = step.runner ?? taskBackend;
@@ -2797,7 +2929,7 @@ export class RunManager {
         let stepProfile;
         try {
             stepProfile = await this.agentEnvForStep(runId, stepBackend, {
-                generateFollowups: followupsEnabled() && input.generateFollowups !== false,
+                generateFollowups: this.semaphore.followupsEnabled() && input.generateFollowups !== false,
             });
         }
         catch (err) {
@@ -2814,7 +2946,7 @@ export class RunManager {
             session = runner.startSession({
                 // Skill body, then the run's extra prompt (POST override or config
                 // default), then the handoff/todos contract — every agent step.
-                systemPrompt: composeSystemPrompt(systemPrompt, extraSystemPrompt, followupsEnabled() && input.generateFollowups !== false
+                systemPrompt: composeSystemPrompt(systemPrompt, extraSystemPrompt, this.semaphore.followupsEnabled() && input.generateFollowups !== false
                     ? HANDOFF_INSTRUCTIONS
                     : HANDOFF_ONLY_INSTRUCTIONS),
                 userPrompt,
@@ -2827,8 +2959,10 @@ export class RunManager {
                 env: stepProfile.env,
                 model: backendModel,
                 sessionId,
-                // Interactive sessions have no wall clock — the idle timer rules.
-                timeoutMs: interactive ? 0 : undefined,
+                // Interactive sessions have no wall clock — the idle timer rules. A
+                // step's own `timeout` (#22) outranks that; with the field absent
+                // this is byte-for-byte the pre-#22 `interactive ? 0 : undefined`.
+                timeoutMs: stepTimeoutMs(step, interactive),
             }, onEvent, {
                 autoEndAfterFirstTurn: !interactive,
                 onUiEvent: (event) => this.handleRunnerUiEvent(runId, state, sink, event),
@@ -3235,17 +3369,29 @@ export class RunManager {
             return null;
         }
     }
+    /**
+     * Arm the idle wall clock for a session that just parked at `waiting`.
+     *
+     * The duration comes from the shared semaphore's cached `resources.idleTimeoutMinutes`,
+     * so a change made in Settings applies to the next park with no restart. `null` means
+     * the operator chose "never close on idle": no timer is armed, and the only exits left
+     * are a user message and Cancel — both of which a `waiting` run already advertises.
+     */
     armIdleTimer(runId, state) {
         this.clearIdleTimer(state);
+        const minutes = this.semaphore.idleTimeoutMinutes();
+        if (minutes === null)
+            return;
+        const timeoutMs = minutes * 60_000;
         state.idleTimer = setTimeout(() => {
             if (state.session?.open && !state.cancelled) {
                 this.store.appendEvent(runId, {
                     type: 'lifecycle',
-                    message: `session closed after ${Math.round(IDLE_TIMEOUT_MS / 60_000)}m of inactivity`,
+                    message: `session closed after ${Math.round(timeoutMs / 60_000)}m of inactivity`,
                 });
                 state.session.end();
             }
-        }, IDLE_TIMEOUT_MS);
+        }, timeoutMs);
         state.idleTimer.unref?.();
     }
     clearIdleTimer(state) {