td-barrage 0.1.3 → 0.1.4

package/README.md

@@ -69,7 +69,6 @@ Supported task fields:
 - `maxAttempts`: per-task retry limit
 - `timeoutMs`: per-task prompt timeout
 - `cwd`: per-task working directory
-- `resultPath`: optional metadata field
 - `success`: `default`, `file_exists`, or `result_json`
 - `recoveryNotes`, `error`, `startedAt`, `finishedAt`: runtime metadata
 
@@ -77,7 +76,7 @@ Supported task fields:
 
 ```sh
 npm run dev -- --tasks queue.json
-npm run dev -- queue.json --max-attempts 3 --cwd /path/to/work --results-dir .queue/results
+npm run dev -- queue.json --max-attempts 3 --cwd /path/to/work
 npm run dev -- --tasks queue.json --dry-run
 npm run dev -- --tasks queue.json --json
 npm run dev -- --tasks queue.json --verbose --timestamps
@@ -88,7 +87,6 @@ Options:
 - `--tasks, -t <path>`: task file (also accepted as a positional argument)
 - `--max-attempts <n>`: global retry limit (per-task `maxAttempts` overrides it)
 - `--cwd <path>`: working directory for tasks that do not set their own
-- `--results-dir <path>`: where result files are expected, default `.queue/results`
 - `--dry-run`: print the topological plan (one id per line) and exit without running
 - `--no-commit`: skip the git commit stage that otherwise runs after each successful task
 - `--json`: emit newline-delimited JSON events instead of human output
@@ -98,11 +96,32 @@ Exit codes:
 - `0`: all reachable tasks completed
 - `1`: at least one task failed or became blocked
 - `2`: CLI usage or missing task-file error
+- `75`: the run paused on a provider quota / rate-limit wall (see below)
+
+## Pausing on quota / rate limits
+
+Running out of provider tokens is treated as a property of the run, not of any
+task. When a prompt fails with a quota, rate-limit, or overload signal (HTTP
+`402`/`429`/`503`/`529`, or matching error wording), the runner:
+
+- rolls back the attempt it charged — the task did not really run, so its retry
+  budget is untouched,
+- leaves the task `pending` (exactly as crash recovery does),
+- stops the rest of the sweep immediately, since every ready task would hit the
+  same wall, and
+- exits `75` (`EX_TEMPFAIL`) with the reason on stderr.
+
+Because state is persisted atomically after every transition, resuming is just
+re-running the same command once tokens are back — work picks up where it left
+off, with no failed or blocked tasks recorded from the pause. The distinct exit
+code lets a wrapper or scheduler tell "try again later" apart from `1` ("something
+is broken"). A `Retry-After` header, when present, is surfaced as a suggested
+wait in the pause message.
 
 ## Telemetry & output
 
 By default the runner is deliberately verbose, narrating progress as it happens:
-a startup header (version, task file, cwd, results dir, limits), the resolved
+a startup header (version, task file, cwd, limits), the resolved
 execution plan, a line as each task starts, and a line as each task finishes with
 its duration and overall progress (`2/5 complete`). Failures, retries, and blocks
 are always reported, along with a closing summary and total elapsed time.

package/dist/client.d.ts

@@ -6,4 +6,6 @@ export interface ClientOptions {
     timeout?: number;
     config?: unknown;
 }
-export declare function createOpenCodeClient(options?: ClientOptions): Promise<OpenCodeClient>;
+/** Imports an SDK module by specifier. Injectable so the export-selection logic is testable. */
+export type SdkImport = (specifier: string) => Promise<unknown>;
+export declare function createOpenCodeClient(options?: ClientOptions, importSdk?: SdkImport): Promise<OpenCodeClient>;

package/dist/client.js

@@ -1,5 +1,7 @@
-export async function createOpenCodeClient(options = {}) {
-    const importSdk = new Function("specifier", "return import(specifier)");
+// A `new Function` indirection keeps TypeScript from rewriting this dynamic
+// import into a require during transpile, so the specifier resolves at runtime.
+const defaultImport = new Function("specifier", "return import(specifier)");
+export async function createOpenCodeClient(options = {}, importSdk = defaultImport) {
     const sdk = (await importSdkWithFallback(importSdk));
     // A bare client only works when we already know where the server lives.
     // Without a baseUrl it would issue requests against relative URLs like

package/dist/deps.d.ts

@@ -1,4 +1,11 @@
 import type { Task } from "./schema.js";
-export type DependencyState = "ready" | "waiting" | "blocked";
+export type DependencyState = {
+    state: "ready";
+} | {
+    state: "waiting";
+} | {
+    state: "blocked";
+    blockedBy: string;
+};
 export declare function dependencyState(task: Task, tasks: Task[]): DependencyState;
 export declare function topologicalOrder(tasks: Task[]): Task[];

package/dist/deps.js

@@ -3,13 +3,14 @@ export function dependencyState(task, tasks) {
     for (const depId of task.dependsOn) {
         const dep = byId.get(depId);
         if (!dep)
-            return "blocked";
-        if (dep.status === "failed" || dep.status === "blocked")
-            return "blocked";
+            return { state: "blocked", blockedBy: `${depId} (missing)` };
+        if (dep.status === "failed" || dep.status === "blocked") {
+            return { state: "blocked", blockedBy: `${depId} (${dep.status})` };
+        }
         if (dep.status !== "done")
-            return "waiting";
+            return { state: "waiting" };
     }
-    return "ready";
+    return { state: "ready" };
 }
 export function topologicalOrder(tasks) {
     const byId = new Map(tasks.map((task) => [task.id, task]));

package/dist/index.js

@@ -9,7 +9,7 @@ import { createOpenCodeClient } from "./client.js";
 import { topologicalOrder } from "./deps.js";
 import { createGitCommitter } from "./git.js";
 import { createLogger } from "./log.js";
-import { defaultResultsDir, runOrchestrator } from "./orchestrator.js";
+import { runOrchestrator } from "./orchestrator.js";
 import { loadTasks } from "./tasks.js";
 export async function main(argv = process.argv.slice(2), deps = {}) {
     const stdout = deps.stdout ?? process.stdout;
@@ -21,7 +21,6 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
             tasks: { type: "string", short: "t" },
             "max-attempts": { type: "string" },
             cwd: { type: "string" },
-            "results-dir": { type: "string" },
             json: { type: "boolean", default: false },
             "dry-run": { type: "boolean", default: false },
             "no-commit": { type: "boolean", default: false },
@@ -51,7 +50,6 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
         timestamps: Boolean(parsed.values.timestamps),
     }, stdout);
     const maxAttempts = parsed.values["max-attempts"] ? Number(parsed.values["max-attempts"]) : undefined;
-    const resultsDir = parsed.values["results-dir"] ?? defaultResultsDir(cwd);
     if (maxAttempts !== undefined && (!Number.isInteger(maxAttempts) || maxAttempts < 1)) {
         stderr.write("--max-attempts must be a positive integer.\n");
         return 2;
@@ -71,11 +69,17 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
             fs: queueFs,
             log: logger,
             cwd,
-            resultsDir,
             maxAttempts,
             git,
             version: readVersion(),
         });
+        // 75 = EX_TEMPFAIL: the run hit a quota/rate-limit wall and stopped cleanly
+        // with work still pending. Distinct from 1 (genuine failures) so a wrapper
+        // or scheduler can tell "try again later" apart from "something is broken".
+        if (summary.paused) {
+            stderr.write(`Paused: ${summary.pauseReason ?? "out of provider tokens"} Re-run to resume.\n`);
+            return 75;
+        }
         return summary.failed > 0 || summary.blocked > 0 ? 1 : 0;
     }
     catch (error) {

package/dist/log.d.ts

@@ -6,7 +6,6 @@ export interface RunInfo {
     maxAttempts: number;
     timeoutMs: number;
     cwd: string;
-    resultsDir: string;
 }
 export type LogEvent = {
     type: "run_started";
@@ -60,6 +59,11 @@ export type LogEvent = {
     taskId: string;
     reason: string;
     blockedBy?: string;
+} | {
+    type: "run_paused";
+    taskId: string;
+    reason: string;
+    resumeAfterMs?: number;
 } | {
     type: "summary";
     summary: Summary;

package/dist/log.js

@@ -12,6 +12,7 @@ const EVENT_LEVEL = {
     task_commit_failed: 0,
     task_failed: 0,
     task_blocked: 0,
+    run_paused: 0,
     summary: 0,
     dry_run: 0,
     server: 1,
@@ -63,42 +64,31 @@ function createPrettyRenderer(output, s) {
     return (event) => {
         switch (event.type) {
             case "run_started": {
-                const i = event.info;
-                intro(s.bold(`td-barrage ${i.version}`), opts);
-                const details = [
-                    `${s.dim("tasks  ")} ${i.tasksPath} ${s.dim(`(${i.total} ${plural(i.total, "task")})`)}`,
-                    `${s.dim("cwd    ")} ${i.cwd}`,
-                    `${s.dim("results")} ${i.resultsDir}`,
-                    `${s.dim("limits ")} ${i.maxAttempts} ${plural(i.maxAttempts, "attempt")} ${s.dim("·")} ${fmtDuration(i.timeoutMs)} timeout`,
-                ].join("\n");
-                note(details, s.dim("run details"), opts);
+                intro(s.bold(`td-barrage ${event.info.version}`), opts);
+                note(runDetailLines(event.info, s).join("\n"), s.dim("run details"), opts);
                 return;
             }
-            case "plan": {
-                const body = event.taskIds.length === 0
-                    ? s.dim("(no tasks)")
-                    : event.taskIds.map((id) => s.cyan(id)).join(s.dim(" → "));
-                clack.step(`${s.dim("plan")}  ${body}`, opts);
+            case "plan":
+                clack.step(`${s.dim("plan")}  ${planBody(event.taskIds, s)}`, opts);
                 return;
-            }
             case "task_started":
                 active = spinner(opts);
                 active.start(`${s.bold(event.taskId)} ${s.dim(`running (attempt ${event.attempt}/${event.maxAttempts})`)}`);
                 return;
             case "task_session":
                 if (active)
-                    active.message(s.dim(`${event.taskId} · session ${event.sessionId}`));
+                    active.message(s.dim(`${event.taskId} · ${sessionText(event.sessionId)}`));
                 else
-                    clack.message(s.dim(`↳ session ${event.sessionId}`), opts);
+                    clack.message(s.dim(`↳ ${sessionText(event.sessionId)}`), opts);
                 return;
             case "task_check":
                 if (active)
-                    active.message(s.dim(`${event.taskId} · check ${event.strategy} → ${event.ok ? "ok" : "fail"}`));
+                    active.message(s.dim(`${event.taskId} · ${checkText(event.strategy, event.ok)}`));
                 else
-                    clack.message(s.dim(`↳ check ${event.strategy} → ${event.ok ? "ok" : "fail"}`), opts);
+                    clack.message(s.dim(`↳ ${checkText(event.strategy, event.ok)}`), opts);
                 return;
             case "task_done": {
-                const msg = `${s.bold(event.taskId)} ${s.green("done")} ${s.dim(`in ${fmtDuration(event.durationMs)} · ${event.done}/${event.total} complete`)}`;
+                const msg = doneMessage(event, s);
                 if (active) {
                     active.stop(msg);
                     active = null;
@@ -107,21 +97,14 @@ function createPrettyRenderer(output, s) {
                     clack.success(msg, opts);
                 return;
             }
-            case "task_committed": {
-                const detail = event.status === "nothing"
-                    ? s.dim("no changes to commit")
-                    : `${s.dim("committed")} ${event.commit ? s.cyan(event.commit) : ""} ${s.dim(event.message)}`;
-                clack.message(detail, opts);
+            case "task_committed":
+                clack.message(committedDetail(event, s), opts);
                 return;
-            }
             case "task_commit_failed":
                 clack.warn(`${s.bold(event.taskId)} ${s.yellow("commit failed")} ${s.dim(event.detail)}`, opts);
                 return;
             case "task_failed": {
-                const tail = event.willRetry
-                    ? s.yellow(`will retry (attempt ${event.attempt}/${event.maxAttempts})`)
-                    : s.red(`gave up after ${event.attempt} ${plural(event.attempt, "attempt")}`);
-                const msg = `${s.bold(event.taskId)} ${s.red("failed")} ${s.dim(`in ${fmtDuration(event.durationMs)}`)}: ${event.error} ${tail}`;
+                const msg = failureMessage(event, s);
                 if (active) {
                     // cancel() finalizes the spinner with a red ■ — distinct from the
                     // ▲ clack uses for a blocked task, and matching clack.error's glyph
@@ -133,9 +116,15 @@ function createPrettyRenderer(output, s) {
                     clack.error(msg, opts);
                 return;
             }
-            case "task_blocked": {
-                const by = event.blockedBy ? s.dim(` (by ${event.blockedBy})`) : "";
-                clack.warn(`${s.bold(event.taskId)} ${s.yellow("blocked")}${by} ${s.dim(event.reason)}`, opts);
+            case "task_blocked":
+                clack.warn(`${s.bold(event.taskId)} ${s.yellow("blocked")}${blockedSuffix(event, s)} ${s.dim(event.reason)}`, opts);
+                return;
+            case "run_paused": {
+                if (active) {
+                    active.stop();
+                    active = null;
+                }
+                clack.warn(pausedMessage(event, s), opts);
                 return;
             }
             case "summary": {
@@ -143,16 +132,8 @@ function createPrettyRenderer(output, s) {
                     active.stop();
                     active = null;
                 }
-                const sm = event.summary;
-                const parts = [
-                    s.green(`${sm.done} done`),
-                    count(sm.failed, "failed", s.red, s),
-                    count(sm.blocked, "blocked", s.yellow, s),
-                    count(sm.pending, "pending", s.yellow, s),
-                ];
-                const ok = sm.failed === 0 && sm.blocked === 0;
-                const head = ok ? s.green("done") : s.red("finished with issues");
-                outro(`${head}  ${parts.join(s.dim(" · "))}  ${s.dim(`(${fmtDuration(event.durationMs)})`)}`, opts);
+                const head = summaryHead(event.summary, s, false);
+                outro(`${head}  ${summaryParts(event.summary, s).join(s.dim(" · "))}  ${s.dim(`(${fmtDuration(event.durationMs)})`)}`, opts);
                 return;
             }
             case "server":
@@ -170,56 +151,36 @@ function createPrettyRenderer(output, s) {
 }
 function formatHuman(event, s) {
     switch (event.type) {
-        case "run_started": {
-            const i = event.info;
-            const lines = [
-                s.bold(`▶ td-barrage ${i.version}`),
-                `  ${s.dim("tasks  ")} ${i.tasksPath} ${s.dim(`(${i.total} ${plural(i.total, "task")})`)}`,
-                `  ${s.dim("cwd    ")} ${i.cwd}`,
-                `  ${s.dim("results")} ${i.resultsDir}`,
-                `  ${s.dim("limits ")} ${i.maxAttempts} ${plural(i.maxAttempts, "attempt")} ${s.dim("·")} ${fmtDuration(i.timeoutMs)} timeout`,
-            ];
-            return lines.join("\n");
-        }
+        case "run_started":
+            return [
+                s.bold(`▶ td-barrage ${event.info.version}`),
+                ...runDetailLines(event.info, s).map((line) => `  ${line}`),
+            ].join("\n");
         case "plan":
-            if (event.taskIds.length === 0)
-                return s.dim("plan    (no tasks)");
-            return `${s.dim("plan   ")} ${event.taskIds.map((id) => s.cyan(id)).join(s.dim(" → "))}`;
+            return event.taskIds.length === 0
+                ? s.dim("plan    (no tasks)")
+                : `${s.dim("plan   ")} ${planBody(event.taskIds, s)}`;
         case "task_started":
             return `${s.blue("▶")} ${s.bold(event.taskId)} ${s.dim(`starting (attempt ${event.attempt}/${event.maxAttempts})`)}`;
         case "task_session":
-            return s.dim(`  ↳ session ${event.sessionId}`);
+            return s.dim(`  ↳ ${sessionText(event.sessionId)}`);
         case "task_check":
-            return s.dim(`  ↳ check ${event.strategy} → ${event.ok ? "ok" : "fail"}`);
+            return s.dim(`  ↳ ${checkText(event.strategy, event.ok)}`);
         case "task_done":
-            return `${s.green("✔")} ${s.bold(event.taskId)} ${s.green("done")} ${s.dim(`in ${fmtDuration(event.durationMs)} · ${event.done}/${event.total} complete`)}`;
+            return `${s.green("✔")} ${doneMessage(event, s)}`;
         case "task_committed":
-            return event.status === "nothing"
-                ? s.dim("  ↳ no changes to commit")
-                : s.dim(`  ↳ committed ${event.commit ? `${event.commit} ` : ""}${event.message}`);
+            return s.dim("  ↳ ") + committedDetail(event, s);
         case "task_commit_failed":
             return `${s.yellow("⚠")} ${s.bold(event.taskId)} ${s.yellow("commit failed")} ${s.dim(event.detail)}`;
-        case "task_failed": {
-            const tail = event.willRetry
-                ? s.yellow(`will retry (attempt ${event.attempt}/${event.maxAttempts})`)
-                : s.red(`gave up after ${event.attempt} ${plural(event.attempt, "attempt")}`);
-            return `${s.red("✖")} ${s.bold(event.taskId)} ${s.red("failed")} ${s.dim(`in ${fmtDuration(event.durationMs)}`)}: ${event.error} ${tail}`;
-        }
-        case "task_blocked": {
-            const by = event.blockedBy ? s.dim(` (by ${event.blockedBy})`) : "";
-            return `${s.yellow("⊘")} ${s.bold(event.taskId)} ${s.yellow("blocked")}${by} ${s.dim(event.reason)}`;
-        }
+        case "task_failed":
+            return `${s.red("✖")} ${failureMessage(event, s)}`;
+        case "task_blocked":
+            return `${s.yellow("⊘")} ${s.bold(event.taskId)} ${s.yellow("blocked")}${blockedSuffix(event, s)} ${s.dim(event.reason)}`;
+        case "run_paused":
+            return `${s.yellow("⏸")} ${pausedMessage(event, s)}`;
         case "summary": {
-            const sm = event.summary;
-            const parts = [
-                s.green(`${sm.done} done`),
-                count(sm.failed, "failed", s.red, s),
-                count(sm.blocked, "blocked", s.yellow, s),
-                count(sm.pending, "pending", s.yellow, s),
-            ];
-            const ok = sm.failed === 0 && sm.blocked === 0;
-            const head = ok ? s.green("✔ done") : s.red("✖ finished with issues");
-            return `${head}  ${parts.join(s.dim(" · "))}  ${s.dim(`(${fmtDuration(event.durationMs)})`)}`;
+            const head = summaryHead(event.summary, s, true);
+            return `${head}  ${summaryParts(event.summary, s).join(s.dim(" · "))}  ${s.dim(`(${fmtDuration(event.durationMs)})`)}`;
         }
         case "dry_run":
             // Plain, uncolored, pipeable plan — one task id per line.
@@ -228,6 +189,70 @@ function formatHuman(event, s) {
             return s.dim(`• ${event.message}`);
     }
 }
+// Shared content builders. Both renderers — the plain line writer and the clack
+// pretty renderer — produce the same message bodies; only the framing (gutters,
+// spinners, boxes) differs. Keeping the text in one place means a field added to
+// an event is formatted once, not twice.
+function runDetailLines(i, s) {
+    return [
+        `${s.dim("tasks  ")} ${i.tasksPath} ${s.dim(`(${i.total} ${plural(i.total, "task")})`)}`,
+        `${s.dim("cwd    ")} ${i.cwd}`,
+        `${s.dim("limits ")} ${i.maxAttempts} ${plural(i.maxAttempts, "attempt")} ${s.dim("·")} ${fmtDuration(i.timeoutMs)} timeout`,
+    ];
+}
+function planBody(taskIds, s) {
+    return taskIds.length === 0 ? s.dim("(no tasks)") : taskIds.map((id) => s.cyan(id)).join(s.dim(" → "));
+}
+function sessionText(sessionId) {
+    return `session ${sessionId}`;
+}
+function checkText(strategy, ok) {
+    return `check ${strategy} → ${ok ? "ok" : "fail"}`;
+}
+function doneMessage(event, s) {
+    return `${s.bold(event.taskId)} ${s.green("done")} ${s.dim(`in ${fmtDuration(event.durationMs)} · ${event.done}/${event.total} complete`)}`;
+}
+function committedDetail(event, s) {
+    if (event.status === "nothing")
+        return s.dim("no changes to commit");
+    const sha = event.commit ? `${s.cyan(event.commit)} ` : "";
+    return `${s.dim("committed")} ${sha}${s.dim(event.message)}`;
+}
+function failureTail(event, s) {
+    return event.willRetry
+        ? s.yellow(`will retry (attempt ${event.attempt}/${event.maxAttempts})`)
+        : s.red(`gave up after ${event.attempt} ${plural(event.attempt, "attempt")}`);
+}
+function failureMessage(event, s) {
+    return `${s.bold(event.taskId)} ${s.red("failed")} ${s.dim(`in ${fmtDuration(event.durationMs)}`)}: ${event.error} ${failureTail(event, s)}`;
+}
+function blockedSuffix(event, s) {
+    return event.blockedBy ? s.dim(` (by ${event.blockedBy})`) : "";
+}
+function pausedMessage(event, s) {
+    const resume = event.resumeAfterMs !== undefined ? s.dim(` · retry after ${fmtDuration(event.resumeAfterMs)}`) : "";
+    return `${s.bold(event.taskId)} ${s.yellow("paused")} ${s.dim(event.reason)}${resume} ${s.dim("— re-run to resume")}`;
+}
+function summaryParts(sm, s) {
+    return [
+        s.green(`${sm.done} done`),
+        count(sm.failed, "failed", s.red, s),
+        count(sm.blocked, "blocked", s.yellow, s),
+        count(sm.pending, "pending", s.yellow, s),
+    ];
+}
+function summaryOk(sm) {
+    return sm.failed === 0 && sm.blocked === 0;
+}
+// `glyph` selects whether the leading symbol is included (plain renderer) or
+// omitted (the clack outro draws its own framing).
+function summaryHead(sm, s, glyph) {
+    if (sm.paused)
+        return glyph ? s.yellow("⏸ paused") : s.yellow("paused");
+    if (summaryOk(sm))
+        return glyph ? s.green("✔ done") : s.green("done");
+    return glyph ? s.red("✖ finished with issues") : s.red("finished with issues");
+}
 function count(n, label, color, s) {
     const text = `${n} ${label}`;
     return n > 0 ? color(text) : s.dim(text);

package/dist/orchestrator.d.ts

@@ -31,12 +31,9 @@ export interface OrchestratorOptions {
     clock?: Clock;
     log?: Logger;
     cwd?: string;
-    resultsDir?: string;
     maxAttempts?: number;
     timeoutMs?: number;
     version?: string;
-    /** Commit the working tree after each task succeeds. Defaults to true. */
-    commit?: boolean;
     /** Commits the working tree after each successful task. Omit to skip committing entirely. */
     git?: GitCommitter;
 }
@@ -47,6 +44,9 @@ export interface Summary {
     done: number;
     failed: number;
     blocked: number;
+    /** Set only when the run halted on a quota/rate-limit wall; otherwise absent. */
+    paused?: boolean;
+    /** Why the run paused — present iff `paused`. */
+    pauseReason?: string;
 }
 export declare function runOrchestrator(options: OrchestratorOptions): Promise<Summary>;
-export declare function defaultResultsDir(cwd: string): string;

package/dist/orchestrator.js

@@ -1,6 +1,6 @@
 import fs from "node:fs/promises";
-import path from "node:path";
 import { dependencyState, topologicalOrder } from "./deps.js";
+import { classifyQuotaError, RunPausedError } from "./pause.js";
 import { checkSuccess } from "./success.js";
 import { loadTasks, saveTasks } from "./tasks.js";
 export const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
@@ -27,7 +27,6 @@ export async function runOrchestrator(options) {
                 maxAttempts: options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
                 timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
                 cwd,
-                resultsDir: options.resultsDir ?? defaultResultsDir(cwd),
             },
         });
         // The plan is a courtesy preview; a dependency cycle is handled gracefully
@@ -40,35 +39,58 @@ export async function runOrchestrator(options) {
             // Cycle or missing dependency — the loop reports it as a deadlock/block.
         }
     }
-    while (true) {
+    let paused;
+    loop: while (true) {
         let progressed = false;
         for (const task of taskFile.tasks) {
             if (!isRunnable(task, options.maxAttempts))
                 continue;
             const state = dependencyState(task, taskFile.tasks);
-            if (state === "waiting")
+            if (state.state === "waiting")
                 continue;
-            if (state === "blocked") {
+            if (state.state === "blocked") {
                 task.status = "blocked";
                 task.error = "Dependency failed, blocked, or missing.";
-                task.finishedAt = nowIso(options.clock);
+                task.finishedAt = nowIso(clock);
                 options.log?.event({
                     type: "task_blocked",
                     taskId: task.id,
                     reason: task.error,
-                    blockedBy: blockingDependency(task, taskFile.tasks),
+                    blockedBy: state.blockedBy,
                 });
                 await saveTasks(options.tasksPath, taskFile, queueFs);
                 progressed = true;
                 continue;
             }
-            await runTask(task, taskFile.tasks, options, queueFs);
+            try {
+                await runTask(task, taskFile.tasks, options, queueFs);
+            }
+            catch (error) {
+                // A quota/rate-limit wall halts the whole run: the task has already been
+                // reset to pending (attempt rolled back) inside runTask, so we just stop
+                // the sweep — every other ready task would hit the same wall this round.
+                if (error instanceof RunPausedError) {
+                    paused = error;
+                    break loop;
+                }
+                throw error;
+            }
             progressed = true;
         }
         if (!progressed)
             break;
     }
     const summary = summarize(taskFile.tasks);
+    if (paused) {
+        summary.paused = true;
+        summary.pauseReason = paused.message;
+        options.log?.event({
+            type: "run_paused",
+            taskId: paused.taskId,
+            reason: paused.message,
+            resumeAfterMs: paused.resumeAfterMs,
+        });
+    }
     options.log?.event({ type: "summary", summary, durationMs: clock.now().getTime() - runStart });
     return summary;
 }
@@ -80,7 +102,7 @@ async function runTask(task, tasks, options, queueFs) {
     task.status = "running";
     task.attempts += 1;
     const startMs = clock.now().getTime();
-    task.startedAt = clock.now().toISOString();
+    task.startedAt = nowIso(clock);
     task.finishedAt = undefined;
     task.error = undefined;
     options.log?.event({
@@ -104,7 +126,7 @@ async function runTask(task, tasks, options, queueFs) {
         if (!success)
             throw new Error("Success check failed.");
         task.status = "done";
-        task.finishedAt = clock.now().toISOString();
+        task.finishedAt = nowIso(clock);
         options.log?.event({
             type: "task_done",
             taskId: task.id,
@@ -114,9 +136,23 @@ async function runTask(task, tasks, options, queueFs) {
         });
     }
     catch (error) {
+        // Out of tokens is not a task defect. Roll back the attempt we charged at
+        // the top, leave the task pending (exactly as crash recovery would), persist
+        // that clean state, then unwind the run — index.ts maps the pause to a
+        // distinct exit code so re-invoking resumes once tokens return.
+        const quota = classifyQuotaError(error);
+        if (quota) {
+            task.attempts -= 1;
+            task.status = "pending";
+            task.startedAt = undefined;
+            task.finishedAt = undefined;
+            task.error = undefined;
+            await saveTasks(options.tasksPath, { tasks }, queueFs);
+            throw new RunPausedError(task.id, quota.reason, quota.resumeAfterMs);
+        }
         task.error = error instanceof Error ? error.message : String(error);
         task.status = task.attempts >= maxAttempts ? "failed" : "pending";
-        task.finishedAt = clock.now().toISOString();
+        task.finishedAt = nowIso(clock);
         options.log?.event({
             type: "task_failed",
             taskId: task.id,
@@ -132,7 +168,7 @@ async function runTask(task, tasks, options, queueFs) {
     // commit captures the task file in its final "done" state. A failed commit
     // is reported but never flips the task back to failed — the task itself
     // already passed its success check. Skipped when no committer is wired in.
-    if (task.status === "done" && options.commit !== false && options.git) {
+    if (task.status === "done" && options.git) {
         await commitTask(task, options.git, options.log, cwd);
     }
 }
@@ -164,18 +200,6 @@ async function commitTask(task, committer, log, cwd) {
 function countDone(tasks) {
     return tasks.reduce((total, task) => (task.status === "done" ? total + 1 : total), 0);
 }
-// Names the first dependency that is failed, blocked, or missing, for telemetry.
-function blockingDependency(task, tasks) {
-    const byId = new Map(tasks.map((candidate) => [candidate.id, candidate]));
-    for (const depId of task.dependsOn) {
-        const dep = byId.get(depId);
-        if (!dep)
-            return `${depId} (missing)`;
-        if (dep.status === "failed" || dep.status === "blocked")
-            return `${depId} (${dep.status})`;
-    }
-    return undefined;
-}
 function isRunnable(task, globalMaxAttempts = DEFAULT_MAX_ATTEMPTS) {
     if (task.status === "pending")
         return true;
@@ -217,6 +241,3 @@ function summarize(tasks) {
 function nowIso(clock = defaultClock) {
     return clock.now().toISOString();
 }
-export function defaultResultsDir(cwd) {
-    return path.join(cwd, ".queue", "results");
-}

package/dist/pause.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Pause/resume support for the orchestrator.
+ *
+ * Running out of provider tokens is a property of the *run*, not the *task*:
+ * nothing is wrong with the task that hit the wall, and every other ready task
+ * would hit the same wall this sweep. So instead of letting a quota error burn
+ * the task's attempt budget and cascade into `blocked` dependents, we classify
+ * it, leave the task resumable, and unwind the whole run with `RunPausedError`.
+ * The persisted state (running -> pending, atomic save after every transition)
+ * is already the resume substrate — re-invoking the CLI just picks up where it
+ * left off once tokens are back.
+ */
+/**
+ * Thrown out of a task to halt the whole run cleanly. The task it names has
+ * been reset to `pending` (its attempt rolled back), so no failure is recorded.
+ */
+export declare class RunPausedError extends Error {
+    readonly taskId: string;
+    /** Wall-clock ms the provider asked us to wait, when it told us (Retry-After). */
+    readonly resumeAfterMs?: number;
+    constructor(taskId: string, reason: string, resumeAfterMs?: number);
+}
+export interface QuotaSignal {
+    /** Human-readable reason, surfaced in logs and on the paused exit. */
+    reason: string;
+    /** Suggested wait before resuming, derived from a Retry-After header. */
+    resumeAfterMs?: number;
+}
+/**
+ * Inspects an unknown thrown value for a quota / rate-limit / overload signal.
+ * Returns a `QuotaSignal` when the run should pause, or `null` when the error
+ * is a genuine task failure that should follow the normal failure path.
+ */
+export declare function classifyQuotaError(error: unknown): QuotaSignal | null;

package/dist/pause.js

@@ -0,0 +1,119 @@
+/**
+ * Pause/resume support for the orchestrator.
+ *
+ * Running out of provider tokens is a property of the *run*, not the *task*:
+ * nothing is wrong with the task that hit the wall, and every other ready task
+ * would hit the same wall this sweep. So instead of letting a quota error burn
+ * the task's attempt budget and cascade into `blocked` dependents, we classify
+ * it, leave the task resumable, and unwind the whole run with `RunPausedError`.
+ * The persisted state (running -> pending, atomic save after every transition)
+ * is already the resume substrate — re-invoking the CLI just picks up where it
+ * left off once tokens are back.
+ */
+/**
+ * Thrown out of a task to halt the whole run cleanly. The task it names has
+ * been reset to `pending` (its attempt rolled back), so no failure is recorded.
+ */
+export class RunPausedError extends Error {
+    taskId;
+    /** Wall-clock ms the provider asked us to wait, when it told us (Retry-After). */
+    resumeAfterMs;
+    constructor(taskId, reason, resumeAfterMs) {
+        super(reason);
+        this.name = "RunPausedError";
+        this.taskId = taskId;
+        this.resumeAfterMs = resumeAfterMs;
+    }
+}
+// HTTP statuses that mean "retryable later, not a task defect":
+//   429 too many requests (rate limit)   402 payment required (out of credit)
+//   529 overloaded (Anthropic)           503 service unavailable
+const QUOTA_STATUSES = new Set([402, 429, 503, 529]);
+// Message fragments that signal a quota / rate / availability wall even when no
+// numeric status is exposed. Kept deliberately broad — a false positive only
+// pauses (recoverable) where a false negative would burn the retry budget.
+const QUOTA_PATTERNS = [
+    /\brate.?limit/i,
+    /too many requests/i,
+    /\bquota\b/i,
+    /insufficient\s+(?:credit|quota|balance|funds?)/i,
+    /out of (?:credit|tokens?)/i,
+    /payment required/i,
+    /overloaded/i,
+    /\b(?:429|402|529)\b/,
+];
+/**
+ * Inspects an unknown thrown value for a quota / rate-limit / overload signal.
+ * Returns a `QuotaSignal` when the run should pause, or `null` when the error
+ * is a genuine task failure that should follow the normal failure path.
+ */
+export function classifyQuotaError(error) {
+    const status = extractStatus(error);
+    if (status !== undefined && QUOTA_STATUSES.has(status)) {
+        return { reason: reasonForStatus(status), resumeAfterMs: extractRetryAfterMs(error) };
+    }
+    const message = extractMessage(error);
+    if (message && QUOTA_PATTERNS.some((pattern) => pattern.test(message))) {
+        return { reason: message, resumeAfterMs: extractRetryAfterMs(error) };
+    }
+    return null;
+}
+function reasonForStatus(status) {
+    switch (status) {
+        case 402:
+            return "Provider returned 402 (payment required / out of credit).";
+        case 429:
+            return "Provider returned 429 (rate limit / quota exceeded).";
+        case 503:
+            return "Provider returned 503 (service unavailable).";
+        case 529:
+            return "Provider returned 529 (overloaded).";
+        default:
+            return `Provider returned ${status}.`;
+    }
+}
+// Provider/SDK errors expose the status under several names and nesting depths,
+// so probe the common shapes rather than assuming one.
+function extractStatus(error) {
+    if (!error || typeof error !== "object")
+        return undefined;
+    const candidates = [
+        error.status,
+        error.statusCode,
+        asObject(error.response)?.status,
+        asObject(error.error)?.status,
+        asObject(error.cause)?.status,
+    ];
+    for (const candidate of candidates) {
+        const n = typeof candidate === "string" ? Number(candidate) : candidate;
+        if (typeof n === "number" && Number.isInteger(n))
+            return n;
+    }
+    return undefined;
+}
+function extractMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === "string")
+        return error;
+    if (error && typeof error === "object") {
+        const message = error.message;
+        if (typeof message === "string")
+            return message;
+    }
+    return "";
+}
+// Retry-After is seconds (or, per RFC, an HTTP date — we only honour the numeric
+// form). Look in the header bags the common SDK error shapes carry.
+function extractRetryAfterMs(error) {
+    const headers = asObject(error?.headers) ??
+        asObject(asObject(error?.response)?.headers);
+    if (!headers)
+        return undefined;
+    const raw = headers["retry-after"] ?? headers["Retry-After"];
+    const seconds = typeof raw === "string" ? Number(raw) : typeof raw === "number" ? raw : NaN;
+    return Number.isFinite(seconds) && seconds >= 0 ? Math.round(seconds * 1000) : undefined;
+}
+function asObject(value) {
+    return value && typeof value === "object" ? value : undefined;
+}

package/dist/schema.d.ts

@@ -34,7 +34,6 @@ export declare const taskSchema: z.ZodObject<{
     maxAttempts: z.ZodOptional<z.ZodNumber>;
     timeoutMs: z.ZodOptional<z.ZodNumber>;
     cwd: z.ZodOptional<z.ZodString>;
-    resultPath: z.ZodOptional<z.ZodString>;
     success: z.ZodOptional<z.ZodDefault<z.ZodDiscriminatedUnion<"strategy", [z.ZodObject<{
         strategy: z.ZodLiteral<"file_exists">;
         path: z.ZodString;
@@ -74,7 +73,6 @@ export declare const taskSchema: z.ZodObject<{
     maxAttempts?: number | undefined;
     timeoutMs?: number | undefined;
     cwd?: string | undefined;
-    resultPath?: string | undefined;
     success?: {
         strategy: "file_exists";
         path: string;
@@ -96,7 +94,6 @@ export declare const taskSchema: z.ZodObject<{
     maxAttempts?: number | undefined;
     timeoutMs?: number | undefined;
     cwd?: string | undefined;
-    resultPath?: string | undefined;
     success?: {
         strategy: "file_exists";
         path: string;
@@ -121,7 +118,6 @@ export declare const taskFileSchema: z.ZodUnion<[z.ZodObject<{
         maxAttempts: z.ZodOptional<z.ZodNumber>;
         timeoutMs: z.ZodOptional<z.ZodNumber>;
         cwd: z.ZodOptional<z.ZodString>;
-        resultPath: z.ZodOptional<z.ZodString>;
         success: z.ZodOptional<z.ZodDefault<z.ZodDiscriminatedUnion<"strategy", [z.ZodObject<{
             strategy: z.ZodLiteral<"file_exists">;
             path: z.ZodString;
@@ -161,7 +157,6 @@ export declare const taskFileSchema: z.ZodUnion<[z.ZodObject<{
         maxAttempts?: number | undefined;
         timeoutMs?: number | undefined;
         cwd?: string | undefined;
-        resultPath?: string | undefined;
         success?: {
             strategy: "file_exists";
             path: string;
@@ -183,7 +178,6 @@ export declare const taskFileSchema: z.ZodUnion<[z.ZodObject<{
         maxAttempts?: number | undefined;
         timeoutMs?: number | undefined;
         cwd?: string | undefined;
-        resultPath?: string | undefined;
         success?: {
             strategy: "file_exists";
             path: string;
@@ -209,7 +203,6 @@ export declare const taskFileSchema: z.ZodUnion<[z.ZodObject<{
         maxAttempts?: number | undefined;
         timeoutMs?: number | undefined;
         cwd?: string | undefined;
-        resultPath?: string | undefined;
         success?: {
             strategy: "file_exists";
             path: string;
@@ -233,7 +226,6 @@ export declare const taskFileSchema: z.ZodUnion<[z.ZodObject<{
         maxAttempts?: number | undefined;
         timeoutMs?: number | undefined;
         cwd?: string | undefined;
-        resultPath?: string | undefined;
         success?: {
             strategy: "file_exists";
             path: string;
@@ -257,7 +249,6 @@ export declare const taskFileSchema: z.ZodUnion<[z.ZodObject<{
     maxAttempts: z.ZodOptional<z.ZodNumber>;
     timeoutMs: z.ZodOptional<z.ZodNumber>;
     cwd: z.ZodOptional<z.ZodString>;
-    resultPath: z.ZodOptional<z.ZodString>;
     success: z.ZodOptional<z.ZodDefault<z.ZodDiscriminatedUnion<"strategy", [z.ZodObject<{
         strategy: z.ZodLiteral<"file_exists">;
         path: z.ZodString;
@@ -297,7 +288,6 @@ export declare const taskFileSchema: z.ZodUnion<[z.ZodObject<{
     maxAttempts?: number | undefined;
     timeoutMs?: number | undefined;
     cwd?: string | undefined;
-    resultPath?: string | undefined;
     success?: {
         strategy: "file_exists";
         path: string;
@@ -319,7 +309,6 @@ export declare const taskFileSchema: z.ZodUnion<[z.ZodObject<{
     maxAttempts?: number | undefined;
     timeoutMs?: number | undefined;
     cwd?: string | undefined;
-    resultPath?: string | undefined;
     success?: {
         strategy: "file_exists";
         path: string;
@@ -344,7 +333,6 @@ export declare const taskFileSchema: z.ZodUnion<[z.ZodObject<{
         maxAttempts?: number | undefined;
         timeoutMs?: number | undefined;
         cwd?: string | undefined;
-        resultPath?: string | undefined;
         success?: {
             strategy: "file_exists";
             path: string;
@@ -367,7 +355,6 @@ export declare const taskFileSchema: z.ZodUnion<[z.ZodObject<{
     maxAttempts?: number | undefined;
     timeoutMs?: number | undefined;
     cwd?: string | undefined;
-    resultPath?: string | undefined;
     success?: {
         strategy: "file_exists";
         path: string;

package/dist/schema.js

@@ -24,7 +24,6 @@ export const taskSchema = z.object({
     maxAttempts: z.number().int().min(1).optional(),
     timeoutMs: z.number().int().positive().optional(),
     cwd: z.string().min(1).optional(),
-    resultPath: z.string().min(1).optional(),
     success: successCheckSchema.optional(),
     recoveryNotes: z.array(z.string()).default([]),
     error: z.string().optional(),

package/dist/server.js

@@ -1,3 +1,7 @@
+// Integration-test harness for standing up a real `opencode serve` at a known
+// port. Production does not use this: createOpenCodeClient (client.ts) lets the
+// SDK's createOpencode spawn its own ephemeral server. These helpers exist so the
+// integration test can connect a client to an explicit baseUrl.
 import { spawn } from "node:child_process";
 import net from "node:net";
 export async function startServer(options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "td-barrage",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "TypeScript queue runner that loads a JSON task file, resolves dependencies, runs tasks through the OpenCode SDK, and resumes interrupted work.",
   "type": "module",
   "engines": {