@workflow-manager/runner 0.6.0 → 0.8.0

package/dist/manPage.d.ts

@@ -1 +1 @@
-export declare const MAN_PAGE_SOURCE = ".TH WFM 1 \"April 2026\" \"@workflow-manager/runner\" \"User Commands\"\n.SH NAME\nwfm \\- run markdown or json workflows from the CLI\n.SH SYNOPSIS\n.B wfm\n.I command\n[options]\n.SH DESCRIPTION\nwfm parses a workflow definition file, validates it, and executes\nit with deterministic in-memory orchestration.\n\nWorkflow files can be Markdown with YAML frontmatter or JSON.\n.SH COMMANDS\n.TP\n.B doctor [workflow.md|workflow.json] [--json]\nInspect host adapter setup, LLM access keys, and current adapter implementation status. When a workflow path is provided, also validate schema and runtime requirements without executing steps.\n.TP\n.B skill list\nList the agent skills bundled with the npm package.\n.TP\n.B skill install [name ...] [--agent claude|opencode] [--global] [--dir path] [--all] [--force]\nInstall bundled agent skills into an agent skill directory. Defaults to the workflow-manager-cli skill and the project-level Claude Code directory (./.claude/skills). Existing skills are not overwritten unless --force is passed.\n.TP\n.B scaffold [path] [--format markdown|json]\nCreate a starter workflow file. Format defaults to markdown unless the output\npath ends in .json.\n.TP\n.B validate <workflow.md|workflow.json>\nValidate workflow structure and report schema errors.\n.TP\n.B run <workflow.md|workflow.json> [--input input.json] [--objective text] [--confirm list] [--auto-confirm-all] [--port number] [--verbose] [--json]\nRun the workflow with live CLI progress and optional JSON output.\n.TP\n.B approve [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]\nApprove the current waiting runner step through the local attach API.\n.TP\n.B resume [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]\nAlias for approve, intended for external resume flows.\n.TP\n.B cancel [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]\nCancel the current waiting runner step through the local attach API.\n.TP\n.B auth <login|whoami|logout> [--token value]\nManage remote registry authentication for CLI publish and pull flows.\n.TP\n.B publish <workflow.md|workflow.json> [--slug slug] [--title text] [--description text] [--visibility public|private] [--version label] [--tag a,b] [--draft]\nPublish a validated local workflow to the remote registry.\n.TP\n.B pull <owner/slug> [--version label] [--output path]\nDownload a remote workflow and write it to a local file.\n.TP\n.B search [query]\nSearch public workflows from the remote registry.\n.TP\n.B remote info <owner/slug>\nShow metadata and source information for a remote workflow.\n.TP\n.B man\nOpen this man page.\n.TP\n.B --version, -v, version\nPrint the installed wfm version and exit.\n.SH RUN OPTIONS\n.TP\n.B --input <path>\nJSON file merged into global workflow input state.\n.TP\n.B --objective <text>\nOverride the default run objective.\n.TP\n.B --confirm <stepA,stepB:human,...>\nProvide explicit confirmations for steps that require validation.\n.TP\n.B --auto-confirm-all\nBypass confirmation gating for all steps.\n.TP\n.B --port <number>\nBind the local attach API to a specific port. If omitted, the OS assigns a free port on 127.0.0.1.\n.TP\n.B --verbose\nStream per-step agent output and execution updates to stderr while the workflow runs.\n.TP\n.B --json\nPrint the final run result as JSON on stdout while keeping live progress on stderr.\n.TP\nHuman approval steps in an interactive terminal show an inline review prompt so they can be approved or cancelled without a separate HTTP client.\n.TP\n.B --url <value>\nRunner attach API base URL for approve, resume, or cancel commands.\n.TP\n.B --token <value>\nRunner attach API bearer token for approve, resume, or cancel commands.\n.TP\n.B --run-id <value>\nRunner id to control. If omitted, the CLI reads it from /session.\n.TP\n.B --step <value>\nOptional step key when controlling a specific waiting step.\n.TP\n.B --actor <value>\nActor name recorded in approval audit events.\n.TP\n.B --note <text>\nOptional approval or cancellation note recorded in the event payload.\n.SH EXAMPLES\n.TP\nValidate markdown workflow:\n.B wfm validate ./example-workflow.md\n.TP\nValidate json workflow:\n.B wfm validate ./example-workflow.json\n.TP\nScaffold json workflow file:\n.B wfm scaffold ./new-workflow.json --format json\n.TP\nAuthenticate with a CLI token:\n.B wfm auth login --token wm_exampletoken\n.TP\nPublish a workflow:\n.B wfm publish ./example-workflow.json --visibility public --tag example,automation\n.TP\nPull a remote workflow:\n.B wfm pull alice/remote-bunny --output ./remote-bunny.json\n.TP\nSearch the remote registry:\n.B wfm search bunny\n.TP\nRun with explicit confirmations:\n.B wfm run ./example-workflow.json --confirm discover:human,qa_gate:human\n.TP\nInspect host setup:\n.B wfm doctor\n.TP\nCheck a workflow before running it:\n.B wfm doctor ./example-workflow.json\n.TP\nInstall the bundled CLI skill for Claude Code:\n.B wfm skill install\n.TP\nInstall every bundled skill globally:\n.B wfm skill install --all --global\n.SH FILES\n.TP\n.B man/wfm.1\nThe manual page source shipped with this repository.\n.SH EXIT STATUS\n.TP\n.B 0\nSuccessful command execution.\n.TP\n.B 1\nValidation or runtime error.\n.TP\n.B 2\nRun completed in non-success terminal status.\n";
+export declare const MAN_PAGE_SOURCE = ".TH WFM 1 \"April 2026\" \"@workflow-manager/runner\" \"User Commands\"\n.SH NAME\nwfm \\- run markdown or json workflows from the CLI\n.SH SYNOPSIS\n.B wfm\n.I command\n[options]\n.SH DESCRIPTION\nwfm parses a workflow definition file, validates it, and executes\nit with deterministic in-memory orchestration.\n\nWorkflow files can be Markdown with YAML frontmatter or JSON.\n.SH COMMANDS\n.TP\n.B doctor [workflow.md|workflow.json] [--json]\nInspect host adapter setup, LLM access keys, and current adapter implementation status. When a workflow path is provided, also validate schema and runtime requirements without executing steps.\n.TP\n.B skill list\nList the agent skills bundled with the npm package.\n.TP\n.B skill install [name ...] [--agent claude|opencode] [--global] [--dir path] [--all] [--force]\nInstall bundled agent skills into an agent skill directory. Defaults to the workflow-manager-cli skill and the project-level Claude Code directory (./.claude/skills). Existing skills are not overwritten unless --force is passed.\n.TP\n.B scaffold [path] [--format markdown|json] [--template default|agent-validated]\nCreate a starter workflow file. Format defaults to markdown unless the output\npath ends in .json. Template defaults to default (the general multi-step example);\nagent-validated scaffolds a compact pipeline demonstrating first-class agent\nvalidation (validation.mode: agent with a validator agent and criteria).\n.TP\n.B validate <workflow.md|workflow.json>\nValidate workflow structure and report schema errors.\n.TP\n.B run <workflow.md|workflow.json> [--input input.json] [--objective text] [--confirm list] [--auto-confirm-all] [--port number] [--session-file path] [--verbose] [--json] [--ui]\nRun the workflow with live CLI progress and optional JSON output.\n.TP\n.B approve [--url value] [--token value] [--session-file path] [--run-id value] [--step value] [--actor value] [--note text]\nApprove the current waiting runner step through the local attach API.\n.TP\n.B resume [--url value] [--token value] [--session-file path] [--run-id value] [--step value] [--actor value] [--note text]\nAlias for approve, intended for external resume flows.\n.TP\n.B cancel [--url value] [--token value] [--session-file path] [--run-id value] [--step value] [--actor value] [--note text]\nCancel the current waiting runner step through the local attach API.\n.TP\n.B status [--url value] [--token value] [--session-file path] [--run-id value] [--step key]\nPrint the current run snapshot (or one step detail with --step) as JSON on stdout.\n.TP\n.B logs [--url value] [--token value] [--session-file path] [--run-id value] [--step key] [--limit number] [--cursor value]\nPrint buffered agent stdout/stderr chunks as JSON on stdout.\n.TP\n.B events [--url value] [--token value] [--session-file path] [--run-id value] [--since sequence] [--include-logs]\nPrint run events as JSON on stdout in a single poll (no streaming). Log events are excluded unless --include-logs is passed.\n.TP\n.B auth <login|whoami|logout> [--token value]\nManage remote registry authentication for CLI publish and pull flows.\n.TP\n.B publish <workflow.md|workflow.json> [--slug slug] [--title text] [--description text] [--visibility public|private] [--version label] [--tag a,b] [--draft]\nPublish a validated local workflow to the remote registry.\n.TP\n.B pull <owner/slug> [--version label] [--output path]\nDownload a remote workflow and write it to a local file.\n.TP\n.B search [query]\nSearch public workflows from the remote registry.\n.TP\n.B remote info <owner/slug>\nShow metadata and source information for a remote workflow.\n.TP\n.B man\nOpen this man page.\n.TP\n.B --version, -v, version\nPrint the installed wfm version and exit.\n.SH RUN OPTIONS\n.TP\n.B --input <path>\nJSON file merged into global workflow input state.\n.TP\n.B --objective <text>\nOverride the default run objective.\n.TP\n.B --confirm <stepA,stepB:human,...>\nProvide explicit confirmations for steps that require validation.\n.TP\n.B --auto-confirm-all\nBypass confirmation gating for all steps.\n.TP\n.B --port <number>\nBind the local attach API to a specific port. If omitted, the OS assigns a free port on 127.0.0.1.\n.TP\n.B --session-file <path>\nWrite attach connection details (base URL, bearer token, run id, pid, timestamps) to a JSON file with mode 0600 when the run starts, and rewrite it with endedAt and the final status when the run finishes. Attach commands (approve, resume, cancel, status, logs, events) accept the same flag to read those details back.\n.TP\n.B --verbose\nStream per-step agent output and execution updates to stderr while the workflow runs.\n.TP\n.B --json\nPrint the final run result as JSON on stdout while keeping live progress on stderr.\n.TP\n.B --ui\nFull-screen terminal UI (requires a TTY; falls back to standard output).\n.TP\nHuman approval steps in an interactive terminal show an inline review prompt so they can be approved or cancelled without a separate HTTP client.\n.TP\n.B --url <value>\nRunner attach API base URL for approve, resume, cancel, status, logs, or events commands.\n.TP\n.B --token <value>\nRunner attach API bearer token for approve, resume, cancel, status, logs, or events commands.\n.TP\n.B --run-id <value>\nRunner id to control. If omitted, the CLI reads it from /session.\n.TP\n.B --step <value>\nOptional step key when controlling a specific waiting step, or when scoping status and logs output.\n.TP\n.B --limit <number>\nMaximum number of log chunks returned by the logs command. Defaults to 200.\n.TP\n.B --cursor <value>\nPagination cursor for the logs command, taken from a previous nextCursor value.\n.TP\n.B --since <sequence>\nOnly return events with a sequence greater than this value in the events command.\n.TP\n.B --include-logs\nInclude agent.stdout and agent.stderr events in the events command output.\n.TP\n.B --actor <value>\nActor name recorded in approval audit events.\n.TP\n.B --note <text>\nOptional approval or cancellation note recorded in the event payload.\n.SH EXAMPLES\n.TP\nValidate markdown workflow:\n.B wfm validate ./example-workflow.md\n.TP\nValidate json workflow:\n.B wfm validate ./example-workflow.json\n.TP\nScaffold json workflow file:\n.B wfm scaffold ./new-workflow.json --format json\n.TP\nScaffold an agent-validated pipeline example:\n.B wfm scaffold ./agent-validated.md --template agent-validated\n.TP\nAuthenticate with a CLI token:\n.B wfm auth login --token wm_exampletoken\n.TP\nPublish a workflow:\n.B wfm publish ./example-workflow.json --visibility public --tag example,automation\n.TP\nPull a remote workflow:\n.B wfm pull alice/remote-bunny --output ./remote-bunny.json\n.TP\nSearch the remote registry:\n.B wfm search bunny\n.TP\nRun with explicit confirmations:\n.B wfm run ./example-workflow.json --confirm discover:human,qa_gate:human\n.TP\nRun with a session file for attach clients:\n.B wfm run ./example-workflow.json --session-file ./run-session.json\n.TP\nObserve and control the run through the session file:\n.B wfm status --session-file ./run-session.json && wfm approve --session-file ./run-session.json --step qa_gate\n.TP\nInspect host setup:\n.B wfm doctor\n.TP\nCheck a workflow before running it:\n.B wfm doctor ./example-workflow.json\n.TP\nInstall the bundled CLI skill for Claude Code:\n.B wfm skill install\n.TP\nInstall every bundled skill globally:\n.B wfm skill install --all --global\n.SH FILES\n.TP\n.B man/wfm.1\nThe manual page source shipped with this repository.\n.SH EXIT STATUS\n.TP\n.B 0\nSuccessful command execution.\n.TP\n.B 1\nValidation or runtime error.\n.TP\n.B 2\nRun completed in non-success terminal status.\n";

