@mingchuno/agent-workflows 0.2.0 → 0.4.0

package/dist/src/tui/views.js

@@ -1,7 +1,167 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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";
@@ -38,56 +198,126 @@ export function summaryLines(run, now, event) {
         ...(run.change ? [`Change request: ${run.change.url}`] : []),
     ];
 }
-export function detailLines(run, sessions, now, recoveryReason = recoveryUnavailable(run)) {
-    return [
-        `#${run.issue.number} ${run.issue.title}`,
-        `${run.outcome} · ${run.phase} · attempt ${run.attempt}`,
-        `Run: ${run.id}`,
-        `Branch: ${run.branch}`,
-        `Issue: ${run.issue.url}`,
-        `Total elapsed: ${elapsedRun(run, now)}`,
-        ...(run.executions ?? []).flatMap((execution, index) => [
+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 ${index + 1}: ${execution.id}`,
-            `${execution.outcome} · ${execution.phase} · duration ${executionDuration(execution, now)}`,
-            `Queue wait: ${duration(execution.createdAt, execution.startedAt ?? execution.finishedAt, now)}`,
-            `Started: ${execution.startedAt ?? "Not started"} · Finished: ${execution.finishedAt ?? "—"}`,
+            `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
-                ? [
-                    `Recovered from: ${execution.recoveryOf}`,
-                    `Reused: ${execution.reusedSteps?.join(", ") ?? "—"}`,
-                ]
+                ? [label("Recovery source", execution.recoveryOf)]
                 : []),
         ]),
-        "",
-        "RECOVERY",
-        recoveryReason ?? "Eligible for admission; runner checks still required",
-        "",
-        "ERROR",
-        run.error ?? "None",
-        "",
-        "VALIDATION",
-        ...(run.validation?.flatMap((check) => [
-            `${check.command} ${check.args.join(" ")} · exit ${check.exitCode} · ${duration(check.startedAt, check.finishedAt, now)}`,
-            `Log: ${check.log}`,
-        ]) ?? ["No checks recorded"]),
-        "",
-        "AGENT SESSIONS",
-        ...sessions.flatMap((session) => [
-            `${session.step} · invocation ${session.attempt} · ${session.outcome}`,
-            `Session: ${session.sessionId ?? session.sessionState}`,
-            `Duration: ${duration(session.startedAt, session.finishedAt, now)}`,
-            `Requested: ${JSON.stringify(session.requested)}`,
-            `Effective: ${JSON.stringify(session.effective)}`,
-            `Log: ${session.log}`,
+        ...(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, }) {
-    const wrapped = wrapLines(lines, width);
+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));
-    return (_jsx(Box, { flexDirection: "column", width: width, height: height, overflow: "hidden", children: wrapped.slice(start, start + height).map((line, index) => (_jsx(Box, { height: 1, flexShrink: 0, children: _jsx(Text, { wrap: "truncate", children: line || " " }) }, `${start + index}`))) }));
+    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));

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,7 +4,13 @@ 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?,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.
+`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.
+
+`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.
 
@@ -17,7 +23,9 @@ the next attempt; another request for the same task fails while that retry is
 queued or running. Replaying the same command ID returns its existing retry,
 without rechecking the checkout or emitting events. A command ID cannot identify
 retries of different runs. Retry creation, project unblocking and their events
-commit together; failure preserves the blocked state.
+commit together; failure preserves the blocked state. The rationale for separate
+run and execution identities is in
+[ADR 0003](adr/0003-run-and-execution-identity.md).
 
 ## Durable operations
 
@@ -29,7 +37,7 @@ 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 |
@@ -44,7 +52,7 @@ 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`.
+at construction using `promptBaseDirectory ?? pathBaseDirectory ?? process.cwd()`.
 
 ```ts
 await operations.invoke("report", stage, {
@@ -135,7 +143,7 @@ Caveats:
 
 ## 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.
 
@@ -150,10 +158,16 @@ Caveats:
 `Store.admitRetry` owns persisted retry admission. Runner supplies its checkout
 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.
+`retry` commands or `Runner.retry`, preserving those safety checks. The locking
+boundary is recorded in [ADR 0005](adr/0005-postgresql-persistence-boundary.md).
 
 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
@@ -171,7 +185,8 @@ markers. `Store.recoveryPlan(runId)` reports persisted eligibility and its reaso
 live safety checks happen at admission and execution. Runs without execution
 metadata remain readable and retryable, but cannot be recovered.
 
-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.
+Recovery preserves the original workflow input and completed checkpoint prefix.
+The accepted command ID identifies the new execution so uncertain dispatch can
+be reconciled after a crash. Live checks still run in the first non-replayed
+operation. See [ADR 0003](adr/0003-run-and-execution-identity.md) for the complete
+identity and recovery decision.