@mingchuno/agent-workflows 0.3.0 → 0.4.0

package/README.md

@@ -52,9 +52,10 @@ agent-workflows monitor
 agent-workflows status --json
 ```
 
-Alternatively, load database, hosting and application variables from one explicit
-file: `agent-workflows --env-file ./runner.env run`. Existing shell values win,
-including empty strings. See [environment file examples and boundaries](docs/configuration.md#cli-environment-files).
+Alternatively, set `"envFile": "./runner.env"` at the top level of
+`agent-workflows.json` to load database, hosting and application variables from
+one explicit file. Existing process values win, including empty strings. See
+[environment file examples and boundaries](docs/configuration.md#cli-environment-files).
 
 The runner fetches the configured base, creates a branch, implements an eligible issue, validates it, generates publication text, commits and pushes, creates a draft PR/MR, and publishes an independent review of its exact head. It never merges. Initial use should target a repository and issue you explicitly intend to automate; running the CLI authorizes these effects and agent usage.
 
@@ -76,6 +77,24 @@ await runner.shutdown();
 
 [Custom workflow](examples/custom-workflow.ts), [complete runner](examples/run.ts), [configuration](examples/config.ts), and [inspection](examples/observe.ts) examples are type-checked with the library. The custom workflow is also exercised using controlled providers.
 
+## Documentation
+
+### Using the package
+
+- [Configuration and profiles](docs/configuration.md)
+- [Default stage prompts](docs/configuration.md#default-stage-prompts)
+- [Public SDK API and composition](docs/api.md)
+- [DBOS SDK direct usage](docs/api.md#dbos-sdk-direct-usage)
+- [Authentication and provider capabilities](docs/providers.md)
+- [CLI, TUI, observability, and recovery](docs/operations.md)
+- [Observability landscape](docs/operations.md#observability-landscape)
+
+### Maintaining the project
+
+- [Architecture decisions](docs/adr/README.md)
+- [Database maintenance](docs/database.md)
+- [Release process](docs/releases.md)
+
 ## Development and review
 
 [mise](https://mise.jdx.dev/getting-started.html) pins the development Node and pnpm versions. Activate it in your shell or prefix commands with `mise exec --`.
@@ -92,14 +111,6 @@ Use `pnpm start --help` to run the CLI from source. `pnpm build` emits the runti
 
 `pnpm test` builds the application, then starts and removes a disposable real PostgreSQL database using `initdb`, `pg_ctl`, and `createdb` on PATH. Alternatively, set `TEST_DATABASE_URL` to a disposable database whose role can create test databases. Tests use real temporary Git repositories and controlled adapters/HTTP servers; they make no paid agent calls or writes to real hosting providers.
 
-Schema changes and database upgrades: [database maintenance](docs/database.md). Biome formats and lints supported source/configuration files; Markdown and YAML are maintained manually.
-
-- [Configuration and profiles](docs/configuration.md)
-- [Default stage prompts](docs/configuration.md#default-stage-prompts)
-- [Public SDK API and composition](docs/api.md)
-- [DBOS SDK direct usage](docs/api.md#dbos-sdk-direct-usage)
-- [Authentication and provider capabilities](docs/providers.md)
-- [CLI, TUI, observability and recovery](docs/operations.md)
-- [Observability Landscape](docs/operations.md#observability-landscape)
-- [Architecture](docs/architecture.md)
-- [Releases](docs/releases.md)
+Schema changes and database upgrades: [database maintenance](docs/database.md).
+Biome formats and lints supported source/configuration files; Markdown and YAML
+are maintained manually.

package/dist/src/cli-config.d.ts

@@ -0,0 +1,2 @@
+import { type Configuration } from "./config.js";
+export declare function readCliConfiguration(path: string, resolveEnvironmentFile: (path: string) => string): Promise<Configuration>;

package/dist/src/cli-config.js

@@ -0,0 +1,35 @@
+import { readFile } from "node:fs/promises";
+import { parseEnv } from "node:util";
+import { z } from "zod";
+import { configSchema } from "./config.js";
+const cliConfigurationSchema = configSchema.extend({
+    envFile: z
+        .string()
+        .refine((path) => path.trim().length > 0, "Environment file path must be nonblank")
+        .optional(),
+});
+export async function readCliConfiguration(path, resolveEnvironmentFile) {
+    const { envFile, ...configuration } = cliConfigurationSchema.parse(JSON.parse(await readFile(path, "utf8")));
+    if (envFile !== undefined)
+        await loadEnvironmentFile(resolveEnvironmentFile(envFile));
+    return configuration;
+}
+async function loadEnvironmentFile(path) {
+    let contents;
+    try {
+        contents = await readFile(path, "utf8");
+    }
+    catch (error) {
+        throw new Error(`Cannot read environment file ${path} (${error.code ?? "read failed"})`);
+    }
+    let values;
+    try {
+        values = parseEnv(contents);
+    }
+    catch (error) {
+        throw new Error(`Cannot parse environment file ${path}`, { cause: error });
+    }
+    for (const [name, value] of Object.entries(values))
+        if (value !== undefined && process.env[name] === undefined)
+            process.env[name] = value;
+}

package/dist/src/cli.js

@@ -2,13 +2,12 @@
 import { realpathSync, statSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 import { basename, dirname, relative, resolve } from "node:path";
-import { parseEnv } from "node:util";
 import { Command } from "commander";
 import { render } from "ink";
 import React from "react";
 import { createAgents } from "./adapters/agents.js";
 import { createHosting } from "./adapters/hosting.js";
-import { configSchema } from "./config.js";
+import { readCliConfiguration } from "./cli-config.js";
 import { defaultValidationTimeoutMs } from "./defaults.js";
 import { Runner } from "./runner.js";
 import { Store } from "./store.js";
@@ -18,27 +17,9 @@ const program = new Command()
     .name("agent-workflows")
     .description("Local durable issue-to-review workflows")
     .option("-c, --config <file>", "configuration path", "agent-workflows.json")
-    .option("--config-base-directory <directory>", "base directory for paths contained in configuration")
-    .option("--env-file <path>", "load literal dotenv values; existing environment wins")
-    .hook("preAction", async () => {
-    const path = program.opts().envFile;
-    if (path === undefined)
-        return;
-    const file = resolve(launchDirectory, path);
-    let contents;
-    try {
-        contents = await readFile(file, "utf8");
-    }
-    catch (error) {
-        throw new Error(`Cannot read environment file ${file} (${error.code ?? "read failed"})`);
-    }
-    for (const [name, value] of Object.entries(parseEnv(contents))) {
-        if (process.env[name] === undefined)
-            process.env[name] = value;
-    }
-});
+    .option("--config-base-directory <directory>", "base directory for paths contained in configuration");
 async function configuration() {
-    return configSchema.parse(JSON.parse(await readFile(configPath(), "utf8")));
+    return readCliConfiguration(configPath(), (path) => resolve(configBaseDirectory(), path));
 }
 function configPath() {
     return resolve(launchDirectory, program.opts().config);
@@ -67,6 +48,9 @@ function databaseUrl(config) {
 }
 async function withStore(action) {
     const config = await configuration();
+    await withConfiguredStore(config, action);
+}
+async function withConfiguredStore(config, action) {
     const store = new Store(databaseUrl(config), config.id);
     try {
         await store.initialize();
@@ -210,9 +194,10 @@ program
     .command("monitor")
     .option("--notify", "notify when an observed execution reaches an outcome")
     .action(async (options) => {
+    const config = await configuration();
     if (!process.stdin.isTTY || !process.stdout.isTTY)
         throw new Error("Monitor requires an interactive terminal; use status --json instead");
-    await withStore(async (store) => {
+    await withConfiguredStore(config, async (store) => {
         await render(React.createElement(Monitor, {
             source: store,
             notificationWriter: options.notify

package/docs/api.md

@@ -23,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
 
@@ -156,7 +158,8 @@ 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.
 
@@ -182,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.

package/docs/configuration.md

@@ -15,6 +15,9 @@ and is canonicalized before startup.
 | `stateDirectory` | `.agent-workflows`; relative to the configuration base and outside every managed checkout                    |
 | `projects`       | Nonempty array; duplicate IDs or canonical checkout roots are rejected                                    |
 
+The JSON file also accepts optional CLI-only `envFile`; it is intentionally not
+part of the public SDK `Configuration` type.
+
 | Project field          | Default / meaning                                                                                   |
 | ---------------------- | --------------------------------------------------------------------------------------------------- |
 | `id`, `checkout`       | Required stable identity and existing Git repository root; relative to the configuration base       |
@@ -43,14 +46,17 @@ is the relative sibling `<checkout-name>.agent-workflows`.
 
 ## CLI environment files
 
-Select one file explicitly for any CLI command:
+Set the optional top-level `envFile` property to load one file for every CLI
+command that reads the configuration:
 
-```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
+```json
+"envFile": "./runner.env"
 ```
 