package/dist/manPage.js

@@ -21,25 +21,36 @@ List the agent skills bundled with the npm package.
 .B skill install [name ...] [--agent claude|opencode] [--global] [--dir path] [--all] [--force]
 Install bundled agent skills into an agent skill directory. Defaults to the workflow-manager-cli skill and the project-level Claude Code directory (./.claude/skills). Existing skills are not overwritten unless --force is passed.
 .TP
-.B scaffold [path] [--format markdown|json]
+.B scaffold [path] [--format markdown|json] [--template default|agent-validated]
 Create a starter workflow file. Format defaults to markdown unless the output
-path ends in .json.
+path ends in .json. Template defaults to default (the general multi-step example);
+agent-validated scaffolds a compact pipeline demonstrating first-class agent
+validation (validation.mode: agent with a validator agent and criteria).
 .TP
 .B validate <workflow.md|workflow.json>
 Validate workflow structure and report schema errors.
 .TP
-.B run <workflow.md|workflow.json> [--input input.json] [--objective text] [--confirm list] [--auto-confirm-all] [--port number] [--verbose] [--json]
+.B run <workflow.md|workflow.json> [--input input.json] [--objective text] [--confirm list] [--auto-confirm-all] [--port number] [--session-file path] [--verbose] [--json] [--ui]
 Run the workflow with live CLI progress and optional JSON output.
 .TP
