@ze-norm/cli 0.11.5 → 0.13.0

package/dist/commands/work.js

@@ -3,7 +3,9 @@ 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";
+import { loadConfig } from "../config/loader.js";
+import { InteractiveAgent, assertUsableTty, processTtyProbe, } from "./interactive-agent.js";
+import { LineSplitter, claudeRenderer, codexRenderer, daemonBanner, failureBanner, postAgentSummary, 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
@@ -19,7 +21,7 @@ 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]
+  zenorm work --agent <${SUPPORTED_AGENTS.join("|")}> [--model <model>] [--interval <seconds>] [--once] [--dry-run] [--interactive]
 
 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
@@ -28,10 +30,23 @@ 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(", ")}
+  --model <model>      Model the agent runs each task with (alias e.g. opus,
+                       sonnet, or a full model id). Optional; when omitted the
+                       agent uses its own configured default. For claude this
+                       also retargets the server-side advisor tool to the same
+                       model, so a gated \`advisorModel\` no longer 400s the run.
   --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.`;
+                       run instead of spawning the agent.
+  --interactive        Opt into coding-agent mode: instead of running each task
+                       headlessly, launch the active coding agent (the one named
+                       by --agent) as a LIVE interactive session seeded with the
+                       spec handoff. Work with the agent, then exit it to release
+                       the worker and continue to the next task. Local terminal
+                       only — requires a usable TTY and fails fast without one.
+                       Can also be enabled per project via \`interactive: true\`
+                       in .zenorm.json.`;
 /**
  * Headless install hints, surfaced when an agent binary is missing so the
  * failure is actionable rather than a bare ENOENT.
@@ -43,31 +58,59 @@ const AGENT_INSTALL_HINT = {
         "(https://github.com/openai/codex).",
 };
 /**
- * Build the handoff prompt that tells the agent to execute THIS already-claimed
- * task via the bundled ZeNorm skills. The `/zenorm task <id>` trigger is what
- * the `zenorm` dispatcher SKILL.md keys on (single-task mode → `execute-task`).
+ * 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 task is already claimed/active server-side (the claim flipped it), so the
- * prompt says "already-claimed" and instructs the agent to complete it via the
- * normal `zenorm task complete` flow — the daemon does NOT post the outcome.
+ * 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 ${task.id}`,
+        ...handoffPromptBody(task, zenormCli),
+        // Headless runs have no operator to wait on — tell the agent to drive
+        // straight through without pausing for input. The interactive variant
+        // (buildInteractiveHandoffPrompt) deliberately omits this line.
+        "Work non-interactively; do not wait for further input.",
+    ].join("\n");
+}
+/**
+ * The interactive (coding-agent mode) handoff prompt. Same spec-mode handoff as
+ * the headless prompt, MINUS the "work non-interactively" instruction: in this
+ * mode the agent runs as a live session the operator drives, so it SHOULD pause
+ * for input. Exported for unit testing.
+ */
+export function buildInteractiveHandoffPrompt(task) {
+    const zenormCli = process.env["ZENORM_CLI"]?.trim() || "zenorm";
+    return handoffPromptBody(task, zenormCli).join("\n");
+}
+/** Shared spec-mode handoff lines for both the headless and interactive prompts. */
+function handoffPromptBody(task, zenormCli) {
+    return [
+        `/zenorm ${task.specId}`,
         "",
-        `Execute the already-claimed ZeNorm task "${task.title}" (id: ${task.id}).`,
+        `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.",
-        "It has already been claimed and flipped to `active` server-side, so do not",
-        "re-claim it. Implement it end-to-end in the current repository working",
-        "directory using the existing ZeNorm execute workflow, then complete it via",
-        `the normal \`${zenormCli} task complete <task-id>\` flow. Work non-interactively;`,
-        "do not wait for further input.",
-    ].join("\n");
+        `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.`,
+    ];
 }
 /**
  * The headless subprocess invocation for a given agent + task. Pure (no
@@ -81,7 +124,7 @@ export function buildHandoffPrompt(task) {
  *
  * Exported for unit testing.
  */
