@mingchuno/agent-workflows 0.1.0

package/dist/src/workspace.js

@@ -0,0 +1,186 @@
+import { createHash, randomUUID } from "node:crypto";
+import { access, lstat, mkdir, readFile, realpath } from "node:fs/promises";
+import { join } from "node:path";
+import { BlockedError, } from "./domain.js";
+import { command } from "./runtime/process.js";
+export class ExistingCheckout {
+    processDirectories = new Map();
+    processDirectory(project) {
+        let directory = this.processDirectories.get(project.checkout);
+        if (!directory) {
+            directory = (async () => {
+                const result = await command("git", ["rev-parse", "--absolute-git-dir"], {
+                    cwd: project.checkout,
+                });
+                const path = join(result.stdout.trim(), "agent-workflows-processes");
+                await mkdir(path, { recursive: true, mode: 0o700 });
+                return path;
+            })();
+            this.processDirectories.set(project.checkout, directory);
+        }
+        return directory;
+    }
+    async runGit(project, args, options = {}) {
+        const directory = await this.processDirectory(project);
+        return command("git", args, {
+            ...options,
+            cwd: project.checkout,
+            processFile: join(directory, `${randomUUID()}.process.json`),
+        });
+    }
+    async git(project, ...args) {
+        return (await this.runGit(project, args)).stdout.trimEnd();
+    }
+    async check(project) {
+        const top = await this.git(project, "rev-parse", "--show-toplevel");
+        if ((await realpath(top)) !== (await realpath(project.checkout)))
+            throw new BlockedError("Checkout must be the canonical repository root");
+        await this.assertNoOperation(project);
+        if (await this.git(project, "status", "--porcelain", "--untracked-files=all"))
+            throw new BlockedError("Checkout must be clean; unfinished files preserved");
+    }
+    async assertNoOperation(project) {
+        for (const marker of [
+            "MERGE_HEAD",
+            "CHERRY_PICK_HEAD",
+            "REVERT_HEAD",
+            "rebase-merge",
+            "rebase-apply",
+            "BISECT_LOG",
+        ]) {
+            const path = await this.git(project, "rev-parse", "--git-path", marker);
+            const exists = await access(path.startsWith("/") ? path : join(project.checkout, path)).then(() => true, () => false);
+            if (exists)
+                throw new BlockedError(`Unresolved Git operation: ${marker}`);
+        }
+    }
+    async prepare(project, branch, signal) {
+        signal?.throwIfAborted();
+        await this.check(project);
+        const original = await this.inspect(project);
+        await this.git(project, "check-ref-format", "--branch", project.baseBranch);
+        await this.git(project, "check-ref-format", "--branch", branch);
+        const existing = await this.runGit(project, ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], { signal, allowFailure: true });
+        if (existing.exitCode === 0)
+            throw new BlockedError(`Branch already exists: ${branch}`);
+        await this.runGit(project, ["fetch", "--no-tags", project.remote, project.baseBranch], { signal });
+        const base = await this.git(project, "rev-parse", "FETCH_HEAD");
+        await this.verify(project, original);
+        await this.runGit(project, ["switch", "-c", branch, base], { signal });
+        const prepared = await this.inspect(project);
+        if (prepared.paths.length)
+            throw new BlockedError("Checkout changed during branch preparation");
+        return prepared;
+    }
+    async inspect(project) {
+        await this.assertNoOperation(project);
+        const head = await this.git(project, "rev-parse", "HEAD");
+        const branch = await this.git(project, "symbolic-ref", "--short", "HEAD");
+        const status = await this.git(project, "status", "--porcelain=v1", "-z", "--untracked-files=all");
+        const diff = await this.git(project, "diff", "HEAD", "--binary", "--no-ext-diff");
+        const tracked = await this.git(project, "diff", "HEAD", "--no-renames", "--name-only", "-z");
+        const untracked = await this.git(project, "ls-files", "--others", "--exclude-standard", "-z");
+        const paths = [
+            ...new Set([...tracked.split("\0"), ...untracked.split("\0")].filter(Boolean)),
+        ].sort();
+        const hash = createHash("sha256")
+            .update(head)
+            .update(branch)
+            .update(status)
+            .update(diff);
+        let fullDiff = diff;
+        const files = {};
+        for (const path of paths) {
+            const absolute = join(project.checkout, path);
+            try {
+                const stat = await lstat(absolute);
+                if (stat.isSymbolicLink())
+                    throw new BlockedError(`Changed symlink requires manual handling: ${path}`);
+                const content = await readFile(absolute);
+                files[path] = createHash("sha256").update(content).digest("hex");
+                hash.update(path).update(content).update(String(stat.mode));
+                if (untracked.split("\0").includes(path))
+                    fullDiff += `\n--- /dev/null\n+++ b/${path}\n${content.toString()}`;
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+                hash.update(`deleted:${path}`);
+                files[path] = null;
+            }
+        }
+        return {
+            branch,
+            head,
+            fingerprint: hash.digest("hex"),
+            diff: fullDiff,
+            paths,
+            files,
+        };
+    }
+    async verify(project, expected) {
+        const actual = await this.inspect(project);
+        if (actual.fingerprint !== expected.fingerprint)
+            throw new BlockedError("Unexpected checkout mutation; files preserved");
+    }
+    async commit(project, expected, publication, runId, signal) {
+        signal?.throwIfAborted();
+        const current = await this.inspect(project);
+        if (current.head !== expected.head) {
+            const message = await this.git(project, "log", "-1", "--format=%B");
+            const parent = await this.git(project, "rev-parse", "HEAD^");
+            if (parent === expected.head &&
+                message.includes(`Agent-Workflows-Run: ${runId}`) &&
+                current.paths.length === 0) {
+                const changed = (await this.git(project, "diff", "HEAD^", "HEAD", "--no-renames", "--name-only", "-z"))
+                    .split("\0")
+                    .filter(Boolean)
+                    .sort();
+                if (JSON.stringify(changed) !== JSON.stringify(expected.paths))
+                    throw new BlockedError("Reconciled commit has an unexpected change set");
+                for (const [path, digest] of Object.entries(expected.files)) {
+                    const actual = await readFile(join(project.checkout, path)).then((content) => createHash("sha256").update(content).digest("hex"), (error) => {
+                        if (error.code === "ENOENT")
+                            return null;
+                        throw error;
+                    });
+                    if (actual !== digest)
+                        throw new BlockedError("Reconciled commit content differs from validated changes");
+                }
+                return current.head;
+            }
+            throw new BlockedError("Cannot reconcile commit with recorded changes");
+        }
+        await this.verify(project, expected);
+        if (!expected.paths.length)
+            throw new BlockedError("No changes to commit");
+        await this.runGit(project, ["add", "--", ...expected.paths], { signal });
+        await this.runGit(project, [
+            "-c",
+            `user.name=${project.gitIdentity.name}`,
+            "-c",
+            `user.email=${project.gitIdentity.email}`,
+            "-c",
+            "core.hooksPath=/dev/null",
+            "commit",
+            "-m",
+            `${publication.commitMessage}\n\nAgent-Workflows-Run: ${runId}`,
+        ], { signal });
+        return this.git(project, "rev-parse", "HEAD");
+    }
+    async push(project, branch, head, signal) {
+        signal?.throwIfAborted();
+        await this.check(project);
+        if ((await this.git(project, "rev-parse", "HEAD")) !== head)
+            throw new BlockedError("Head changed before push");
+        const result = await this.runGit(project, ["ls-remote", "--heads", project.remote, `refs/heads/${branch}`], { signal });
+        const existing = result.stdout.trimEnd();
+        if (existing && existing.split(/\s/)[0] !== head)
+            throw new BlockedError("Remote branch changed; refusing overwrite");
+        if (!existing)
+            await this.runGit(project, ["push", project.remote, `${head}:refs/heads/${branch}`], { signal });
+    }
+    async release(project) {
+        await this.check(project);
+    }
+}

