@mingchuno/agent-workflows 0.1.0 → 0.2.0

package/dist/src/tui/views.js

@@ -0,0 +1,97 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+import { recoveryUnavailable } from "../recovery.js";
+import { cells, colorFor, duration, elapsedRun, executionDuration, wrapLines, } from "./format.js";
+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)) {
+    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) => [
+            "",
+            `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.recoveryOf
+                ? [
+                    `Recovered from: ${execution.recoveryOf}`,
+                    `Reused: ${execution.reusedSteps?.join(", ") ?? "—"}`,
+                ]
+                : []),
+        ]),
+        "",
+        "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}`,
+            "",
+        ]),
+    ];
+}
+export function Lines({ lines, width, height, offset = 0, }) {
+    const wrapped = wrapLines(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}`))) }));
+}
+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/docs/api.md

@@ -4,9 +4,9 @@ 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?,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.
+`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.
 
@@ -36,17 +36,110 @@ commit together; failure preserves the blocked state.
 | `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`.
+
+```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.
 
 `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 +152,26 @@ 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.
+
+`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.

package/docs/configuration.md

@@ -6,7 +6,7 @@ The CLI reads `agent-workflows.json`, or `--config PATH`. Unknown properties are
 | ---------------- | --------------------------------------------------------------------------------------------------------- |
 | `id`             | Required stable letters/digits/underscore/hyphen identity; scopes records and queues                      |
 | `databaseUrlEnv` | `AGENT_WORKFLOWS_DATABASE_URL`; environment variable containing a PostgreSQL connection URL with username |
-| `stateDirectory` | `.agent-workflows`; persistent local artifact directory                                                   |
+| `stateDirectory` | `.agent-workflows`; must resolve outside every managed checkout                                                   |
 | `projects`       | Nonempty array; duplicate IDs or canonical checkout roots are rejected                                    |
 
 | Project field          | Default / meaning                                                                                   |
@@ -20,10 +20,64 @@ The CLI reads `agent-workflows.json`, or `--config PATH`. Unknown properties are
 | `gitIdentity`          | Required `name` and `email`; used by application commits                                            |
 | `validation`           | Array of `{command,args,timeoutMs}`; no shell expansion; timeout defaults to 300000 ms              |
 | `agent`                | Required default profile                                                                            |
-| `stages`               | `implementation`, `writing`, `review`; each has optional `profile`, `prompt`, `skills`, `timeoutMs` |
+| `stages`               | `implementation`, `publication`, `review`; each has optional `profile`, `prompt`, `promptFile`, `timeoutMs` |
 
 Issues are selected in ascending issue-number order within each intake scan. Deduplication persists across restarts. An explicit retry is a new numbered attempt linked through `retryOf`.
 
+## CLI environment files
+
+Select one file explicitly for any CLI command:
+
+```sh
+agent-workflows --env-file ./runner.env run
+agent-workflows --env-file ./runner.env status --json
+agent-workflows --env-file /absolute/path/runner.env monitor
+```
+
+Example `runner.env` (replace placeholders locally):
+
+```dotenv
+AGENT_WORKFLOWS_DATABASE_URL="postgresql://USER:PASSWORD@localhost/agent_workflows"
+GITHUB_TOKEN="YOUR_GITHUB_TOKEN"
+APP_MODE=development # unquoted comment
+APP_GREETING="hello # literal text"
+APP_REFERENCE='${APP_MODE}'
+```
+
+- Existing process values win, including empty strings. Empty required database
+  or hosting values still fail existing validation. Missing keys are filled from
+  the file; arbitrary application variable names are supported. `databaseUrlEnv`
+  and `hosting.tokenEnv` still select which names the runner uses.
+- Relative paths resolve from the CLI launch directory, independently of
+  `--config` and project checkouts. Absolute paths work too. No `.env` discovery
+  or multiple-file layering is performed.
+- Parsing uses Node's literal dotenv syntax: quotes and comments are supported;
+  `$NAME`, `${NAME}`, backticks and `$(command)` in values are not expanded or
+  executed. This is not shell sourcing.
+- The file is read once before the command action, database access, hosting
+  adapters or runner creation. Missing or unreadable files stop the command with
+  a nonzero exit and a path/error code, without printing file contents. Restart
+  the runner to pick up edits. Help only displays usage and does not load files.
+- The merged environment is shared across all projects in the runner. Validation,
+  Git and agent worker subprocesses inherit it. Provider runtimes may apply their
+  own environment policies to tools they launch; see [providers](providers.md).
+  No per-project environment isolation is added.
+
+Keep local environment files out of version control. Add their actual names to
+`.gitignore` (or `.git/info/exclude`), especially inside managed checkouts where
+untracked files interfere with cleanliness checks. Do not copy credentials into
+configuration, prompts or issue bodies. Existing database/hosting credential
+redaction remains in effect; arbitrary variable support does not classify every
+application value as a secret. A GitHub API token does not configure Git push
+credentials.
+
+The flag belongs to `agent-workflows`, not the separate `pnpm db:migrate` command.
+SDK callers load their own process environment before creating a runner and
+continue passing `databaseUrl` explicitly. Node startup-only settings, such as
+`NODE_EXTRA_CA_CERTS`, must be set before launching Node to affect the CLI process.
+When invoking the script directly through Node, separate Node arguments from
+application arguments: `node -- dist/src/cli.js --env-file ./runner.env status`.
+
 ## Profiles
 
 A profile has `provider`, optional `model`, optional `reasoningEffort`, and optional `context`. Each stage merges its profile over project defaults. Switching provider discards the old provider's settings, so incompatible defaults cannot leak between providers. Each invocation starts a fresh session, including repeated custom steps.
@@ -34,8 +88,86 @@ Copilot queries its SDK model catalog for explicit settings. Supported context c
 
 See [checked examples](../examples/config.ts). Model IDs in `modelOverrides` are placeholders that must be replaced with available models. No provider silently clamps or substitutes explicit options.
 
-## Prompts and skills
+## Stage prompts
+
+Omit `prompt` and `promptFile` to use the installed defaults. `init` leaves both
+out so package upgrades update default task instructions. An override replaces
+only task instructions; issue context, captured change evidence, permission rules
+and output contracts remain application-owned.
+
+### Default stage prompts
+
+Implementation:
+
+```text
+Implement the supplied issue in the current checkout. Follow repository
+instructions and existing conventions. Keep changes focused on the issue's
+requirements, and add or update tests where needed to verify the behavior.
+```
+
+Publication:
+
+```text
+Prepare a Git commit message and a pull request or merge request title and
+description for the supplied changes. Follow repository conventions. Describe
+what changed and why, summarize the recorded validation accurately, and state
+material limitations. Do not claim checks passed unless the supplied evidence
+shows they ran and passed.
+```
+
+Review:
+
+```text
+Independently review the supplied published changes against the issue's
+requirements and repository conventions. Inspect the change artifacts and
+relevant source for correctness, regressions, and missing validation. Report
+actionable findings with supporting locations where possible. State any gaps
+in inspection explicitly; do not present an incomplete review as a clean review.
+```
+
+These exact defaults are checked against the runtime source.
+
+Use either nonblank literal `prompt` text or a `promptFile` path, never both.
+Files must contain nonblank UTF-8 text. Relative paths resolve from the CLI
+configuration file's directory, independently of the launch directory; absolute
+paths are allowed. Files load once when the runner is constructed. Restart to
+apply edits. No templating, interpolation, or includes are supported. SDK callers
+supply `promptBaseDirectory` for relative paths.
+
+```json
+"stages": {
+  "implementation": {},
+  "publication": { "promptFile": "prompts/publication.md" },
+  "review": { "prompt": "Review correctness and missing regression tests." }
+}
+```
+
+`writing` is now `publication`; `skills` was removed. Both old keys are rejected
+without aliases. Configure skills in the selected agent runtime and request them
+in task text. Old invocation records and skill snapshots remain readable.
+
+Stage timeout defaults to 30 minutes, including profile validation and at most
+one format-correction attempt. Correction uses a fresh inspection-only session
+and only the remaining deadline. Provider failures, cancellation, timeout and
+workspace mutation never trigger correction. Custom text-only stages do not
+receive format correction. Credentials belong in environment variables or
+runtime authentication stores, not prompts.
+
+## Change evidence
+
+Use a `stateDirectory` outside every managed checkout. `init` chooses a sibling
+`<checkout-name>.agent-workflows` directory. Publication and review receive a
+small overview and an absolute index path, then read ordered artifact chunks.
+Publication captures staged, unstaged and untracked changes. Review captures the
+exact base and published head. Hash checks reject missing or modified evidence.
 
-`prompt` is literal stage text. `skills` contains paths to `SKILL.md` files, relative to the checkout or absolute. The runner snapshots their content and SHA-256 revision into invocation records and explicitly tells the agent to apply them. Copilot additionally receives skill directories; Codex receives explicit skill text. Automatic provider discovery is not assumed equivalent.
+Text chunks are at most 64 KiB; total text evidence, including indexes, is at most
+32 MiB per stage. Capture fails explicitly above the limit. Large indexes have
+bounded pages; binary changes contain metadata instead of encoded content.
+These are internal limits, not configurable model context limits.
 
-Stage timeout defaults to 30 minutes. Custom agent steps use the same `Stage` schema, profile resolution, snapshots, cancellation and session tracking as built-in stages. Credentials stay in environment variables/runtime authentication stores; do not place them in prompts or source files.
+Review output includes `complete` and `limitations`. Incomplete reviews preserve
+partial findings locally and block normal review publication. Prompt content,
+output contract and evidence identities are retained with each response attempt.
+Changed effective prompts, including upgraded defaults, block recovery with
+fresh-retry guidance; file edits do not change an already running instance.

package/docs/database.md

@@ -26,3 +26,10 @@ attempts. Runner's checkout/process safety check runs while that lock is held;
 command replay skips it and does not write new events.
 
 `src/db/locks.ts` contains the only application driver SQL: fixed, parameterized PostgreSQL session-lock calls, which have no Drizzle query-builder equivalent. Generated migration SQL and the frozen legacy-schema test fixture are intentional SQL artifacts. No interpolated SQL template strings are used for record access.
+
+Execution history is stored in the existing run JSON record. Publication recovery
+adds optional fields without changing SQL tables; no migration or backfill is
+required. Legacy records remain readable, but lack the evidence needed for
+recovery. Recovery admission atomically appends an execution, queues the same
+run and writes an event under the project/task locks used by retry admission.
+The persisted execution ID lets dispatch reconcile a DBOS fork across crashes.

package/docs/operations.md

@@ -13,12 +13,100 @@ All commands accept `--config PATH` before the subcommand.
 | `logs RUN [--invocation ID]`       | Local agent and validation artifacts                            |
 | `pause PROJECT` / `resume PROJECT` | Queue an intake control command                                 |
 | `stop RUN`                         | Queue cancellation; success means active local work has stopped |
+| `recover RUN`                      | Continue a failed publication step using completed checkpoints |
 | `retry RUN`                        | Queue an explicit new attempt after checkout validation         |
 | `monitor`                          | Attach an interactive terminal view                             |
 
 Control commands return a command ID and `pending`; inspect `status --json` or the monitor for success/failure. With no runner, commands stay pending. Run and monitor are separate processes. Closing the monitor never cancels work. Ctrl-C on the runner stops intake, cancels active work, waits for process termination and releases ownership. Queued issues remain durable for the next start.
 
-In the monitor, Left/Right selects a project, Up/Down a run, `[`/`]` a step/attempt event, Tab an agent invocation, `l` displays its log tail, `v` cycles validation logs, `p` pauses/resumes intake, `s` stops the selected run, `r` retries it, and `q` closes the view. Session IDs are displayed in full for terminal selection/copying. Outcomes, validation, profiles and session state use text as well as color. Noninteractive tools use `status --json` and `inspect`.
+The monitor uses a full-screen view and restores the terminal when closed.
+It refreshes persisted workflow state and open logs every 400 ms. Database
+connectivity is shown separately from command acknowledgements; it does not
+prove that a runner is alive. Requires an interactive terminal of at least
+80 columns by 24 rows. Wide terminals show run list, summary and sessions;
+compact terminals show the focused pane. Titles and identifiers are available
+in full in scrollable details. `NO_COLOR=1` disables semantic colors.
+
+| Context | Keys |
+| --- | --- |
+| Dashboard | Left/Right project; Tab/Shift+Tab pane; Up/Down selection or scroll |
+| Details | Enter opens; Up/Down or PgUp/PgDn scroll; Esc returns |
+| Progress | `[`/`]` inspect step history; End follows latest event |
+| Sessions | `a` focuses session list; Up/Down selects invocation; `l` opens log |
+| Validation | `v` opens validation logs |
+| Controls | `p` pauses/resumes intake; `s` stops; `r` retries; `c` recovers publication |
+| Monitor | `?` opens the shortcut dialog; `q` or Ctrl-C closes only the monitor |
+| Shortcut dialog | Tab/Shift+Tab or Left/Right changes category; Up/Down scrolls; Esc closes |
+| Logs | Up/Down or `j`/`k` scroll; PgUp/PgDn page; Left/Right pan long lines |
+| Logs | Home/End or `g`/`G` first/last page; `f` resumes live follow |
+| Logs | Tab selects next log; `R` toggles readable/raw presentation |
+| Search | `/` opens; Enter applies; `n`/`N` next/previous matching record |
+| Back | Esc dismisses search/help first, then returns from logs |
+
+Stop, retry and publication recovery require confirmation of the selected issue;
+The centered dialog defaults to Cancel. Tab/Shift+Tab or Left/Right switches
+between Cancel and Confirm; Enter activates the highlighted option and Esc
+cancels. Unavailable actions are omitted from the footer.
+A pending command stays pending until the runner acknowledges it, including
+while switching projects. Logs and search cannot send workflow commands.
+
+Search is literal and covers the entire selected file, not only the visible page.
+Lowercase queries ignore case; any uppercase character makes the query
+case-sensitive. Search wraps at file boundaries. Scrolling or searching pauses
+follow so arriving output does not move the view. Known agent events render as
+readable messages/tool activity; unknown events remain visible as JSON. Raw
+presentation preserves the stored text except unsafe terminal control codes.
+
+Execution duration includes eligibility, preparation and waits within one
+execution. It excludes queue waiting and gaps before publication recovery.
+Details show each execution, its queue wait and the run's total elapsed time.
+Completed execution durations freeze at their first terminal outcome. Records
+without timing evidence show an em dash. Noninteractive tools use `status --json`
+and `inspect`. See [TUI design](tui-redesign.md) for implementation boundaries.
+
+## Observability Landscape
+
+This section includes only options that run locally without a license key.
+Cloud services and tools requiring a license key are excluded. These boundaries
+apply to observability; agent and hosting providers retain their own requirements.
+
+| Option | Available information | Integration path |
+| ------ | --------------------- | ---------------- |
+| Project CLI/TUI | Run outcomes, phases, invocations, sessions and local logs | Built in: `monitor`, `status --json`, `inspect RUN`, `logs RUN` |
+| DBOS SDK CLI | Durable workflow status and step history | Connect directly to the runner's PostgreSQL database |
+| Project `Store` API | Application records and ordered events | Build a local script or dashboard using `runs`, `run`, `invocations`, `events` and `subscribe` |
+| `DBOSClient` | DBOS workflow and step records | Build a local inspector using `getWorkflow`, `listWorkflows` and `listWorkflowSteps`; close it with `destroy()` |
+
+For DBOS CLI inspection from this repository:
+
+```sh
+pnpm exec dbos workflow list --sys-db-url "$AGENT_WORKFLOWS_DATABASE_URL"
+pnpm exec dbos workflow get "<run-id>" --sys-db-url "$AGENT_WORKFLOWS_DATABASE_URL"
+pnpm exec dbos workflow steps "<run-id>" --sys-db-url "$AGENT_WORKFLOWS_DATABASE_URL"
+```
+
+Use the database URL selected by `config.databaseUrlEnv` if it differs from the
+default above. These commands use the installed SDK CLI and require no running
+Conductor service or cloud login. See the [DBOS CLI reference](https://docs.dbos.dev/typescript/reference/cli).
+
+The initial DBOS workflow ID equals the run ID. Publication recovery keeps the
+run ID and adds a new DBOS execution ID; `inspect RUN` includes execution history
+and a persisted recovery eligibility assessment. Admission performs live checks.
+Inspect both layers: the
+runner catches execution errors and persists application outcomes, so a DBOS
+`SUCCESS` can accompany an application `failed` or `blocked` outcome. DBOS step
+history does not replace the local agent/validation artifacts.
+
+A browser dashboard is an extension path, not a bundled feature. A local server
+could combine the [Store query/event API](api.md#query-and-event-interface) with
+`DBOSClient.create({ systemDatabaseUrl: databaseUrl })`, joining records by run ID.
+Neither inspector needs to launch another DBOS runtime. Keep database access on
+the server and bind a local-only dashboard to loopback. See the
+[inspection example](../examples/observe.ts) for Store lifecycle handling.
+
+Route dashboard controls through `Store.request` or the runner's public controls.
+Direct DBOS cancellation, resumption or forking bypasses application coordination
+for process termination, checkout safety and retry admission.
 
 ## Ownership and recovery
 
@@ -30,7 +118,32 @@ Startup and phase boundaries check ownership assumptions, branch/head and actual
 
 Publication effects have independent DBOS checkpoints. A task commit carries `Agent-Workflows-Run`; commit recovery checks parent and marker, push recovery checks the remote ref, request creation checks the source branch, and review publication checks stable markers. Transient publication failures use bounded retries and reconciliation. Interrupted agent stages block rather than starting another writer.
 
-After a blocked/failed task:
+## Publication recovery
+
+For the default workflow, `recover RUN` continues a run whose latest execution
+failed at `push`, `change-request`, or `review-publication`. It reuses completed
+checkpoints, keeps the branch, commit and publication markers, and gives the
+failed step three new attempts. Later steps execute normally. Each execution
+retains its outcome, error and source execution; a repeated command ID identifies
+the same recovery.
+
+Keep the original branch and commit checked out with a clean working tree.
+Recovery verifies process ownership, complete checkpoint history, local artifacts,
+remote revision, workflow version, configuration and skill contents. Environment
+credential rotation is allowed. Changed code or execution inputs require a fresh
+retry. Recovery honors project pause and never removes an existing project block.
+Checks run again inside the first step that executes, including after a crash.
+
+Use `inspect RUN` before recovery and check command outcomes afterward. Monitor
+shows execution history and the recovery restriction, if any. Eligibility based
+on persisted records is provisional until the runner finishes live checks.
+
+Agent/validation failures, cancelled or blocked runs, custom workflows, and older
+runs without recovery metadata use the existing inspection and fresh-retry path.
+Recovery does not restore checkouts or accept arbitrary restart steps. A newer
+fresh attempt supersedes recovery of the older run.
+
+After a blocked/failed task that cannot be recovered:
 
 1. Read `inspect RUN`, logs, session IDs and the local Git diff.
 2. Establish that no worker/process group is still running. If startup reports an old PID or process journal, inspect that exact process and stop it before recovery. Never remove a live owner's lease.
@@ -41,6 +154,8 @@ A failed review after publication remains a failed automation attempt, even if i
 
 ## Evidence and limits
 
+Git hooks are disabled for application-authored task commits; configure required checks as validation commands. Changed symlinks and submodules require manual handling. Checkout checks detect boundary changes but do not sandbox custom adapters or prevent unrelated local tools from writing.
+
 Validation records say exactly which command ran, when, its exit code and artifact path. No-change work skips publication. Generated commit/request text is validated and saved before Git/API writes. Logs, prompts and errors redact configured credentials and recognized secret environment values; this does not sanitize arbitrary repository content or secrets unknown to the runner.
 
 Back up both PostgreSQL and the state directory if history/artifacts matter. The checkout and runtime session stores are separate local state. Losing them cannot be repaired from DBOS checkpoints alone. Do not change a custom workflow's step order or rename projects while its runs are pending; use a new workflow version and finish or explicitly resolve existing runs first.