@mingchuno/agent-workflows 0.3.0 → 0.5.0

package/docs/api.md

@@ -12,7 +12,7 @@ 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.
+`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 using its saved issue. `retry(runId, commandId, { refreshIssue: true })` fetches and validates the current hosted issue once during admission, saving it on the new run. `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.
 
@@ -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       |
@@ -25,11 +28,44 @@ and is canonicalized before startup.
 | `pollIntervalMs`       | 30000; minimum 100                                                                                  |
 | `includeAgentCoAuthors` | `true`; append co-author trailers for providers whose writable invocations produced retained changes |
 | `validation`           | Array of `{command,args,timeoutMs}`; no shell expansion; timeout defaults to 300000 ms              |
+| `validationProfiles`   | Named, nonempty arrays of validation commands selectable by a ticket; defaults to `{}`                |
 | `agent`                | Required default profile                                                                            |
 | `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`.
 
+## Ticket-selected validation
+
+Define optional checks under a project in `validationProfiles` using the same
+command format as `validation`:
+
+```json
+{
+  "validation": [{ "command": "pnpm", "args": ["lint"] }],
+  "validationProfiles": {
+    "migration": [{ "command": "pnpm", "args": ["test:migrations"] }]
+  }
+}
+```
+
+An issue description selects one profile with a standalone fenced block:
+
+````markdown
+```agent-workflows-validation
+migration
+```
+````
+
+The runner executes the project's `validation` commands first, then the selected
+profile's commands. Without the block, only the baseline runs. The block must
+contain exactly one configured profile name (`A-Z`, `a-z`, digits, `_`, or `-`);
+duplicate, malformed, and unknown selections fail the run before checkout
+preparation or agent invocation. The issue body is saved with the run, so edits
+to the hosted issue do not change an existing run. A plain retry creates a new
+run from its recorded issue. Use `retry RUN --refresh-issue` (or `R` in the
+monitor) to snapshot the current hosted issue and its validation selection for
+the new run. Later issue edits do not change that run.
+
 Absolute configuration paths remain absolute. Effective state and checkout
 paths are normalized once during startup before safety and ownership checks, so
 a later working-directory change cannot redirect a running process. Validation
@@ -43,14 +79,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 +104,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 +130,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

@@ -10,11 +10,12 @@ All commands accept `--config PATH` before the subcommand.
 | `run [--project ID ...]`           | Start selected projects in the foreground                       |
 | `status [--json]`                  | Projects, runs and command outcomes                             |
 | `inspect RUN`                      | Full run and invocation/session records as JSON                 |
-| `logs RUN [--invocation ID]`       | Local agent and validation artifacts                            |
+| `logs RUN [--invocation ID]`       | Local stage, 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         |
+| `retry RUN --refresh-issue`        | Queue a new attempt using the current hosted issue              |
 | `monitor [--notify]`               | Attach an interactive terminal view; optionally alert on outcomes |
 
 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.
@@ -57,7 +58,7 @@ fallback. An overflowing document shows its visible line range in the heading.
 | 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; `l` opens the latest current-execution session, preferring a running session |
+| Details | Enter opens; Up/Down or PgUp/PgDn scroll; Esc returns; `l` opens the latest current-execution session, or the stage diagnostic before a session exists |
 | 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 |
@@ -93,7 +94,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 +122,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
 
@@ -184,7 +177,7 @@ 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.
 3. Preserve unfinished work on a developer-owned commit/branch or move it to a safe location. Resolve merge/rebase state yourself. Do not rely on DBOS to restore files.
-4. Once the checkout is clean, request `retry RUN`. This creates a new attempt and branch from the configured base, keeping the old run and files/commits inspectable.
+4. Once the checkout is clean, request `retry RUN`. This creates a new attempt and branch from the configured base, keeping the old run and files/commits inspectable. Use `retry RUN --refresh-issue` to capture the current hosted issue description and validation selection in the new run. The hosted issue must retain its identity, be open, and have the required labels; its selected validation profile must be configured.
 
 A failed review after publication remains a failed automation attempt, even if its draft request exists. Explicit retry starts the full workflow as a new attempt; it does not silently modify the old request. Human review/merging remains separate. A stale review never claims coverage of a changed remote head.
 

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.5.0",
   "description": "Local durable coding workflows on DBOS",
   "type": "module",
   "license": "MIT",

package/dist/src/tui/actions.d.ts

@@ -1,16 +0,0 @@
-import type { RunRecord } from "../domain.js";
-import type { ProjectState } from "../store.js";
-/** Display eligibility only; the runner still validates command admission. */
-export declare function actionAvailability({ run, project, projectRuns, pending, }: {
-    run?: RunRecord;
-    project?: ProjectState;
-    projectRuns: RunRecord[];
-    pending: boolean;
-}): {
-    recoveryReason: string | undefined;
-    available: {
-        stop: boolean;
-        retry: boolean;
-        recover: boolean;
-    };
-};

package/dist/src/tui/actions.js

@@ -1,23 +0,0 @@
-import { recoveryUnavailable } from "../recovery.js";
-/** Display eligibility only; the runner still validates command admission. */
-export function actionAvailability({ run, project, projectRuns, pending, }) {
-    const recoveryReason = run
-        ? (recoveryUnavailable(run) ??
-            project?.blocked ??
-            (projectRuns.some((item) => item.taskKey === run.taskKey && item.attempt > run.attempt)
-                ? "A newer attempt has superseded this run"
-                : undefined))
-        : undefined;
-    return {
-        recoveryReason,
-        available: {
-            stop: Boolean(run && !pending && ["queued", "running"].includes(run.outcome)),
-            retry: Boolean(run &&
-                !pending &&
-                ["failed", "blocked", "cancelled"].includes(run.outcome) &&
-                !projectRuns.some((item) => item.taskKey === run.taskKey &&
-                    ["queued", "running"].includes(item.outcome))),
-            recover: Boolean(run && !pending && !recoveryReason),
-        },
-    };
-}

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.