@mingchuno/agent-workflows 0.1.0 → 0.3.0

package/dist/src/tui/views.js

@@ -0,0 +1,327 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+import stringWidth from "string-width";
+import { recoveryUnavailable } from "../recovery.js";
+import { cells, colorFor, duration, elapsedRun, executionDuration, wrapLines, } from "./format.js";
+// The detail panel contributes four columns of border and padding.
+const detailWideBreakpoint = 136;
+const detailLabelWidth = 19;
+const hangingLabelMarker = "\u{e000}";
+const conciseErrorWidth = 120;
+const detailColumnGap = " │ ";
+function localTimestamp(value) {
+    if (!value)
+        return "not recorded";
+    const date = new Date(value);
+    if (!Number.isFinite(date.valueOf()))
+        return "unavailable";
+    return new Intl.DateTimeFormat(undefined, {
+        dateStyle: "medium",
+        timeStyle: "medium",
+    }).format(date);
+}
+function profileValue(value, key) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const candidate = value[key];
+    return typeof candidate === "string" && candidate ? candidate : undefined;
+}
+function readableProfile(value, fallbackProvider) {
+    return [
+        profileValue(value, "provider") ??
+            fallbackProvider ??
+            "provider unavailable",
+        profileValue(value, "model") ?? "model unavailable",
+        profileValue(value, "reasoningEffort") ?? "reasoning unavailable",
+    ].join(" / ");
+}
+function sameProfile(requested, effective, provider) {
+    return (readableProfile(requested, provider) ===
+        readableProfile(effective, provider));
+}
+function json(value) {
+    return JSON.stringify(value) ?? "unavailable";
+}
+function conciseError(run) {
+    const error = run.error ?? run.executions?.at(-1)?.error;
+    if (!error)
+        return run.outcome === "cancelled"
+            ? "Run was cancelled."
+            : run.outcome === "blocked"
+                ? "Run is blocked."
+                : "Run requires operator attention.";
+    const firstLine = error.split("\n", 1)[0].replace(/^Error:\s*/i, "");
+    const summary = cells(firstLine, conciseErrorWidth);
+    return cells(firstLine, conciseErrorWidth + 1) === summary
+        ? summary
+        : `${cells(firstLine, conciseErrorWidth - 1)}…`;
+}
+function label(label, value) {
+    return `${hangingLabelMarker}${label.padEnd(detailLabelWidth)}${value}`;
+}
+export function wrapDetailLines(lines, width) {
+    return lines.flatMap((line) => {
+        if (!line.startsWith(hangingLabelMarker))
+            return wrapLines([line], width);
+        const content = line.slice(hangingLabelMarker.length);
+        const prefix = content.slice(0, detailLabelWidth);
+        const value = content.slice(detailLabelWidth);
+        const wrappedValue = wrapLines([value], Math.max(1, width - detailLabelWidth));
+        return wrappedValue.map((part, index) => index === 0
+            ? `${prefix}${part}`
+            : `${" ".repeat(detailLabelWidth)}${part}`);
+    });
+}
+function validationLines(run, now) {
+    return [
+        "VALIDATION",
+        ...(run.validation?.length
+            ? run.validation.flatMap((check) => [
+                `${check.command} ${check.args.join(" ")} · exit ${check.exitCode} · ${duration(check.startedAt, check.finishedAt, now)}`,
+            ])
+            : ["not recorded"]),
+    ];
+}
+function validationSummary(run) {
+    const checks = run.validation ?? [];
+    if (!checks.length)
+        return "not recorded";
+    const successful = checks.filter((check) => check.exitCode === 0).length;
+    const failed = checks.length - successful;
+    return [
+        `${checks.length} recorded`,
+        successful ? `${successful} exit 0` : "",
+        failed ? `${failed} nonzero` : "",
+    ]
+        .filter(Boolean)
+        .join(" · ");
+}
+function sessionLines(sessions, now) {
+    return [
+        "AGENT SESSIONS",
+        ...(sessions.length
+            ? sessions.flatMap((session) => {
+                const effective = readableProfile(session.effective, session.provider);
+                const profile = sameProfile(session.requested, session.effective, session.provider)
+                    ? `Effective ${effective}`
+                    : `Requested ${readableProfile(session.requested, session.provider)} → Effective ${effective}`;
+                return [
+                    `${session.step} · invocation ${session.attempt} · ${session.outcome} · ${duration(session.startedAt, session.finishedAt, now)}`,
+                    profile,
+                ];
+            })
+            : ["not recorded"]),
+    ];
+}
+function executionLines(run, now) {
+    const executions = [...(run.executions ?? [])].reverse();
+    if (!executions.length)
+        return ["CURRENT EXECUTION", "not started"];
+    return executions.flatMap((execution, index) => {
+        const executionTime = execution.startedAt
+            ? executionDuration(execution, now).replace("—", "unavailable")
+            : "not started";
+        const queueWait = duration(execution.createdAt, execution.startedAt ?? execution.finishedAt, now);
+        const recovery = execution.recoveryOf
+            ? [
+                label("Recovery", "continued from prior execution"),
+                label("Recovery gap", duration(run.executions?.find((candidate) => candidate.id === execution.recoveryOf)?.finishedAt, execution.createdAt, now).replace("—", "unavailable")),
+                label("Reused steps", execution.reusedSteps?.length
+                    ? execution.reusedSteps.join(", ")
+                    : "none recorded"),
+            ]
+            : [];
+        const lines = index === 0
+            ? [
+                "CURRENT EXECUTION",
+                label("Outcome", execution.outcome),
+                label("Phase", execution.phase),
+                label("Execution duration", executionTime),
+                label("Queue wait", queueWait),
+                label("Created", localTimestamp(execution.createdAt)),
+                label("Started", localTimestamp(execution.startedAt)),
+                label("Finished", localTimestamp(execution.finishedAt)),
+                ...recovery,
+            ]
+            : [
+                `PRIOR EXECUTION ${executions.length - index}`,
+                `${execution.outcome} · ${execution.phase} · duration ${executionTime} · queue ${queueWait}`,
+                `${localTimestamp(execution.startedAt)} → ${localTimestamp(execution.finishedAt)}`,
+                ...recovery,
+            ];
+        return index < executions.length - 1 ? [...lines, ""] : lines;
+    });
+}
+function padToWidth(value, width) {
+    return `${value}${" ".repeat(Math.max(0, width - stringWidth(value)))}`;
+}
+function composeDetailColumns(left, right, width) {
+    const leftWidth = Math.floor((width - detailColumnGap.length) * 0.58);
+    const rightWidth = width - leftWidth - detailColumnGap.length;
+    const leftLines = wrapDetailLines(left, leftWidth);
+    const rightLines = wrapDetailLines(right, rightWidth);
+    return Array.from({ length: Math.max(leftLines.length, rightLines.length) }, (_, index) => `${padToWidth(leftLines[index] ?? "", leftWidth)}${detailColumnGap}${rightLines[index] ?? ""}`);
+}
+function stepText(event) {
+    if (!event)
+        return "No steps recorded";
+    const payload = event.payload;
+    return `${payload.name ?? "step"} · ${payload.status ?? "recorded"} · attempt ${payload.attempt ?? "—"}`;
+}
+export function summaryLines(run, now, event) {
+    return [
+        `#${run.issue.number} ${run.issue.title}`,
+        `${run.outcome.toUpperCase()} · ${run.phase}`,
+        `Attempt ${run.attempt} · Execution ${executionDuration(run.executions?.at(-1), now)}`,
+        "",
+        "PROGRESS",
+        stepText(event),
+        "",
+        "VALIDATION",
+        ...(run.validation?.map((check) => `${check.command}: exit ${check.exitCode}`) ?? ["No checks recorded"]),
+        "",
+        "NEXT ACTION",
+        ...(run.error
+            ? [
+                `Error: ${run.error.split("\n")[0]}`,
+                "Enter details for the full error and recovery evidence",
+            ]
+            : [
+                run.outcome === "running"
+                    ? "Workflow is running"
+                    : run.outcome === "queued"
+                        ? "Waiting for runner and project intake"
+                        : ["failed", "blocked", "cancelled"].includes(run.outcome)
+                            ? "Inspect details before retry or recovery"
+                            : "Workflow finished; inspect the outcome",
+            ]),
+        ...(run.change ? [`Change request: ${run.change.url}`] : []),
+    ];
+}
+export function detailLines(run, sessions, now, recoveryReason = recoveryUnavailable(run), width = 76, available = {
+    stop: false,
+    retry: false,
+    recover: false,
+}) {
+    const validation = validationSummary(run);
+    const recovery = run.outcome === "failed"
+        ? recoveryReason
+            ? "restricted"
+            : "eligible"
+        : "not applicable";
+    const attention = ["failed", "blocked", "cancelled"].includes(run.outcome)
+        ? [
+            "",
+            "ATTENTION",
+            label("Problem", conciseError(run)),
+            label("Recovery", recoveryReason ?? "Eligible; runner checks still apply"),
+            label("Action", [
+                available.recover ? "c recover" : "",
+                available.retry ? "r retry" : "",
+                available.stop ? "s stop" : "",
+            ]
+                .filter(Boolean)
+                .join(" · ") || "none available"),
+        ]
+        : [];
+    const executions = executionLines(run, now);
+    const evidence = [
+        ...validationLines(run, now),
+        "",
+        ...sessionLines(sessions, now),
+    ];
+    const evidenceArea = width >= detailWideBreakpoint
+        ? composeDetailColumns(executions, evidence, width)
+        : [...executions, "", ...evidence];
+    const executionsByRecency = [...(run.executions ?? [])].reverse();
+    const executionErrors = executionsByRecency.filter((execution) => execution.error);
+    const diagnostics = run.error || executionErrors.length
+        ? [
+            "",
+            "DIAGNOSTICS",
+            ...(run.error ? [label("Run error", run.error)] : []),
+            ...executionErrors.map((execution, index) => label(index === 0 ? "Current error" : "Prior error", execution.error)),
+        ]
+        : [];
+    const technical = [
+        "",
+        "TECHNICAL DETAILS",
+        label("Run ID", run.id),
+        label("Issue URL", run.issue.url || "unavailable"),
+        label("Checkout", run.checkout || "unavailable"),
+        label("Task key", run.taskKey),
+        label("Created ISO", run.createdAt),
+        label("Updated ISO", run.updatedAt),
+        ...(run.retryOf ? [label("Retry of", run.retryOf)] : []),
+        ...(run.base ? [label("Base revision", run.base)] : []),
+        ...(run.head ? [label("Head revision", run.head)] : []),
+        ...(run.change ? [label("Change URL", run.change.url)] : []),
+        ...executionsByRecency.flatMap((execution, index) => [
+            "",
+            `Execution ${executionsByRecency.length - index}`,
+            label("Execution ID", execution.id),
+            label("Created ISO", execution.createdAt),
+            label("Started ISO", execution.startedAt ?? "not recorded"),
+            label("Finished ISO", execution.finishedAt ?? "not recorded"),
+            ...(execution.recoveryOf
+                ? [label("Recovery source", execution.recoveryOf)]
+                : []),
+        ]),
+        ...(run.validation?.flatMap((check, index) => [
+            "",
+            `Validation ${index + 1}`,
+            label("Log path", check.log),
+            label("Started ISO", check.startedAt),
+            label("Finished ISO", check.finishedAt),
+        ]) ?? []),
+        ...sessions.flatMap((session, index) => [
+            "",
+            `Agent session ${index + 1}`,
+            label("Invocation ID", session.id),
+            label("Session ID", session.sessionId ?? session.sessionState),
+            label("Provider", session.provider),
+            label("Log path", session.log),
+            label("Started ISO", session.startedAt),
+            label("Finished ISO", session.finishedAt ?? "not recorded"),
+            label("Requested profile", json(session.requested)),
+            label("Effective profile", json(session.effective)),
+        ]),
+    ];
+    return [
+        `#${run.issue.number} ${run.issue.title}`,
+        label("Outcome", run.outcome),
+        label("Phase", run.phase),
+        label("Attempt", String(run.attempt)),
+        label("Total elapsed", elapsedRun(run, now).replace("—", "unavailable")),
+        label("Branch", run.branch || "unavailable"),
+        label("Health", `Error ${run.error || run.executions?.some((execution) => execution.error) ? "recorded" : "none"} · Validation ${validation} · Recovery ${recovery}`),
+        ...attention,
+        "",
+        ...evidenceArea,
+        ...diagnostics,
+        ...technical,
+    ];
+}
+export function Lines({ lines, width, height, offset = 0, outcome, }) {
+    const wrapped = wrapDetailLines(lines, width);
+    const start = Math.min(offset, Math.max(0, wrapped.length - height));
+    const summaryOutcomeIndex = wrapped.findIndex((line) => line.startsWith("Outcome"));
+    return (_jsx(Box, { flexDirection: "column", width: width, height: height, overflow: "hidden", children: wrapped.slice(start, start + height).map((line, index) => {
+            const absoluteIndex = start + index;
+            const divider = line.indexOf(detailColumnGap);
+            const left = divider >= 0 ? line.slice(0, divider) : line;
+            const right = divider >= 0
+                ? line.slice(divider + detailColumnGap.length)
+                : undefined;
+            const isHeading = (value) => /^[A-Z][A-Z0-9 ]+$/.test(value.trim());
+            return (_jsx(Box, { height: 1, flexShrink: 0, children: _jsxs(Text, { wrap: "truncate", color: absoluteIndex === summaryOutcomeIndex
+                        ? colorFor(outcome ?? "")
+                        : undefined, children: [_jsx(Text, { bold: isHeading(left), children: left || " " }), right !== undefined ? (_jsxs(_Fragment, { children: [_jsx(Text, { children: detailColumnGap }), _jsx(Text, { bold: isHeading(right), children: right })] })) : null] }) }, `${absoluteIndex}`));
+        }) }));
+}
+export function RunList({ runs, selected, width, height, now, }) {
+    const count = Math.max(1, Math.floor(height / 3));
+    const current = Math.max(0, runs.findIndex((run) => run.id === selected));
+    const start = Math.max(0, Math.min(current - Math.floor(count / 2), runs.length - count));
+    return (_jsx(Box, { flexDirection: "column", height: height, overflow: "hidden", children: runs.length ? (runs.slice(start, start + count).map((run) => (_jsxs(Box, { flexDirection: "column", height: 3, children: [_jsx(Text, { inverse: run.id === selected, bold: run.id === selected, wrap: "truncate", children: cells(`${run.id === selected ? ">" : " "} #${run.issue.number} ${run.issue.title}`, width) }), _jsx(Text, { color: colorFor(run.outcome), wrap: "truncate", children: cells(`  ${run.outcome} · ${run.phase} · ${executionDuration(run.executions?.at(-1), now)}`, width) }), _jsx(Text, { dimColor: true, children: cells(`  attempt ${run.attempt}`, width) })] }, run.id)))) : (_jsx(Text, { children: "No runs yet. Waiting for eligible issues." })) }));
+}

