td-barrage 0.1.1 → 0.1.3

package/README.md

@@ -80,14 +80,47 @@ 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 -- --tasks queue.json --dry-run
 npm run dev -- --tasks queue.json --json
+npm run dev -- --tasks queue.json --verbose --timestamps
 ```
 
+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
+
 Exit codes:
 
 - `0`: all reachable tasks completed
 - `1`: at least one task failed or became blocked
 - `2`: CLI usage or missing task-file error
 
+## 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
+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.
+
+Verbosity flags:
+
+- `--verbose, -v`: add per-step traces — the OpenCode session id and the
+  success-check result for every task
+- `--quiet, -q`: show only failures, blocks, and the final summary
+- `--timestamps`: prefix each line with a wall-clock time
+- `--color` / `--no-color`: force or disable ANSI color (auto-detected from the
+  TTY otherwise; the `NO_COLOR` and `FORCE_COLOR` environment variables are honored)
+
+`--json` emits every event — including the enriched fields above — as one JSON
+object per line, regardless of verbosity, which is the format to pipe into log
+aggregators or `jq`. `--dry-run` always prints a bare, uncolored id list so it
+stays easy to pipe.
+
 ## Success Checks
 
 `default` succeeds unconditionally.
@@ -96,6 +129,14 @@ Exit codes:
 
 `result_json` succeeds when the configured JSON file parses and contains `"status": "ok"`.
 
+## Commits
+
+After a task passes its success check, the orchestrator stages everything with
+`git add -A` and commits it in the task's cwd with the message `feat: <id>`. A
+clean working tree (nothing to commit) is a quiet no-op, and a commit that fails
+outright is reported as a warning but never flips the task back to failed — the
+task already succeeded. Pass `--no-commit` to skip this stage entirely.
+
 ## Recovery
 
 On startup, any task persisted as `running` is reset to `pending`, annotated in `recoveryNotes`, and retried. The `attempts` counter is preserved, so a task that crashed mid-run still counts that attempt.

package/dist/git.d.ts

@@ -0,0 +1,28 @@
+export interface GitExecResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/** Runs `git <args>` in `cwd` and resolves with its exit code and output (never rejects). */
+export type GitExec = (args: string[], cwd: string) => Promise<GitExecResult>;
+export interface CommitInput {
+    cwd: string;
+    message: string;
+}
+export interface CommitResult {
+    /** "committed" — a new commit was made; "nothing" — clean tree, nothing staged; "error" — git failed. */
+    status: "committed" | "nothing" | "error";
+    /** Short SHA of the new commit, when status is "committed". */
+    commit?: string;
+    /** Human-readable detail, primarily for the "error" status. */
+    detail?: string;
+}
+export interface GitCommitter {
+    commit(input: CommitInput): Promise<CommitResult>;
+}
+/**
+ * Stages every change with `git add -A` and commits it. A clean working tree
+ * (nothing to commit) is reported as "nothing" rather than an error, since a
+ * task can legitimately succeed without touching tracked files.
+ */
+export declare function createGitCommitter(exec?: GitExec): GitCommitter;

package/dist/git.js

@@ -0,0 +1,47 @@
+import { execFile } from "node:child_process";
+/**
+ * Stages every change with `git add -A` and commits it. A clean working tree
+ * (nothing to commit) is reported as "nothing" rather than an error, since a
+ * task can legitimately succeed without touching tracked files.
+ */
+export function createGitCommitter(exec = defaultExec) {
+    return {
+        async commit({ cwd, message }) {
+            const add = await exec(["add", "-A"], cwd);
+            if (add.code !== 0) {
+                return { status: "error", detail: detailOf(add) || "git add failed" };
+            }
+            const commit = await exec(["commit", "-m", message], cwd);
+            if (commit.code === 0) {
+                const head = await exec(["rev-parse", "--short", "HEAD"], cwd);
+                return { status: "committed", commit: head.code === 0 ? head.stdout.trim() : undefined };
+            }
+            if (isNothingToCommit(commit)) {
+                return { status: "nothing" };
+            }
+            return { status: "error", detail: detailOf(commit) || `git commit exited with code ${commit.code}` };
+        },
+    };
+}
+// `git commit` exits non-zero with this phrasing when the index has no staged
+// changes — a no-op we treat as success, not failure.
+function isNothingToCommit(result) {
+    const text = `${result.stdout}\n${result.stderr}`;
+    return /nothing to commit|no changes added to commit|nothing added to commit/i.test(text);
+}
+function detailOf(result) {
+    return (result.stderr.trim() || result.stdout.trim()).split("\n")[0] ?? "";
+}
+const defaultExec = (args, cwd) => new Promise((resolve) => {
+    execFile("git", args, { cwd }, (error, stdout, stderr) => {
+        if (!error) {
+            resolve({ code: 0, stdout: String(stdout), stderr: String(stderr) });
+            return;
+        }
+        // A process that exits non-zero surfaces a numeric `code`; a spawn
+        // failure (e.g. git not installed) surfaces a string code like "ENOENT",
+        // in which case we fall back to 1 and lean on the error message.
+        const code = typeof error.code === "number" ? error.code : 1;
+        resolve({ code, stdout: String(stdout), stderr: String(stderr) || error.message });
+    });
+});

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
 import fs from "node:fs/promises";
+import { type GitCommitter } from "./git.js";
 import { type OpenCodeClient } from "./orchestrator.js";
 export interface MainDeps {
     fs?: typeof fs;
     client?: OpenCodeClient;
+    git?: GitCommitter;
     stdout?: Pick<NodeJS.WritableStream, "write">;
     stderr?: Pick<NodeJS.WritableStream, "write">;
 }

package/dist/index.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 import fs from "node:fs/promises";
 import { realpathSync } from "node:fs";
+import { createRequire } from "node:module";
 import process from "node:process";
 import { pathToFileURL } from "node:url";
 import { parseArgs } from "node:util";
 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 { loadTasks } from "./tasks.js";
@@ -22,6 +24,12 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
             "results-dir": { type: "string" },
             json: { type: "boolean", default: false },
             "dry-run": { type: "boolean", default: false },
+            "no-commit": { type: "boolean", default: false },
+            verbose: { type: "boolean", short: "v", default: false },
+            quiet: { type: "boolean", short: "q", default: false },
+            color: { type: "boolean", default: false },
+            "no-color": { type: "boolean", default: false },
+            timestamps: { type: "boolean", default: false },
         },
     });
     const tasksPath = parsed.values.tasks ?? parsed.positionals[0];
@@ -31,7 +39,17 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
     }
     const queueFs = deps.fs ?? fs;
     const cwd = parsed.values.cwd ?? process.cwd();
-    const logger = createLogger(Boolean(parsed.values.json), stdout);
+    if (parsed.values.quiet && parsed.values.verbose) {
+        stderr.write("--quiet and --verbose cannot be combined.\n");
+        return 2;
+    }
+    const level = parsed.values.quiet ? 0 : parsed.values.verbose ? 2 : 1;
+    const logger = createLogger({
+        json: Boolean(parsed.values.json),
+        level,
+        color: resolveColor(parsed.values, stdout),
+        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)) {
@@ -46,6 +64,7 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
             return 0;
         }
         const client = deps.client ?? (await createOpenCodeClient());
+        const git = parsed.values["no-commit"] ? undefined : deps.git ?? createGitCommitter();
         const summary = await runOrchestrator({
             tasksPath,
             client,
@@ -54,6 +73,8 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
             cwd,
             resultsDir,
             maxAttempts,
+            git,
+            version: readVersion(),
         });
         return summary.failed > 0 || summary.blocked > 0 ? 1 : 0;
     }
@@ -63,6 +84,25 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
         return code;
     }
 }
+// Color is on when the stream is a TTY, unless overridden. NO_COLOR disables and
+// FORCE_COLOR / --color force it on, matching the conventions other CLIs follow.
+function resolveColor(values, stdout) {
+    if (values["no-color"] || process.env.NO_COLOR)
+        return false;
+    if (values.color || process.env.FORCE_COLOR)
+        return true;
+    return Boolean(stdout.isTTY);
+}
+function readVersion() {
+    try {
+        const require = createRequire(import.meta.url);
+        const pkg = require("../package.json");
+        return pkg.version ?? "";
+    }
+    catch {
+        return "";
+    }
+}
 function isMissingFile(error) {
     return Boolean(error &&
         typeof error === "object" &&

package/dist/log.d.ts

@@ -1,21 +1,69 @@
+import type { Summary } from "./orchestrator.js";
+export interface RunInfo {
+    version: string;
+    tasksPath: string;
+    total: number;
+    maxAttempts: number;
+    timeoutMs: number;
+    cwd: string;
+    resultsDir: string;
+}
 export type LogEvent = {
+    type: "run_started";
+    info: RunInfo;
+} | {
+    type: "plan";
+    taskIds: string[];
+} | {
     type: "task_started";
     taskId: string;
     attempt: number;
+    maxAttempts: number;
+    cwd: string;
+    timeoutMs: number;
+} | {
+    type: "task_session";
+    taskId: string;
+    sessionId: string;
+} | {
+    type: "task_check";
+    taskId: string;
+    strategy: string;
+    ok: boolean;
 } | {
     type: "task_done";
     taskId: string;
+    durationMs: number;
+    done: number;
+    total: number;
+} | {
+    type: "task_committed";
+    taskId: string;
+    message: string;
+    status: "committed" | "nothing";
+    commit?: string;
+} | {
+    type: "task_commit_failed";
+    taskId: string;
+    message: string;
+    detail: string;
 } | {
     type: "task_failed";
     taskId: string;
     error: string;
+    attempt: number;
+    maxAttempts: number;
+    willRetry: boolean;
+    durationMs: number;
 } | {
     type: "task_blocked";
     taskId: string;
     reason: string;
+    blockedBy?: string;
 } | {
     type: "summary";
-    summary: unknown;
+    summary: Summary;
+    durationMs: number;
 } | {
     type: "dry_run";
     taskIds: string[];
@@ -26,4 +74,15 @@ export type LogEvent = {
 export interface Logger {
     event(event: LogEvent): void;
 }
-export declare function createLogger(json: boolean, stream?: Pick<NodeJS.WritableStream, "write">): Logger;
+/** 0 = quiet (problems + summary only), 1 = normal, 2 = verbose. */
+export type Verbosity = 0 | 1 | 2;
+export interface LoggerOptions {
+    json?: boolean;
+    level?: Verbosity;
+    color?: boolean;
+    timestamps?: boolean;
+    now?: () => Date;
+}
+export declare function createLogger(options?: LoggerOptions, stream?: Pick<NodeJS.WritableStream, "write"> & {
+    isTTY?: boolean;
+}): Logger;

package/dist/log.js

@@ -1,26 +1,263 @@
-export function createLogger(json, stream = process.stdout) {
+import { intro, outro, note, log as clack, spinner } from "@clack/prompts";
+// Lowest verbosity level at which each event is shown in human mode.
+// Level 0 events (failures, blocks, summary, dry-run) always surface.
+const EVENT_LEVEL = {
+    run_started: 1,
+    plan: 1,
+    task_started: 1,
+    task_session: 2,
+    task_check: 2,
+    task_done: 1,
+    task_committed: 1,
+    task_commit_failed: 0,
+    task_failed: 0,
+    task_blocked: 0,
+    summary: 0,
+    dry_run: 0,
+    server: 1,
+};
+export function createLogger(options = {}, stream = process.stdout) {
+    const json = Boolean(options.json);
+    const level = options.level ?? 1;
+    const styles = makeStyles(Boolean(options.color));
+    const now = options.now ?? (() => new Date());
+    // The clack treatment is reserved for an interactive, colored terminal: it
+    // animates spinners and draws connecting gutters that only make sense live.
+    // Pipes, CI, --no-color, --timestamps, and tests fall through to the plain
+    // line renderer so output stays deterministic and grep/pipe-friendly.
+    const pretty = !json && !options.timestamps && Boolean(options.color) && Boolean(stream.isTTY);
+    const renderPretty = pretty ? createPrettyRenderer(stream, styles) : null;
     return {
         event(event) {
             if (json) {
-                stream.write(`${JSON.stringify({ time: new Date().toISOString(), ...event })}\n`);
+                stream.write(`${JSON.stringify({ time: now().toISOString(), ...event })}\n`);
                 return;
             }
-            stream.write(`${formatHuman(event)}\n`);
+            if (EVENT_LEVEL[event.type] > level)
+                return;
+            // The plan preview is meant to be piped, so it stays bare even in pretty mode.
+            if (renderPretty && event.type !== "dry_run") {
+                renderPretty(event);
+                return;
+            }
+            const text = formatHuman(event, styles);
+            if (text === null)
+                return;
+            const stamp = options.timestamps ? `${styles.gray(formatClock(now()))} ` : "";
+            const out = text
+                .split("\n")
+                .map((line) => `${stamp}${line}`)
+                .join("\n");
+            stream.write(`${out}\n`);
         },
     };
 }
-function formatHuman(event) {
-    if (event.type === "task_started")
-        return `starting ${event.taskId} (attempt ${event.attempt})`;
-    if (event.type === "task_done")
-        return `done ${event.taskId}`;
-    if (event.type === "task_failed")
-        return `failed ${event.taskId}: ${event.error}`;
-    if (event.type === "task_blocked")
-        return `blocked ${event.taskId}: ${event.reason}`;
-    if (event.type === "summary")
-        return `summary ${JSON.stringify(event.summary)}`;
-    if (event.type === "dry_run")
-        return event.taskIds.join("\n");
-    return event.message;
+/**
+ * Renders events through @clack/prompts: an `intro` banner, a boxed `note` of
+ * run details, a live spinner for the task in flight (the orchestrator runs
+ * tasks sequentially, so at most one is active), and an `outro` summary.
+ */
+function createPrettyRenderer(output, s) {
+    const opts = { output };
+    let active = null;
+    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);
+                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);
+                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}`));
+                else
+                    clack.message(s.dim(`↳ session ${event.sessionId}`), opts);
+                return;
+            case "task_check":
+                if (active)
+                    active.message(s.dim(`${event.taskId} · check ${event.strategy} → ${event.ok ? "ok" : "fail"}`));
+                else
+                    clack.message(s.dim(`↳ check ${event.strategy} → ${event.ok ? "ok" : "fail"}`), 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`)}`;
+                if (active) {
+                    active.stop(msg);
+                    active = null;
+                }
+                else
+                    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);
+                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}`;
+                if (active) {
+                    // cancel() finalizes the spinner with a red ■ — distinct from the
+                    // ▲ clack uses for a blocked task, and matching clack.error's glyph
+                    // below. Called directly it only selects the symbol (no onCancel).
+                    active.cancel(msg);
+                    active = null;
+                }
+                else
+                    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);
+                return;
+            }
+            case "summary": {
+                if (active) {
+                    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);
+                return;
+            }
+            case "server":
+                if (active)
+                    active.message(s.dim(event.message));
+                else
+                    clack.info(s.dim(event.message), opts);
+                return;
+            case "dry_run":
+                // Handled before reaching the pretty renderer; kept exhaustive for the type checker.
+                output.write(`${event.taskIds.join("\n")}\n`);
+                return;
+        }
+    };
+}
+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 "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(" → "))}`;
+        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}`);
+        case "task_check":
+            return s.dim(`  ↳ check ${event.strategy} → ${event.ok ? "ok" : "fail"}`);
+        case "task_done":
+            return `${s.green("✔")} ${s.bold(event.taskId)} ${s.green("done")} ${s.dim(`in ${fmtDuration(event.durationMs)} · ${event.done}/${event.total} complete`)}`;
+        case "task_committed":
+            return event.status === "nothing"
+                ? s.dim("  ↳ no changes to commit")
+                : s.dim(`  ↳ committed ${event.commit ? `${event.commit} ` : ""}${event.message}`);
+        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 "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)})`)}`;
+        }
+        case "dry_run":
+            // Plain, uncolored, pipeable plan — one task id per line.
+            return event.taskIds.join("\n");
+        case "server":
+            return s.dim(`• ${event.message}`);
+    }
+}
+function count(n, label, color, s) {
+    const text = `${n} ${label}`;
+    return n > 0 ? color(text) : s.dim(text);
+}
+function plural(n, word) {
+    return n === 1 ? word : `${word}s`;
+}
+function fmtDuration(ms) {
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    const seconds = ms / 1000;
+    if (seconds < 60)
+        return `${seconds.toFixed(1)}s`;
+    const minutes = Math.floor(seconds / 60);
+    const rest = Math.round(seconds % 60);
+    return `${minutes}m${rest.toString().padStart(2, "0")}s`;
+}
+function formatClock(date) {
+    return date.toTimeString().slice(0, 8);
+}
+function makeStyles(enabled) {
+    const wrap = (open, close) => (text) => enabled ? `[${open}m${text}[${close}m` : text;
+    return {
+        bold: wrap(1, 22),
+        dim: wrap(2, 22),
+        red: wrap(31, 39),
+        green: wrap(32, 39),
+        yellow: wrap(33, 39),
+        blue: wrap(34, 39),
+        cyan: wrap(36, 39),
+        gray: wrap(90, 39),
+    };
 }

package/dist/orchestrator.d.ts

@@ -1,3 +1,4 @@
+import type { GitCommitter } from "./git.js";
 import { type SuccessFs } from "./success.js";
 import { type TaskFs } from "./tasks.js";
 import type { Logger } from "./log.js";
@@ -33,6 +34,11 @@ export interface OrchestratorOptions {
     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;
 }
 export interface Summary {
     total: number;

package/dist/orchestrator.js

@@ -1,6 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { dependencyState } from "./deps.js";
+import { dependencyState, topologicalOrder } from "./deps.js";
 import { checkSuccess } from "./success.js";
 import { loadTasks, saveTasks } from "./tasks.js";
 export const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
@@ -12,8 +12,34 @@ const defaultClock = {
 };
 export async function runOrchestrator(options) {
     const queueFs = options.fs ?? fs;
+    const clock = options.clock ?? defaultClock;
+    const runStart = clock.now().getTime();
     const taskFile = await loadTasks(options.tasksPath, queueFs);
     await saveTasks(options.tasksPath, taskFile, queueFs);
+    if (options.log) {
+        const cwd = options.cwd ?? process.cwd();
+        options.log.event({
+            type: "run_started",
+            info: {
+                version: options.version ?? "",
+                tasksPath: options.tasksPath,
+                total: taskFile.tasks.length,
+                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
+        // by the loop below, so never let topological ordering abort the run.
+        try {
+            const ordered = topologicalOrder(taskFile.tasks);
+            options.log.event({ type: "plan", taskIds: ordered.map((task) => task.id) });
+        }
+        catch {
+            // Cycle or missing dependency — the loop reports it as a deadlock/block.
+        }
+    }
     while (true) {
         let progressed = false;
         for (const task of taskFile.tasks) {
@@ -26,7 +52,12 @@ export async function runOrchestrator(options) {
                 task.status = "blocked";
                 task.error = "Dependency failed, blocked, or missing.";
                 task.finishedAt = nowIso(options.clock);
-                options.log?.event({ type: "task_blocked", taskId: task.id, reason: task.error });
+                options.log?.event({
+                    type: "task_blocked",
+                    taskId: task.id,
+                    reason: task.error,
+                    blockedBy: blockingDependency(task, taskFile.tasks),
+                });
                 await saveTasks(options.tasksPath, taskFile, queueFs);
                 progressed = true;
                 continue;
@@ -38,7 +69,7 @@ export async function runOrchestrator(options) {
             break;
     }
     const summary = summarize(taskFile.tasks);
-    options.log?.event({ type: "summary", summary });
+    options.log?.event({ type: "summary", summary, durationMs: clock.now().getTime() - runStart });
     return summary;
 }
 async function runTask(task, tasks, options, queueFs) {
@@ -48,30 +79,102 @@ async function runTask(task, tasks, options, queueFs) {
     const maxAttempts = task.maxAttempts ?? options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
     task.status = "running";
     task.attempts += 1;
+    const startMs = clock.now().getTime();
     task.startedAt = clock.now().toISOString();
     task.finishedAt = undefined;
     task.error = undefined;
-    options.log?.event({ type: "task_started", taskId: task.id, attempt: task.attempts });
+    options.log?.event({
+        type: "task_started",
+        taskId: task.id,
+        attempt: task.attempts,
+        maxAttempts,
+        cwd,
+        timeoutMs,
+    });
     await saveTasks(options.tasksPath, { tasks }, queueFs);
     try {
         const session = await options.client.session.create({ cwd });
         const sessionId = typeof session === "string" ? session : session.id;
+        options.log?.event({ type: "task_session", taskId: task.id, sessionId });
         const controller = new AbortController();
         await withTimeout(options.client.session.prompt(sessionId, { prompt: task.prompt, signal: controller.signal }), timeoutMs, clock, controller);
+        const strategy = task.success?.strategy ?? "default";
         const success = await checkSuccess(task.success, { fs: queueFs, cwd });
+        options.log?.event({ type: "task_check", taskId: task.id, strategy, ok: success });
         if (!success)
             throw new Error("Success check failed.");
         task.status = "done";
         task.finishedAt = clock.now().toISOString();
-        options.log?.event({ type: "task_done", taskId: task.id });
+        options.log?.event({
+            type: "task_done",
+            taskId: task.id,
+            durationMs: clock.now().getTime() - startMs,
+            done: countDone(tasks),
+            total: tasks.length,
+        });
     }
     catch (error) {
         task.error = error instanceof Error ? error.message : String(error);
         task.status = task.attempts >= maxAttempts ? "failed" : "pending";
         task.finishedAt = clock.now().toISOString();
-        options.log?.event({ type: "task_failed", taskId: task.id, error: task.error });
+        options.log?.event({
+            type: "task_failed",
+            taskId: task.id,
+            error: task.error,
+            attempt: task.attempts,
+            maxAttempts,
+            willRetry: task.status === "pending",
+            durationMs: clock.now().getTime() - startMs,
+        });
     }
     await saveTasks(options.tasksPath, { tasks }, queueFs);
+    // Commit the work the task produced. This runs after the save above so the
+    // 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) {
+        await commitTask(task, options.git, options.log, cwd);
+    }
+}
+async function commitTask(task, committer, log, cwd) {
+    const message = `feat: ${task.id}`;
+    try {
+        const result = await committer.commit({ cwd, message });
+        if (result.status === "error") {
+            log?.event({ type: "task_commit_failed", taskId: task.id, message, detail: result.detail ?? "" });
+            return;
+        }
+        log?.event({
+            type: "task_committed",
+            taskId: task.id,
+            message,
+            status: result.status,
+            commit: result.commit,
+        });
+    }
+    catch (error) {
+        log?.event({
+            type: "task_commit_failed",
+            taskId: task.id,
+            message,
+            detail: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+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")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "td-barrage",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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": {
@@ -34,6 +34,7 @@
     "prepublishOnly": "npm run typecheck && npm test && npm run build"
   },
   "dependencies": {
+    "@clack/prompts": "^1.4.0",
     "@opencode-ai/sdk": "^1.15.10",
     "zod": "^3.25.0"
   },