-export function buildAgentCommand(agent, task) {
+export function buildAgentCommand(agent, task, model) {
     const prompt = buildHandoffPrompt(task);
     switch (agent) {
         case "claude":
@@ -107,11 +150,29 @@ export function buildAgentCommand(agent, task) {
                     "--verbose",
                     "--permission-mode",
                     "auto",
+                    // --model sets the main session model; it does NOT retarget the
+                    // server-side advisor tool, which carries its OWN model from the
+                    // `advisorModel` setting. If that setting points at a model the
+                    // account can't access (e.g. a gated `claude-fable-5`), EVERY turn
+                    // 400s with `tools.N.model: ... is not available`. So when the user
+                    // pins a model we also override `advisorModel` for THIS session via
+                    // --settings, keeping the advisor on a model we know is reachable.
+                    ...(model
+                        ? [
+                            "--model",
+                            model,
+                            "--settings",
+                            JSON.stringify({ advisorModel: model }),
+                        ]
+                        : []),
                     prompt,
                 ],
             };
         case "codex":
-            return { command: "codex", args: ["exec", "--json", prompt] };
+            return {
+                command: "codex",
+                args: ["exec", "--json", ...(model ? ["-m", model] : []), prompt],
+            };
         default: {
             // Exhaustiveness guard — fail loud if SUPPORTED_AGENTS grows without a
             // matching headless invocation here (no error-masking default).
@@ -120,11 +181,112 @@ export function buildAgentCommand(agent, task) {
         }
     }
 }
+/**
+ * The INTERACTIVE invocation for a given agent + task: launch the agent as a
+ * live session (NOT headless) seeded with the spec handoff, so the operator
+ * works with it directly in its own TUI. Pure (no side effects) so it can be
+ * unit-tested without spawning anything.
+ *
+ * Unlike `buildAgentCommand`, there is no `-p`/`exec`/`--json` and no
+ * stream-json: both agents start an interactive session by default, and the
+ * agent's own TUI renders straight to the inherited terminal (so there is no
+ * raw JSON event stream for us to re-render, and nothing to dump as raw text).
+ * - claude: `claude --permission-mode auto [--model <m>] "<prompt>"`
+ *   (interactive by default; `-p` would make it headless, so it is deliberately
+ *   absent). `--permission-mode auto` runs the background classifier that
+ *   auto-approves safe actions and only blocks destructive ones, so the
+ *   operator is not interrupted by a permission prompt on every gated tool call
+ *   — same guardrail the headless path uses, just keeping the session live.
+ * - codex:  `codex --ask-for-approval never --sandbox workspace-write [-m <m>]
+ *   "<prompt>"` (interactive by default; the `exec` subcommand is what makes it
+ *   non-interactive, so it is deliberately absent). `--ask-for-approval never`
+ *   is codex's full-auto: the operator is never interrupted by an approval
+ *   prompt, while `--sandbox workspace-write` still confines writes to the
+ *   workspace (NOT `--dangerously-bypass-approvals-and-sandbox`, which would
+ *   drop the sandbox entirely).
+ *
+ * Exported for unit testing.
+ */
+export function buildInteractiveAgentCommand(agent, task, model) {
+    const prompt = buildInteractiveHandoffPrompt(task);
+    switch (agent) {
+        case "claude":
+            return {
+                command: "claude",
+                args: ["--permission-mode", "auto", ...(model ? ["--model", model] : []), prompt],
+            };
+        case "codex":
+            return {
+                command: "codex",
+                args: [
+                    "--ask-for-approval",
+                    "never",
+                    "--sandbox",
+                    "workspace-write",
+                    ...(model ? ["-m", model] : []),
+                    prompt,
+                ],
+            };
+        default: {
+            // Exhaustiveness guard — fail loud if SUPPORTED_AGENTS grows without a
+            // matching interactive invocation here (no error-masking default).
+            const never = agent;
+            throw new CliError(`No interactive 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 working-tree snapshot: `git status --porcelain` in the current repo. */
+function realGitStatus() {
+    return execFileSync("git", ["status", "--porcelain"], {
+        cwd: process.cwd(),
+        encoding: "utf-8",
+    });
+}
+/**
+ * Parse one `git status --porcelain` line into its path. The format is a 2-char
+ * status code + a space, then the path; a rename/copy renders as `old -> new`,
+ * for which we take the NEW path (`new`). Returns null for a blank line.
+ */
+function porcelainPath(line) {
+    if (line.trim().length === 0)
+        return null;
+    // Drop the 3-char status prefix ("XY ").
+    const rest = line.slice(3);
+    const arrow = rest.indexOf(" -> ");
+    return arrow >= 0 ? rest.slice(arrow + 4) : rest;
+}
+/**
+ * Diff two `git status --porcelain` snapshots into the set of files the agent
+ * touched during the session. We compare the porcelain LINE per path across
+ * before/after: a path is "touched" when its line differs (added, removed, or
+ * its status code changed). This deliberately IGNORES pre-existing dirt whose
+ * status did not change during the session (so unrelated stray files already in
+ * the tree don't pollute the summary). Returns a sorted, deduped path list.
+ */
+export function diffTouchedFiles(before, after) {
+    const index = (porcelain) => {
+        const map = new Map();
+        for (const line of porcelain.split("\n")) {
+            const path = porcelainPath(line);
+            if (path !== null)
+                map.set(path, line);
+        }
+        return map;
+    };
+    const beforeLines = index(before);
+    const afterLines = index(after);
+    const touched = new Set();
+    for (const path of new Set([...beforeLines.keys(), ...afterLines.keys()])) {
+        if (beforeLines.get(path) !== afterLines.get(path))
+            touched.add(path);
+    }
+    return [...touched].sort();
+}
 /**
  * The real runner: spawns the chosen coding agent headlessly against the
  * claimed task and awaits its exit.
@@ -138,16 +300,50 @@ const AGENT_RENDERER = {
 export class AgentRunner {
     agent;
     spawnFn;
+    model;
+    interactive;
+    gitStatus;
+    fetchTaskStatus;
     agentName;
     constructor(agent, 
     // Injectable for tests; defaults to node:child_process spawn.
-    spawnFn = spawn) {
+    spawnFn = spawn, 
+    // Optional model pin, threaded into the agent invocation.
+    model, 
+    // When true, coding-agent (interactive) mode is on: instead of running the
+    // agent headlessly and re-rendering its JSON event stream, the agent is
+    // launched as a LIVE session that owns the terminal (inherited stdio). The
+    // operator works with it until they close it; its exit releases the worker.
+    // The caller is responsible for having already passed the fail-fast TTY
+    // check (assertUsableTty).
+    interactive = false, 
+    // Working-tree snapshot for the interactive post-agent summary. Injectable
+    // for tests; defaults to a real `git status --porcelain`. Only the
+    // interactive path reads it (before open() + after a clean exit).
+    gitStatus = realGitStatus, 
+    // Reads the claimed task's current server-side status for the summary.
+    // Optional: when absent (e.g. the existing interactive unit tests that
+    // construct the runner with no client) the summary falls back to status
+    // `unknown` without warning — only a real fetch FAILURE warns. Wired to the
+    // real client in `workCommand`.
+    fetchTaskStatus) {
         this.agent = agent;
         this.spawnFn = spawnFn;
+        this.model = model;
+        this.interactive = interactive;
+        this.gitStatus = gitStatus;
+        this.fetchTaskStatus = fetchTaskStatus;
         this.agentName = agent;
     }
     run(task) {
-        const { command, args } = buildAgentCommand(this.agent, task);
+        return this.interactive ? this.runInteractive(task) : this.runHeadless(task);
+    }
+    /**
+     * Default (non-interactive) path — UNCHANGED behavior: spawn the agent
+     * headlessly, pipe + re-render its JSON event stream, await its exit.
+     */
+    runHeadless(task) {
+        const { command, args } = buildAgentCommand(this.agent, task, this.model);
         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
@@ -158,16 +354,13 @@ export class AgentRunner {
                 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.
+            // Render stdout line-by-line 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);
+                        process.stdout.write(`${out}\n`);
                 }
             };
             child.stdout?.setEncoding("utf-8");
@@ -177,30 +370,125 @@ export class AgentRunner {
             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;
+            this.wireChild(child, command, task, resolve, reject);
+        });
+    }
+    /**
+     * Coding-agent (interactive) path. Launch the agent as a LIVE session via
+     * `InteractiveAgent`: inherited stdio so the agent's own TUI owns the terminal
+     * (no piping, no re-render — and therefore no raw text dumping), seeded with
+     * the spec handoff. The operator works with it; when they close the agent it
+     * exits, which resolves this run and RELEASES THE WORKER so the loop claims
+     * the next task. A clean operator exit (code 0) is success; a crash/non-zero
+     * exit is still a loud failure.
+     */
+    runInteractive(task) {
+        const { command, args } = buildInteractiveAgentCommand(this.agent, task, this.model);
+        // A fresh session per task (the daemon reuses one runner across tasks, so
+        // the single-operator InteractiveAgent instance must not be shared).
+        const session = new InteractiveAgent(command, args, this.spawnFn);
+        // Snapshot the working tree BEFORE the agent runs so we can diff it against
+        // the post-session state and report which files the agent touched.
+        const before = this.gitStatus();
+        return new Promise((resolve, reject) => {
+            let child;
+            try {
+                // open() enforces the single-operator invariant and local-only spawn
+                // options, then spawns the agent. A throw here (e.g. local-option guard)
+                // means nothing was spawned, so there is no child to orphan.
+                child = session.open();
+            }
+            catch (err) {
+                reject(err instanceof Error ? err : new CliError(String(err)));
+                return;
+            }
+            // On a CLEAN exit, print the one-line post-agent summary BEFORE releasing
+            // the worker (the real `resolve` fires only inside summarizeThenRelease).
+            // `wireChild`'s exit handler stays synchronous (shared with the headless
+            // path); we hand it a wrapper that defers the resolve until the summary is
+            // written. A non-zero exit still rejects through `wireChild` unchanged.
+            const releaseAfterSummary = () => {
+                void this.summarizeThenRelease(task, before, resolve);
+            };
+            this.wireChild(child, command, task, releaseAfterSummary, reject);
+        });
+    }
+    /**
+     * Print the ONE-LINE post-agent change summary, then RESOLVE (releasing the
+     * worker) — in that order, per the spec constraint "Summary before worker
+     * release". Computes the touched-file set from the before/after porcelain
+     * snapshots and reads the claimed task's current server-side status.
+     *
+     * Robustness: this runs after a CLEAN agent exit, so it must NEVER turn that
+     * success into a failure. The whole body is wrapped so `resolve()` always
+     * fires even if the summary work throws. The status read is the one sanctioned
+     * soft-fallback — a fetch failure warns and reports `unknown` rather than
+     * blocking the release; an absent status fetcher (no client wired, e.g. unit
+     * tests) is silently `unknown`.
+     */
+    async summarizeThenRelease(task, before, resolve) {
+        try {
+            const after = this.gitStatus();
+            const filesTouched = diffTouchedFiles(before, after);
+            let status = "unknown";
+            if (this.fetchTaskStatus) {
+                try {
+                    status = await this.fetchTaskStatus(task);
                 }
-                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;
+                catch (err) {
+                    // The status read must not block worker release — warn and fall back
+                    // to `unknown` (the one allowed soft-fallback) instead of throwing.
+                    log.warn(`Could not read task ${shortId(task.id)} status for summary`, {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
                 }
-                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)}.`));
+            }
+            process.stdout.write(`${postAgentSummary({
+                filesTouched,
+                status,
+                shortTaskId: shortId(task.id),
+            })}\n`);
+        }
+        catch (err) {
+            // A summary failure must never convert a clean agent exit into a failure;
+            // warn and still release the worker below.
+            log.warn(`Could not print post-agent summary for task ${shortId(task.id)}`, {
+                error: err instanceof Error ? err.message : String(err),
             });
+        }
+        finally {
+            resolve();
+        }
+    }
+    /**
+     * Shared exit/error handling for both paths: ENOENT → install hint, non-zero
+     * exit → loud failure, code 0 → success (releases the worker). `settled`
+     * guards against a double-settle if error and exit both fire.
+     */
+    wireChild(child, command, task, resolve, reject) {
+        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)}.`));
         });
     }
 }
@@ -211,13 +499,15 @@ export class AgentRunner {
  */
 export class DryRunRunner {
     agent;
+    model;
     agentName;
-    constructor(agent) {
+    constructor(agent, model) {
         this.agent = agent;
+        this.model = model;
         this.agentName = agent;
     }
     run(task) {
-        const { command, args } = buildAgentCommand(this.agent, task);
+        const { command, args } = buildAgentCommand(this.agent, task, this.model);
         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)}`);
