oh-my-super-agent 0.1.0

package/docs/PLAN.md

@@ -0,0 +1,216 @@
+# OMS Build Plan
+
+## Purpose and current status
+
+Oh My Super Agent (OMS) is a Linux-first Node.js/TypeScript harness for
+coordinating supported Claude Code and Codex CLI ticket workflows. It composes
+native sessions, goals, hooks, subagents, git worktrees, and operator-managed
+service managers instead of replacing them with a daemon or framework.
+
+The local control plane described below is implemented. The release is still
+`not_stable`: no real live GitHub ticket, elapsed 12-hour canary, fresh elapsed
+24-hour canary, or completed executor-group evidence is
+shipped. Those are evidence obligations, not claims inferred from unit tests or
+from the existence of a `12h` or `24h` run option.
+
+The approved next delivery sequence is tracked in
+[`docs/ROADMAP.md`](ROADMAP.md). It replaces the earlier per-worker manual-start
+direction with one human-started read-only conductor, OMS-native typed dispatch,
+immediate provider observations, 60-second GitHub polling, and a 15-minute
+recovery-only watchdog. The conductor, typed-dispatch, and interactive
+worker-pane, event-synchronization, protected result-gate, and draft-review
+delivery slices are implemented; the actual live GitHub and endurance evidence
+remain pending.
+
+The implementation follows this escalation ladder:
+
+1. Use a native CLI feature.
+2. Add a skill or prompt.
+3. Compose it with a small Node.js/TypeScript command.
+4. Add a larger custom service only after the command boundary is demonstrably
+   inadequate.
+
+All tracked runtime automation is TypeScript. OMS has no tracked shell
+automation scripts, custom daemon, application framework, database, or runtime
+npm dependency.
+
+## Operating constraints
+
+- Runtime dependencies are Node.js 20+, `git`, Linux `bubblewrap` for the
+  protected live verifier, and pinned Gitleaks 8.30.1 for live review delivery;
+  npm and pinned development dependencies build and test the TypeScript source.
+- Live authentication, billing, transport, model, sandbox, session, and
+  unattended eligibility remain explicit role policy. Unknown or incompatible
+  values fail closed.
+- OMS never uses an interactive pane as a billing workaround and does not
+  implement Claude print-mode transport.
+- `doctor`, `verify`, tests, the HUD, release assessment, and the local trace
+  fixture make no provider or network call.
+- The named GitHub queue probe is disclosure-first and requires explicit live
+  confirmation before contact. Its presence is not live-ticket evidence.
+- Normal progress is driven by provider hooks and 60-second GitHub polling. The
+  minute command remains an internal audit/due-work pass; the 15-minute
+  watchdog is limited to recovery and stall detection.
+- Automatic merge is disabled. Trust assessment is review-only and cannot
+  grant merge or execution authority.
+- OMS can explicitly generate, install, inspect, and remove one exact
+  user-scoped cron/systemd/launchd schedule containing only GitHub polling and
+  the recovery watchdog.
+- Slack support ends at a typed request-only outbox event. OMS has no Slack
+  transport, credentials, or delivery receipt authority.
+
+## Role roster
+
+The tracked role policy is configuration, not proof that a provider ran:
+
+| Role | Default surface | Implemented boundary |
+| --- | --- | --- |
+| conductor | Claude Opus persistent pane | Read-only goal/advice/dispatch routing; approved dispatches enter the typed OMS delivery adapter |
+| advise | fresh Codex exec | Mandatory exact-intent verdict with protected immutable evidence before dispatch |
+| execute | Claude Sonnet ticket worktree | OMS-managed interactive pane, session-bound worker tools, sandboxed worktree writes |
+| execute-long | Codex goal in a ticket worktree | OMS-managed interactive TUI with native `/goal` input and resumable session state |
+| grade | fresh engine different from executor when available | Supplemental structured evidence only; deterministic gate remains final |
+| dream | fresh context or subagent | Bounded reflection evidence; no queue authority |
+
+Every role declares authentication, billing, unattended eligibility, sandbox,
+session mode, and evidence policy. Credit-billed or otherwise non-default models
+remain opt-in and absent from the default roster; OMS does not infer billing
+from a model name.
+
+## Goal-mode routing
+
+- Canonical OMS goal records are the durable authority.
+- Configured long-running tickets may use an OMS-managed interactive Codex Goal pane.
+- `oms team start` groups already accepted executor dispatches; it adds no verifier lane.
+- Imported native goal or external team-workflow snapshots are evidence only and never a runtime dependency.
+
+The shipped CLI exposes canonical `goal create` and `goal status` operator
+surfaces, launches only configured OMS worker lanes, and keeps all workflow
+authority in typed OMS records.
+
+## Implemented ticket and runtime flow
+
+```text
+materialize pending ticket -> human goal -> journal/prepare/lease -> fresh exact-intent advice -> dispatch/run
+                         -> deterministic verify -> supplemental grade
+                         -> completed with human hold, retryable, blocked, or parked
+
+provider hook -> typed outbox -> session/activity/health/quota observation
+GitHub poll -> typed deduplicated event -> materialize pending ticket -> opaque conductor notification
+passing result -> secret scan -> non-force branch/draft PR -> typed PR/check events -> READY_FOR_HUMAN
+watchdog -> dead-waiter/conductor recovery + lease/session/outbox evidence
+```
+
+Ticket mutations use expected versions, attempts, actors, operation nonces, and
+lease tokens. Raw issue content is held in immutable files and is not sent as a
+command or tmux keystroke. The local `trace fixture` exercises the full local
+ticket path without a provider, network call, or tracked source mutation; it is
+explicitly non-certifying and leaves merge on human hold.
+
+Fresh advice is mandatory before execution and cannot authorize a changed
+intent. The deterministic verification gate votes after execution and finally.
+A grader explains evidence and cannot turn a failed deterministic result into a pass. The trust
+format accepts only protected live deterministic evidence bound to the same
+ticket, attempt, lease, session, worktree commit, role policy, and
+verification-plan digest. The protected result gate is the sole live writer;
+it runs candidate checks in a native filesystem sandbox, requires one fresh
+opposite-engine grade, records both passing and failed deterministic trust runs,
+and keeps every completed ticket on human hold. The offline tracer remains
+non-certifying and cannot complete tickets or mint trust.
+
+## Delivered milestones
+
+### M0: constitution and local scaffold
+
+Delivered:
+
+- `.agents/` source of truth and idempotent managed projection;
+- compiled TypeScript CLI plus a small Node.js source-checkout shim;
+- strict JSON schemas, private runtime root, immutable evidence, atomic record
+  replacement, branded authority boundaries, and offline verification;
+- explicit role policy with unattended execution disabled by default.
+
+### M1: local one-ticket tracer
+
+Delivered:
+
+- opaque ticket materialization, canonical lifecycle record, dedicated branch
+  and worktree management, deterministic check, supplemental grade, bounded
+  retry/reflection records, and human-held completion;
+- a fully offline contributor fixture;
+- a disclosure-first GitHub queue probe that cannot be confused with generic
+  evidence writing.
+
+Not proven: a real GitHub issue completed through a live provider session.
+
+### M2: durable endurance control plane
+
+Delivered:
+
+- typed event bus and idempotent outbox receipts;
+- canonical session registry and quota observations bound to validated hook
+  events and session versions;
+- bounded native-hook ingestion and projection;
+- one-minute resume/audit reconciliation and 15-minute recovery watchdog;
+- immutable audit-run service plans plus exact user schedule lifecycle;
+- read-only HUD and non-certifying `run start`, `run tick`, `run close`, `run
+  abort`, `run recover-controller`, and `run status`;
+- immutable start intents, full ticket identity/content admission snapshots,
+  persisted completion proofs, service-plan revalidation, and process-restart
+  continuity markers.
+
+The user schedule is operator-invoked; the conductor remains the sole human
+start and no daemon is installed.
+Not proven: an elapsed 12-hour or fresh elapsed 24-hour run.
+
+### M3: trust and goal authorities
+
+Delivered:
+
+- ticket-bound trust-run evidence and closed-UTC-day, review-only trust reports;
+- one canonical OMS goal authority with immutable native, Team, Ultragoal, and
+  regression artifacts;
+- fail-closed parking on stale or mismatched goal evidence;
+- canonical `goal create` and `goal status` CLI commands.
+
+Trust does not enable automatic merge, and the CLI does not automatically
+execute native goals or regression tickets.
+
+### M4 foundation: OMS-native executor groups and release truth
+
+Delivered:
+
+- immutable executor-group manifests over accepted dispatches;
+- direct interactive Claude and Codex Goal panes behind typed OMS lifecycle commands;
+- session-bound worker read, acknowledgement, and HEAD-derived result tools;
+- a negative-only `release status` surface fixed to `not_stable`, human hold,
+  and automatic merge disabled;
+- an opaque `conductor next` decision plus automatic delivery after accepted dispatch.
+
+Also delivered: pinned provider hooks, typed GitHub polling with removal/re-add
+inventory, conductor-selected version-bound ticket preparation, opaque notification/waiter
+recovery, idempotent user scheduling, repository-scoped live-contact journals,
+and a fixed secret-scanned branch/draft-PR handoff after the protected result
+gate. Not implemented here: Slack sending or automatic merge. No real
+provider-backed GitHub completion evidence is shipped yet.
+
+## Remaining proof and product backlog
+
+1. Complete one explicitly authorized live GitHub ticket using supported
+   provider authentication and retain the resulting evidence.
+2. Run and independently review a real elapsed 12-hour canary.
+3. Run and independently review a fresh elapsed 24-hour canary.
+4. Capture a real multi-worker executor group through the normal ticket review
+   path.
+5. Consider automatic merge only through a future, explicit positive-release
+   design. The current schema intentionally has no positive release state.
+
+## Review and provenance policy
+
+- The project is an original implementation under the repository license.
+- External protocols may inform behavior, but code is not copied without
+  license review and attribution.
+- Change size is a risk signal, not a substitute for review and evidence.
+- Tests prove deterministic local contracts. They do not prove provider policy,
+  network availability, elapsed endurance, current remote GitHub state, or production
+  readiness.