+Add this alongside the other top-level properties in `agent-workflows.json`.
+`envFile` is a CLI-file setting, not part of the public SDK `Configuration`.
+SDK callers continue to prepare their own process environment.
+
 Example `runner.env` (replace placeholders locally):
 
 ```dotenv
@@ -65,16 +71,19 @@ APP_REFERENCE='${APP_MODE}'
   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.
+- Relative paths resolve from the effective configuration base: the directory
+  containing the resolved configuration file, or `--config-base-directory`
+  when supplied. Absolute paths work too. Omitting `envFile` performs no `.env`
+  discovery. Multiple-file layering is not supported.
 - 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 configuration is validated before its environment file can be discovered.
+  The file is then read once before database access, hosting adapters or runner
+  creation. Missing, unreadable or invalid files stop the command with a nonzero
+  exit without printing file contents. Restart the runner to pick up edits.
+  `init` creates a configuration without `envFile`; help and `init` do not load
+  an environment file.
 - 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).
@@ -88,12 +97,13 @@ 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`.
+The setting belongs to the CLI configuration file, not the separate
+`pnpm db:migrate` command. SDK callers load their own process environment before
+creating a runner and continue passing `databaseUrl` explicitly. The setting's
+path and contents are not part of publication-recovery fingerprints, so
+credential rotation does not invalidate recovery. Node startup-only settings,
+such as `NODE_EXTRA_CA_CERTS`, must be set before launching Node to affect the
+CLI process.
 
 ## Profiles
 

