@mingchuno/agent-workflows 0.1.0 → 0.2.0

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.

package/examples/config.ts

@@ -23,7 +23,7 @@ export const configuration = configSchema.parse({
         implementation: {
           prompt: "Implement the issue and follow repository guidance.",
         },
-        writing: {
+        publication: {
           profile: { provider: "copilot" },
           prompt:
             "Write concise publication text from the diff and validation evidence.",
@@ -45,7 +45,7 @@ export const modelOverrides = {
     model: "YOUR_CODEX_MODEL",
     reasoningEffort: "high",
   },
-  writing: {
+  publication: {
     provider: "copilot" as const,
     model: "YOUR_COPILOT_MODEL",
     reasoningEffort: "low",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mingchuno/agent-workflows",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Local durable coding workflows on DBOS",
   "type": "module",
   "license": "MIT",
@@ -40,7 +40,7 @@
     "pack:smoke": "pnpm build && node scripts/test.mjs --pack-smoke",
     "release:publish": "node scripts/publish.mjs",
     "lint:pr": "node scripts/lint-pr-title.mjs",
-    "start": "tsx src/cli.ts",
+    "start": "node --import tsx -- src/cli.ts",
     "format": "biome format --write .",
     "format:check": "biome format .",
     "lint": "biome check .",
@@ -60,6 +60,8 @@
     "pg": "^8.23.0",
     "pino": "^10.3.1",
     "react": "^19.3.0",
+    "string-width": "^8.2.2",
+    "wrap-ansi": "^9.0.2",
     "zod": "^4.6.5"
   },
   "devDependencies": {

package/dist/src/tui-data.js

@@ -1,89 +0,0 @@
-import { useEffect, useState } from "react";
-export function useMonitorData(source, selection) {
-    const { projectIndex, runIndex } = selection;
-    const [projects, setProjects] = useState([]);
-    const [runs, setRuns] = useState([]);
-    const [sessions, setSessions] = useState([]), [events, setEvents] = useState([]);
-    const [message, setMessage] = useState("Connecting…"), [pending, setPending] = useState();
-    const project = projects[projectIndex];
-    const projectRuns = runs.filter((run) => run.projectId === project?.id);
-    const run = projectRuns[runIndex];
-    const selectedRunId = run?.id;
-    useEffect(() => {
-        let closed = false, busy = false;
-        const update = async () => {
-            if (busy)
-                return;
-            busy = true;
-            try {
-                const [nextProjects, nextRuns] = await Promise.all([
-                    source.projects(),
-                    source.runs(),
-                ]);
-                if (closed)
-                    return;
-                setProjects(nextProjects);
-                setRuns(nextRuns);
-                if (selectedRunId) {
-                    const [nextSessions, nextEvents] = await Promise.all([
-                        source.invocations(selectedRunId),
-                        source.events(0, selectedRunId),
-                    ]);
-                    if (closed)
-                        return;
-                    setSessions(nextSessions);
-                    setEvents(nextEvents.filter((event) => event.runId === selectedRunId));
-                }
-                else {
-                    setSessions([]);
-                    setEvents([]);
-                }
-                if (pending) {
-                    const command = (await source.commands()).find((command) => command.id === pending);
-                    if (command && command.status !== "pending") {
-                        setMessage(`${command.kind}: ${command.status}${command.error ? ` — ${command.error}` : ""}`);
-                        setPending(undefined);
-                    }
-                }
-                else
-                    setMessage((current) => current === "Connecting…" ? "Connected" : current);
-            }
-            catch (error) {
-                if (!closed)
-                    setMessage(`Connection error: ${String(error)}`);
-            }
-            finally {
-                busy = false;
-            }
-        };
-        void update();
-        const timer = setInterval(() => void update(), 400);
-        return () => {
-            closed = true;
-            clearInterval(timer);
-        };
-    }, [source, selectedRunId, pending]);
-    const action = async (kind, target) => {
-        setMessage(`${kind}: pending`);
-        setPending("submitting");
-        try {
-            setPending(await source.request(kind, target));
-        }
-        catch (error) {
-            setPending(undefined);
-            setMessage(`${kind}: failed — ${String(error)}`);
-        }
-    };
-    return {
-        projects,
-        project,
-        projectRuns,
-        run,
-        sessions,
-        events,
-        message,
-        setMessage,
-        pending,
-        action,
-    };
-}

package/dist/src/tui.d.ts

@@ -1,5 +0,0 @@
-import { type MonitorSource } from "./tui-data.js";
-export type { MonitorSource } from "./tui-data.js";
-export declare function Monitor({ source }: {
-    source: MonitorSource;
-}): import("react").JSX.Element;

package/dist/src/tui.js

@@ -1,69 +0,0 @@
-import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { readFile } from "node:fs/promises";
-import { Box, Text, useApp, useInput } from "ink";
-import { useState } from "react";
-import { useMonitorData } from "./tui-data.js";
-export function Monitor({ source }) {
-    const { exit } = useApp();
-    const [projectIndex, setProjectIndex] = useState(0), [runIndex, setRunIndex] = useState(0), [sessionIndex, setSessionIndex] = useState(0), [stepIndex, setStepIndex] = useState(0), [validationIndex, setValidationIndex] = useState(0);
-    const { projects, project, projectRuns, run, sessions, events, message, setMessage, pending, action, } = useMonitorData(source, { projectIndex, runIndex });
-    const [log, setLog] = useState("");
-    const session = sessions[sessionIndex];
-    const steps = events.filter((event) => event.kind === "step");
-    const selectedStep = steps[stepIndex];
-    const showLog = (path) => {
-        void readFile(path, "utf8").then((text) => setLog(text.split("\n").slice(-8).join("\n")), (error) => setMessage(`Log unavailable: ${String(error)}`));
-    };
-    useInput((input, key) => {
-        if (input === "q") {
-            exit();
-            return;
-        }
-        if (key.leftArrow || key.rightArrow) {
-            setProjectIndex((index) => Math.max(0, Math.min(projects.length - 1, index + (key.rightArrow ? 1 : -1))));
-            setRunIndex(0);
-            setSessionIndex(0);
-            setStepIndex(0);
-            setValidationIndex(0);
-            setLog("");
-        }
-        if (key.upArrow || key.downArrow) {
-            setRunIndex((index) => Math.max(0, Math.min(projectRuns.length - 1, index + (key.downArrow ? 1 : -1))));
-            setSessionIndex(0);
-            setStepIndex(0);
-            setValidationIndex(0);
-            setLog("");
-        }
-        if (key.tab) {
-            setSessionIndex((index) => (index + 1) % Math.max(sessions.length, 1));
-            setLog("");
-        }
-        if (input === "l" && session)
-            showLog(session.log);
-        if (input === "[" || input === "]")
-            setStepIndex((index) => Math.max(0, Math.min(steps.length - 1, index + (input === "]" ? 1 : -1))));
-        if (input === "v" && run?.validation?.length) {
-            const check = run.validation[validationIndex % run.validation.length];
-            setMessage(`Validation: ${check.command} · exit ${check.exitCode}`);
-            showLog(check.log);
-            setValidationIndex((index) => index + 1);
-        }
-        if (pending)
-            return;
-        if (input === "p" && project)
-            void action(project.paused ? "resume" : "pause", project.id);
-        if (input === "s" && run)
-            void action("stop", run.id);
-        if (input === "r" && run)
-            void action("retry", run.id);
-    });
-    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsx(Text, { bold: true, children: "Agent Workflows \u00B7 Monitor" }), _jsx(Text, { children: "\u2190 \u2192 project \u00B7 \u2191 \u2193 run \u00B7 [ ] step/attempt \u00B7 Tab session \u00B7 l agent log \u00B7 v validation log \u00B7 p pause/resume \u00B7 s stop \u00B7 r retry \u00B7 q close" }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: project
-                            ? `${project.id} · ${project.paused ? "intake paused" : "intake enabled"} · ${projectRuns.filter((run) => run.outcome === "queued").length} queued`
-                            : "No projects registered. Start the runner to populate this view." }), project?.blocked && (_jsxs(Text, { color: "yellow", children: ["Blocked: ", project.blocked] })), projectRuns
-                        .slice(Math.max(0, runIndex - 1), runIndex + 2)
-                        .map((item) => (_jsxs(Text, { inverse: item.id === run?.id, children: [item.id === run?.id ? ">" : " ", " #", item.issue.number, " \u00B7 attempt", " ", item.attempt, " \u00B7 ", item.outcome, " \u00B7 ", item.phase] }, item.id))), project && projectRuns.length === 0 && (_jsx(Text, { children: "No runs yet. Eligible issues appear after polling." }))] }), run && (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Text, { bold: true, children: ["Run ", run.id] }), _jsx(Text, { children: run.issue.title }), run.error && _jsx(Text, { color: "red", children: run.error }), _jsxs(Text, { children: ["Validation:", " ", run.validation
-                                ?.map((check) => `${check.command}: exit ${check.exitCode}`)
-                                .join(" · ") || "No checks recorded"] }), _jsxs(Text, { children: ["Step/attempt event ", steps.length ? stepIndex + 1 : 0, "/", steps.length, ":", " ", selectedStep
-                                ? JSON.stringify(selectedStep.payload)
-                                : "No steps recorded"] }), _jsxs(Text, { bold: true, children: ["Agent sessions \u00B7 ", sessions.length] }), session ? (_jsxs(_Fragment, { children: [_jsxs(Text, { children: [session.step, " \u00B7 invocation ", session.attempt, " \u00B7", " ", session.outcome] }), _jsxs(Text, { children: ["Session: ", session.sessionId ?? session.sessionState] }), _jsxs(Text, { children: ["Requested: ", JSON.stringify(session.requested)] }), _jsxs(Text, { children: ["Effective: ", JSON.stringify(session.effective)] }), _jsxs(Text, { children: ["Log: ", session.log] })] })) : (_jsx(Text, { children: "No agent sessions recorded" })), log && _jsx(Text, { children: log })] })), _jsx(Box, { marginTop: 1, children: _jsx(Text, { children: message }) }), _jsx(Text, { dimColor: true, children: "Closing this monitor leaves the runner and its tasks running." })] }));
-}

