@mingchuno/agent-workflows 0.2.0 → 0.4.0

package/docs/configuration.md

@@ -1,39 +1,62 @@
 # Configuration
 
-The CLI reads `agent-workflows.json`, or `--config PATH`. Unknown properties are rejected by Zod. Paths are local filesystem paths; checkout paths are canonicalized before ownership is acquired. Use absolute paths when launching from different working directories.
+The CLI reads `agent-workflows.json`, or `--config PATH`. Both paths resolve from
+the launch directory. Unknown properties are rejected by Zod. Relative
+configuration-owned paths resolve from the directory containing the resolved
+configuration file, independently of where the CLI is launched. Use
+`--config-base-directory DIRECTORY` to select another base; a relative option
+value resolves from the launch directory. The base must be an existing directory
+and is canonicalized before startup.
 
 | Runner field     | Default / meaning                                                                                         |
 | ---------------- | --------------------------------------------------------------------------------------------------------- |
 | `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`; must resolve outside every managed checkout                                                   |
+| `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                                           |
+| `id`, `checkout`       | Required stable identity and existing Git repository root; relative to the configuration base       |
 | `hosting`              | `provider` (`github`/`gitlab`), web `origin`, `repository`, and `tokenEnv`; no serialized tokens    |
 | `labels`               | `['ready-for-agent']`; all labels must match                                                        |
 | `baseBranch`, `remote` | `main`, `origin`; Git remote is independent of hosting API origin                                   |
 | `branchTemplate`       | `agent/{issue}-{attempt}`; `{issue}` required; `{attempt}` and `{run}` supported                    |
 | `pollIntervalMs`       | 30000; minimum 100                                                                                  |
-| `gitIdentity`          | Required `name` and `email`; used by application commits                                            |
+| `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              |
 | `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`.
 
+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
+commands still execute in the canonical checkout; command names and arguments
+are passed unchanged and are not rebased to the configuration directory.
+
+`init` writes relative checkout and external sibling-state paths from the
+effective configuration base. It still refuses to overwrite an existing file.
+When the configuration is in the checkout root, the checkout is `.` and state
+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
@@ -48,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).
@@ -71,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
 
@@ -128,11 +155,12 @@ 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.
+Files must contain nonblank UTF-8 text. Relative paths use the same configuration
+base as state and checkout paths; 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 use `pathBaseDirectory` as
+the general base. `promptBaseDirectory`, when supplied, overrides it for prompt
+files only.
 
 ```json
 "stages": {
@@ -146,6 +174,29 @@ supply `promptBaseDirectory` for relative paths.
 without aliases. Configure skills in the selected agent runtime and request them
 in task text. Old invocation records and skill snapshots remain readable.
 
+## Git identity and agent attribution
+
+Commits use Git's native author and committer selection. The application does
+not configure, validate, snapshot, or override identity. Repository, worktree,
+global, system, and identity environment settings therefore behave as they do
+for `git commit`, including distinct author and committer identities. Missing or
+invalid identity fails at the commit operation with Git's error. The removed
+`gitIdentity` property is rejected as unknown input.
+
+Agent assistance is represented separately. With `includeAgentCoAuthors: true`,
+the finalized commit message includes each provider once, ordered by its first
+successful writable invocation that produced a retained change:
+
+- `Codex <noreply@openai.com>` (OpenAI's published implementation convention)
+- `Copilot <223556219+Copilot@users.noreply.github.com>` (GitHub's current
+  first-party convention, not a stable product API guarantee)
+
+Read-only publication/review invocations and writable invocations with no
+accepted retained change are not attributed. Existing trailers are preserved,
+matching agent trailers are deduplicated, and exactly one
+`Agent-Workflows-Run` trailer remains. Set `includeAgentCoAuthors: false` per
+project to disable injection; existing publication trailers are not removed.
+
 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

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

@@ -15,7 +15,7 @@ All commands accept `--config PATH` before the subcommand.
 | `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                             |