package/dist/src/workspace.js

@@ -3,6 +3,12 @@ import { access, lstat, mkdir, readFile, realpath } from "node:fs/promises";
 import { join } from "node:path";
 import { BlockedError, } from "./domain.js";
 import { command } from "./runtime/process.js";
+function fileStateDigest(content, mode) {
+    return createHash("sha256")
+        .update(content)
+        .update(String(mode))
+        .digest("hex");
+}
 export class ExistingCheckout {
     processDirectories = new Map();
     processDirectory(project) {
@@ -97,7 +103,7 @@ export class ExistingCheckout {
                 if (stat.isSymbolicLink())
                     throw new BlockedError(`Changed symlink requires manual handling: ${path}`);
                 const content = await readFile(absolute);
-                files[path] = createHash("sha256").update(content).digest("hex");
+                files[path] = fileStateDigest(content, stat.mode);
                 hash.update(path).update(content).update(String(stat.mode));
                 if (untracked.split("\0").includes(path))
                     fullDiff += `\n--- /dev/null\n+++ b/${path}\n${content.toString()}`;
@@ -125,12 +131,19 @@ export class ExistingCheckout {
     }
     async commit(project, expected, publication, runId, signal) {
         signal?.throwIfAborted();
+        const runMarkers = publication.commitMessage
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line.startsWith("Agent-Workflows-Run:"));
+        if (runMarkers.length !== 1 ||
+            runMarkers[0] !== `Agent-Workflows-Run: ${runId}`)
+            throw new BlockedError("Commit message must contain exactly one matching workflow run marker");
         const current = await this.inspect(project);
         if (current.head !== expected.head) {
             const message = await this.git(project, "log", "-1", "--format=%B");
             const parent = await this.git(project, "rev-parse", "HEAD^");
             if (parent === expected.head &&
-                message.includes(`Agent-Workflows-Run: ${runId}`) &&
+                message.trimEnd() === publication.commitMessage.trimEnd() &&
                 current.paths.length === 0) {
                 const changed = (await this.git(project, "diff", "HEAD^", "HEAD", "--no-renames", "--name-only", "-z"))
                     .split("\0")
@@ -139,7 +152,11 @@ export class ExistingCheckout {
                 if (JSON.stringify(changed) !== JSON.stringify(expected.paths))
                     throw new BlockedError("Reconciled commit has an unexpected change set");
                 for (const [path, digest] of Object.entries(expected.files)) {
-                    const actual = await readFile(join(project.checkout, path)).then((content) => createHash("sha256").update(content).digest("hex"), (error) => {
+                    const absolute = join(project.checkout, path);
+                    const actual = await Promise.all([
+                        readFile(absolute),
+                        lstat(absolute),
+                    ]).then(([content, stat]) => fileStateDigest(content, stat.mode), (error) => {
                         if (error.code === "ENOENT")
                             return null;
                         throw error;
@@ -156,15 +173,11 @@ export class ExistingCheckout {
             throw new BlockedError("No changes to commit");
         await this.runGit(project, ["add", "--", ...expected.paths], { signal });
         await this.runGit(project, [
-            "-c",
-            `user.name=${project.gitIdentity.name}`,
-            "-c",
-            `user.email=${project.gitIdentity.email}`,
             "-c",
             "core.hooksPath=/dev/null",
             "commit",
             "-m",
-            `${publication.commitMessage}\n\nAgent-Workflows-Run: ${runId}`,
+            publication.commitMessage,
         ], { signal });
         return this.git(project, "rev-parse", "HEAD");
     }

package/docs/api.md

@@ -4,9 +4,15 @@ Exports are in `src/index.ts`; the built package resolves to `dist/src/index.js`
 
 ## Runner and controls
 
-`new Runner({config,databaseUrl,hosting,agents,workspace?,workflow?,workflowVersion?})` injects hosting/agent adapters and optionally a workspace strategy or workflow. `hosting(project)` returns a host-qualified adapter. `agents` maps provider names to adapters. The default workspace uses the existing checkout. One DBOS runtime runs per Node process; one runner owns each configuration and checkout.
+`new Runner({config,databaseUrl,hosting,agents,workspace?,workflow?,workflowVersion?,pathBaseDirectory?,promptBaseDirectory?})` injects hosting/agent adapters and optionally a workspace strategy or workflow. `hosting(project)` returns a host-qualified adapter. `agents` maps provider names to adapters. The default workspace uses the existing checkout. One DBOS runtime runs per Node process; one runner owns each configuration and checkout.
 
-`start()` validates registration, acquires ownership, launches DBOS, registers concurrency-one project queues, and starts polling. `poll(projectId?)` performs an immediate scan. `pause(projectId)` stops new starts while active work continues. `resume(projectId)` refuses blocked checkouts. `stop(runId)` waits for the active invocation/process to end, or cancels queued work. `retry(runId)` requires a terminal failed/blocked/cancelled run and a clean checkout, then returns a new linked run ID. `shutdown()` stops intake, cancels and awaits active work, closes DBOS and releases ownership.
+`pathBaseDirectory` must identify an existing directory. It resolves relative
+state, checkout, and prompt-file paths once when the runner is constructed.
+Omitting it preserves current-working-directory behavior for SDK callers.
+`promptBaseDirectory` retains its narrower role and, when both are supplied,
+overrides only relative prompt files.
+
+`start()` validates registration, acquires ownership, launches DBOS, registers concurrency-one project queues, and starts polling. `poll(projectId?)` performs an immediate scan. `pause(projectId)` stops new starts while active work continues. `resume(projectId)` refuses blocked checkouts. `stop(runId)` waits for the active invocation/process to end, or cancels queued work. `retry(runId)` requires a terminal failed/blocked/cancelled run and a clean checkout, then returns a new linked run ID. `recover(runId)` returns a new execution ID for publication recovery of the same run. `shutdown()` stops intake, cancels and awaits active work, closes DBOS and releases ownership.
 
 Use `try/finally` to call `shutdown()`, including failed startup. A custom `workflowVersion` must change when its durable step order changes; finish existing work before replacing an incompatible version.
 
@@ -29,24 +35,117 @@ commit together; failure preserves the blocked state.
 | `prepare()`                              | Require clean Git state; fetch base and create unique branch                 |
 | `implement()`                            | Fresh implementation session; reject unexpected commits or branch changes    |
 | `validate()`                             | Run commands and verify unchanged diff; false means no change                |
-| `writePublication()`                     | Fresh writer session; schema-check and persist generated text                |
+| `writePublication()`                     | Validate text; finalize persisted run/co-author trailers from retained changes |
 | `commit()` / `push()`                    | Separate reconciled Git effects using the verified change set                |
 | `publish()`                              | Find existing request by branch before creating a draft                      |
 | `review()`                               | Fresh read-only reviewer; exact published diff, head and validation evidence |
 | `publishReview()`                        | Reject stale head; reconcile review marker; map valid added-line findings    |
 | `complete(outcome?)`                     | Require clean checkout and persist terminal outcome                          |
 | `step(name, operation)`                  | Custom durable operation receiving current `RunRecord`                       |
-| `invoke(name, stage, prompt, readOnly?)` | Custom agentic step with profile resolution and session history              |
+| `invoke(name, stage, task)` | Custom agentic step with profile resolution and session history              |
+
+`task` separates `defaultPrompt` from an optional `context(run)` supplier.
+Optional `readOnly`, Zod `outputContract`, and captured `evidence` control runtime
+checks. Stage overrides replace only `defaultPrompt`. Custom stages have no
+inferred built-in default; resolve file-based custom stages before invocation
+with `resolveStagePrompt(stage, defaultPrompt, baseDirectory)` if they must be
+frozen alongside startup configuration. The runner resolves built-in prompt files
+at construction using `promptBaseDirectory ?? pathBaseDirectory ?? process.cwd()`.
+
+```ts
+await operations.invoke("report", stage, {
+  defaultPrompt: "Summarize the recorded validation.",
+  context: (run) => JSON.stringify(run.validation ?? []),
+  readOnly: true,
+});
+```
+
+An output contract enables strict response validation and one format correction
+within the original deadline. Both attempts retain separate invocation/session
+records under the same durable step. The returned string is validated JSON when
+a contract is supplied. Codex output contracts must use its supported JSON-schema
+subset: every property is required; use nullable defaults for optional locations.
+Built-in review parsing accepts omitted locations and normalizes them to `null`. Interrupted calls are never automatically replayed.
 
 Put side effects inside `step`; custom effects must be idempotent or reconcile their own ambiguous results. A DBOS checkpoint does not snapshot a checkout. Returning from a custom workflow without calling a terminal operation is invalid. [Reporting workflow](../examples/custom-workflow.ts) inserts a validation report without editing provider code.
 
+## DBOS SDK direct usage
+
+A custom `workflow(operations)` runs inside the runner's registered DBOS workflow.
+It can mix predefined operations with direct SDK calls; no additional workflow
+registration or DBOS runtime is needed. In a consuming application, declare
+`@dbos-inc/dbos-sdk` as a direct dependency compatible with this package's SDK
+version, and ensure both resolve to the same runtime instance.
+
+This example adds a checkpointed health check against a local service before the
+standard workflow. The service must expose `/health` on port 8080.
+
+```ts
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import {
+  defaultWorkflow,
+  type Operations,
+} from "@mingchuno/agent-workflows";
+
+export async function customWorkflow(operations: Operations): Promise<void> {
+  await DBOS.runStep(
+    async () => {
+      const signal = AbortSignal.any([
+        operations.dependencies.signal,
+        AbortSignal.timeout(5_000),
+      ]);
+      signal.throwIfAborted();
+      const response = await fetch("http://127.0.0.1:8080/health", { signal });
+      await response.body?.cancel();
+      if (!response.ok) {
+        throw new Error(`Local service returned ${response.status}`);
+      }
+    },
+    { name: "check-local-service", retriesAllowed: false },
+  );
+
+  await defaultWorkflow(operations);
+}
+```
+
+In the [runner example](../examples/run.ts), import this function and replace its
+`workflow` and `workflowVersion` options:
+
+```ts
+workflow: customWorkflow,
+workflowVersion: "local-health-v1",
+```
+
+The successful check is checkpointed and skipped during recovery; it is not a
+fresh health check on every restart. `defaultWorkflow` supplies the normal coding
+operations and terminal outcome. See the [DBOS step API](https://docs.dbos.dev/typescript/reference/workflows-steps).
+
+Caveats:
+
+- `operations.step(name, callback)` adds cancellation and checkout checks, phase
+  updates, step events and error redaction around `DBOS.runStep`. Prefer it for
+  custom application operations. Raw steps retain DBOS history but bypass those
+  additions; pass the runner's abort signal to cancellable work, as above.
+- Keep I/O, time reads and randomness inside durable steps. Call orchestration
+  APIs such as `DBOS.sleepms` at workflow level. Do not wrap predefined operations
+  or the whole workflow inside `runStep`; each operation owns its checkpoints.
+- Disabling retries does not make external writes exactly-once. A crash after an
+  effect but before checkpointing can repeat it. Use stable idempotency keys or
+  reconcile ambiguous results. DBOS does not snapshot or restore checkout files.
+- Finish custom paths with a terminal operation such as `operations.complete()`;
+  returning while a run remains queued/running is invalid.
+- Change `workflowVersion` when durable step order changes, and finish or
+  explicitly resolve pending runs before deploying an incompatible workflow.
+- Let `Runner` own `DBOS.setConfig`, `launch` and `shutdown`. Direct SDK use inside
+  a workflow does not grant another runtime or bypass checkout ownership rules.
+
 ## Extension contracts
 
-`Workspace` separates `check`, `prepare`, `inspect`, `verify`, `commit`, `push` and `release`. `Snapshot` contains branch/head, changed paths, diff and a content fingerprint. Never implement release by discarding files. A future isolated workspace implementation can replace this interface without changing workflow composition.
+`Workspace` separates `check`, `prepare`, `inspect`, `verify`, `commit`, `push` and `release`. `Snapshot` contains branch/head, changed paths, diff and a content fingerprint. `commit` receives the already-finalized message, including attribution and run marker, and must preserve native Git identity selection. Never implement release by discarding files. A future isolated workspace implementation can replace this interface without changing workflow composition.
 
 `prepare`, `commit` and `push` receive an optional final `AbortSignal`. Custom workspaces must stop their subprocesses before settling a cancelled operation. The existing-checkout strategy journals Git processes under the Git directory; ownership acquisition rejects surviving process groups after a runner crash.
 
-`AgentAdapter.validate(profile)` returns observable effective settings. `invoke(input)` receives working directory, prompt/skills, read-only intent, abort signal, stage `timeoutMs` and session/event callbacks. The abort signal also covers cancellation and time spent validating the profile. Call `session(id)` immediately when available. Await event persistence; invocation must not settle until its work has stopped. SDK adapters enforce process-group lifecycle; custom adapters must uphold the same contract. `processFile` is available for controlled subprocess ownership.
+`AgentAdapter.validate(profile)` returns observable effective settings. `invoke(input)` receives working directory, prompt, optional application-owned `outputSchema`, read-only intent, abort signal, stage `timeoutMs` and session/event callbacks. The abort signal also covers cancellation and time spent validating the profile. Call `session(id)` immediately when available. Await event persistence; invocation must not settle until its work has stopped. SDK adapters enforce process-group lifecycle; custom adapters must uphold the same contract. `processFile` is available for controlled subprocess ownership.
 
 `HostingAdapter` provides issue pagination/revalidation, instance-qualified `identity`, change-request lookup/create, remote head, and idempotent review publication. `preflight` is optional. Reconciliation keys must be stable across response loss; providers must never infer successful publication from agent prose.
 
@@ -59,6 +158,31 @@ and process safety check, which runs under the project lock for new admissions
 only. This callback must not mutate Store records. Operator tools should use
 `retry` commands or `Runner.retry`, preserving those safety checks.
 
-Invocation records include project/run IDs, stable DBOS step ID and name, invocation ID, attempt, timestamps, requested/effective profile, provider, prompt/skill snapshots, artifact path and session state (`pending`, `available`, `unavailable`). Repeated custom steps retain separate invocations. A retry has a separate run record linked to its predecessor.
+Invocation records include project/run IDs, stable DBOS step ID and name, invocation ID, attempt, timestamps, requested/effective profile, provider, effective task prompt/source/hash, output-contract and evidence identities, artifact path and session state (`pending`, `available`, `unavailable`). Repeated custom steps retain separate invocations. A retry has a separate run record linked to its predecessor.
+
+Writable invocation before/after evidence is retained on the run. Publication
+finalization persists contributing provider identities in first-contribution
+order, independent of custom stage names. Recovery reuses that provenance and
+the finalized publication message.
+
+`request(kind,target)` queues the same `pause`, `resume`, `stop`, `retry`, or `recover` commands used by the CLI/TUI; `commands()` reports pending/success/failure. A runner must be active to execute them. `finishCommand` and record-writing methods support adapters and custom workflows; operator tools should prefer commands over direct mutation.
+
+## Publication recovery
+
+`Runner.recover(runId, commandId?)` supports failed publication steps in the
+default workflow. It validates the source execution, checkout, configuration,
+artifacts and remote state. `Store.admitRecovery` commits intent and its event
+under the same project lock as retry admission; its safety callback must not
+mutate Store records. Operator tools should use the runner or queued commands.
+
+`RunRecord.executions` contains the initial execution and recovery executions,
+including DBOS IDs, source execution, restart step, reused steps, configuration
+fingerprint and outcomes. Run IDs remain stable for invocations and publication
+markers. `Store.recoveryPlan(runId)` reports persisted eligibility and its reason;
+live safety checks happen at admission and execution. Runs without execution
+metadata remain readable and retryable, but cannot be recovered.
 
-`request(kind,target)` queues the same `pause`, `resume`, `stop`, or `retry` commands used by the CLI/TUI; `commands()` reports pending/success/failure. A runner must be active to execute them. `finishCommand` and record-writing methods support adapters and custom workflows; operator tools should prefer commands over direct mutation.
+Recovery uses DBOS forks, retaining the original workflow input and checkpoint
+prefix. The accepted command ID is the fork ID: dispatch adopts an existing fork
+after an uncertain response or crash. Copied start gates do not replace live
+checks in the first non-replayed operation. Successful prefixes cannot rerun.

package/docs/architecture.md

@@ -5,20 +5,37 @@ DBOS owns workflow execution, durable steps and concurrency-one project queues.
 - `config.ts` / `domain.ts`: validated configuration, vocabulary and adapter contracts.
 - `runner.ts`: local ownership, intake/deduplication, DBOS lifecycle and operator controls.
 - `operations.ts`: reusable durable coding operations and the default workflow.
+- `prompts.ts` / `invocation.ts`: resolved task text, output contracts and bounded format correction.
+- `evidence.ts`: indexed, hashed change artifacts and capture limits.
+- `recovery.ts`: publication recovery eligibility, input fingerprints and live safety checks.
 - `workspace.ts`: existing-checkout Git operations and change verification.
 - `store.ts`: typed Drizzle queries for run, invocation, project, command and event records; `db/schema.ts` and `drizzle/` own the application schema and migrations.
 - `adapters/`: provider clients and isolated SDK workers.
 - `runtime/`: process groups, ownership journals and redacted logging.
-- `cli.ts` / `tui.tsx`: shared command/query interfaces.
+- `cli.ts` / `tui/`: shared command/query interfaces.
 
-Application records live in `agent_workflows`; DBOS maintains its own execution schema in the same PostgreSQL database. Large streamed agent/validation logs live under the configured state directory, referenced by records. Agent calls are never automatically retried. Publication retries reconcile external state first. Clean terminal state and terminal workflow outcome are deliberately separate.
+Application records live in `agent_workflows`; DBOS maintains its own execution schema in the same PostgreSQL database. Large streamed agent/validation logs live under the configured state directory, referenced by records. Interrupted or failed agent calls are never automatically retried. A returned response that fails its output contract may receive one fresh inspection-only format-correction attempt within the same stage deadline. Publication retries and explicit recovery reconcile external state first. Clean terminal state and terminal workflow outcome are deliberately separate.
 
 Node/PostgreSQL/Git are the only runtime infrastructure; providers require their normal local authentication. Zod, Commander, Ink/React, Drizzle/node-postgres, Pino, Octokit and Gitbeaker handle standard infrastructure. Drizzle ORM and Codex SDK are Apache-2.0; the other listed runtime libraries and Copilot SDK are MIT-licensed. Exact dependency versions are pinned by the lockfile. No custom HTTP client, CLI parser or terminal renderer is introduced.
 
 The test boundary is the public runner/workflow API using real PostgreSQL, real temporary Git repositories and controlled adapters. Separate adapter contracts exercise SDK argument/event mapping and HTTP behavior. Process-level recovery tests terminate a runner after external effects and restart it against the same state. Runtime/provider smoke calls are intentionally separate from deterministic acceptance tests.
 
-Phase 1 supports existing checkouts only. Higher per-project concurrency requires isolated workspaces and lifecycle design; changing the DBOS queue limit alone is unsafe.
+The runner supports existing checkouts only. Higher per-project concurrency requires isolated workspaces and lifecycle design; changing the DBOS queue limit alone is unsafe.
 
 ## Package boundary
 
-Keep one package while the SDK, CLI and TUI share a runtime, schema and release cycle. `src/adapters`, `src/runtime` and `src/db` provide internal boundaries without workspace packages. Split into a monorepo when a separately deployed app or independently versioned package needs its own dependencies and build. `pnpm-workspace.yaml` currently configures installation policy only.
+Keep one package while the SDK, CLI and TUI share a runtime, schema and release cycle. `src/adapters`, `src/runtime`, `src/db` and `src/tui` provide internal boundaries without workspace packages. Split into a monorepo when a separately deployed app or independently versioned package needs its own dependencies and build. `pnpm-workspace.yaml` currently configures installation policy only.
+
+## Run and execution identity
+
+A run owns the branch, commit and publication markers. Its initial DBOS execution
+uses the run ID; publication recovery forks the failed execution at its failed
+step under a new execution ID, preserving completed checkpoints and the original
+run input. Execution history stays in the run record. Fresh retry creates a new
+run and branch.
+
+Recovery admission and retry share a project lock. Admission persists the fork ID
+before dispatch so a restarted runner can adopt an existing fork. Recovery gates
+run inside the first operation that actually executes, avoiding copied pause and
+safety decisions. Recovery is limited to the default workflow's publication
+steps; interrupted agents still require manual inspection.