@ze-norm/cli 0.11.3 → 0.12.0

package/dist/commands/work.d.ts

@@ -0,0 +1,126 @@
+import type { SpawnOptions, ChildProcess } from "node:child_process";
+import { ZenormClient } from "../api/client.js";
+import type { SpecTaskRecord } from "../api/types.js";
+/**
+ * Agents whose subprocess runner slice 3 will wire up. Validated here so an
+ * unknown/missing `--agent` fails loud rather than silently defaulting (project
+ * rule: no error-masking defaults).
+ */
+declare const SUPPORTED_AGENTS: readonly ["codex", "claude"];
+type SupportedAgent = (typeof SUPPORTED_AGENTS)[number];
+/**
+ * A pluggable per-task runner. The work loop calls `run(task)` after a
+ * successful claim. The default is the real `AgentRunner` (which spawns the
+ * chosen `claude` / `codex` agent headlessly); tests inject fakes via
+ * `workCommand`'s `deps.runner`.
+ */
+export interface TaskRunner {
+    readonly agentName?: string;
+    run(task: SpecTaskRecord): Promise<void>;
+}
+/**
+ * Build the handoff prompt that hands the agent the WHOLE SPEC the claimed task
+ * belongs to, so a single agent session implements every available task for that
+ * spec with shared context — instead of one fresh session per task. The
+ * `/zenorm <specId>` trigger is what the `zenorm` dispatcher SKILL.md keys on
+ * (spec mode → `execute-task` walks every `planned`/`todo` task in order).
+ *
+ * The claim only flips THIS one task to `active` server-side (the lease that
+ * proves there is work for this repo and guards against a second daemon). The
+ * prompt tells the agent that `task.id` is already active so spec mode picks it
+ * up alongside its still-`todo` siblings rather than skipping it. The agent
+ * completes each task itself via `zenorm task complete` — the daemon does NOT
+ * post outcomes.
+ *
+ * Exported for unit testing.
+ */
+export declare function buildHandoffPrompt(task: SpecTaskRecord): string;
+/**
+ * The headless subprocess invocation for a given agent + task. Pure (no
+ * side effects) so it can be unit-tested directly without spawning anything.
+ *
+ * Both agents run in their JSON *event-stream* modes so we can re-render a
+ * compact, interactive-style transcript (see `work-render.ts`) instead of the
+ * agent's raw headless output:
+ * - claude: `claude -p --output-format stream-json --verbose` (JSONL events).
+ * - codex:  `codex exec --json` (JSONL events).
+ *
+ * Exported for unit testing.
+ */
+export declare function buildAgentCommand(agent: SupportedAgent, task: SpecTaskRecord): {
+    command: string;
+    args: string[];
+};
+/**
+ * Minimal spawn signature we depend on — injectable so `AgentRunner` can be
+ * unit-tested without launching a real agent.
+ */
+export type SpawnFn = (command: string, args: string[], options: SpawnOptions) => ChildProcess;
+/**
+ * The real runner: spawns the chosen coding agent headlessly against the
+ * claimed task and awaits its exit.
+ *
+ * Division of responsibility (intentional): the daemon only CLAIMS the task and
+ * LAUNCHES + AWAITS the agent. The agent itself runs the `execute-task` skill,
+ * which posts the task outcome via `zenorm task complete`. So this runner does
+ * NOT post any outcome — it returns once the agent exits 0, and throws on a
+ * non-zero exit or a missing binary so the failure is never read as success.
+ */
+export declare class AgentRunner implements TaskRunner {
+    private readonly agent;
+    private readonly spawnFn;
+    readonly agentName: SupportedAgent;
+    constructor(agent: SupportedAgent, spawnFn?: SpawnFn);
+    run(task: SpecTaskRecord): Promise<void>;
+}
+/**
+ * `--dry-run` runner: prints the exact headless command + handoff prompt it
+ * WOULD spawn, without launching the agent. Lets the user inspect the wiring
+ * (and verify the daemon end-to-end) without burning a real agent run.
+ */
+export declare class DryRunRunner implements TaskRunner {
+    private readonly agent;
+    readonly agentName: SupportedAgent;
+    constructor(agent: SupportedAgent);
+    run(task: SpecTaskRecord): Promise<void>;
+}
+/**
+ * Parse `owner/name` from a git remote URL. Handles SSH
+ * (`git@github.com:owner/name.git`) and HTTPS
+ * (`https://github.com/owner/name(.git)`) forms. Trailing `.git` is stripped.
+ * Throws CliError on anything we can't parse — fail loud.
+ *
+ * Exported for unit testing.
+ */
+export declare function parseGitRemote(url: string): {
+    owner: string;
+    name: string;
+};
+interface DaemonDeps {
+    runner?: TaskRunner;
+    client?: ZenormClient;
+}
+/**
+ * The poll loop, isolated from arg/repo resolution so it can be unit-tested
+ * with an injected client and runner. Returns the number of tasks processed.
+ */
+export declare function runWorkLoop(opts: {
+    client: ZenormClient;
+    runner: TaskRunner;
+    repo: {
+        owner: string;
+        name: string;
+    };
+    intervalMs: number;
+    once: boolean;
+}): Promise<number>;
+/**
+ * `zenorm work` — claim-and-run daemon for the current repository.
+ *
+ * `deps` lets tests inject a fake client and/or runner. When omitted, a real
+ * ZenormClient and the real `AgentRunner` (or `DryRunRunner` under `--dry-run`)
+ * are wired, so the default path actually spawns the chosen agent.
+ */
+export declare function workCommand(argv: string[], deps?: DaemonDeps): Promise<void>;
+export {};
+//# sourceMappingURL=work.d.ts.map