package/docs/database.md

@@ -15,21 +15,5 @@ Do not edit applied migration files or use schema push against existing data. Ad
 
 The initial migration adopts the original application's identical tables using `IF NOT EXISTS`, preserving records and constraints. This supports the original schema, not arbitrary manually altered schemas; inspect and reconcile any local schema changes first.
 
-## Query boundary
-
-`Store` uses typed Drizzle inserts, updates and selects. Concurrent JSON record patches use a transaction and row lock to preserve unrelated fields. Full-scope run and invocation queries sort their JSON fields in memory; introduce typed indexed columns if history size requires database pagination.
-
-Retry admission locks the project row before checking task history, then commits
-the new run, project unblocking and admission events in one transaction. The
-project lock serializes requests even when they target different historical
-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.
+The persistence and locking rationale is recorded in
+[ADR 0005](adr/0005-postgresql-persistence-boundary.md).

package/docs/operations.md

@@ -93,7 +93,7 @@ or `unavailable`. Noninteractive tools use `status --json` and `inspect`. Run
 details keeps complete errors under Diagnostics and exact identifiers, paths,
 profiles and ISO timestamps under Technical details.
 
-## Observability Landscape
+## 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
@@ -121,38 +121,30 @@ Conductor service or cloud login. See the [DBOS CLI reference](https://docs.dbos
 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.
+Inspect both layers: the runner catches execution errors and persists application
+outcomes, so DBOS `SUCCESS` can accompany an application `failed` or `blocked`
+outcome. DBOS step history does not replace local agent or validation artifacts.
+See [ADR 0003](adr/0003-run-and-execution-identity.md) for the identity model.
 
 ## Ownership and recovery
 
-Only the runner may edit or switch managed checkouts while it is active. PostgreSQL advisory locks protect runner/configuration and checkout identities. A local Git-directory lease also prevents runners using different databases from owning the same checkout. Worker/validation process-group journals prevent reuse while old work may still run.
+Only the runner may edit or switch managed checkouts while it is active.
+PostgreSQL advisory locks, a local Git-directory lease, and worker/validation
+process journals prevent concurrent ownership and reuse while old work may still
+run. See [ADR 0002](adr/0002-existing-checkouts-and-exclusive-ownership.md) for
+the checkout and concurrency tradeoff.
 
 Git process journals live in `<git-directory>/agent-workflows-processes/`, independently of the configured state directory. A surviving Git process blocks ownership acquisition after a crash. Stop requests propagate to active fetch, staging, commit and push commands; interrupted effects still require reconciliation.
 
 Startup and phase boundaries check ownership assumptions, branch/head and actual changes. Unfinished files are never reset, cleaned, stashed or discarded automatically. Dirty files, unresolved Git operations, branch collisions, unexpected mutations and ambiguous agent recovery become inspectable blocked states. Other eligible projects continue.
 
-Publication effects have independent DBOS checkpoints. A task commit preserves
-publication trailers, carries exactly one `Agent-Workflows-Run`, and by default
-adds co-author trailers for providers with retained writable contributions.
-Commit reconciliation checks the expected parent, change set, finalized message,
-and clean checkout. 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.
+Publication effects have independent DBOS checkpoints. A task commit carries
+exactly one `Agent-Workflows-Run` marker and, by default, co-author trailers for
+providers with retained writable contributions. Commit, push, request creation,
+and review publication reconcile their durable identities before retrying an
+ambiguous effect. Interrupted agent stages block rather than starting another
+writer. See [ADR 0003](adr/0003-run-and-execution-identity.md) for the recovery
+boundary.
 
 ## Publication recovery
 

package/docs/providers.md

@@ -21,7 +21,7 @@ The runner deliberately does not automatically resume interrupted agent work. Ru
 
 ## Environment inheritance
 
-CLI `--env-file` values reach validation commands, Git subprocesses and agent
+CLI `envFile` values reach validation commands, Git subprocesses and agent
 workers through the runner's process environment. SDK callers get the same
 inheritance from their own process environment. The installed Codex SDK forwards
 that environment to its executable; Copilot uses it for its local runtime, with
@@ -58,7 +58,7 @@ In GitHub **Settings → Developer settings → Personal access tokens → Fine-
 
 Git push uses the checkout's configured remote and Git credentials independently of this API token. The API adapter does not require **Contents** permission. If you also use this PAT for HTTPS Git pushes, grant **Contents: Read and write**; pushing changes to `.github/workflows/` additionally requires **Workflows: Read and write**. Do not embed credentials in remote URLs.
 
-If access is denied, check the selected owner/repository, PR write permission, token expiration, organization approval, and the token owner's repository access. If you replace the token value, restart the runner with the updated environment; existing environment variables override `--env-file` values. An already failed run requires explicit [recovery](operations.md#ownership-and-recovery); updating permissions does not restart it.
+If access is denied, check the selected owner/repository, PR write permission, token expiration, organization approval, and the token owner's repository access. If you replace the token value, restart the runner with the updated environment; existing environment variables override configured `envFile` values. An already failed run requires explicit [recovery](operations.md#ownership-and-recovery); updating permissions does not restart it.
 
 References: GitHub's [PAT creation guide](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens), [issue permissions](https://docs.github.com/en/rest/issues/issues#list-repository-issues), [PR creation permissions](https://docs.github.com/en/rest/pulls/pulls#create-a-pull-request), and [review permissions](https://docs.github.com/en/rest/pulls/reviews#create-a-review-for-a-pull-request).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mingchuno/agent-workflows",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Local durable coding workflows on DBOS",
   "type": "module",
   "license": "MIT",

package/docs/architecture.md

@@ -1,41 +0,0 @@
-# Architecture
-
-DBOS owns workflow execution, durable steps and concurrency-one project queues. The runner only discovers candidates, dispatches durable identities and handles local operator commands. It does not introduce a workflow language or an interchangeable scheduler.
-
-- `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/`: 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. 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.
-
-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`, `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.