package/docs/acceptance.md

@@ -1,35 +0,0 @@
-# Phase 1 review guide
-
-Implementation scope is the unchanged [specification in issue #1](https://github.com/mingchuno/agent-workflows/issues/1). Review the public contracts first, then the workspace/recovery boundaries. No task-specific worktrees, clones, merges or automatic review/fix loops are implemented.
-
-| Acceptance area                                                     | Implementation / behavioral evidence                                                                                                                                  |
-| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Existing checkout, clean startup, branch policy and base transition | `ExistingCheckout`; real Git tests cover dirty files, collisions, unresolved Git operations, mutation detection and next-task base                                    |
-| Durable default workflow and extension                              | `Operations`, `defaultWorkflow`; PostgreSQL runner tests and the executable reporting-workflow example                                                                |
-| Deduplication, one task/project, independent progress               | Instance-qualified task keys, DBOS concurrency-one queues; all four agent/host combinations and multi-project tests                                                   |
-| GitHub/GitLab intake and publication                                | Octokit/Gitbeaker contracts; pagination, PR exclusion, label queries, custom GitLab root/credentials, draft MR and inline review fixtures                             |
-| Agent profiles, SDKs, prompts and sessions                          | Isolated SDK workers; profile/default isolation, supported-setting rejection, SDK argument/event contracts and invocation records                                     |
-| Validation and generated publication                                | Actual Git diff/fingerprints, schema-checked text; failed validation, malformed text, no-change and timeout tests                                                     |
-| Recovery and external effects                                       | Process-level interruptions after edits, commit, push, request creation and review publication; blocked ambiguous agent recovery and no duplicate publication effects |
-| Cancellation and ownership                                          | Real stubborn child process, journals, local leases, advisory locks; cancellation/reuse and duplicate-owner tests                                                     |
-| Independent exact-revision review                                   | Fresh sessions, published diff/head context, added-line mapping and stale-head rejection                                                                              |
-| Public observability and controls                                   | Store query/subscription, retained sessions, timestamps, artifacts, credential redaction, CLI JSON and explicit retries                                               |
-| CLI/TUI                                                             | Init/error/help tests; keyboard step/session navigation, live state and action feedback; controls share application commands                                          |
-| SDK documentation                                                   | Quickstart, configuration, API, providers, operations/recovery and type-checked examples; reporting example runs with controlled adapters                             |
-
-## Local verification
-
-Run `pnpm check`, `pnpm test`, `pnpm build`, and `pnpm lint`. Tests create a disposable PostgreSQL database unless `TEST_DATABASE_URL` is set, use real temporary Git repositories, and use controlled agents/hosting endpoints. `pnpm audit --prod` checks runtime dependency advisories. The GitHub Actions job supplies the same fixture boundary on Linux.
-
-The implementation was verified locally on macOS with Node 24 and PostgreSQL 17. Remote CI has not run for this uncommitted working tree. No authenticated live Codex/Copilot model invocation, real GitHub publication or real GitLab instance smoke test was performed. Those require a deliberately chosen test repository and provider access and are separate from deterministic acceptance.
-
-## Deliberate operational boundaries
-
-- Interrupted agent work blocks if ownership/state is ambiguous; it never starts another writer merely because DBOS recovered.
-- Explicit retry creates a new attempt from the base after the developer restores a clean checkout. It preserves the previous run and branch and does not silently amend an existing PR/MR.
-- Runtime context controls are supported only where exposed by the provider; unknown defaults remain unknown. Codex explicit-model validation depends on its local model catalog or an injected catalog.
-- Git hooks are disabled for the application-authored task commit; configure required checks as validation commands. Changed symlinks and submodules require manual handling.
-- The runner assumes exclusive checkout use. It detects boundary changes but does not sandbox arbitrary custom adapters or prevent every unrelated local tool write.
-- macOS/Linux process groups are required. Windows startup fails explicitly.
-
-Human review should concentrate on cancellation/ownership, recovery reconciliation and adapter permissions before enabling unattended work on a real repository. Completion means the automation has published its draft and review, not that the code is approved.