+| `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.
 
@@ -27,10 +27,37 @@ prove that a runner is alive. Requires an interactive terminal of at least
 compact terminals show the focused pane. Titles and identifiers are available
 in full in scrollable details. `NO_COLOR=1` disables semantic colors.
 
+`monitor --notify` emits one desktop notification when an Execution first
+reaches `completed`, `failed`, `blocked`, `cancelled`, `no-change` or
+`ineligible` during that monitor session. The initial snapshot is silent;
+later terminal Executions are detected across every visible project, including
+Executions first seen after a database reconnection. Delivery uses OSC 9 and is
+best-effort: notifications are not persisted, retried or acknowledged, and a
+terminal write failure does not affect monitoring or workflow state. Current
+iTerm2, Kitty, WezTerm and Ghostty releases are supported; other OSC 9
+implementations may work, while Windows Terminal is not supported in this
+version. Terminal permissions and settings determine whether an alert appears,
+including whether foreground alerts are suppressed.
+
+The notification payload is display-only and contains only
+`agent-workflows: <project> · <issue reference> · <outcome>`. It excludes issue
+titles, diagnostics, paths and internal Run, Execution and session identifiers.
+Under tmux, the monitor emits one layer of DCS passthrough wrapping. tmux 3.3
+and later requires `set -g allow-passthrough on`; the CLI does not change tmux
+configuration.
+
+Run details is one responsive, vertically scrollable document. It leads with
+the issue, outcome, phase, attempt, total elapsed time and branch, and adds an
+attention summary only when operator action may be required. At 140 columns
+and above, execution history appears beside validation and agent-session
+evidence; narrower terminals stack those sections in the same reading order.
+The primary design target is 160×48, with 80×24 retained as the functional
+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 |
+| Details | Enter opens; Up/Down or PgUp/PgDn scroll; Esc returns; `l` opens the latest current-execution session, preferring a running session |
 | 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 |
@@ -61,10 +88,12 @@ 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.
+without timing evidence use factual labels such as `not started`, `not recorded`
+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
@@ -92,31 +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 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.
+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
 
@@ -156,6 +184,10 @@ A failed review after publication remains a failed automation attempt, even if i
 
 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.
 
+Git chooses author and committer through its normal configuration and environment
+rules. Runner startup performs no identity preflight; missing identity fails at
+the commit step before push or hosting publication.
+
 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.

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/examples/config.ts

@@ -1,13 +1,13 @@
 import { configSchema } from "@mingchuno/agent-workflows";
 
-/** Replace paths, repository, identity and model IDs with locally available values. */
+/** Replace paths, repository and model IDs with locally available values. */
 export const configuration = configSchema.parse({
   id: "local",
-  stateDirectory: "/absolute/path/outside-the-checkout/agent-workflows-state",
+  stateDirectory: "../application.agent-workflows",
   projects: [
     {
       id: "application",
-      checkout: "/absolute/path/to/existing-checkout",
+      checkout: ".",
       hosting: {
         provider: "gitlab",
         origin: "https://git.example.com/gitlab",
@@ -17,7 +17,7 @@ export const configuration = configSchema.parse({
       labels: ["ready-for-agent"],
       baseBranch: "main",
       branchTemplate: "agent/{issue}-{attempt}",
-      gitIdentity: { name: "Workflow Agent", email: "agent@example.com" },
+      includeAgentCoAuthors: true,
       agent: { provider: "codex" },
       stages: {
         implementation: {

package/examples/run.ts

@@ -1,4 +1,5 @@
 import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
 import {
   configSchema,
   createAgents,
@@ -7,13 +8,15 @@ import {
 } from "@mingchuno/agent-workflows";
 import { reportingWorkflow } from "./custom-workflow.js";
 
+const configPath = resolve(process.argv[2] ?? "agent-workflows.json");
 const config = configSchema.parse(
-  JSON.parse(await readFile(process.argv[2] ?? "agent-workflows.json", "utf8")),
+  JSON.parse(await readFile(configPath, "utf8")),
 );
 const databaseUrl = process.env[config.databaseUrlEnv];
 if (!databaseUrl) throw new Error(`Set ${config.databaseUrlEnv}`);
 const runner = new Runner({
   config,
+  pathBaseDirectory: dirname(configPath),
   databaseUrl,
   hosting: createHosting,
   agents: createAgents(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mingchuno/agent-workflows",
-  "version": "0.2.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.