package/dist/commands/work.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"work.d.ts","sourceRoot":"","sources":["../../src/commands/work.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,KAAK,EAAqB,cAAc,EAAgB,MAAM,iBAAiB,CAAC;AAgBvF;;;;GAIG;AACH,QAAA,MAAM,gBAAgB,8BAA+B,CAAC;AACtD,KAAK,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AA0BxD;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,GAAG,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C;AAeD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAmB/D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,cAAc,GACnB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAsCrC;AAQD;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG,CACpB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,YAAY,KAClB,YAAY,CAAC;AAElB;;;;;;;;;GASG;AACH,qBAAa,WAAY,YAAW,UAAU;IAI1C,OAAO,CAAC,QAAQ,CAAC,KAAK;IAEtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAL1B,SAAgB,SAAS,EAAE,cAAc,CAAC;gBAGvB,KAAK,EAAE,cAAc,EAErB,OAAO,GAAE,OAAe;IAK3C,GAAG,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;CA0EzC;AAED;;;;GAIG;AACH,qBAAa,YAAa,YAAW,UAAU;IAGjC,OAAO,CAAC,QAAQ,CAAC,KAAK;IAFlC,SAAgB,SAAS,EAAE,cAAc,CAAC;gBAEb,KAAK,EAAE,cAAc;IAIlD,GAAG,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;CAOzC;AAUD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAmD3E;AA4BD,UAAU,UAAU;IAClB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AA+GD;;;GAGG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE;IACtC,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,OAAO,CAAC,MAAM,CAAC,CA2HlB;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,CAAC,EAAE,UAAU,GAChB,OAAO,CAAC,IAAI,CAAC,CA0Bf"}

package/dist/commands/work.js