package/docs/acceptance.md

@@ -0,0 +1,35 @@
+# 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.

package/docs/api.md

@@ -0,0 +1,64 @@
+# Public SDK API
+
+Exports are in `src/index.ts`; the built package resolves to `dist/src/index.js`. Generated TypeScript declarations describe full argument/return types. Node ESM is required.
+
+## Runner and controls
+
+`new Runner({config,databaseUrl,hosting,agents,workspace?,workflow?,workflowVersion?})` injects hosting/agent adapters and optionally a workspace strategy or workflow. `hosting(project)` returns a host-qualified adapter. `agents` maps provider names to adapters. The default workspace uses the existing checkout. One DBOS runtime runs per Node process; one runner owns each configuration and checkout.
+
+`start()` validates registration, acquires ownership, launches DBOS, registers concurrency-one project queues, and starts polling. `poll(projectId?)` performs an immediate scan. `pause(projectId)` stops new starts while active work continues. `resume(projectId)` refuses blocked checkouts. `stop(runId)` waits for the active invocation/process to end, or cancels queued work. `retry(runId)` requires a terminal failed/blocked/cancelled run and a clean checkout, then returns a new linked run ID. `shutdown()` stops intake, cancels and awaits active work, closes DBOS and releases ownership.
+
+Use `try/finally` to call `shutdown()`, including failed startup. A custom `workflowVersion` must change when its durable step order changes; finish existing work before replacing an incompatible version.
+
+Polling runs independently per project, with at most one scan in flight per project. `start()` does not wait for scans to finish; `poll(projectId?)` waits for the requested scans, joining any already in flight. Shutdown drains outstanding scans without admitting their results or starting queued work.
+
+Retry admission serializes competing requests per project. One request creates
+the next attempt; another request for the same task fails while that retry is
+queued or running. Replaying the same command ID returns its existing retry,
+without rechecking the checkout or emitting events. A command ID cannot identify
+retries of different runs. Retry creation, project unblocking and their events
+commit together; failure preserves the blocked state.
+
+## Durable operations
+
+`defaultWorkflow(operations)` composes the standard issue-to-review path. The runner calls your optional `workflow(operations)` inside an ordinary registered DBOS workflow. Use [DBOS TypeScript documentation](https://docs.dbos.dev/typescript/programming-guide) for workflow, step, queue and determinism semantics.
+
+| Operation                                | Contract                                                                     |
+| ---------------------------------------- | ---------------------------------------------------------------------------- |
+| `eligible()`                             | Re-fetch issue; true only if open and still labelled                         |
+| `prepare()`                              | Require clean Git state; fetch base and create unique branch                 |
+| `implement()`                            | Fresh implementation session; reject unexpected commits or branch changes    |
+| `validate()`                             | Run commands and verify unchanged diff; false means no change                |
+| `writePublication()`                     | Fresh writer session; schema-check and persist generated text                |
+| `commit()` / `push()`                    | Separate reconciled Git effects using the verified change set                |
+| `publish()`                              | Find existing request by branch before creating a draft                      |
+| `review()`                               | Fresh read-only reviewer; exact published diff, head and validation evidence |
+| `publishReview()`                        | Reject stale head; reconcile review marker; map valid added-line findings    |
+| `complete(outcome?)`                     | Require clean checkout and persist terminal outcome                          |
+| `step(name, operation)`                  | Custom durable operation receiving current `RunRecord`                       |
+| `invoke(name, stage, prompt, readOnly?)` | Custom agentic step with profile resolution and session history              |
+
+Put side effects inside `step`; custom effects must be idempotent or reconcile their own ambiguous results. A DBOS checkpoint does not snapshot a checkout. Returning from a custom workflow without calling a terminal operation is invalid. [Reporting workflow](../examples/custom-workflow.ts) inserts a validation report without editing provider code.
+
+## Extension contracts
+
+`Workspace` separates `check`, `prepare`, `inspect`, `verify`, `commit`, `push` and `release`. `Snapshot` contains branch/head, changed paths, diff and a content fingerprint. Never implement release by discarding files. A future isolated workspace implementation can replace this interface without changing workflow composition.
+
+`prepare`, `commit` and `push` receive an optional final `AbortSignal`. Custom workspaces must stop their subprocesses before settling a cancelled operation. The existing-checkout strategy journals Git processes under the Git directory; ownership acquisition rejects surviving process groups after a runner crash.
+
+`AgentAdapter.validate(profile)` returns observable effective settings. `invoke(input)` receives working directory, prompt/skills, read-only intent, abort signal, stage `timeoutMs` and session/event callbacks. The abort signal also covers cancellation and time spent validating the profile. Call `session(id)` immediately when available. Await event persistence; invocation must not settle until its work has stopped. SDK adapters enforce process-group lifecycle; custom adapters must uphold the same contract. `processFile` is available for controlled subprocess ownership.
+
+`HostingAdapter` provides issue pagination/revalidation, instance-qualified `identity`, change-request lookup/create, remote head, and idempotent review publication. `preflight` is optional. Reconciliation keys must be stable across response loss; providers must never infer successful publication from agent prose.
+
+## Query and event interface
+
+`runner.store` is a `Store`. Independently construct `new Store(databaseUrl, runnerId)` to inspect history after shutdown; always `close()` it. `projects()`, `runs()`, `run(id)`, `invocations(runId)` and `events(afterSequence)` return persisted data. Events are ordered by monotonic sequence, paged at 1000; advance the cursor to retrieve more. `subscribe(listener,{after,intervalMs})` polls and returns an unsubscribe function. Delivery resumes from the caller's cursor; persist it if needed.
+
+`Store.admitRetry` owns persisted retry admission. Runner supplies its checkout
+and process safety check, which runs under the project lock for new admissions
+only. This callback must not mutate Store records. Operator tools should use
+`retry` commands or `Runner.retry`, preserving those safety checks.
+
+Invocation records include project/run IDs, stable DBOS step ID and name, invocation ID, attempt, timestamps, requested/effective profile, provider, prompt/skill snapshots, artifact path and session state (`pending`, `available`, `unavailable`). Repeated custom steps retain separate invocations. A retry has a separate run record linked to its predecessor.
+
+`request(kind,target)` queues the same `pause`, `resume`, `stop`, or `retry` commands used by the CLI/TUI; `commands()` reports pending/success/failure. A runner must be active to execute them. `finishCommand` and record-writing methods support adapters and custom workflows; operator tools should prefer commands over direct mutation.

package/docs/architecture.md

@@ -0,0 +1,24 @@
+# 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.
+- `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.tsx`: 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. Agent calls are never automatically retried. Publication retries 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.
+
+Phase 1 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` and `src/db` 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.

package/docs/configuration.md

@@ -0,0 +1,41 @@
+# 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.
+
+| 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                                                   |
+| `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                                           |
+| `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                                            |
+| `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` |
+
+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`.
+
+## 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.
+
+Codex rejects `context`: its TypeScript SDK exposes no runtime context-budget/compaction controls. Explicit Codex model/effort settings are checked against the local runtime's `models_cache.json`, or a supplied `new SDKAgent("codex", {models})` catalog. A missing catalog fails clearly; omitted settings use runtime defaults and remain `unknown` in effective-profile records. The cache can be stale; refresh it using the authenticated Codex runtime when a newly available model is rejected.
+
+Copilot queries its SDK model catalog for explicit settings. Supported context controls are `backgroundCompactionThreshold` and `bufferExhaustionThreshold`, fractions of context utilization, with defaults 0.8 and 0.95 when a partial context object is supplied. Background must be lower than exhaustion. These control compaction, not the model's hard context-window capacity. Hard capacity is recorded separately in tokens when the model catalog supplies it.
+
+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
+
+`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.
+
+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.

package/docs/database.md

@@ -0,0 +1,28 @@
+# Database maintenance
+
+`src/db/schema.ts` defines application tables in `agent_workflows`. Drizzle generates versioned SQL in `drizzle/`; its migration history lives in `agent_workflows_migrations`. DBOS owns its execution schema separately.
+
+## Change the schema
+
+1. Edit `src/db/schema.ts`.
+2. Run `pnpm db:generate --name describe_change` and review the generated SQL and snapshot.
+3. Run `pnpm test` against disposable PostgreSQL before applying the change. The test role needs `CREATEDB` for isolated migration fixtures.
+4. Back up an existing database, stop runners, then run `AGENT_WORKFLOWS_DATABASE_URL=... pnpm db:migrate`.
+
+Do not edit applied migration files or use schema push against existing data. Add a new migration for later changes. The migration command uses `AGENT_WORKFLOWS_DATABASE_URL`; with a custom `databaseUrlEnv`, supply that URL under this name for the command.
+
+`Store.initialize()` also applies pending migrations, preserving automatic startup setup. A dedicated PostgreSQL advisory lock serializes migration attempts across processes. Build copies migrations into `dist/drizzle`, so the built runtime works outside the repository working directory; ship the whole `dist` directory.
+
+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.

package/docs/operations.md

@@ -0,0 +1,46 @@
+# Operating the local runner
+
+## CLI and monitor
+
+All commands accept `--config PATH` before the subcommand.
+
+| Command                            | Effect                                                          |
+| ---------------------------------- | --------------------------------------------------------------- |
+| `init`                             | Write a starter config; refuse overwrite                        |
+| `run [--project ID ...]`           | Start selected projects in the foreground                       |
+| `status [--json]`                  | Projects, runs and command outcomes                             |
+| `inspect RUN`                      | Full run and invocation/session records as JSON                 |
+| `logs RUN [--invocation ID]`       | Local agent and validation artifacts                            |
+| `pause PROJECT` / `resume PROJECT` | Queue an intake control command                                 |
+| `stop RUN`                         | Queue cancellation; success means active local work has stopped |
+| `retry RUN`                        | Queue an explicit new attempt after checkout validation         |
+| `monitor`                          | Attach an interactive terminal view                             |
+
+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`.
+
+## 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.
+
+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.
+
+After a blocked/failed task:
+
+1. Read `inspect RUN`, logs, session IDs and the local Git diff.
+2. Establish that no worker/process group is still running. If startup reports an old PID or process journal, inspect that exact process and stop it before recovery. Never remove a live owner's lease.
+3. Preserve unfinished work on a developer-owned commit/branch or move it to a safe location. Resolve merge/rebase state yourself. Do not rely on DBOS to restore files.
+4. Once the checkout is clean, request `retry RUN`. This creates a new attempt and branch from the configured base, keeping the old run and files/commits inspectable.
+
+A failed review after publication remains a failed automation attempt, even if its draft request exists. Explicit retry starts the full workflow as a new attempt; it does not silently modify the old request. Human review/merging remains separate. A stale review never claims coverage of a changed remote head.
+
+## Evidence and limits
+
+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

@@ -0,0 +1,49 @@
+# Prerequisites and provider capabilities
+
+Install Node.js 22.12+, Git and PostgreSQL 17+. Native PostgreSQL and a local PostgreSQL container are both supported. Tests were developed against PostgreSQL 17 and Node 24 on macOS; A Linux fixture CI job is supplied; remote CI has not been run for this working tree. The database must be writable by the configured role so DBOS and the application can create their schemas.
+
+Authenticate the selected local agent runtime before starting. Codex SDK uses the bundled Codex executable and its local authentication/configuration; Copilot SDK manages a local Copilot runtime. Subscription/access policy and model availability belong to those runtimes. See [official Codex SDK documentation](https://developers.openai.com/codex/sdk/) and [Copilot SDK documentation](https://github.com/github/copilot-sdk/tree/main/docs). Routine tests never invoke paid models.
+
+| Capability                                  | Codex                                                                | Copilot                                                           |
+| ------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| Implementation, writing, 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                                |
+| Session ID                                  | `thread.started` event                                               | Session creation response                                         |
+| Read-only stages                            | Read-only sandbox                                                    | Read permissions only; shell/write permission denied              |
+| Cancellation                                | Owned worker process group, TERM then KILL                           | Owned worker process group, TERM then KILL                        |
+| Inspection/resumption                       | Saved thread ID; SDK `resumeThread` supports local persisted threads | Saved session ID; SDK `resumeSession` supports persisted sessions |
+
+Codex implementation uses its workspace-write sandbox. Copilot implementation approves runtime permission requests and is not an operating-system sandbox; its read-only stages deny non-read permissions. Run selected issues and skills with the permissions of the local runtime account. Checkout checks detect unexpected changes at phase boundaries.
+
+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.
+
+## 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.
+
+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.
+
+## GitLab.com and self-hosted GitLab
+
+Supported range: GitLab **17.x–19.x**, REST API v4. Startup checks the metadata endpoint and rejects versions outside this range. Controlled version-shaped HTTP fixtures test the shared issue/MR/review contract; no real GitLab instance has been smoke-tested in this implementation run.
+
+```json
+{
+  "provider": "gitlab",
+  "origin": "https://git.example.com/gitlab",
+  "repository": "group/project",
+  "tokenEnv": "WORK_GITLAB_TOKEN"
+}
+```
+
+The relative root is preserved in API routes (`/gitlab/api/v4/...`). Provider identity includes origin, root and repository, so equal project IDs on different instances do not collide. Returned issue/MR links come from that instance. The API origin does not rewrite the Git push remote.
+
+Use a token with API access and the project permissions needed to publish MRs and comments. Configure private CA trust with `NODE_EXTRA_CA_CERTS` before starting Node; TLS verification remains enabled. Plain HTTP is allowed only for localhost fixture servers. Never disable TLS verification globally.
+
+Draft MRs use the supported `Draft:` title prefix. Revision-bound inline discussions use GitLab diff refs and reconcile per-finding markers; a final summary marker reconciles overall completion. See [GitLab merge requests](https://docs.gitlab.com/api/merge_requests/) and [discussions](https://docs.gitlab.com/api/discussions/) for provider semantics.
+
+## 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.

package/docs/releases.md

@@ -0,0 +1,89 @@
+# Releases
+
+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/).
+
+## 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.
+
+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.
+
+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.