@@ -309,9 +599,11 @@ function parseWorkArgs(argv) {
             args: argv,
             options: {
                 agent: { type: "string" },
+                model: { type: "string" },
                 interval: { type: "string" },
                 once: { type: "boolean" },
                 "dry-run": { type: "boolean" },
+                interactive: { type: "boolean" },
             },
             strict: true,
         }));
@@ -327,6 +619,17 @@ function parseWorkArgs(argv) {
     if (!SUPPORTED_AGENTS.includes(agent)) {
         throw new CliError(`Unsupported agent "${agent}".\n\nSupported agents: ${SUPPORTED_AGENTS.join(", ")}`);
     }
+    // --model is optional: when omitted the agent uses its own configured
+    // default. But an explicit empty `--model ""` is a mistake we fail loud on
+    // rather than silently passing a blank model through to the agent.
+    const rawModel = values["model"];
+    let model;
+    if (rawModel !== undefined) {
+        if (rawModel.trim() === "") {
+            throw new CliError(`Invalid --model "${rawModel}". Provide a model alias (e.g. opus, sonnet) or full model id.`);
+        }
+        model = rawModel;
+    }
     let intervalSeconds = DEFAULT_INTERVAL_SECONDS;
     const rawInterval = values["interval"];
     if (rawInterval !== undefined) {
@@ -344,11 +647,25 @@ function parseWorkArgs(argv) {
         // Validated above against SUPPORTED_AGENTS; the readonly-tuple `includes`
         // check above does not narrow `string`, so assert the proven type here.
         agent: agent,
+        model,
         intervalMs: intervalSeconds * 1000,
         once: values["once"] === true,
         dryRun: values["dry-run"] === true,
+        interactive: values["interactive"] === true,
     };
 }
+/**
+ * Resolve whether interactive mode is on. Opt-in is explicit by design (the
+ * spec keeps existing runs non-interactive unless enabled): the `--interactive`
+ * flag, or `interactive: true` in `.zenorm.json`. The flag wins; config only
+ * supplies the default when the flag is absent. A bad config value already
+ * threw in `validateConfig`, so this never silently coerces.
+ */
+export function resolveInteractive(flagPassed, config) {
+    if (flagPassed)
+        return true;
+    return config?.interactive === true;
+}
 /** Write daemon-only meta output (e.g. the dry-run banner) to stderr. */
 function writeDaemonLine(line) {
     process.stderr.write(`${line}\n`);
@@ -363,6 +680,22 @@ async function releaseTaskToTodo(client, task) {
         });
     }
 }
