@qodeca/xezar 0.11.2 → 0.13.1

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;