-.B approve [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]
+.B approve [--url value] [--token value] [--session-file path] [--run-id value] [--step value] [--actor value] [--note text]
 Approve the current waiting runner step through the local attach API.
 .TP
-.B resume [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]
+.B resume [--url value] [--token value] [--session-file path] [--run-id value] [--step value] [--actor value] [--note text]
 Alias for approve, intended for external resume flows.
 .TP
-.B cancel [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]
+.B cancel [--url value] [--token value] [--session-file path] [--run-id value] [--step value] [--actor value] [--note text]
 Cancel the current waiting runner step through the local attach API.
 .TP
+.B status [--url value] [--token value] [--session-file path] [--run-id value] [--step key]
+Print the current run snapshot (or one step detail with --step) as JSON on stdout.
+.TP
+.B logs [--url value] [--token value] [--session-file path] [--run-id value] [--step key] [--limit number] [--cursor value]
+Print buffered agent stdout/stderr chunks as JSON on stdout.
+.TP
+.B events [--url value] [--token value] [--session-file path] [--run-id value] [--since sequence] [--include-logs]
+Print run events as JSON on stdout in a single poll (no streaming). Log events are excluded unless --include-logs is passed.
+.TP
 .B auth <login|whoami|logout> [--token value]
 Manage remote registry authentication for CLI publish and pull flows.
 .TP