+/**
+ * Read the claimed task's CURRENT server-side status for the interactive
+ * post-agent summary. `GET /v1/specs/:specId/tasks` returns the spec's tasks;
+ * we find this one by id and return its status. Throws if the task is missing
+ * from the response (fail loud rather than masking a wrong/empty list) — the
+ * caller (`summarizeThenRelease`) catches and degrades to `unknown` so a status
+ * read never blocks worker release.
+ */
+async function fetchTaskStatus(client, task) {
+    const { tasks } = await client.get(`/v1/specs/${task.specId}/tasks`);
+    const found = tasks.find((t) => t.id === task.id);
+    if (!found) {
+        throw new CliError(`Task ${shortId(task.id)} not found in spec ${task.specId} tasks list.`);
+    }
+    return found.status;
+}
 async function heartbeatTask(client, task) {
     try {
         await client.post(`/v1/tasks/${task.id}/heartbeat`, {});
@@ -422,11 +755,15 @@ export async function runWorkLoop(opts) {
         }
         return response.task ?? null;
     };
-    // Run a single claimed task to completion. 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 task header and closes with a
-    // ✓/✗ outcome line (+ a loud banner on failure). A failed run is released back
-    // to `todo` so it can be re-claimed.
+    // 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";
@@ -504,16 +841,42 @@ 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 { agent, model, intervalMs, once, dryRun, interactive: interactiveFlag } = parseWorkArgs(argv);
     const repo = resolveCurrentRepo();
+    // Resolve the interactive opt-in (flag OR project config). `loadConfig` walks
+    // up from cwd for `.zenorm.json`; a malformed config throws (no masked errors).
+    const interactive = resolveInteractive(interactiveFlag, loadConfig());
+    if (interactive && dryRun) {
+        // --dry-run never spawns an agent, so there is no live agent session to drop
+        // into. Refuse the combination loudly rather than silently ignoring one.
+        throw new CliError("`--interactive` cannot be combined with `--dry-run`: dry-run never " +
+            "launches an agent, so there is no interactive coding-agent session to open.");
+    }
+    // Fail-fast gate (spec: "Fail-fast without usable TTY"). Done BEFORE the loop
+    // and BEFORE any claim so a misconfigured interactive run errors immediately
+    // instead of claiming a task and then hanging. Non-interactive runs skip this
+    // entirely — they never require a TTY and never prompt.
+    if (interactive) {
+        assertUsableTty(deps?.ttyProbe ?? processTtyProbe());
+    }
     const client = deps?.client ?? new ZenormClient();
-    const runner = deps?.runner ?? (dryRun ? new DryRunRunner(agent) : new AgentRunner(agent));
+    const runner = deps?.runner ??
+        (dryRun
+            ? new DryRunRunner(agent, model)
+            : new AgentRunner(agent, spawn, model, interactive, 
+            // Real working-tree snapshot for the interactive post-agent summary.
+            realGitStatus, 
+            // Real status read: list the spec's tasks and pick out this task's
+            // current status (it is likely `done` once the agent inside the
+            // session ran `zenorm task complete`).
+            (task) => fetchTaskStatus(client, task)));
     // 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,
+        model,
         repo: `${repo.owner}/${repo.name}`,
         intervalSeconds: intervalMs / 1000,
         once,