@mingchuno/agent-workflows 0.1.0 → 0.3.0

package/docs/configuration.md

@@ -1,29 +1,100 @@
 # 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`; persistent local artifact directory                                                   |
+| `stateDirectory` | `.agent-workflows`; relative to the configuration base and outside every managed checkout                    |
 | `projects`       | Nonempty array; duplicate IDs or canonical checkout roots are rejected                                    |
 
 | 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`, `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`.
 
+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:
+
+```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 +105,110 @@ 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 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": {
+  "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.
+
+## 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
+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,129 @@ 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                             |
+| `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.
 
-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.
+
+`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; `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 |
+| 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 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
+
+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
 
@@ -28,9 +145,41 @@ Git process journals live in `<git-directory>/agent-workflows-processes/`, indep
 
 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.
-
-After a blocked/failed task:
+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 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 +190,12 @@ 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.
+
+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

@@ -6,7 +6,7 @@ Authenticate the selected local agent runtime before starting. Codex SDK uses th
 
 | Capability                                  | Codex                                                                | Copilot                                                           |
 | ------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------- |
-| Implementation, writing, independent review | SDK fresh thread                                                     | SDK fresh session                                                 |
+| Implementation, publication, independent review | SDK fresh thread                                                     | SDK fresh session                                                 |
 | Explicit model/effort validation            | Runtime model cache or injected catalog                              | SDK model catalog or injected catalog                             |
 | Runtime context controls                    | Rejected                                                             | Compaction/exhaustion utilization fractions                       |
 | Structured publication/review               | Application JSON schema validation                                   | Application JSON schema validation                                |
@@ -19,9 +19,48 @@ Codex implementation uses its workspace-write sandbox. Copilot implementation ap
 
 The runner deliberately does not automatically resume interrupted agent work. Runtime session existence does not establish whether old processes are still writing. Use runtime-specific tools/SDKs to inspect sessions after stopping the runner and establishing ownership; there is no universal session-opening command.
 
+## Environment inheritance
+
+CLI `--env-file` 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
+SDK-specific adjustments such as removing `NODE_DEBUG`.
+
+Commands launched inside a provider remain subject to its runtime configuration.
+For example, Codex's [shell environment policy](https://developers.openai.com/codex/config-advanced/#shell-environment-policy)
+can filter or replace inherited values. The CLI does not override these policies
+or inject environment values into an already-running remote Copilot runtime.
+Controlled executable tests cover the SDK worker boundary; live model-driven
+shell-tool inheritance requires the explicit smoke verification below.
+
 ## GitHub
 
-Set `hosting.origin` to `https://github.com` or the GitHub Enterprise web origin. Repository is `owner/name`; the adapter derives the REST endpoint. `tokenEnv` names the environment variable holding a token authorized to read issues and create change requests/reviews. Git push uses the checkout's configured remote and Git credentials, independently of the API token. Do not embed credentials in remote URLs.
+Set `hosting.origin` to `https://github.com` or the GitHub Enterprise web origin. Repository is `owner/name`; the adapter derives the REST endpoint. `hosting.tokenEnv` names the environment variable holding the API token, for example `GITHUB_TOKEN`.
+
+### Create a fine-grained personal access token
+
+In GitHub **Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token**:
+
+1. Set an expiration and choose the repository's user or organization as **Resource owner**.
+2. Under **Repository access**, choose **Only select repositories** and select the configured `owner/name`, including for a public repository.
+3. Under **Repository permissions**, grant:
+
+   | Permission | Access | Used for |
+   | ---------- | ------ | -------- |
+   | Issues | Read-only | List and recheck issues for intake |
+   | Pull requests | Read and write | Find/create draft PRs, check their head, and publish reviews with inline comments |
+   | Metadata | Read-only (automatically included) | Required baseline repository access |
+
+4. Generate the token and store it through your secret manager in the variable named by `hosting.tokenEnv`. If organization approval is required, wait for approval before starting the runner; pending tokens can only read public resources.
+
+**Pull requests must be Read and write.** Reading issues or pushing a branch successfully does not establish permission to create a PR. Missing PR write access can fail the `change-request` step with `Resource not accessible by personal access token` after implementation has completed.
+
+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.
+
+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).
 
 Issue intake paginates and excludes PRs. Publications default to draft. Reviews use the exact commit ID and right-side added lines where valid; other findings appear in the summary.
 