@@ -77,25 +88,43 @@ Bypass confirmation gating for all steps.
 .B --port <number>
 Bind the local attach API to a specific port. If omitted, the OS assigns a free port on 127.0.0.1.
 .TP
+.B --session-file <path>
+Write attach connection details (base URL, bearer token, run id, pid, timestamps) to a JSON file with mode 0600 when the run starts, and rewrite it with endedAt and the final status when the run finishes. Attach commands (approve, resume, cancel, status, logs, events) accept the same flag to read those details back.
+.TP
 .B --verbose
 Stream per-step agent output and execution updates to stderr while the workflow runs.
 .TP
 .B --json
 Print the final run result as JSON on stdout while keeping live progress on stderr.
 .TP
+.B --ui
+Full-screen terminal UI (requires a TTY; falls back to standard output).
+.TP
 Human approval steps in an interactive terminal show an inline review prompt so they can be approved or cancelled without a separate HTTP client.
 .TP
 .B --url <value>
-Runner attach API base URL for approve, resume, or cancel commands.
+Runner attach API base URL for approve, resume, cancel, status, logs, or events commands.
 .TP
 .B --token <value>
-Runner attach API bearer token for approve, resume, or cancel commands.
+Runner attach API bearer token for approve, resume, cancel, status, logs, or events commands.
 .TP
 .B --run-id <value>
 Runner id to control. If omitted, the CLI reads it from /session.
 .TP
 .B --step <value>