package/docs/REFERENCES.md

@@ -0,0 +1,42 @@
+# References and Provenance
+
+Last reviewed: 2026-07-11.
+
+This file records the official sources used to review the OMS M0 design. Links describe provider behavior at the review date; they are not a promise that a feature, entitlement, price, or policy will remain unchanged.
+
+## OpenAI sources
+
+- [Codex authentication](https://developers.openai.com/codex/auth) documents ChatGPT subscription sign-in and usage-based API-key sign-in for local Codex clients. It recommends API-key authentication for programmatic CLI workflows and describes enterprise access tokens for trusted non-interactive automation.
+- [Follow a goal](https://learn.chatgpt.com/codex/use-cases/follow-goals) documents `/goal`, `/goal pause`, `/goal resume`, and `/goal clear`. It frames a goal as one durable objective with a verifiable stopping condition, not an unrelated backlog.
+- [Codex CLI developer commands](https://developers.openai.com/codex/cli/reference) is the official reference for supported CLI commands and flags. Local feature detection still uses the installed CLI's `--help` output because the binary version may differ from the current documentation.
+
+## Anthropic sources
+
+- [Claude Code CLI reference](https://code.claude.com/docs/en/cli-usage) documents named and resumable sessions, authentication-status commands, and interactive versus print-mode entry points.
+- [Claude Code hooks reference](https://code.claude.com/docs/en/hooks) documents command hooks, asynchronous hooks, and `asyncRewake`. OMS uses hooks and outbox events for normal progress; its heartbeat remains a watchdog.
+- [Claude Code subagents](https://code.claude.com/docs/en/sub-agents) documents foreground and background subagents and their fresh-context, permission, and concurrency behavior.
+- [Claude Code setup](https://docs.anthropic.com/en/docs/claude-code/getting-started) documents supported authentication options, including Claude subscriptions, Anthropic Console billing, and enterprise cloud platforms.
+- [Manage API key environment variables in Claude Code](https://support.claude.com/en/articles/12304248-manage-api-key-environment-variables-in-claude-code) documents authentication precedence and the risk of unexpected API charges when `ANTHROPIC_API_KEY` is set.
+- [Use the Claude Agent SDK with your Claude plan](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) is a time-sensitive account-policy source for Agent SDK, `claude -p`, and third-party usage. Its June 15 update says the announced credit-pool change is paused and those surfaces continue to draw subscription limits for now.
+- [Log in to your Claude account](https://support.claude.com/en/articles/13189465-log-in-to-your-claude-account) separately says third-party/open-source tools should prefer API or supported cloud authentication and prohibits attempts to route third-party traffic against subscription limits. OMS treats the two pages as a live policy gate rather than silently choosing the cheaper interpretation.
+- [Claude API key security practices](https://support.claude.com/en/articles/9767949-api-key-best-practices-keeping-your-keys-safe-and-secure) supports keeping keys out of source control and treating third-party credential handling as a security boundary.
+
+## GitHub and scanner sources
+
+- [Gitleaks releases](https://github.com/gitleaks/gitleaks/releases) is the upstream source for the exact scanner version and release archive pinned by policy and CI.
+- [GitHub-hosted runner images](https://github.com/actions/runner-images) documents the changing `ubuntu-latest` image inventory. The workflow installs `bubblewrap` explicitly rather than assuming it is preinstalled.
+- [AppArmor's `bwrap-userns-restrict` profile](https://gitlab.com/apparmor/apparmor/-/blob/master/profiles/apparmor/profiles/extras/bwrap-userns-restrict) grants Bubblewrap the namespace setup capabilities its children do not retain. CI installs Ubuntu's `apparmor-profiles` package, loads its extra profile, and smoke-tests `--unshare-all` without relaxing the host-wide user-namespace policy.
+
+## Provenance boundary
+
+OMS is an original implementation. The sources above provide product facts and design constraints; they are not source-code inputs. No OpenAI, Anthropic, or third-party implementation code is copied into OMS.
+
+Ideas such as leases, nonces, atomic replacement, outboxes, watchdogs, worktrees, and deterministic verification are reimplemented from general systems-design principles. If a later change uses code, schemas, or a distinctive protocol from another project, that change must first record the source, license, compatible terms, attribution requirements, and the exact material reused.
+
+Documentation links do not grant a license to copy examples wholesale. Small command invocations may be restated as interoperability facts; substantive code requires a separate license review.
+
+## Runtime policy prerequisite
+
+Provider authentication, billing, acceptable-use, subscription, automation, data-handling, and feature-availability rules are runtime prerequisites. Before OMS enables a live or unattended provider workflow, an operator must verify the current official policy and configure an explicitly supported authentication mode.
+
+OMS fails closed when authentication mode or unattended eligibility is absent, unknown, or incompatible with the requested run. Offline `doctor`, tests, and `make verify` do not contact providers or consume model usage. A passing link check proves only that a referenced page was reachable; it does not prove that the operator's account is eligible for a workflow.

package/docs/ROADMAP.md

@@ -0,0 +1,327 @@
+# OMS Conductor-First Live Delivery Roadmap
+
+Status: approved on 2026-07-11; implementation pending
+
+Baseline: commit `066777f`; the local file-backed control plane, schemas, hooks, queue, worktrees, reconciliation, HUD, and negative-only release assessment are implemented and verified.
+
+## Outcome
+
+A human runs interactive bare `oms`, which performs any one-time repository-scoped confirmation, then creates or resumes a persistent read-only Claude Opus conductor in the OMS tmux session. The human types a freeform goal. The conductor normalizes it into durable OMS goal state and then uses typed OMS commands to route tickets, start isolated Claude or Codex workers, observe immediate provider events, react to GitHub events, verify results, and prepare review-ready pull requests. The explicit `oms conductor start` form remains only for advanced recovery or state-root selection.
+
+OMS v1 stops at `READY_FOR_HUMAN`. It never merges, tags, publishes, releases, or claims stability.
+
+## Simplicity contract
+
+Use the smallest existing primitive that works:
+
+1. Native features: interactive Claude/Codex CLIs, Codex Goal and exec, Claude local stdio MCP tools and `asyncRewake` hooks, provider hooks, tmux, git worktrees, `gh`, and user-owned schedulers.
+2. Skills: conductor routing, executor protocol, advisor, grader, bounded reflection, quota handling, scheduling, and team behavior.
+3. Small Node.js/TypeScript commands: a session-scoped seven-tool conductor bridge, durable state, typed dispatch, provider delivery, event synchronization, reconciliation, deterministic verification, evidence, and process lifecycle.
+4. No v1 framework layer: no daemon, database, webhook server, custom mux library, general workflow engine, or tracked shell automation.
+
+Review remains deliberately simple: deterministic verification is the final vote; one fresh cross-engine structured grade is supplemental. Reflection occurs only after failure and is bounded by the configured attempt limit.
+
+## Non-negotiable boundaries
+
+- The human starts only the persistent conductor. Claude print mode and the Agent SDK are forbidden.
+- The conductor has no Edit/Write tool and cannot invoke raw tmux. Goal,
+  ticket preparation, pre-dispatch advice, and approved dispatch cross four schema-bound data tools;
+  worker lifecycle, executor grouping, and protected result processing use three
+  fixed controls with opaque canonical IDs.
+- `oms` is the only shipped orchestration surface. Product code, generated instructions, and public docs must not require another orchestration CLI.
+- All provider/model/auth/billing combinations are explicit configuration. Unknown or ineligible combinations fail closed. Credit-billed models remain disabled by default.
+- The conductor may make routing decisions only inside configured roles, budgets, capabilities, attempts, and stopping conditions.
+- Raw issue, review, model, hook, and pane text are untrusted content. They never become commands or authority.
+- Deterministic OMS state owns goals, tickets, leases, dispatches, sessions, events, verification, evidence, attempts, audit, and human holds.
+- Workers may change only their isolated ticket worktrees. They never own goal, verification, trust, merge, or release authority.
+- A worker reporting `done` moves its ticket to `verifying`, not `completed`.
+- Provider hooks are immediate. GitHub polling defaults to 60 seconds. The 15-minute watchdog is recovery-only.
+- Merge, automatic merge, tag, publish, release, and positive stability remain human-held or absent.
+
+## Operator flow
+
+```text
+human: oms
+  -> OMS preflight + create/resume tmux session
+  -> interactive read-only Claude Opus conductor
+
+human types freeform goal
+  -> conductor calls mcp__oms__propose_goal with structured JSON
+  -> session-scoped OMS bridge validates and commits it
+  -> durable canonical goal before first dispatch
+
+conductor loop
+  -> read canonical queue/events/status
+  -> choose an eligible ticket and configured role
+  -> call mcp__oms__prepare_dispatch with expected_ticket_version and exact content digest
+  -> OMS proves current GitHub eligibility, journals the selection, and returns the leased intent
+  -> call mcp__oms__advise_dispatch with the exact structured intent
+  -> fresh Codex advice must approve that exact digest
+  -> call mcp__oms__propose_dispatch with the unchanged intent + evidence
+  -> OMS validates and starts isolated worker pane/worktree
+  -> provider hooks publish immediate lifecycle/quota/completion observations
+  -> GitHub sync publishes deduplicated issue/PR/review/check events
+  -> deterministic verify
+  -> one fresh cross-engine grade
+  -> completed + READY_FOR_HUMAN, retry, park, or block
+
+watchdog
+  -> every 15 minutes, recover only stale panes/sessions/leases/outbox work
+```
+
+## Canonical state model
+
+### Goal
+
+The conductor normalizes the human request into a record containing:
+
+- goal ID and version;
+- objective;
+- repository and queue scope;
+- stopping condition;
+- runtime horizon: `until-empty`, `12h`, or `24h`;
+- budget and policy profile.
+
+Every ticket, dispatch, attempt, event decision, result, and evidence record references the goal ID. Restarts re-read the record; conductor memory is never authoritative.
+
+### Agent
+
+- Activity: `idle | working | blocked | done`
+- Health overlay: `healthy | parked | stalled | stopped`
+
+### Ticket
+
+`pending | leased | running | verifying | completed | retryable | parked | blocked`
+
+Agent activity and ticket lifecycle are separate. A terminal worker result cannot bypass verification.
+
+### Dispatch
+
+Each accepted dispatch binds:
+
+- goal, ticket, lease, attempt, and dispatch IDs;
+- worker, configured role/model, provider mode, and worktree;
+- capability set, budget snapshot, acceptance criteria, and evidence requirements;
+- freeform agentic task body and operation nonce.
+- canonical dispatch-intent digest and immutable advisor-evidence reference.
+
+OMS validates and persists the envelope before a provider adapter delivers it. The worker acknowledges and returns typed receipts referencing the dispatch ID.
+
+### Structured conductor ingress
+
+Goal, advice, dispatch, and bounded controls use one native, session-scoped tool boundary:
+
+1. Interactive bare `oms` (or the explicit `oms conductor start` form) generates a strict local stdio MCP configuration whose only server command is the installed `oms conductor bridge` TypeScript entrypoint bound to the exact workspace/state root.
+2. CD-01 begins with `mcp__oms__propose_goal` and an inert `mcp__oms__propose_dispatch`; later slices activate dispatch and add version-bound `mcp__oms__prepare_dispatch` plus mandatory `mcp__oms__advise_dispatch` over a distinct exact-intent schema.
+3. CD-03 adds `mcp__oms__manage_worker` for observe/park/resume/stop and `mcp__oms__start_team` for grouping already accepted dispatch IDs. CD-05 adds `mcp__oms__process_result` for the protected result and fixed review-delivery path. The complete bridge exposes exactly seven schema-bound tools: four data tools and three fixed controls.
+4. Claude starts with `--strict-mcp-config`, `dontAsk`, those seven exact tool permissions, reviewed fixed OMS/read-only diagnostic rules, and no Edit/Write or raw tmux permission.
+5. The bridge has no generic filesystem, shell, provider, GitHub, verification, merge, or release tool. Proposal tools validate current goal/ticket/lease/policy/budget authority; control tools accept only canonical IDs and bounded lifecycle fields. `process_result` can invoke only the installed deterministic gate and fixed human-held review delivery.
+6. Tool calls are operation-nonce bound and replay-safe; tool output contains only bounded status and opaque canonical IDs.
+
+The bridge is a local stdio child of the interactive conductor session, not a daemon, network listener, framework, or separate orchestrator. Freeform model text travels only through schema-bound goal, preparation, advice, and dispatch JSON and never enters argv or a shell. Because MCP subprocess capabilities are enforced inside OMS rather than by the Bash sandbox, the bridge must expose no ambient authority beyond those four data validators and three fixed-action controls.
+
+## Events and clocks
+
+Three mechanisms have distinct jobs:
+
+1. Provider hooks immediately emit bounded session, activity, completion-observed, and quota observations. Hooks never provide the terminal result authority described below.
+2. `oms events sync github` is a one-shot TypeScript command. A user-owned schedule runs it every 60 seconds by default. Durable watermarks and stable event keys deduplicate issue, comment/label, branch, PR, review, and check events.
+3. `oms reconcile watchdog` runs every 15 minutes by default and handles only recovery and stall detection.
+
+After successful event projection and pending-ticket materialization, OMS appends one deduplicated conductor-notification batch containing only opaque event IDs. A session-scoped `oms conductor wait-event` command is armed by Claude `SessionStart`/`Stop` command hooks with `asyncRewake`; it waits for the next batch, emits only its opaque notification ID, and exits with the documented wake code so an idle conductor re-reads canonical state. One durable waiter-generation record is bound to the conductor session and process identity with `armed | notified | failed | superseded` state plus expected-version/nonce transitions. The conductor consumes the notification only through the matching route/read operation. No raw GitHub/provider text is injected into the session.
+
+The existing one-shot 15-minute watchdog is the sole dead-waiter recovery owner. After proving the waiter dead, it may CAS-claim one recovery generation only when the conductor is idle or dead, then resume/respawn the same conductor session so `SessionStart` arms a replacement. It never interrupts an active conductor; the next normal `Stop` re-arms instead. Unsafe or failed resume becomes visible `stalled`/`blocked` state while the notification remains pending. PID reuse, duplicate watchdog passes, and restarts cannot create two waiter generations.
+
+Normal state progression is event-driven. The watchdog must not become a second scheduler or repeat valid work. OMS may install, inspect, and remove only the exact generated user-scoped schedule after the human explicitly starts the conductor; it does not ship an always-running daemon.
+
+## Provider policy
+
+- Claude conductor and ticket executors use supported interactive CLI sessions in tmux. No `claude -p` or Agent SDK path exists.
+- Codex exec remains the fresh, schema-validated read-only advisor/grader surface when its configured auth/billing policy is eligible.
+- Codex Goal is a resumable interactive worker lane for long tickets, not a headless-service promise.
+- When Codex executes, one fresh Claude grade is mandatory; when Claude executes, one fresh Codex grade is mandatory. If the opposite engine is unavailable or ineligible, the ticket parks or blocks visibly—there is no same-engine fallback or skipped grade.
+- Provider hooks authoritatively update provider session/activity/health observations within their documented local boundary. Only one schema-valid result receipt bound to the current goal/dispatch/attempt/lease/session/worktree/commit may set `agent=done` and move a ticket to `verifying`. Completion hooks alone cannot. Pane capture and sentinels are diagnostics only.
+
+Official provider evidence was checked on 2026-07-11:
+
+- https://code.claude.com/docs/en/authentication
+- https://code.claude.com/docs/en/cli-usage
+- https://code.claude.com/docs/en/headless
+- https://code.claude.com/docs/en/legal-and-compliance
+- https://code.claude.com/docs/en/hooks
+- https://code.claude.com/docs/en/mcp
+- https://code.claude.com/docs/en/permissions
+- https://developers.openai.com/codex/cli/reference
+- https://developers.openai.com/codex/auth
+- https://developers.openai.com/codex/use-cases/follow-goals
+
+## Delivery slices
+
+### CD-01 — Conductor-first bootstrap and durable goal
+
+Add the human-started interactive bare `oms` path, its explicit `oms conductor start` authorization/state override, repository-read-only permission/profile projection, session-scoped two-tool OMS bridge, conductor session resume, and freeform-to-canonical goal normalization. Promote the conductor-first ADR.
+
+Acceptance:
+
+- One human command creates or resumes the named tmux session and attaches to an interactive Claude Opus conductor.
+- CD-01 begins with a pinned Claude Code compatibility proof (initial target: installed v2.1.207): the interactive subscription session loads only the generated local stdio OMS server, commits a goal through the goal tool, receives deterministic `dispatch-not-enabled` with no mutation from the dispatch tool, and cannot access Edit, Write, raw tmux, an unlisted MCP tool, or an unapproved shell command. Failure stops CD-01 and requires an ADR revision; permissions are never widened.
+- The conductor cannot edit/write product files or canonical state, mutate policy directly, or invoke raw tmux. It can call only the two allowlisted structured proposal tools, fixed typed OMS commands with opaque IDs, and read-only diagnostics.
+- Goal text crosses only JSON tool input and is committed only after exact schema/size/current-authority validation; shell metacharacters remain inert.
+- No print mode, Agent SDK, provider proxy, or default credit-billed model appears in launch arguments or configuration.
+- A canonical goal is durable before the first dispatch and is recovered after conductor restart.
+- Unknown auth, billing, CLI version, permission profile, or repository scope blocks launch.
+
+Blocked by: none.
+
+### CD-02 — Typed dispatch and separated runtime states
+
+Add canonical dispatch records, worker records, acceptance/result schemas, and deterministic transitions for agent activity, health, and ticket lifecycle.
+
+Acceptance:
+
+- OMS validates and persists a dispatch before delivery.
+- CD-02 replaces the inert dispatch handler with exact canonical validation/commit while preserving the same tool name, input schema boundary, and conductor permission set.
+- Dispatch freeform content crosses only the schema-bound
+  `mcp__oms__advise_dispatch` and `mcp__oms__propose_dispatch` tools; it never
+  enters a command argument or file Write.
+- The envelope binds the exact goal, ticket, lease, attempt, worker, role/model, worktree, capabilities, budget, acceptance/evidence requirements, and nonce.
+- `agent=done` can move a ticket only to `verifying`.
+- Stale leases, replayed nonces, exhausted attempts, unconfigured roles/models, or expanded capabilities fail closed without mutation.
+- The conductor cannot use dispatch to edit policy, expand goal scope, verify its own work, or grant merge/release authority.
+
+Blocked by: CD-01.
+
+### CD-03 — OMS-owned worker panes, provider adapters, and teams
+
+Implement OMS-native worker delivery and pane lifecycle behind typed commands. A team is only a group of executor dispatches with isolated worktrees; all results later use the same deterministic gate and single cross-engine grade from CD-05.
+
+Acceptance:
+
+- OMS starts, observes, parks, resumes, and stops one or N isolated worker panes from accepted dispatches.
+- Provider CLIs start directly; no public raw `tmux send-keys` command or pane text authority is exposed.
+- Workers acknowledge dispatch IDs and return typed result receipts bound to the exact session and worktree commit.
+- Claude remains interactive; Codex Goal remains resumable; Codex exec remains schema-validated and read-only for its configured role.
+- Replace the current per-worker `human_attended` / `human_started_native` assumptions with one explicitly reviewed `operator_originated_oms_managed_interactive` session policy. It remains distinct from headless/unattended eligibility and must fail closed when current provider policy or version preflight cannot support it.
+- Unknown provider eligibility blocks launch; capabilities cannot grant verification, trust, merge, or release authority.
+- Teams add no verifier agent or second model-review lane; team outputs flow into CD-05.
+- Product code, generated skills, tests, and docs contain no runtime dependency on an external orchestration CLI.
+
+Blocked by: CD-02.
+
+### CD-04 — Immediate events, GitHub sync, scheduling, and recovery
+
+Extend the existing event/outbox path with provider session/activity/completion-observed events, typed GitHub events, durable sync watermarks, schedule lifecycle, and pane-aware recovery.
+
+Acceptance:
+
+- Provider hooks immediately publish bounded session, activity, completion-observed, and quota observations.
+- Completion hooks can record `completion-observed` but cannot set `agent=done` or move a ticket to `verifying`; only the dispatch-bound typed result receipt can do that.
+- `oms events sync github` emits deduplicated typed issue, comment/label, branch, PR, review, and check events; default schedule is 60 seconds and configurable.
+- Each projected event batch creates one durable opaque conductor notification. The version-pinned `asyncRewake` waiter wakes an idle conductor, which re-reads canonical state and consumes the matching notification. Projection/notify/wake/consume is replay-safe.
+- Waiter state is generation/CAS bound to the exact conductor session/process. The watchdog is the sole recovery writer: it resumes/respawns only a proven idle/dead conductor, never interrupts an active one, and otherwise records visible stalled/blocked state with the notification retained.
+- `oms reconcile watchdog` runs every 15 minutes by default and only recovers or reports dead panes, stalled sessions/outbox work, expired leases, and resumable quota state.
+- Generated user-scoped schedules can be installed, inspected, and removed idempotently; no daemon or webhook listener is introduced.
+- Expired auth parks the lane for human login. Recovery never starts a duplicate worker or silently widens credentials.
+- Raw provider/GitHub content never becomes a command, branch, path, or authority.
+
+Blocked by: CD-03.
+
+### CD-05 — Protected verification, cross-engine grade, and bounded retry
+
+Connect typed worker results to the protected live deterministic verifier, then run exactly one fresh configured opposite-engine grade. On failure, store one bounded reflection and retry within the configured attempt limit.
+
+Acceptance:
+
+- A result binds the exact goal, dispatch, ticket, attempt, lease, session, worktree, and commit.
+- The installed OMS runner and frozen verification plan produce immutable deterministic evidence outside the candidate's authority.
+- Failed or incomplete deterministic verification is final and cannot be overridden by conductor, grader, trust, or operator text.
+- Exactly one fresh schema-validated opposite-engine grade is mandatory and supplemental; it consumes raw bounded check output plus immutable diff/evidence references. Unavailable/ineligible opposite-engine grading parks or blocks visibly.
+- State follows `agent done -> ticket verifying -> completed | retryable | blocked`; max attempts produce a visible block.
+- Completed tickets remain `human_hold`, and trust input can originate only from the protected verdict.
+
+Blocked by: CD-03.
+
+### CD-06 — Real GitHub backlog-to-PR tracer
+
+Use the normal GitHub event path to complete one small ready issue through conductor routing, execution, verification, grade, branch push, and a draft review-ready PR.
+
+Implementation is present locally: human-start authorization, pre-notification
+ticket admission, pinned secret scanning, non-force branch/draft-PR delivery,
+typed-event waiting, and immutable review proof. CD-06 remains open until the
+real provider/GitHub run and exact remote branch/PR/check evidence are captured.
+
+Acceptance:
+
+- One exact issue-to-goal-to-dispatch-to-session-to-commit-to-check-to-grade-to-PR evidence chain is independently replayable.
+- OMS may create/update the isolated branch and draft PR, attach evidence, and report `READY_FOR_HUMAN`; no merge, auto-merge, tag, publish, or release command exists.
+- Fresh GitHub read-back confirms the exact remote branch and draft PR still point at the verified commit; a typed event confirms the named deterministic check passed.
+- A PR/check/review update becomes one deduplicated typed event and causes only a legal state transition.
+- Secrets and raw credentials are absent from argv, tracked files, logs, evidence, and GitHub content.
+- `release status` remains `not_stable`.
+
+Blocked by: CD-04 and CD-05.
+
+### CD-07 — Real elapsed 12-hour canary
+
+Run a same-boot 12-hour goal with multiple short workers, at least one Codex long-goal lane, a grouped team delivery processed by the normal deterministic gate and single grade, quota park/resume, worker failure, conductor resume, GitHub polling, and recovery observation.
+
+Acceptance:
+
+- Wall and same-boot monotonic evidence both reach 12 hours; labels or simulated time do not count.
+- There are no duplicate dispatches, active leases, provider sessions, unverified completions, hidden recoveries, or manual state repairs.
+- A recoverable fault resolves within two watchdog intervals or becomes explicit blocked evidence with no active owner.
+- Independent verification accepts the exact evidence set; PR merge and release remain human-held.
+
+Blocked by: CD-06.
+
+### CD-08 — Fresh elapsed 24-hour canary and closeout
+
+After independent acceptance of CD-07, start a new goal/run/ticket set and execute the same invariants for 24 elapsed hours.
+
+Acceptance:
+
+- The 24-hour run uses fresh goal, run, ticket, dispatch, session, process, and evidence identities.
+- Every CD-07 invariant holds for 24 real elapsed hours.
+- GitHub event, team-delivery, deterministic-verification, and grade evidence are refreshed.
+- Closeout lists proven and unproven obligations without adding a positive release state or automatic merge.
+
+Blocked by: CD-07.
+
+## Dependency graph
+
+```text
+CD-01 conductor + goal
+  -> CD-02 dispatch + states
+    -> CD-03 workers + teams
+      -> CD-04 events + recovery ----+
+      -> CD-05 verify + grade -------+-> CD-06 live GitHub PR
+                                          -> CD-07 12h canary
+                                            -> CD-08 fresh 24h canary
+```
+
+## Removed from the previous roadmap
+
+- Per-ticket human launch ceremonies: the human starts only the conductor.
+- Product-facing external team/goal workflow commands: OMS owns its team and long-worker adapters.
+- Raw conductor tmux commands: provider adapters encapsulate transport.
+- Separate quota, long-goal, and team-proof implementation tracks: each now lands in the vertical slice that consumes it.
+- Custom shell scripts: all tracked deterministic automation remains TypeScript.
+- Separate team-verifier/model-review layers: executor groups feed the same deterministic gate plus one fresh cross-engine grade used by every ticket.
+
+## Global verification gate
+
+Every implementation issue must run targeted tests first, then:
+
+```text
+npm run typecheck
+npm test
+npm run build
+node dist/src/cli.js verify
+git diff --check
+```
+
+Also verify no tracked runtime state or secrets, no tracked shell automation, no product/runtime dependency on another orchestration CLI, and no claim beyond the evidence class.
+
+## Stop conditions
+
+Stop and preserve evidence on unknown provider eligibility or billing, failed auth/version/tool-permission preflight, unavailable mandatory opposite-engine grading, invalid/replayed structured proposal, stale goal/ticket/lease/dispatch/result authority, completion without a valid result receipt, lost/contradictory notification authority, capability expansion, candidate-tree drift, deterministic failure, duplicate owner/start, continuity gap, exhausted attempts, secret finding, branch mismatch, or attempted merge/release authority. Recovery may choose only a path already allowed by the durable policy.