@@ -47,3 +86,20 @@ Draft MRs use the supported `Draft:` title prefix. Revision-bound inline discuss
 ## Explicit smoke verification
 
 Real-provider smoke tests are opt-in manual runs: configure a disposable repository/issue, authenticated agent, hosting token, Git push access and validation; run one project; inspect the draft request, exact-head review and session records. This performs paid agent usage and real remote writes. The automated acceptance evidence is fixture-based, not a claim of live-provider compatibility or account access.
+
+## Structured output and evidence access
+
+Codex receives the application output schema through `runStreamed` options.
+Copilot receives generated JSON instructions; common strict validation gates both
+providers. Stage task text cannot remove those checks. Both retain their existing
+inspection permissions: Codex's read-only sandbox and Copilot's read-only
+permission handler (`approve-once` for reads, `reject` for non-read requests).
+Managed human-approval requirements remain denied. No shell permission is added
+for Copilot.
+
+Evidence indexes use absolute paths outside the checkout. Controlled tests check
+schema mapping, outside-directory reads and denied write/shell requests. The
+optional `AGENT_WORKFLOWS_LIVE_AGENTS=codex,copilot` test checks actual runtime
+file-reader access using the authenticated local providers; it is separate from
+local fixture acceptance. Missing runtime authentication is a live-test failure,
+not evidence of successful provider access.

package/docs/releases.md

@@ -2,88 +2,43 @@
 
 One public npm package, `@mingchuno/agent-workflows`, contains the SDK and
 `agent-workflows` CLI/TUI. Release Please opens a version/changelog PR from
-Conventional Commits on `main`. Review and merge that PR to create its GitHub
-release and publish to npm when enabled. The first release is `0.1.0`; fixes
-bump patch, features bump minor, and breaking changes bump minor before 1.0.
-
-## GitHub setup
-
-- Add this repository to the existing release GitHub App installation. It needs
-  Contents, Pull requests and Issues read/write. Store `RELEASE_APP_ID` and
-  `RELEASE_APP_PRIVATE_KEY` as repository Actions secrets. Tokens are scoped to
-  this repository; no webhook server is needed. App-created release PRs trigger CI.
-- Enable squash merging with the PR title and description as the commit message.
-  Protect `main` with the `check` and `commitlint` checks after their first run.
-  Preserve `!` or `BREAKING CHANGE:` when squashing breaking changes.
-- Create the `npm` environment with deployment branches restricted to `main`.
-  Required reviewers are optional: merging the release PR is the normal release
-  decision; environment reviewers would add a second publishing approval.
-- Leave the repository variable `NPM_PUBLISH_ENABLED` unset until npm setup is
-  complete. Setting it to `true` enables subsequent automatic publications.
-
-## First publication and npm setup
-
-The maintainer must control the `@mingchuno` npm scope and have account 2FA.
-The package must exist before configuring its trusted publisher.
-
-1. Merge the implementation, let Release Please open its first release PR, then
-   review and merge the proposed `0.1.0` release. Keep automated publishing disabled.
-2. In a clean checkout of tag `v0.1.0`, install the pinned tools and dependencies,
-   then verify and test the package:
-
-   ```sh
-   mise trust
-   mise install
-   mise exec -- pnpm install --frozen-lockfile
-   mise exec -- pnpm verify
-   mise exec -- pnpm pack:smoke
-   ```
-
-   The smoke test leaves `.artifacts/mingchuno-agent-workflows-0.1.0.tgz`.
-   Authenticate interactively and publish that tested tarball:
-
-   ```sh
-   mise exec -- pnpm exec npm login --registry=https://registry.npmjs.org/
-   mise exec -- pnpm exec npm publish .artifacts/mingchuno-agent-workflows-0.1.0.tgz --access public --ignore-scripts --registry=https://registry.npmjs.org/
-   ```
-
-3. In the npm package settings, add a GitHub Actions trusted publisher:
-
-   | Field | Value |
-   | --- | --- |
-   | Owner | `mingchuno` |
-   | Repository | `agent-workflows` |
-   | Workflow filename | `release.yml` |
-   | Environment | `npm` |
-   | Publication permission | Allow direct `npm publish` |
-
-4. Set GitHub repository variable `NPM_PUBLISH_ENABLED=true`. The next releasable
-   change exercises OIDC; the manual first publication does not verify it.
-
-The GitHub App manages releases; npm OIDC authenticates publication independently.
-No `NPM_TOKEN` is required. The publishing job uses a GitHub-hosted runner,
-`id-token: write`, and pinned npm 12. Public repository/package visibility enables
-automatic provenance. See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
+Conventional Commits on `main`. Merging that PR creates a GitHub release and,
+when `NPM_PUBLISH_ENABLED=true`, publishes to npm. Fixes bump patch, features
+bump minor, and breaking changes bump minor before 1.0.
+
+## Configuration
+
+- The release GitHub App needs Contents, Pull requests and Issues read/write.
+  Actions secrets `RELEASE_APP_ID` and `RELEASE_APP_PRIVATE_KEY` provide its
+  credentials. App-created release PRs trigger CI.
+- Squash commits use the PR title and description. Protect `main` with `check`
+  and `commitlint`; preserve `!` or `BREAKING CHANGE:` for breaking changes.
+- The `npm` environment restricts deployment to `main`. Environment reviewers
+  are optional; merging the release PR is the normal release decision.
+- npm trusted publishing uses GitHub Actions owner `mingchuno`, repository
+  `agent-workflows`, workflow `release.yml`, environment `npm`, and permission
+  to publish directly. It authenticates independently of the GitHub App via
+  OIDC; no `NPM_TOKEN` is required. See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
+- The repository variable `NPM_PUBLISH_ENABLED=true` enables publication.
+  Unset it or set it to `false` to pause future publishing. Inspect active runs
+  separately: they may already have evaluated the switch.
 
 ## Verification and recovery
 