-Optional step key when controlling a specific waiting step.
+Optional step key when controlling a specific waiting step, or when scoping status and logs output.
+.TP
+.B --limit <number>
+Maximum number of log chunks returned by the logs command. Defaults to 200.
+.TP
+.B --cursor <value>
+Pagination cursor for the logs command, taken from a previous nextCursor value.
+.TP
+.B --since <sequence>
+Only return events with a sequence greater than this value in the events command.
+.TP
+.B --include-logs
+Include agent.stdout and agent.stderr events in the events command output.
 .TP
 .B --actor <value>
 Actor name recorded in approval audit events.
@@ -113,6 +142,9 @@ Validate json workflow:
 Scaffold json workflow file:
 .B wfm scaffold ./new-workflow.json --format json
 .TP
+Scaffold an agent-validated pipeline example:
+.B wfm scaffold ./agent-validated.md --template agent-validated
+.TP
 Authenticate with a CLI token:
 .B wfm auth login --token wm_exampletoken
 .TP
@@ -128,6 +160,12 @@ Search the remote registry:
 Run with explicit confirmations:
 .B wfm run ./example-workflow.json --confirm discover:human,qa_gate:human
 .TP
+Run with a session file for attach clients:
+.B wfm run ./example-workflow.json --session-file ./run-session.json
+.TP
+Observe and control the run through the session file:
+.B wfm status --session-file ./run-session.json && wfm approve --session-file ./run-session.json --step qa_gate
+.TP
 Inspect host setup:
 .B wfm doctor
 .TP

package/dist/parser.js

@@ -185,9 +185,18 @@ export function validateWorkflow(def) {
             errors.push(`Unsupported adapter for ${step.key}: ${adapter}`);
         }
         const mode = step.validation?.mode ?? step.approvalSpec?.validation?.mode;