@@ -0,0 +1,536 @@
+import { parseArgs } from "node:util";
+import { execFileSync, spawn } from "node:child_process";
+import { ZenormClient } from "../api/client.js";
+import { CliError } from "../util/errors.js";
+import { log } from "../util/logger.js";
+import { LineSplitter, claudeRenderer, codexRenderer, daemonBanner, failureBanner, sessionSummary, statusLine, taskHeader, taskOutcome, } from "./work-render.js";
+/**
+ * Agents whose subprocess runner slice 3 will wire up. Validated here so an
+ * unknown/missing `--agent` fails loud rather than silently defaulting (project
+ * rule: no error-masking defaults).
+ */
+const SUPPORTED_AGENTS = ["codex", "claude"];
+/**
+ * The AC requires ready tasks to be picked up within 10 seconds, so the poll
+ * interval is hard-capped at this value. Requests above the cap fail loud — we
+ * do NOT silently clamp.
+ */
+const MAX_INTERVAL_SECONDS = 10;
+const DEFAULT_INTERVAL_SECONDS = 5;
+const HEARTBEAT_INTERVAL_MS = 30_000;
+const USAGE = `Usage:
+  zenorm work --agent <${SUPPORTED_AGENTS.join("|")}> [--interval <seconds>] [--once] [--dry-run]
+
+Runs a daemon that claims and processes ready tasks for the current git
+repository (resolved from \`git remote get-url origin\`), oldest-first, one at a
+time. Each claimed task is handed off to the chosen coding agent, which runs the
+bundled ZeNorm \`execute-task\` skill and posts the task outcome itself.
+
+Options:
+  --agent <agent>      Agent to run each task with. Required. One of: ${SUPPORTED_AGENTS.join(", ")}
+  --interval <seconds> Poll interval when idle. Default ${DEFAULT_INTERVAL_SECONDS}, max ${MAX_INTERVAL_SECONDS}.
+  --once               Process at most one claim (or one idle poll) then exit.
+  --dry-run            Print the agent command + handoff prompt each task would
+                       run instead of spawning the agent.`;
+/**
+ * Headless install hints, surfaced when an agent binary is missing so the
+ * failure is actionable rather than a bare ENOENT.
+ */
+const AGENT_INSTALL_HINT = {
+    claude: "Install the Claude Code CLI and ensure `claude` is on your PATH " +
+        "(https://docs.anthropic.com/en/docs/claude-code).",
+    codex: "Install the Codex CLI and ensure `codex` is on your PATH " +
+        "(https://github.com/openai/codex).",
+};
+/**
+ * Build the handoff prompt that hands the agent the WHOLE SPEC the claimed task
+ * belongs to, so a single agent session implements every available task for that
+ * spec with shared context — instead of one fresh session per task. The
+ * `/zenorm <specId>` trigger is what the `zenorm` dispatcher SKILL.md keys on
+ * (spec mode → `execute-task` walks every `planned`/`todo` task in order).
+ *
+ * The claim only flips THIS one task to `active` server-side (the lease that
+ * proves there is work for this repo and guards against a second daemon). The
+ * prompt tells the agent that `task.id` is already active so spec mode picks it
+ * up alongside its still-`todo` siblings rather than skipping it. The agent
+ * completes each task itself via `zenorm task complete` — the daemon does NOT
+ * post outcomes.
+ *
+ * Exported for unit testing.
+ */
+export function buildHandoffPrompt(task) {
+    const zenormCli = process.env["ZENORM_CLI"]?.trim() || "zenorm";
+    return [
+        `/zenorm ${task.specId}`,
+        "",
+        `Execute ALL available tasks for ZeNorm spec ${task.specId} in THIS one`,
+        "session (spec mode — walk every `planned`/`todo` task in list order). Do not",
+        "stop after a single task; drain the spec's ready work before exiting.",
+        `For ZeNorm CLI shell commands, use \`${zenormCli}\`; if the installed`,
+        "skill text shows `zenorm ...`, substitute that command with the one",
+        "named here for this run.",
+        `Task "${task.title}" (id: ${task.id}) has already been claimed and flipped to`,
+        "`active` server-side — do NOT re-claim it; treat it as one of the spec's",
+        "ready tasks and implement it alongside the rest. Implement everything",
+        "end-to-end in the current repository working directory using the existing",
+        "ZeNorm execute workflow, completing each task via the normal",
+        `\`${zenormCli} task complete <task-id>\` flow as you finish it. Work`,
+        "non-interactively; do not wait for further input.",
+    ].join("\n");
+}
+/**
+ * The headless subprocess invocation for a given agent + task. Pure (no
+ * side effects) so it can be unit-tested directly without spawning anything.
+ *
+ * Both agents run in their JSON *event-stream* modes so we can re-render a
+ * compact, interactive-style transcript (see `work-render.ts`) instead of the
+ * agent's raw headless output:
+ * - claude: `claude -p --output-format stream-json --verbose` (JSONL events).
+ * - codex:  `codex exec --json` (JSONL events).
+ *
+ * Exported for unit testing.
+ */
+export function buildAgentCommand(agent, task) {
+    const prompt = buildHandoffPrompt(task);
+    switch (agent) {
+        case "claude":
+            // stream-json requires --verbose; it does NOT make the transcript verbose
+            // (we render the events ourselves), it just unlocks event streaming.
+            //
+            // --permission-mode auto: the daemon runs headlessly with no TTY, so an
+            // interactive permission prompt can never be answered — in `default` mode
+            // every gated tool call (notably the ZeNorm CLI Bash calls the
+            // execute-task skill relies on) blocks forever. `auto` mode runs
+            // a background classifier that auto-approves safe actions and blocks
+            // destructive ones (force-push, `curl | bash`, etc.) instead of bypassing
+            // checks entirely (`--dangerously-skip-permissions`). In headless mode it
+            // never prompts; if the classifier denies too many actions the run aborts
+            // non-zero, which `AgentRunner` already surfaces as a task failure
+            // (released back to `todo`). Requires Claude Code v2.1.83+.
+            return {
+                command: "claude",
+                args: [
+                    "-p",
+                    "--output-format",
+                    "stream-json",
+                    "--verbose",
+                    "--permission-mode",
+                    "auto",
+                    prompt,
+                ],
+            };
+        case "codex":
+            return { command: "codex", args: ["exec", "--json", prompt] };
+        default: {
+            // Exhaustiveness guard — fail loud if SUPPORTED_AGENTS grows without a
+            // matching headless invocation here (no error-masking default).
+            const never = agent;
+            throw new CliError(`No headless invocation defined for agent "${String(never)}".`);
+        }
+    }
+}
+/** The transcript renderer for each agent's JSON event stream. */
+const AGENT_RENDERER = {
+    claude: claudeRenderer,
+    codex: codexRenderer,
+};
+/**
+ * The real runner: spawns the chosen coding agent headlessly against the
+ * claimed task and awaits its exit.
+ *
+ * Division of responsibility (intentional): the daemon only CLAIMS the task and
+ * LAUNCHES + AWAITS the agent. The agent itself runs the `execute-task` skill,
+ * which posts the task outcome via `zenorm task complete`. So this runner does
+ * NOT post any outcome — it returns once the agent exits 0, and throws on a
+ * non-zero exit or a missing binary so the failure is never read as success.
+ */
+export class AgentRunner {
+    agent;
+    spawnFn;
+    agentName;
+    constructor(agent, 
+    // Injectable for tests; defaults to node:child_process spawn.
+    spawnFn = spawn) {
+        this.agent = agent;
+        this.spawnFn = spawnFn;
+        this.agentName = agent;
+    }
+    run(task) {
+        const { command, args } = buildAgentCommand(this.agent, task);
+        const renderer = AGENT_RENDERER[this.agent];
+        return new Promise((resolve, reject) => {
+            // Pipe the agent's stdout so we can re-render its JSON event stream into a
+            // clean transcript (work-render.ts); inherit stderr so real agent errors
+            // still surface; close stdin (the prompt is passed as an arg, and codex
+            // --json otherwise blocks reading from stdin). cwd is the current repo.
+            const child = this.spawnFn(command, args, {
+                cwd: process.cwd(),
+                stdio: ["ignore", "pipe", "inherit"],
+            });
+            // Render stdout line-by-line. Transcript lines go to the user's stdout so
+            // the work session reads like the agent's own interactive session.
+            const splitter = new LineSplitter();
+            const emit = (line) => {
+                process.stdout.write(`${line}\n`);
+            };
+            const renderLines = (lines) => {
+                for (const raw of lines) {
+                    for (const out of renderer(raw))
+                        emit(out);
+                }
+            };
+            child.stdout?.setEncoding("utf-8");
+            child.stdout?.on("data", (chunk) => {
+                renderLines(splitter.push(chunk));
+            });
+            child.stdout?.on("end", () => {
+                renderLines(splitter.flush());
+            });
+            let settled = false;
+            child.on("error", (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (err.code === "ENOENT") {
+                    reject(new CliError(`Could not launch agent "${this.agent}": \`${command}\` was not found on PATH.\n\n` +
+                        AGENT_INSTALL_HINT[this.agent]));
+                    return;
+                }
+                reject(new CliError(`Failed to launch agent "${this.agent}" (\`${command}\`): ${err.message}`));
+            });
+            child.on("exit", (code, signal) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (code === 0) {
+                    resolve();
+                    return;
+                }
+                const detail = code !== null ? `exited with code ${code}` : `was terminated by signal ${signal}`;
+                // Fail loud — a non-zero/aborted agent run is a FAILURE, never success.
+                reject(new CliError(`Agent "${this.agent}" (\`${command}\`) ${detail} while running task ${shortId(task.id)}.`));
+            });
+        });
+    }
+}
+/**
+ * `--dry-run` runner: prints the exact headless command + handoff prompt it
+ * WOULD spawn, without launching the agent. Lets the user inspect the wiring
+ * (and verify the daemon end-to-end) without burning a real agent run.
+ */
+export class DryRunRunner {
+    agent;
+    agentName;
+    constructor(agent) {
+        this.agent = agent;
+        this.agentName = agent;
+    }
+    run(task) {
+        const { command, args } = buildAgentCommand(this.agent, task);
+        log.info(`[dry-run] would spawn agent "${this.agent}" for task ${shortId(task.id)}`);
+        log.plain(`  cwd: ${process.cwd()}`);
+        log.plain(`  command: ${command} ${formatDryRunArgs(args)}`);
+        return Promise.resolve();
+    }
+}
+/**
+ * Render spawn args for the dry-run preview: the prompt arg is multi-line, so
+ * wrap it in quotes (purely cosmetic — this string is shown, never executed).
+ */
+function formatDryRunArgs(args) {
+    return args.map((arg) => (/\s/.test(arg) ? `"${arg}"` : arg)).join(" ");
+}
+/**
+ * Parse `owner/name` from a git remote URL. Handles SSH
+ * (`git@github.com:owner/name.git`) and HTTPS
+ * (`https://github.com/owner/name(.git)`) forms. Trailing `.git` is stripped.
+ * Throws CliError on anything we can't parse — fail loud.
+ *
+ * Exported for unit testing.
+ */
+export function parseGitRemote(url) {
+    const trimmed = url.trim();
+    if (!trimmed) {
+        throw new CliError("Empty git remote URL — cannot resolve the current repository.");
+    }
+    // SSH scp-like form: git@host:owner/name(.git)
+    // (also covers ssh://git@host/owner/name handled by the URL branch below)
+    const sshMatch = /^[^@]+@[^:]+:(.+)$/.exec(trimmed);
+    let path = null;
+    if (sshMatch && !trimmed.includes("://")) {
+        path = sshMatch[1] ?? null;
+    }
+    else {
+        // URL form: https://host/owner/name(.git), ssh://git@host/owner/name(.git)
+        try {
+            const parsed = new URL(trimmed);
+            path = parsed.pathname;
+        }
+        catch {
+            path = null;
+        }
+    }
+    if (path === null) {
+        throw new CliError(`Could not parse owner/name from git remote URL: "${url}".`);
+    }
+    const cleaned = path
+        .replace(/^\/+/, "")
+        .replace(/\.git$/, "")
+        .replace(/\/+$/, "");
+    const segments = cleaned.split("/").filter((s) => s.length > 0);
+    if (segments.length < 2) {
+        throw new CliError(`Could not parse owner/name from git remote URL: "${url}".`);
+    }
+    // owner/name are the LAST two segments (handles nested groups / extra path).
+    const name = segments[segments.length - 1];
+    const owner = segments[segments.length - 2];
+    if (!owner || !name) {
+        throw new CliError(`Could not parse owner/name from git remote URL: "${url}".`);
+    }
+    return { owner, name };
+}
+/** Resolve the current repo's owner/name from the `origin` remote. */
+function resolveCurrentRepo() {
+    let remoteUrl;
+    try {
+        remoteUrl = execFileSync("git", ["remote", "get-url", "origin"], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        throw new CliError("Not in a git repository with an `origin` remote.\n\n" +
+            "`zenorm work` scopes to the current repository. Run it from inside a git " +
+            "repo whose `origin` remote points at the GitHub repository you want to work.");
+    }
+    return parseGitRemote(remoteUrl);
+}
+function shortId(id) {
+    return id.length > 8 ? id.slice(0, 8) : id;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function parseWorkArgs(argv) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args: argv,
+            options: {
+                agent: { type: "string" },
+                interval: { type: "string" },
+                once: { type: "boolean" },
+                "dry-run": { type: "boolean" },
+            },
+            strict: true,
+        }));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new CliError(`Invalid zenorm work arguments: ${message}\n\n${USAGE}`);
+    }
+    const agent = values["agent"];
+    if (!agent) {
+        throw new CliError(`Missing --agent flag.\n\nSupported agents: ${SUPPORTED_AGENTS.join(", ")}\n\n${USAGE}`);
+    }
+    if (!SUPPORTED_AGENTS.includes(agent)) {
+        throw new CliError(`Unsupported agent "${agent}".\n\nSupported agents: ${SUPPORTED_AGENTS.join(", ")}`);
+    }
+    let intervalSeconds = DEFAULT_INTERVAL_SECONDS;
+    const rawInterval = values["interval"];
+    if (rawInterval !== undefined) {
+        const parsed = Number(rawInterval);
+        if (!Number.isFinite(parsed) || parsed <= 0) {
+            throw new CliError(`Invalid --interval "${rawInterval}". Must be a positive number of seconds (max ${MAX_INTERVAL_SECONDS}).`);
+        }
+        if (parsed > MAX_INTERVAL_SECONDS) {
+            throw new CliError(`--interval ${parsed} exceeds the maximum of ${MAX_INTERVAL_SECONDS} seconds. ` +
+                `Ready tasks must be picked up within ${MAX_INTERVAL_SECONDS}s.`);
+        }
+        intervalSeconds = parsed;
+    }
+    return {
+        // Validated above against SUPPORTED_AGENTS; the readonly-tuple `includes`
+        // check above does not narrow `string`, so assert the proven type here.
+        agent: agent,
+        intervalMs: intervalSeconds * 1000,
+        once: values["once"] === true,
+        dryRun: values["dry-run"] === true,
+    };
+}
+/** Write daemon-only meta output (e.g. the dry-run banner) to stderr. */
+function writeDaemonLine(line) {
+    process.stderr.write(`${line}\n`);
+}
+async function releaseTaskToTodo(client, task) {
+    try {
+        await client.patch(`/v1/tasks/${task.id}`, { status: "todo" });
+    }
+    catch (err) {
+        log.warn(`Could not release task ${shortId(task.id)} back to todo`, {
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+async function heartbeatTask(client, task) {
+    try {
+        await client.post(`/v1/tasks/${task.id}/heartbeat`, {});
+    }
+    catch (err) {
+        log.warn(`Task ${shortId(task.id)} heartbeat failed`, {
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+async function runTaskWithHeartbeat(client, runner, task) {
+    const interval = setInterval(() => {
+        void heartbeatTask(client, task);
+    }, HEARTBEAT_INTERVAL_MS);
+    try {
+        await runner.run(task);
+    }
+    finally {
+        clearInterval(interval);
+    }
+}
+/**
+ * The poll loop, isolated from arg/repo resolution so it can be unit-tested
+ * with an injected client and runner. Returns the number of tasks processed.
+ */
+export async function runWorkLoop(opts) {
+    const { client, runner, repo, intervalMs, once } = opts;
+    let processed = 0;
+    let failed = 0;
+    let started = 0;
+    let stopping = false;
+    // Track whether we're currently in the idle/polling state so the "polling…"
+    // status line is printed once per idle stretch, not once per poll.
+    let announcedIdle = false;
+    const onSigint = () => {
+        // Request a graceful stop; an in-flight runner.run call finishes first.
+        stopping = true;
+        log.warn("Received SIGINT — finishing the active task and shutting down...");
+    };
+    process.on("SIGINT", onSigint);
+    // Claim the next ready task. Returns the task, or null when nothing is
+    // claimable (or a transient claim error — the daemon survives those and
+    // retries after the interval).
+    const claimNext = async () => {
+        let response;
+        try {
+            response = await client.post("/v1/tasks/claim", {
+                owner: repo.owner,
+                name: repo.name,
+            });
+        }
+        catch (err) {
+            // A daemon must survive a transient API blip — warn and retry after the
+            // interval. (Fatal arg/git errors are thrown before the loop starts.)
+            log.warn(`Claim request failed, retrying after ${intervalMs / 1000}s`, { error: err instanceof Error ? err.message : String(err) });
+            return null;
+        }
+        return response.task ?? null;
+    };
+    // Run one claimed task's SPEC to completion. The claim flips a single task to
+    // `active` to prove there is ready work for this repo; the agent it launches
+    // then drains every available task of that spec in ONE session (spec mode —
+    // see buildHandoffPrompt). The agent's own transcript (its tool calls + prose,
+    // re-rendered by work-render.ts) IS the body of the output; the daemon frames
+    // it with a numbered header (the claimed entry task) and closes with a ✓/✗
+    // outcome line (+ a loud banner on failure). On failure the entry task is
+    // released back to `todo` so the spec can be re-claimed; tasks the agent
+    // already completed stay `done`.
+    const runTask = async (task) => {
+        started += 1;
+        const agentName = runner.agentName ?? "agent";
+        const short = shortId(task.id);
+        process.stdout.write(`${taskHeader(short, task.title, agentName, started)}\n`);
+        const startedAt = Date.now();
+        try {
+            await runTaskWithHeartbeat(client, runner, task);
+        }
+        catch (err) {
+            const durationMs = Date.now() - startedAt;
+            const message = err instanceof Error ? err.message : String(err);
+            await releaseTaskToTodo(client, task);
+            failed += 1;
+            // Loud, framed failure (banner) + the daemon's own ✗ outcome line so a
+            // failure is impossible to miss when scrolling a long daemon log.
+            process.stdout.write(`${failureBanner({ shortTaskId: short, title: task.title, error: message })}\n`);
+            process.stdout.write(`${taskOutcome({ ok: false, shortTaskId: short, title: task.title, durationMs })}\n`);
+            return;
+        }
+        process.stdout.write(`${taskOutcome({
+            ok: true,
+            shortTaskId: short,
+            title: task.title,
+            durationMs: Date.now() - startedAt,
+        })}\n`);
+        processed += 1;
+    };
+    let claimedOnce = false;
+    try {
+        while (!stopping) {
+            // `--once` processes at most one claim (or one idle poll) then exits.
+            if (once && claimedOnce)
+                break;
+            claimedOnce = true;
+            const task = await claimNext();
+            if (task) {
+                announcedIdle = false;
+                await runTask(task);
+                if (once)
+                    break;
+                // Claim the next task immediately — no idle wait while work remains.
+                continue;
+            }
+            // No claimable work right now. Announce the idle state ONCE per idle
+            // stretch (not once per poll, which would spam), then wait and re-poll —
+            // so the daemon visibly says "waiting" instead of going silent.
+            if (once)
+                break;
+            if (!announcedIdle) {
+                process.stdout.write(`${statusLine(`no ready tasks — polling every ${intervalMs / 1000}s`)}\n`);
+                announcedIdle = true;
+            }
+            await sleep(intervalMs);
+        }
+    }
+    finally {
+        process.removeListener("SIGINT", onSigint);
+        // Close the run with a tally so the user sees the session total instead of
+        // counting outcome lines. Skipped under --once (single-shot, no session).
+        if (!once) {
+            process.stdout.write(`${sessionSummary({ completed: processed, failed })}\n`);
+        }
+    }
+    return processed;
+}
+/**
+ * `zenorm work` — claim-and-run daemon for the current repository.
+ *
+ * `deps` lets tests inject a fake client and/or runner. When omitted, a real
+ * ZenormClient and the real `AgentRunner` (or `DryRunRunner` under `--dry-run`)
+ * are wired, so the default path actually spawns the chosen agent.
+ */
+export async function workCommand(argv, deps) {
+    // Fatal (CliError) failures — bad args, not a git repo — abort BEFORE the
+    // loop starts so they surface immediately rather than being swallowed as a
+    // transient blip.
+    const { agent, intervalMs, once, dryRun } = parseWorkArgs(argv);
+    const repo = resolveCurrentRepo();
+    const client = deps?.client ?? new ZenormClient();
+    const runner = deps?.runner ?? (dryRun ? new DryRunRunner(agent) : new AgentRunner(agent));
+    // Startup banner — shown on EVERY run (not just --dry-run) so a real session
+    // announces what it's claiming for instead of sitting silent until the first
+    // task lands. Written to stderr so it never interleaves with the agent
+    // transcript when stdout is piped to a file.
+    writeDaemonLine(daemonBanner({
+        agent,
+        repo: `${repo.owner}/${repo.name}`,
+        intervalSeconds: intervalMs / 1000,
+        once,
+        dryRun,
+    }));
+    await runWorkLoop({ client, runner, repo, intervalMs, once });
+}