-`pnpm verify` runs type checking, linting, release guard tests and the existing
-PostgreSQL-backed application tests. `pnpm pack:smoke` additionally needs registry
-access: it installs the tarball in a temporary consumer, checks SDK imports and
-TypeScript resolution, runs the CLI, and applies migrations to an isolated database.
-Both commands use disposable local PostgreSQL or `TEST_DATABASE_URL`; its role must
-be able to create test databases. Neither invokes paid agents or real hosting writes.
+The publishing job runs `pnpm verify` and `pnpm pack:smoke` at the release commit.
+The smoke test installs the tarball in a temporary consumer, checks SDK imports
+and TypeScript resolution, runs the CLI, and applies migrations to an isolated
+database. It needs registry access and the [development test prerequisites](../README.md#development-and-review).
+Neither command invokes paid agents or writes to real hosting providers.
 
-Publishing checks the tag, release SHA, package version and tested tarball integrity.
-It publishes the same tarball that passed the smoke test. Release runs are serialized
-and never cancelled by newer pushes.
+Publishing checks the tag, release SHA, package version and tested tarball
+integrity, then publishes that same tarball. Release runs are serialized and
+never cancelled by newer pushes.
 
 After a publishing failure, choose **Re-run failed jobs** on that Actions run to
-retain the release outputs and commit. An existing npm version is skipped only when
-its integrity matches; differing contents require a new version. Re-running the
-whole workflow or dispatching a new run may find no new release and skip publishing.
-If Release Please failed after creating a tag, inspect the existing release before
-recovering; never overwrite a published version or delete a release tag to retry.
-
-To pause future publishing, unset `NPM_PUBLISH_ENABLED` or set it to `false`.
-Inspect active runs separately: they may already have evaluated the switch.
+retain the release outputs and commit. An existing npm version is skipped only
+when its integrity matches; differing contents require a new version. Re-running
+the whole workflow or dispatching a new run may find no new release and skip
+publishing. If Release Please failed after creating a tag, inspect the existing
+release before recovering; never overwrite a published version or delete a
+release tag to retry.