-        if (mode && !["none", "human", "external"].includes(mode)) {
+        if (mode && !["none", "human", "external", "agent"].includes(mode)) {
             errors.push(`Invalid validation mode for ${step.key}: ${mode}`);
         }
+        if (step.approvalSpec?.validation?.mode === "agent") {
+            errors.push(`Approval step ${step.key} cannot use agent validation`);
+        }
+        if (step.validation?.mode === "agent" && step.validation.agent?.adapterKey) {
+            const validatorAdapter = step.validation.agent.adapterKey;
+            if (!SUPPORTED_ADAPTERS.includes(validatorAdapter)) {
+                errors.push(`Unsupported validator adapter for ${step.key}: ${validatorAdapter}`);
+            }
+        }
     }
     const cycle = findDependencyCycle(def);
     if (cycle) {

package/dist/runFormat.d.ts

@@ -0,0 +1,11 @@
+import type { StepDefinition, StepRunStatus, WorkflowRunStatus } from "./types.js";
+export declare function isTerminalStatus(status: WorkflowRunStatus): boolean;
+export declare function formatCount(value: number, singular: string, plural: string): string;
+export declare function formatDurationMs(value: number): string;
+export declare function elapsedFrom(iso: string | null, now?: number): string;
+export declare function splitLines(value: string): {
+    lines: string[];
+    remainder: string;
+};
+export declare function describeAgentStatus(status: StepRunStatus): string;
+export declare function stepLabel(step: StepDefinition): string;

package/dist/runFormat.js

@@ -0,0 +1,56 @@
+export function isTerminalStatus(status) {
+    return status === "succeeded" || status === "failed" || status === "cancelled";
+}
+export function formatCount(value, singular, plural) {
+    return `${value} ${value === 1 ? singular : plural}`;
+}
+export function formatDurationMs(value) {
+    if (!Number.isFinite(value) || value < 0) {
+        return "0s";
+    }
+    if (value < 1000) {
+        return `${Math.max(0, Math.round(value))}ms`;
+    }
+    const seconds = value / 1000;
+    if (seconds < 60) {
+        return `${seconds.toFixed(seconds < 10 ? 1 : 0)}s`;
+    }
+    const minutes = Math.floor(seconds / 60);
+    const remainingSeconds = Math.round(seconds % 60);
+    return `${minutes}m ${remainingSeconds}s`;
+}
+export function elapsedFrom(iso, now = Date.now()) {
+    if (!iso) {
+        return "0s";
+    }
+    const startedAt = Date.parse(iso);
+    if (Number.isNaN(startedAt)) {
+        return "0s";
+    }
+    return formatDurationMs(now - startedAt);
+}
+export function splitLines(value) {
+    const normalized = value.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+    const parts = normalized.split("\n");
+    const remainder = parts.pop() ?? "";
+    return { lines: parts, remainder };
+}
+export function describeAgentStatus(status) {
+    switch (status) {
+        case "running":
+            return "started";
+        case "succeeded":
+            return "succeeded";
+        case "failed":
+            return "failed";
+        case "waiting_for_approval":
+            return "waiting for approval";
+        case "cancelled":
+            return "cancelled";
+        default:
+            return status.replace(/_/g, " ");
+    }
+}
+export function stepLabel(step) {
+    return step.title ?? step.objective ?? step.key;
+}

package/dist/runnerApi.js

@@ -136,6 +136,20 @@ export async function startRunnerApiServer(store, requestedPort) {
                 });
                 return;
             }
