@workflow-manager/runner 0.6.0 → 0.8.0

package/dist/index.js

@@ -7,13 +7,16 @@ import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import matter from "gray-matter";
 import { CliRunRenderer } from "./cliRunRenderer.js";
+import { TuiRunRenderer } from "./tui/tuiRunRenderer.js";
 import { startRunnerApiServer } from "./runnerApi.js";
 import { RunnerSessionStore } from "./runnerSession.js";
 import { parseWorkflowFile, validateWorkflow } from "./parser.js";
 import { MAN_PAGE_SOURCE } from "./manPage.js";
 import { promptForApprovalDecision, runWorkflow } from "./engine.js";
 import { cmdAuth, cmdPublish, cmdPull, cmdRemoteInfo, cmdSearch } from "./remote/commands.js";
+import { readSessionFile, writeSessionFile } from "./sessionFile.js";
 import { emitRunTelemetryBestEffort } from "./remote/telemetry.js";
+import { BUNDLED_SKILLS } from "./generated/bundledSkills.js";
 import { adapterImplementationStatuses, adapterMockFallbackWarnings, runtimeDoctorChecks, validateRuntimeRequirements, } from "./runtimePreflight.js";
 function resolveVersion() {
     if (typeof WFM_VERSION === "string" && WFM_VERSION) {
@@ -52,15 +55,20 @@ function usage() {
         `Usage: ${cli} <command> [options]`,
         "",
         "Author and run workflows",
-        row("scaffold [path]", "Write a starter workflow file"),
+        row("scaffold [path]", "Write a starter workflow file (--template agent-validated for validator example)"),
         row("validate <file>", "Check a workflow for errors"),
         row("doctor [file]", "Check host setup; with a file, preflight it"),
-        row("run <file>", "Run a workflow with live progress"),
+        row("run <file>", "Run a workflow with live progress (--ui for full-screen)"),
         "",
-        "Control a running workflow",
+        "Control or observe a running workflow",
         row("approve", "Approve a step waiting for review"),
         row("resume", "Resume a step waiting on external input"),
         row("cancel", "Cancel a waiting step"),
+        row("status [--step <key>]", "Print the run (or step) snapshot as JSON"),
+        row("logs [--step <key>]", "Print buffered agent logs as JSON"),
+        row("events [--since <seq>]", "Print run events as JSON (one-shot poll)"),
+        "  Connect with --url/--token, --session-file <path> (written by run --session-file),",
+        "  or WFM_RUNNER_URL/WFM_RUNNER_TOKEN.",
         "",
         "Share workflows (remote registry)",
         row("auth <login|whoami|logout>", "Sign in, check, or sign out"),
@@ -313,6 +321,159 @@ steps:
 
 Edit frontmatter to configure orchestration behavior.
 `;
+const WORKFLOW_SCAFFOLD_AGENT_VALIDATED_JSON = {
+    key: "agent-validated-pipeline",
+    title: "Agent-Validated Pipeline",
+    description: "Repeatable task pipeline where a second agent checks the implementation against explicit criteria",
+    objectives: ["ship a change that meets the stated acceptance criteria"],
+    defaultRetryPolicy: { maxAttempts: 2 },
+    steps: [
+        {
+            key: "implement",
+            kind: "task",
+            objective: "Implement the requested change",
+            dependsOn: [],
+            retryPolicy: { maxAttempts: 2 },
+            validation: {
+                mode: "agent",
+                required: true,
+                autoConfirm: false,
+                agent: {
+                    criteria: "The change satisfies the workflow objective, builds cleanly, and includes tests for new behavior.",
+                    init: {
+                        model: "openrouter/anthropic/claude-sonnet-4",
+                        systemPrompts: ["Check the diff against the criteria; be specific about any gaps found"],
+                    },
+                },
+            },
+            taskSpec: {
+                init: {
+                    context: { repo: "example/repo" },
+                    skills: ["coding", "testing"],
+                    systemPrompts: ["Implement the change described in the workflow objective"],
+                },
+                payload: { mockResult: "success" },
+            },
+        },
+        {
+            key: "review-gate",
+            kind: "approval",
+            objective: "Human sign-off before finalizing",
+            dependsOn: ["implement"],
+            validation: { mode: "human", required: true, autoConfirm: false },
+            approvalSpec: {
+                autoApprove: false,
+                validation: { mode: "human", required: true, autoConfirm: false },
+            },
+        },
+        {
+            key: "finalize",
+            kind: "task",
+            objective: "Finalize the change (for example, open a PR)",
+            dependsOn: ["review-gate"],
+            validation: { mode: "none", required: false, autoConfirm: true },
+            taskSpec: {
+                init: {
+                    systemPrompts: ["Open a PR summarizing the change and its validation history"],
+                },
+                payload: { mockResult: "success" },
+            },
+        },
+    ],
+};
+const WORKFLOW_SCAFFOLD_AGENT_VALIDATED_MARKDOWN = `---
+key: agent-validated-pipeline
+title: Agent-Validated Pipeline
+description: Repeatable task pipeline where a second agent checks the implementation against explicit criteria
+objectives:
+  - ship a change that meets the stated acceptance criteria
+defaultRetryPolicy:
+  maxAttempts: 2
+steps:
+  # "implement" omits taskSpec.adapterKey, so it runs on the default pi-agent adapter.
+  - key: implement
+    kind: task
+    objective: Implement the requested change
+    dependsOn: []
+    retryPolicy:
+      maxAttempts: 2
+    validation:
+      # mode: agent routes this step through a second, independent agent call after
+      # implement finishes. That validator agent reads validation.agent.criteria,
+      # returns a verdict (SUCCESS/QA_REJECTED/...), and the engine maps it to a QA
+      # action: PROCEED keeps going, RETRY_CURRENT reruns this step, ROLLBACK_PREVIOUS
+      # reruns an earlier step, RESTART_ALL restarts the run. Sharpen criteria to
+      # control what the validator accepts.
+      mode: agent
+      required: true
+      autoConfirm: false
+      agent:
+        criteria: >-
+          The change satisfies the workflow objective, builds cleanly, and
+          includes tests for new behavior.
+        init:
+          model: openrouter/anthropic/claude-sonnet-4
+          systemPrompts:
+            - Check the diff against the criteria; be specific about any gaps found
+    taskSpec:
+      init:
+        context:
+          repo: example/repo
+        skills: [coding, testing]
+        systemPrompts: [Implement the change described in the workflow objective]
+      payload:
+        # mockResult drives the mock adapter for local dry runs; real adapters ignore it.
+        mockResult: success
+  - key: review-gate
+    kind: approval
+    objective: Human sign-off before finalizing
+    dependsOn: [implement]
+    # Top-level validation must match approvalSpec.validation: without it, the
+    # parser's default (autoConfirm: true) wins and the gate auto-approves.
+    validation:
+      mode: human
+      required: true
+      autoConfirm: false
+    approvalSpec:
+      autoApprove: false
+      validation:
+        mode: human
+        required: true
+        autoConfirm: false
+  - key: finalize
+    kind: task
+    objective: "Finalize the change (for example, open a PR)"
+    dependsOn: [review-gate]
+    validation:
+      mode: none
+      required: false
+      autoConfirm: true
+    taskSpec:
+      init:
+        systemPrompts: [Open a PR summarizing the change and its validation history]
+      payload:
+        mockResult: success
+---
+
+# Agent-Validated Pipeline
+
+This workflow shows first-class agent validation: instead of (or in addition to) a
+human or external check, a step's own output can be graded by a second agent call.
+
+- \`implement\` runs, then its \`validation.agent\` config sends the result to a
+  validator agent along with \`criteria\` — plain-language acceptance criteria the
+  validator checks the work against.
+- The validator's verdict becomes a QA action: \`PROCEED\` lets the run continue,
+  \`RETRY_CURRENT\` re-runs \`implement\` with the validator's feedback,
+  \`ROLLBACK_PREVIOUS\` re-runs an earlier step, and \`RESTART_ALL\` restarts the run.
+  Retries are bounded by \`retryPolicy.maxAttempts\`.
+- \`review-gate\` is a human approval step — agent validation cannot be used on
+  approval steps, so high-stakes changes still get a human in the loop before
+  \`finalize\` runs.
+
+Tighten \`validation.agent.criteria\` to describe exactly what "done" means for this
+step; the validator only knows what criteria tells it.
+`;
 function resolveScaffoldFormat(targetPath, explicitFormat) {
     if (explicitFormat === "markdown" || explicitFormat === "json") {
         return explicitFormat;
@@ -322,6 +483,7 @@ function resolveScaffoldFormat(targetPath, explicitFormat) {
 function parseScaffoldArgs(args) {
     let targetPath;
     let format;
+    let template;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === "--format") {
@@ -329,11 +491,16 @@ function parseScaffoldArgs(args) {
             i += 1;
             continue;
         }
+        if (arg === "--template") {
+            template = args[i + 1];
+            i += 1;
+            continue;
+        }
         if (!arg.startsWith("-") && !targetPath) {
             targetPath = arg;
         }
     }
-    return { targetPath, format };
+    return { targetPath, format, template };
 }
 const DEFAULT_INSTALL_SKILL = "workflow-manager-cli";
 const SKILL_INSTALL_TARGETS = {
@@ -346,11 +513,22 @@ const SKILL_INSTALL_TARGETS = {
         globalDir: path.join(os.homedir(), ".config", "opencode", "skill"),
     },
 };
-function packagedSkillsDir() {
+export function packagedSkillsDir() {
     return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "skills");
 }
-function listPackagedSkills() {
-    const root = packagedSkillsDir();
+export function parseSkillDescription(skillMarkdown) {
+    try {
+        const parsed = matter(skillMarkdown);
+        if (typeof parsed.data.description === "string") {
+            return parsed.data.description.replace(/\s+/g, " ").trim();
+        }
+    }
+    catch {
+        // skills without parseable frontmatter are still installable
+    }
+    return "";
+}
+export function listPackagedSkillsFromDisk(root) {
     if (!fs.existsSync(root)) {
         return [];
     }
@@ -362,20 +540,44 @@ function listPackagedSkills() {
         const skillFile = path.join(dir, "SKILL.md");
         if (!fs.existsSync(skillFile))
             continue;
-        let description = "";
-        try {
-            const parsed = matter(fs.readFileSync(skillFile, "utf-8"));
-            if (typeof parsed.data.description === "string") {
-                description = parsed.data.description.replace(/\s+/g, " ").trim();
-            }
-        }
-        catch {
-            // skills without parseable frontmatter are still installable
-        }
-        skills.push({ name: entry.name, dir, description });
+        const description = parseSkillDescription(fs.readFileSync(skillFile, "utf-8"));
+        skills.push({ name: entry.name, description, source: { kind: "disk", dir } });
     }
     return skills;
 }
+export function listPackagedSkillsFromBundle(bundle = BUNDLED_SKILLS) {
+    const skills = [];
+    for (const name of Object.keys(bundle).sort()) {
+        const files = bundle[name];
+        const skillFile = files.find((file) => file.name === "SKILL.md");
+        if (!skillFile)
+            continue;
+        skills.push({ name, description: parseSkillDescription(skillFile.content), source: { kind: "bundled", files } });
+    }
+    return skills;
+}
+export function listPackagedSkills(root = packagedSkillsDir()) {
+    const onDisk = listPackagedSkillsFromDisk(root);
+    if (onDisk.length > 0) {
+        return onDisk;
+    }
+    return listPackagedSkillsFromBundle();
+}
+export function materializeSkillFiles(skill, destDir) {
+    if (skill.source.kind === "disk") {
+        for (const entry of fs.readdirSync(skill.source.dir, { withFileTypes: true })) {
+            if (!entry.isFile() || entry.name === "README.md")
+                continue;
+            fs.copyFileSync(path.join(skill.source.dir, entry.name), path.join(destDir, entry.name));
+        }
+        return;
+    }
+    for (const file of skill.source.files) {
+        if (file.name === "README.md")
+            continue;
+        fs.writeFileSync(path.join(destDir, file.name), file.content, "utf-8");
+    }
+}
 function cmdSkillList() {
     const skills = listPackagedSkills();
     if (skills.length === 0) {
@@ -460,16 +662,12 @@ function cmdSkillInstall(args) {
             return 1;
         }
         fs.mkdirSync(destDir, { recursive: true });
-        for (const entry of fs.readdirSync(skill.dir, { withFileTypes: true })) {
-            if (!entry.isFile() || entry.name === "README.md")
-                continue;
-            fs.copyFileSync(path.join(skill.dir, entry.name), path.join(destDir, entry.name));
-        }
+        materializeSkillFiles(skill, destDir);
         console.log(`Installed skill ${name} -> ${destDir}`);
     }
     return 0;
 }
-function cmdScaffold(targetPath, format) {
+function cmdScaffold(targetPath, format, template) {
     const resolvedPath = targetPath ? path.resolve(targetPath) : path.resolve("./example-workflow.md");
     const normalizedFormat = format?.toLowerCase();
     const resolvedFormat = resolveScaffoldFormat(resolvedPath, normalizedFormat);
@@ -477,10 +675,19 @@ function cmdScaffold(targetPath, format) {
         console.error(`Invalid --format value: ${format}. Use markdown or json.`);
         return 1;
     }
-    const template = resolvedFormat === "json"
-        ? `${JSON.stringify(WORKFLOW_SCAFFOLD_JSON, null, 2)}\n`
-        : WORKFLOW_SCAFFOLD_MARKDOWN;
-    fs.writeFileSync(resolvedPath, template, "utf-8");
+    const normalizedTemplate = template?.toLowerCase() ?? "default";
+    if (normalizedTemplate !== "default" && normalizedTemplate !== "agent-validated") {
+        console.error(`Invalid --template value: ${template}. Use default or agent-validated.`);
+        return 1;
+    }
+    const content = normalizedTemplate === "agent-validated"
+        ? resolvedFormat === "json"
+            ? `${JSON.stringify(WORKFLOW_SCAFFOLD_AGENT_VALIDATED_JSON, null, 2)}\n`
+            : WORKFLOW_SCAFFOLD_AGENT_VALIDATED_MARKDOWN
+        : resolvedFormat === "json"
+            ? `${JSON.stringify(WORKFLOW_SCAFFOLD_JSON, null, 2)}\n`
+            : WORKFLOW_SCAFFOLD_MARKDOWN;
+    fs.writeFileSync(resolvedPath, content, "utf-8");
     console.log(`Scaffolded ${resolvedFormat} workflow: ${resolvedPath}`);
     return 0;
 }
@@ -623,40 +830,66 @@ function cmdDoctor(args) {
     }
     return exitCode;
 }
-async function runnerControlRequest(action, args) {
-    const baseUrl = getFlagFromArgs(args, "--url") ?? process.env.WFM_RUNNER_URL;
-    const token = getFlagFromArgs(args, "--token") ?? process.env.WFM_RUNNER_TOKEN;
-    const stepKey = getFlagFromArgs(args, "--step");
-    const actor = getFlagFromArgs(args, "--actor");
-    const note = getFlagFromArgs(args, "--note");
-    const source = getFlagFromArgs(args, "--source") ?? "cli";
+function resolveRunnerConnection(args) {
+    let baseUrl = getFlagFromArgs(args, "--url");
+    let token = getFlagFromArgs(args, "--token");
+    let runId = getFlagFromArgs(args, "--run-id");
+    const sessionFilePath = getFlagFromArgs(args, "--session-file");
+    if (sessionFilePath && (!baseUrl || !token || !runId)) {
+        const session = readSessionFile(sessionFilePath);
+        if (typeof session === "string") {
+            return session;
+        }
+        baseUrl = baseUrl ?? session.baseUrl;
+        token = token ?? session.attachToken;
+        runId = runId ?? session.runId;
+    }
+    baseUrl = baseUrl ?? process.env.WFM_RUNNER_URL;
+    token = token ?? process.env.WFM_RUNNER_TOKEN;
     if (!baseUrl) {
-        console.error(`Missing --url. You can also set WFM_RUNNER_URL.`);
-        return 1;
+        return `Missing --url. You can also pass --session-file or set WFM_RUNNER_URL.`;
     }
     if (!token) {
-        console.error(`Missing --token. You can also set WFM_RUNNER_TOKEN.`);
+        return `Missing --token. You can also pass --session-file or set WFM_RUNNER_TOKEN.`;
+    }
+    return { baseUrl, token, runId };
+}
+async function resolveRunnerRunId(connection, headers) {
+    if (connection.runId) {
+        return { runId: connection.runId };
+    }
+    const sessionResponse = await fetch(`${connection.baseUrl}/session`, { headers });
+    if (!sessionResponse.ok) {
+        const message = await sessionResponse.text();
+        return { error: `Failed to discover run id: ${message}` };
+    }
+    const session = (await sessionResponse.json());
+    const runId = session.run?.runId;
+    if (!runId) {
+        return { error: "Could not determine run id. Pass --run-id explicitly." };
+    }
+    return { runId };
+}
+async function runnerControlRequest(action, args) {
+    const connection = resolveRunnerConnection(args);
+    if (typeof connection === "string") {
+        console.error(connection);
         return 1;
     }
+    const stepKey = getFlagFromArgs(args, "--step");
+    const actor = getFlagFromArgs(args, "--actor");
+    const note = getFlagFromArgs(args, "--note");
+    const source = getFlagFromArgs(args, "--source") ?? "cli";
     const headers = {
-        Authorization: `Bearer ${token}`,
+        Authorization: `Bearer ${connection.token}`,
     };
-    let runId = getFlagFromArgs(args, "--run-id");
-    if (!runId) {
-        const sessionResponse = await fetch(`${baseUrl}/session`, { headers });
-        if (!sessionResponse.ok) {
-            const message = await sessionResponse.text();
-            console.error(`Failed to discover run id: ${message}`);
-            return 1;
-        }
-        const session = (await sessionResponse.json());
-        runId = session.run?.runId;
-    }
-    if (!runId) {
-        console.error("Could not determine run id. Pass --run-id explicitly.");
+    const resolved = await resolveRunnerRunId(connection, headers);
+    if (resolved.error || !resolved.runId) {
+        console.error(resolved.error ?? "Could not determine run id. Pass --run-id explicitly.");
         return 1;
     }
-    const response = await fetch(`${baseUrl}/runs/${runId}/${action}`, {
+    const runId = resolved.runId;
+    const response = await fetch(`${connection.baseUrl}/runs/${runId}/${action}`, {
         method: "POST",
         headers: {
             ...headers,
@@ -681,13 +914,84 @@ async function runnerControlRequest(action, args) {
     console.log(`${decision} ${resolvedStep}`);
     return 0;
 }
+async function runnerReadRequest(command, args) {
+    const connection = resolveRunnerConnection(args);
+    if (typeof connection === "string") {
+        console.error(connection);
+        return 1;
+    }
+    const headers = {
+        Authorization: `Bearer ${connection.token}`,
+    };
+    try {
+        const resolved = await resolveRunnerRunId(connection, headers);
+        if (resolved.error || !resolved.runId) {
+            console.error(resolved.error ?? "Could not determine run id. Pass --run-id explicitly.");
+            return 1;
+        }
+        const runId = encodeURIComponent(resolved.runId);
+        let requestPath;
+        if (command === "status") {
+            const stepKey = getFlagFromArgs(args, "--step");
+            requestPath = stepKey ? `/runs/${runId}/steps/${encodeURIComponent(stepKey)}` : `/runs/${runId}`;
+        }
+        else if (command === "logs") {
+            const query = new URLSearchParams();
+            const stepKey = getFlagFromArgs(args, "--step");
+            const limit = getFlagFromArgs(args, "--limit");
+            const cursor = getFlagFromArgs(args, "--cursor");
+            if (stepKey)
+                query.set("stepKey", stepKey);
+            if (limit)
+                query.set("limit", limit);
+            if (cursor)
+                query.set("cursor", cursor);
+            const queryString = query.toString();
+            requestPath = `/runs/${runId}/logs${queryString ? `?${queryString}` : ""}`;
+        }
+        else {
+            const query = new URLSearchParams();
+            const since = getFlagFromArgs(args, "--since");
+            if (since)
+                query.set("sinceSequence", since);
+            query.set("includeLogs", args.includes("--include-logs") ? "true" : "false");
+            requestPath = `/runs/${runId}/events/list?${query.toString()}`;
+        }
+        const response = await fetch(`${connection.baseUrl}${requestPath}`, { headers });
+        const payloadText = await response.text();
+        if (!response.ok) {
+            let message = `Request failed with status ${response.status}`;
+            try {
+                const payload = JSON.parse(payloadText);
+                if (typeof payload.message === "string") {
+                    message = payload.message;
+                }
+            }
+            catch {
+                // keep the fallback message
+            }
+            console.error(`${command} failed: ${message}`);
+            return 1;
+        }
+        console.log(payloadText);
+        return 0;
+    }
+    catch (error) {
+        console.error(`${command} failed: ${error.message}`);
+        return 1;
+    }
+}
 async function cmdRun(filePath) {
     const resolvedPath = path.resolve(filePath);
     const startedAt = Date.now();
+    const sessionFilePath = getFlag("--session-file");
+    let sessionFileState;
+    let finalRunStatus;
     let workflow;
     let runnerServer;
     let sessionStore;
     let liveRenderer;
+    let tuiRenderer;
     try {
         workflow = parseWorkflowFile(resolvedPath);
         const errors = validateWorkflow(workflow);
@@ -729,57 +1033,89 @@ async function cmdRun(filePath) {
             console.error("--port must be an integer between 0 and 65535");
             return 1;
         }
+        const wantUi = hasFlag("--ui");
+        const useTui = wantUi && process.stdout.isTTY === true && process.stdin.isTTY === true;
+        if (wantUi && !useTui) {
+            process.stderr.write("⚠ --ui requires an interactive terminal; falling back to standard output\n");
+        }
         sessionStore = new RunnerSessionStore({
             runId,
             workflow,
             objective: objective ?? workflow.title,
             objectives: workflow.objectives ?? [],
         });
-        liveRenderer = new CliRunRenderer({
-            workflow,
-            verbose: hasFlag("--verbose"),
-        });
+        if (!useTui) {
+            liveRenderer = new CliRunRenderer({
+                workflow,
+                verbose: hasFlag("--verbose"),
+            });
+        }
         runnerServer = await startRunnerApiServer(sessionStore, requestedPort);
         const session = sessionStore.sessionInfo();
-        process.stderr.write(`Attach API: ${session.baseUrl} (token ${session.attachToken})\n`);
+        if (sessionFilePath) {
+            sessionFileState = {
+                baseUrl: session.baseUrl,
+                attachToken: session.attachToken,
+                runId,
+                pid: process.pid,
+                startedAt: session.startedAt,
+            };
+            writeSessionFile(sessionFilePath, sessionFileState);
+        }
+        if (!useTui) {
+            process.stderr.write(`Attach API: ${session.baseUrl} (token ${session.attachToken})\n`);
+        }
+        if (useTui) {
+            tuiRenderer = new TuiRunRenderer({
+                workflow,
+                session: sessionStore,
+                attachUrl: session.baseUrl,
+                attachToken: session.attachToken,
+            });
+            tuiRenderer.start();
+        }
         const result = await runWorkflow(workflow, {
             runId,
             objective,
             input,
             confirmations,
             autoConfirmAll: hasFlag("--auto-confirm-all"),
-            interactive: process.stdin.isTTY,
+            interactive: useTui ? false : process.stdin.isTTY,
             workflowFilePath: resolvedPath,
-            approvalPrompt: async (request) => {
-                liveRenderer?.pauseHeartbeat();
-                try {
-                    const decision = await promptForApprovalDecision(request.stepKey, request.reason, request.validation ?? "external", request.preview ?? null, "cli", request.signal);
-                    if (!decision) {
+            approvalPrompt: useTui
+                ? undefined
+                : async (request) => {
+                    liveRenderer?.pauseHeartbeat();
+                    try {
+                        const decision = await promptForApprovalDecision(request.stepKey, request.reason, request.validation ?? "external", request.preview ?? null, "cli", request.signal);
+                        if (!decision) {
+                            return null;
+                        }
+                        const metadata = {
+                            actor: decision.actor,
+                            note: decision.note,
+                            source: decision.source,
+                        };
+                        const outcome = decision.decision === "cancelled"
+                            ? sessionStore?.cancel(request.stepKey, metadata)
+                            : request.validation === "external"
+                                ? sessionStore?.resume(request.stepKey, metadata)
+                                : sessionStore?.approve(request.stepKey, metadata);
+                        if (outcome && !outcome.ok) {
+                            process.stderr.write(`Could not apply terminal decision for ${request.stepKey}: ${outcome.reason ?? "unknown error"}\n`);
+                        }
                         return null;
                     }
-                    const metadata = {
-                        actor: decision.actor,
-                        note: decision.note,
-                        source: decision.source,
-                    };
-                    const outcome = decision.decision === "cancelled"
-                        ? sessionStore?.cancel(request.stepKey, metadata)
-                        : request.validation === "external"
-                            ? sessionStore?.resume(request.stepKey, metadata)
-                            : sessionStore?.approve(request.stepKey, metadata);
-                    if (outcome && !outcome.ok) {
-                        process.stderr.write(`Could not apply terminal decision for ${request.stepKey}: ${outcome.reason ?? "unknown error"}\n`);
+                    finally {
+                        liveRenderer?.resumeHeartbeat();
                     }
-                    return null;
-                }
-                finally {
-                    liveRenderer?.resumeHeartbeat();
-                }
-            },
-            observer: combineRunObservers(sessionStore, liveRenderer),
+                },
+            observer: combineRunObservers(sessionStore, useTui ? tuiRenderer : liveRenderer),
             controller: sessionStore,
         });
-        liveRenderer.close();
+        tuiRenderer?.stop();
+        liveRenderer?.close();
+        finalRunStatus = result.status;
         if (hasFlag("--json")) {
             console.log(JSON.stringify({ session: sessionStore.sessionInfo(), ...result }, null, 2));
         }
@@ -807,6 +1143,7 @@ async function cmdRun(filePath) {
         return result.status === "succeeded" ? 0 : 2;
     }
     catch (err) {
+        tuiRenderer?.stop();
         liveRenderer?.close();
         console.error(`Run error: ${err.message}`);
         if (workflow) {
@@ -820,7 +1157,20 @@ async function cmdRun(filePath) {
         return 1;
     }
     finally {
+        tuiRenderer?.stop();
         liveRenderer?.close();
+        if (sessionFilePath && sessionFileState) {
+            try {
+                writeSessionFile(sessionFilePath, {
+                    ...sessionFileState,
+                    endedAt: new Date().toISOString(),
+                    status: finalRunStatus ?? "failed",
+                });
+            }
+            catch {
+                // session-file finalization is best effort; the run result is authoritative
+            }
+        }
         await runnerServer?.close().catch(() => undefined);
     }
 }
@@ -849,8 +1199,8 @@ async function main() {
         process.exit(1);
     }
     if (cmd === "scaffold") {
-        const { targetPath, format } = parseScaffoldArgs(process.argv.slice(3));
-        process.exit(cmdScaffold(targetPath, format));
+        const { targetPath, format, template } = parseScaffoldArgs(process.argv.slice(3));
+        process.exit(cmdScaffold(targetPath, format, template));
     }
     if (cmd === "man") {
         process.exit(cmdMan());
@@ -874,6 +1224,9 @@ async function main() {
     if (cmd === "approve" || cmd === "resume" || cmd === "cancel") {
         process.exit(await runnerControlRequest(cmd, process.argv.slice(3)));
     }
+    if (cmd === "status" || cmd === "logs" || cmd === "events") {
+        process.exit(await runnerReadRequest(cmd, process.argv.slice(3)));
+    }
     if (cmd === "auth") {
         process.exit(await cmdAuth(process.argv.slice(3)));
     }
@@ -907,4 +1260,30 @@ async function main() {
     usage();
     process.exit(1);
 }
-void main();
+// Run main() only when this module is the process entrypoint (direct `bun
+// run`/`node` invocation, an npm-installed symlinked bin, or a `bun build
+// --compile` standalone binary) — never when imported as a module, e.g. by
+// tests exercising the exported skill-catalog helpers below.
+function isEntryModule() {
+    if (!process.argv[1]) {
+        return false;
+    }
+    const self = fileURLToPath(import.meta.url);
+    let invoked = process.argv[1];
+    try {
+        invoked = fs.realpathSync(invoked);
+    }
+    catch {
+        // compiled/virtual filesystem paths (e.g. bun's $bunfs) can't be
+        // realpath'd; fall back to the raw invoked path.
+    }
+    try {
+        return path.resolve(invoked) === self;
+    }
+    catch {
+        return false;
+    }
+}
+if (isEntryModule()) {
+    void main();
+}