+            const eventsListMatch = pathname.match(/^\/runs\/([^/]+)\/events\/list$/);
+            if (method === "GET" && eventsListMatch) {
+                const runId = decodeURIComponent(eventsListMatch[1] ?? "");
+                if (!store.isKnownRun(runId)) {
+                    errorResponse(res, 404, "not_found", `Unknown run: ${runId}`);
+                    return;
+                }
+                const sinceSequence = Number.parseInt(url.searchParams.get("sinceSequence") ?? "0", 10) || undefined;
+                const includeLogs = parseBoolean(url.searchParams.get("includeLogs"), true);
+                const items = store.events(sinceSequence, includeLogs);
+                const nextSequence = items.reduce((max, event) => Math.max(max, event.sequence), sinceSequence ?? 0);
+                jsonResponse(res, 200, { items, nextSequence });
+                return;
+            }
             const eventsMatch = pathname.match(/^\/runs\/([^/]+)\/events$/);
             if (method === "GET" && eventsMatch) {
                 const runId = decodeURIComponent(eventsMatch[1] ?? "");

package/dist/sessionFile.d.ts

@@ -0,0 +1,11 @@
+export interface RunnerSessionFile {
+    baseUrl: string;
+    attachToken: string;
+    runId: string;
+    pid: number;
+    startedAt: string;
+    endedAt?: string;
+    status?: string;
+}
+export declare function writeSessionFile(filePath: string, session: RunnerSessionFile): void;
+export declare function readSessionFile(filePath: string): RunnerSessionFile | string;

package/dist/sessionFile.js

@@ -0,0 +1,61 @@
+import fs from "node:fs";
+import path from "node:path";
+export function writeSessionFile(filePath, session) {
+    const resolvedPath = path.resolve(filePath);
+    fs.mkdirSync(path.dirname(resolvedPath), { recursive: true });
+    fs.writeFileSync(resolvedPath, `${JSON.stringify(session, null, 2)}\n`, {
+        encoding: "utf-8",
+        mode: 0o600,
+    });
+    // writeFileSync only applies the mode on creation; enforce it on rewrites too.
+    fs.chmodSync(resolvedPath, 0o600);
+}
+export function readSessionFile(filePath) {
+    const resolvedPath = path.resolve(filePath);
+    let raw;
+    try {
+        raw = fs.readFileSync(resolvedPath, "utf-8");
+    }
+    catch (error) {
+        return `Could not read session file ${resolvedPath}: ${error.message}`;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return `Session file ${resolvedPath} is not valid JSON`;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return `Session file ${resolvedPath} must contain a JSON object`;
+    }
+    const record = parsed;
+    for (const field of ["baseUrl", "attachToken", "runId", "startedAt"]) {
+        if (typeof record[field] !== "string" || record[field] === "") {
+            return `Session file ${resolvedPath} is missing required field: ${field}`;
+        }
+    }
+    if (typeof record.pid !== "number" || !Number.isInteger(record.pid)) {
+        return `Session file ${resolvedPath} is missing required field: pid`;
+    }
+    if (record.endedAt !== undefined && typeof record.endedAt !== "string") {
+        return `Session file ${resolvedPath} has an invalid endedAt field`;
+    }
+    if (record.status !== undefined && typeof record.status !== "string") {
+        return `Session file ${resolvedPath} has an invalid status field`;
+    }
+    const session = {
+        baseUrl: record.baseUrl,
+        attachToken: record.attachToken,
+        runId: record.runId,
+        pid: record.pid,
+        startedAt: record.startedAt,
+    };
+    if (typeof record.endedAt === "string") {
+        session.endedAt = record.endedAt;
+    }
+    if (typeof record.status === "string") {
+        session.status = record.status;
+    }
+    return session;
+}

package/dist/tui/ansi.d.ts

@@ -0,0 +1,23 @@
+export declare const ALT_SCREEN_ENTER = "\u001B[?1049h";
+export declare const ALT_SCREEN_LEAVE = "\u001B[?1049l";
+export declare const CURSOR_HIDE = "\u001B[?25l";
+export declare const CURSOR_SHOW = "\u001B[?25h";
+export declare const CURSOR_HOME = "\u001B[H";
+export declare const CLEAR_SCREEN = "\u001B[2J";
+export declare const CLEAR_LINE_END = "\u001B[K";
+export declare function stripAnsi(text: string): string;
+/** ANSI-aware column count (per code unit; see module comment). */
+export declare function visibleWidth(text: string): number;
+/**
+ * Truncates `text` to at most `width` visible columns, appending `ellipsis`
+ * when truncation happens. ANSI escape sequences are copied through intact
+ * (never split) and do not count toward the width. If any escape sequence
+ * was emitted before the cut, a style reset is appended so styling does not
+ * bleed past the truncated text.
+ *
+ * Invariant: visibleWidth(result) <= width. When `width` is smaller than the
+ * ellipsis itself, a slice of the ellipsis is returned to keep the invariant.
+ */
+export declare function truncateVisible(text: string, width: number, ellipsis?: string): string;
+/** Right-pads `text` with spaces up to `width` visible columns (no-op when already wider). */
+export declare function padVisible(text: string, width: number): string;

package/dist/tui/ansi.js

@@ -0,0 +1,102 @@
+// Escape-code constants and ANSI-aware string math for the TUI renderer.
+// Pure string helpers only: no I/O, no terminal capability detection.
+//
+// Width is counted per UTF-16 code unit after stripping ANSI CSI sequences.
+// Grapheme clusters and East Asian wide characters are intentionally not
+// handled (no grapheme lib); this is acceptable for the status/log text the
+// TUI renders and keeps these helpers dependency-free.
+export const ALT_SCREEN_ENTER = "\x1b[?1049h";
+export const ALT_SCREEN_LEAVE = "\x1b[?1049l";
+export const CURSOR_HIDE = "\x1b[?25l";
+export const CURSOR_SHOW = "\x1b[?25h";
+export const CURSOR_HOME = "\x1b[H";
+export const CLEAR_SCREEN = "\x1b[2J";
+export const CLEAR_LINE_END = "\x1b[K";
+const ESC = "\x1b";
+const STYLE_RESET = "\x1b[0m";
+/**
+ * Returns the length of the ANSI CSI escape sequence starting at `start`,
+ * or 0 when `start` does not begin a well-formed CSI sequence.
+ *
+ * CSI grammar: ESC `[` then parameter/intermediate bytes (0x20-0x3f)
+ * terminated by a final byte (0x40-0x7e).
+ */
+function escapeSequenceLength(text, start) {
+    if (text[start] !== ESC || text[start + 1] !== "[") {
+        return 0;
+    }
+    let index = start + 2;
+    while (index < text.length) {
+        const code = text.charCodeAt(index);
+        if (code >= 0x40 && code <= 0x7e) {
+            return index - start + 1;
+        }
+        if (code < 0x20 || code > 0x3f) {
+            return 0;
+        }
+        index += 1;
+    }
+    return 0;
+}
+export function stripAnsi(text) {
+    let out = "";
+    let index = 0;
+    while (index < text.length) {
+        const skip = escapeSequenceLength(text, index);
+        if (skip > 0) {
+            index += skip;
+            continue;
+        }
+        out += text[index];
+        index += 1;
+    }
+    return out;
+}
+/** ANSI-aware column count (per code unit; see module comment). */
+export function visibleWidth(text) {
+    return stripAnsi(text).length;
+}
+/**
+ * Truncates `text` to at most `width` visible columns, appending `ellipsis`
+ * when truncation happens. ANSI escape sequences are copied through intact
+ * (never split) and do not count toward the width. If any escape sequence
+ * was emitted before the cut, a style reset is appended so styling does not
+ * bleed past the truncated text.
+ *
+ * Invariant: visibleWidth(result) <= width. When `width` is smaller than the
+ * ellipsis itself, a slice of the ellipsis is returned to keep the invariant.
+ */
+export function truncateVisible(text, width, ellipsis = "…") {
+    if (visibleWidth(text) <= width) {
+        return text;
+    }
+    if (width <= 0) {
+        return "";
+    }
+    if (width < ellipsis.length) {
+        return ellipsis.slice(0, width);
+    }
+    const budget = width - ellipsis.length;
+    let out = "";
+    let visible = 0;
+    let sawEscape = false;
+    let index = 0;
+    while (index < text.length && visible < budget) {
+        const skip = escapeSequenceLength(text, index);
+        if (skip > 0) {
+            out += text.slice(index, index + skip);
+            sawEscape = true;
+            index += skip;
+            continue;
+        }
+        out += text[index];
+        visible += 1;
+        index += 1;
+    }
+    return out + ellipsis + (sawEscape ? STYLE_RESET : "");
+}
+/** Right-pads `text` with spaces up to `width` visible columns (no-op when already wider). */
+export function padVisible(text, width) {
+    const missing = width - visibleWidth(text);
+    return missing > 0 ? text + " ".repeat(missing) : text;
+}

package/dist/tui/layout.d.ts

@@ -0,0 +1,18 @@
+import type { RunSnapshot, StepDetailSnapshot } from "../types.js";
+import type { TuiLogStore } from "./logStore.js";
+import type { Theme } from "./theme.js";
+export interface TuiFrameState {
+    snapshot: RunSnapshot | null;
+    stepDetails: Map<string, StepDetailSnapshot>;
+    logs: TuiLogStore;
+    selectedStepKey: string | null;
+    follow: boolean;
+    attachUrl: string;
+    attachToken: string;
+    statusMessage?: string | null;
+    width: number;
+    height: number;
+    now: number;
+    theme: Theme;
+}
+export declare function renderFrame(state: TuiFrameState): string[];