oh-my-super-agent 0.1.0

package/docs/SECURITY.md

@@ -0,0 +1,242 @@
+# Security Model
+
+## Trust boundaries
+
+OMS treats the following as untrusted input:
+
+- GitHub issue titles, bodies, comments, labels, and branch suggestions;
+- model, subagent, grader, and reflection output;
+- tmux pane content and captured terminal output;
+- raw native-hook input and external session metadata;
+- repository content from a ticket branch;
+- environment variables and runtime files not created through the current
+  validated authority.
+
+Untrusted content is data, never command source or a tmux keystroke sequence.
+Typed outbox events and canonical records become trusted only after exact schema,
+identity, version, policy, path, and branded-authority checks.
+
+## Authentication and billing safety
+
+Authentication mode, billing class, overage permission, and unattended
+eligibility are explicitly declared per role. OMS fails closed when a value is
+absent, unknown, or incompatible with an operation.
+
+- Interactive panes must not be used to evade provider billing or automation
+  restrictions.
+- Subscription credentials are used only through provider-supported native
+  application workflows.
+- Programmatic or unattended traffic requires the provider-supported
+  credential and policy for that surface.
+- Secrets are supplied at runtime and are never committed to `.agents/`, logs,
+  evidence, ticket files, Slack request events, or generated service plans.
+- Local verification, tests, HUD, release assessment, and the trace fixture make
+  no paid or live model call.
+
+Provider policy changes over time. Operators must confirm current official
+guidance before a live run; the existence of a local adapter or launch plan is
+not authorization to contact a provider.
+
+## Implemented side-effect boundary
+
+The human starts the read-only conductor with bare `oms`. On the first live run,
+the CLI displays the inferred repository and exact side-effect boundary, then
+requires one matching typed confirmation before initialization or provider
+contact. That repository confirmation creates
+two immutable, session-scoped authorities: the live-delivery authorization and
+a separate pre-dispatch-advice authorization bound to the first authorization,
+conductor session, and repository. Neither can be added to or widened on an
+already-running conductor; the human must exit and run bare `oms` again.
+
+Before that session can commit an accepted dispatch, OMS canonicalizes the
+exact intent, journals the fresh Codex contact, and requires immutable protected
+evidence approving that digest. Revision, veto, missing, tampered, stale, or
+cross-ticket evidence creates no dispatch, worker reservation, delivery event,
+provider probe, or pane. After an approved unchanged dispatch is committed, OMS
+may launch its configured interactive Claude or Codex Goal worker in the
+verified worktree. Lifecycle controls are typed OMS tools; raw tmux is not
+exposed to the conductor.
+
+OMS uses only fixed internal tmux input for provider workspace trust, dispatch-ID
+activation, and native Codex `/goal pause` or `/goal resume`. Ticket text, model
+output, and pane text never enter tmux input. Pane capture and sentinels are
+diagnostic only and cannot acknowledge a dispatch or complete a ticket.
+
+Schedule lifecycle is explicit and user-scoped: OMS can generate, install,
+inspect, or remove only the exact two-job cron, systemd, or launchd plan after
+state/workspace validation. It does not install a daemon or accept arbitrary
+scheduled commands.
+Slack support records a typed notification request only; there is no URL, token,
+HTTP sender, retry worker, or provider delivery receipt. Automatic merge is
+disabled and has no positive enabling state.
+
+Provider launch still requires the operator-originated, repository-authorized
+conductor, an accepted
+dispatch, current policy and subscription eligibility, exact ticket/lease and
+worktree authority, and a reviewed provider argument array. Unknown eligibility
+parks before launch. No worker, Team manifest, or lifecycle tool grants
+verification, trust, merge, or release authority.
+
+GitHub polling has no admission authority. `prepare_dispatch` requires an
+active repository-scoped goal, exact `github:label=oms:ready` membership,
+authorized repository match when live delivery is enabled, selected ticket
+version and content digest, and a subscription executor role. It writes an
+immutable request before worktree/lease mutation and an immutable derived
+intent afterward. Exact replay may recover the gap; nonce reuse, stale ticket
+versions, changed requests, or a conflicting accepted dispatch fail before a
+second advisor contact.
+
+Claude executor panes receive only repository read/edit tools and the
+session-bound OMS worker bridge; Bash, web, subagents, and raw tmux are denied.
+The result tool creates a fixed local git commit with hooks and signing disabled.
+Codex Goal workers keep the provider's native workspace-write sandbox. Each Goal
+session uses a private, strict-config Codex home so unrelated user MCP servers,
+plugins, apps, and configuration are not inherited. OMS does not copy the
+subscription credential: it creates one validated session-private reference to
+the provider's existing native auth file. Ambient `/tmp` and `TMPDIR` writable
+roots are explicitly excluded, even when a test state root is temporary; only
+the exact ticket worktree remains writable. Neither executor receives provider
+credentials as task data or any merge/release tool.
+
+## Command and content safety
+
+- Pass opaque ticket IDs and absolute file paths across subprocess and future
+  tmux boundaries.
+- Never interpolate issue text, model output, pane content, or hook input into
+  `eval`, `sh -c`, command substitutions, branch names, paths, service-manager
+  directives, or tmux key sequences.
+- Construct provider and verification subprocesses with executable-plus-argument
+  arrays and no shell.
+- Require the accepted ticket worktree to match its root, branch, base commit,
+  and a clean tracked/untracked status immediately before provider launch.
+- Use `--` before externally derived positional arguments where supported.
+- Reject identifiers containing path separators, controls, shell
+  metacharacters, or values outside their exact schema.
+- Bound stdin, file, payload, and log sizes and redact credential-shaped values.
+- Do not execute repository-provided hooks or scripts merely because a ticket
+  requests them; verification commands come from reviewed tracked policy.
+
+Prompt injection is an authorization problem: issue or model text cannot widen
+filesystem, network, merge, credential, provider, service, or command authority.
+
+Fresh advisor output is untrusted model data. It may contain only the exact
+intent digest, verdict, summary, recommendations, and risks. OMS owns and binds
+the provider request, fresh-session, contact-journal, and human-authorization
+identities before its protected writer can mint advisor evidence.
+
+## Hook, event, session, and quota safety
+
+`hook ingest` accepts one bounded JSON object from stdin and computes its source
+digest internally. Callers cannot assert their own trusted digest. The projector
+matches session role, engine, mode, run, ticket, native reference, pane ID,
+version, state, timestamp, and event identity before mutation.
+
+The stdin transport is not cryptographically authenticated to a provider in
+this release. It is therefore a local operator/control-plane surface only and
+does not establish live provider provenance or certification.
+
+Event kinds have exact schemas. Immutable outbox events are idempotent per
+identity and consumer receipts bind the operation nonce. A replay returns the
+stored outcome; copied or foreign event buses and authorities are rejected.
+
+Quota evidence is session-bound and freshness-bounded. A quota exhaustion event
+must carry the active ticket's original version, attempt, actor, and lease
+authority. Availability must be newer than the limiting observation and session
+version. Stale, ambiguous, cross-policy, future-dated, or unrelated evidence
+fails closed.
+
+The watchdog can recover an expired lease, mark a missed-heartbeat session
+stalled, supersede a dead waiter, repair the typed receipt/notification for an
+exact waiting structured-role result, explicitly recover that request's exact
+dead projector-lock generation, and resume the same proven dead conductor. It
+may wake only a proven idle pane with an opaque notification ID;
+it cannot interrupt working state, perform ordinary routing, send raw model
+content, send Slack, or turn a stalled report into successful external
+delivery.
+
+## Filesystem and concurrency safety
+
+- Resolve and validate `OMS_STATE_ROOT` as an absolute path before use.
+- Reject empty, root, home, repository-root, or otherwise unsafe state roots.
+- Prevent traversal, no-follow violations, and symlink swaps at canonical runtime
+  paths. The sole deliberate runtime symlink is the private Codex auth reference;
+  its exact regular-file target is revalidated before launch and it is never read
+  as OMS state or evidence.
+- Create sensitive runtime directories and files with restrictive permissions.
+- Use same-filesystem temporary files, atomic rename, expected versions,
+  nonces, and exclusive locks for mutable state.
+- Validate durable JSON against its schema before and after a transition.
+- Write evidence, manifests, decisions, plans, and receipts immutably; a replay
+  must match existing bytes.
+- Treat stale-lock recovery and lease expiry as explicit auditable operations.
+
+Cleanup commands must prove that their target is below the validated state root
+and must never follow an untrusted path recursively.
+
+## Git and worktree safety
+
+- One traced ticket uses one dedicated opaque branch and worktree.
+- Branch names derive from validated identifiers, not issue titles.
+- Preserve unrelated workspace changes.
+- Do not force-push, rewrite shared history, publish a remote, or merge without
+  explicit operator authority.
+- Deterministic verification runs before supplemental grading.
+- A completed local ticket remains `human_hold`; trust reporting cannot change
+  that disposition.
+
+A future merge gate would require deterministic checks, provenance, trust
+evidence, executor-group evidence, and an explicit
+idempotent reviewed transition. None is inferred from local test success.
+
+Passing live GitHub results may enter one fixed review-delivery authority. It
+accepts only the exact protected result chain, validates the local `origin`,
+runs pinned redacted Gitleaks scans over the commit range, tracked worktree,
+immutable evidence, canonical issue content, fixed argv, and draft-PR content,
+then pushes the verified commit without force and creates at most one draft PR.
+Fresh GraphQL readback must show the exact remote branch and draft PR still bind
+the verified commit; a typed check event must show the named deterministic check passed. Raw scanner
+reports are always removed; durable scan and contact records retain digests,
+not secrets or response bodies.
+
+## Doctor, probes, runs, and release evidence
+
+Offline `doctor` checks local executables, configuration, schemas, paths,
+permissions, and git prerequisites. Tests and `verify` remain deterministic and
+network-free.
+
+The GitHub queue probe remains a separately confirmed diagnostic contact. The
+first normal live path is interactive bare `oms`. It infers the GitHub
+repository when possible and requires the human to type the displayed
+repository-scoped authorization phrase. That start creates both the immutable
+live-delivery authorization and its separately validated pre-dispatch-advice
+authorization. Later bare invocations reuse those session-scoped authorities;
+no invocation widens a running session, and non-interactive bare invocation
+contacts no provider. The explicit `oms conductor start` form remains an
+advanced recovery/state-root override. Advisor, worker, grade, reflection,
+GitHub sync, review-read,
+branch-push, and draft-PR contacts each write a digest-only disclosure before
+contact. None grants merge or release authority, and this repository still
+contains no claimed completed live proof.
+
+`run start --for 12h|24h` creates a non-certifying audit manifest; the label
+does not prove elapsed runtime. Manifests freeze `provider_started: false`,
+manual start required, `release: not_stable`, and human hold. `release status`
+can express only the negative assessment and cannot ingest flags or evidence to
+promote itself.
+
+Run admission binds ticket content and policy, not only IDs. Native hooks,
+scheduler resumes, watchdog recovery, and terminal operations serialize through
+the controller lock and append continuity-aware audit events. Terminal status
+is accepted only with the exact immutable controller payload and proof/reason
+artifact. Timed close remains audit-only. Crashed controller-lock recovery is a
+separate explicit command requiring the exact generation and refusing a live
+owner process.
+
+## Incident posture
+
+On invalid state, a lease conflict, stale authority, unknown authentication,
+suspected injection, credential exposure, outbox conflict, goal mismatch, or
+verification ambiguity, OMS stops the affected transition and preserves
+evidence. Recovery uses a new audited operation or explicit reconciliation; it
+does not rewrite history, fabricate completion, certify a canary, or mark the
+release stable.

package/docs/adr/0001-tracer-first-file-backed-certification.md

@@ -0,0 +1,41 @@
+# ADR 0001: Tracer-first, file-backed certification
+
+## Status
+
+Accepted; branch-protection requirements removed by operator decision on 2026-07-12.
+
+## Context
+
+OMS must coordinate ticket work for long periods without becoming a second agent runtime. Its decisions must survive process restarts, remain auditable, and fail closed when execution, verification, quota, remote-identity, or provider evidence is missing. A background service or database would add another authority before the file-backed tracer has proved insufficient.
+
+Release certification also needs evidence from real elapsed operation. Fast-forwarded clocks, mocked timers, and a model's claim that a run completed cannot certify endurance.
+
+## Decision
+
+OMS is tracer-first. One ticket is followed through its durable lifecycle, and each consequential transition is justified by immutable, schema-validated evidence stored under the runtime root.
+
+V1 uses tracked JSON policy and file-backed runtime records. It adds no daemon and no database. Native completion hooks and outbox events drive normal progress; the 15-minute heartbeat and watchdog are recovery mechanisms only. Recovery stops after two unsuccessful heartbeats and requires operator attention.
+
+Merges remain human-held. Automatic merge is disabled and OMS exposes no merge or ready-for-review mutation. Server-side branch protection is not an OMS dependency; repository administrators remain responsible for any controls outside OMS.
+
+Release certification requires manually attested, real elapsed canaries in this order: a 12-hour run, followed by a fresh 24-hour run. The 24-hour canary cannot reuse the 12-hour process, session, lease, or elapsed-time claim.
+
+## Alternatives
+
+- A custom orchestration daemon was rejected because native hooks and one-shot commands cover normal flow while a heartbeat covers recovery.
+- A database-backed queue was rejected because atomic, locked file records are sufficient for the current single-host boundary and are easier to audit and recover.
+- Polling as the normal execution path was rejected because it duplicates native completion signals and makes latency and failure ownership less clear.
+- Automatic merge after deterministic checks was rejected because verification success alone does not prove human review authority, provenance, or endurance certification.
+- Simulated or accelerated canaries were rejected because they do not demonstrate real quota windows, process recovery, or elapsed-time stability.
+
+## Consequences
+
+Runtime behavior remains inspectable with ordinary file and Git tools, and each release claim can be traced to immutable evidence. Normal operation does not depend on a resident OMS process. Deterministic recovery is deliberately bounded and may park work for human review instead of guessing.
+
+This design accepts lower throughput and manual merge latency in exchange for a smaller authority surface. OMS itself refuses force-push and merge operations, but without server-side branch protection it cannot prevent repository administrators or other credentials from changing remote history. File-backed coordination remains limited to the reviewed single-host concurrency model; evidence compaction or distributed coordination would require a new decision.
+
+## Follow-ups
+
+- Run and manually attest a real elapsed 12-hour canary.
+- Start a fresh run and manually attest a real elapsed 24-hour canary only after the 12-hour canary passes.
+- Revisit a daemon, database, or automatic merge only through a superseding ADR backed by observed tracer limitations and new deterministic gates.

package/docs/adr/0002-conductor-first-typed-dispatch.md

@@ -0,0 +1,102 @@
+# ADR: Conductor-First Typed Dispatch Authority
+
+Status: Accepted on 2026-07-11; bridge counts and dispatch admission are superseded by ADR 0003.
+
+## Context
+
+OMS already has a TypeScript, file-backed queue/control/evidence foundation, bounded provider hooks, reconciliation, worktrees, role policy, a local tracer, and a negative-only release assessment. It does not yet run the desired live product flow.
+
+The required operator experience is one human-started persistent Claude Opus conductor in tmux. The human types the goal once; the read-only conductor then routes work across configured Claude and Codex lanes. OMS must observe provider and GitHub changes, survive restarts and quota pauses, and prepare verified pull requests without becoming a daemon or granting models merge/release authority.
+
+The previous operator-first design required a human start ceremony for every worker and emitted product instructions for an external team runtime. That does not satisfy the desired OMS-owned conductor loop.
+
+## Decision
+
+V1 uses a conductor-first, typed-dispatch architecture:
+
+1. A human runs interactive bare `oms` to create or resume an interactive read-only Claude Opus conductor in the OMS tmux session. On the first live run, the CLI obtains one exact repository-scoped human confirmation before state initialization or provider contact. The explicit `oms conductor start` form remains only for advanced recovery or a selected state root; non-interactive bare invocation prints help and contacts no provider.
+2. The human enters a freeform goal. CD-01 begins with exactly two proposal tools on the session-scoped local stdio `oms conductor bridge`: `mcp__oms__propose_goal` and `mcp__oms__propose_dispatch`. The goal tool validates and atomically commits durable objective, scope, stopping condition, horizon, and budget/policy state. The dispatch tool is initially advertised and schema-valid but deterministically returns `dispatch-not-enabled` with no mutation.
+3. CD-02 activates that same dispatch handler without adding tools or permissions. Every worker assignment then becomes a validated, persisted OMS envelope bound to exact goal, ticket, lease, attempt, role/model, provider eligibility, worktree, capabilities, budget, acceptance/evidence requirements, and nonce before delivery. Freeform content never enters argv, a shell, or file Write.
+4. CD-03 adds exactly two narrow control tools: `mcp__oms__manage_worker` for observe/park/resume/stop and `mcp__oms__start_team` for grouping already accepted dispatch IDs. The complete conductor bridge therefore has four tools: two proposal tools and two fixed-action controls. It exposes no generic shell, filesystem, tmux, provider, GitHub, verification, merge, or release authority.
+5. OMS provider adapters start and observe interactive Claude workers, resumable Codex Goal workers, and eligible fresh read-only exec roles. Worker sessions require an explicitly reviewed `operator_originated_oms_managed_interactive` policy; legacy per-worker human-start flags are not silently reinterpreted. Direct tmux operations are encapsulated; the conductor cannot invoke them.
+6. Provider hooks drive immediate session/activity/health/completion-observed/quota observations. Completion hooks cannot set `agent=done` or `ticket=verifying`; only one dispatch-bound typed result receipt can. A one-shot GitHub sync runs every 60 seconds by default. Projected events form opaque notification batches, and a version-pinned `asyncRewake` waiter wakes an idle conductor to re-read canonical state. Waiter generations are durable CAS records bound to conductor session/process identity. The 15-minute watchdog is the sole dead-waiter recovery owner: it may resume/respawn only a proven idle/dead conductor so `SessionStart` re-arms, never interrupt active work, and otherwise record visible stalled/blocked state.
+7. Deterministic verification is the final vote. Exactly one fresh opposite-engine grade is mandatory and supplemental. An unavailable/ineligible opposite engine parks or blocks visibly; bounded reflection/retry cannot bypass attempts or verification.
+8. OMS may push isolated branches, open/update draft pull requests, attach evidence, and report `READY_FOR_HUMAN`. Only a human may merge, tag, publish, or release.
+
+## Simplicity boundary
+
+- Native primitives provide provider sessions, local stdio MCP tools, `asyncRewake` hooks, tmux, worktrees, GitHub access, and scheduling.
+- Skills define conductor, worker, advisor, grader, reflection, quota, schedule, and team behavior.
+- Small Node.js/TypeScript commands provide the four-tool session bridge, state, dispatch, adapters, event synchronization, generation-safe notification waiting, watchdog recovery, verification, and evidence.
+- V1 adds no daemon, database, framework, webhook listener, custom mux library, tracked shell automation, or general workflow engine.
+- A team is only a group of executor dispatches. V1 uses one deterministic review gate followed by one fresh structured cross-engine grade; teams add no second verifier/model-review lane.
+
+## Authority boundary
+
+The conductor may prioritize eligible tickets, select configured roles/lanes, ask for advice or grading, launch/observe/park/resume/stop workers through OMS, and select a legal retry or escalation.
+
+The conductor may not edit product code or canonical state, modify durable policy, widen goal scope silently, introduce providers/models/credentials/spend classes, issue raw tmux commands, override verification or stale authority, exceed attempts/budget, merge, publish, release, or claim stability. It has no Edit/Write permission. Freeform goal and task proposals use only the two proposal tools; worker lifecycle and team grouping use the two narrow control tools with opaque canonical IDs. All other access is read-only diagnostics.
+
+Workers may mutate only their isolated ticket worktrees and may acknowledge/return results only for their dispatch. They cannot write goal, verification, trust, queue, merge, or release authority.
+
+OMS owns durable goal, ticket, lease, dispatch, worker/session, event, quota, verification, evidence, attempt, audit, and human-hold state.
+
+## State semantics
+
+- Agent activity: `idle | working | blocked | done`
+- Agent health: `healthy | parked | stalled | stopped`
+- Ticket lifecycle: `pending | leased | running | verifying | completed | retryable | parked | blocked`
+
+`agent=done` means one schema-valid result receipt bound to the current goal, dispatch, attempt, lease, session, worktree, and commit arrived. It moves the ticket to `verifying`; only protected deterministic evidence plus the mandatory opposite-engine grade may complete it.
+
+## Security boundary
+
+- Raw issue, comment, review, provider, hook, pane, and model text is untrusted content and never becomes a command or authority.
+- Freeform goal/task text crosses only the two proposal tools. CD-01 can mutate only goal authority while dispatch remains `dispatch-not-enabled`; CD-02 activates dispatch; CD-03 adds two schema-bound lifecycle/team controls that accept canonical IDs and bounded control fields. The bridge rejects oversize/non-schema input, stale authority, capability expansion, changed identity, and replay before canonical mutation and exposes no ambient filesystem/shell/provider/GitHub/verification/merge/release capability.
+- Dispatch, hook, event, result, and evidence identities are replay-safe and exact-version bound.
+- One expected-version/nonce waiter generation is active per conductor session/process. Dead-waiter recovery is watchdog-owned; duplicate recovery, PID reuse, unsafe resume, or lost notification fails visible rather than widening authority.
+- Hook completion is observational only. Missing/stale/cross-dispatch result receipts cannot create `done` or `verifying` state regardless of event order.
+- Pane text and sentinels are diagnostic only.
+- Candidate code cannot replace the installed verifier, frozen plan, policy snapshot, or evidence writer.
+- Unknown provider/auth/billing/version eligibility, credential widening, stale authority, or deterministic failure stops the path.
+- Hook/receipt evidence proves the documented local OMS continuity boundary, not cryptographic provider attestation.
+
+## Alternatives
+
+### Human starts every worker
+
+Rejected. It preserves a narrow operator boundary but fails the intended experience that the human starts only the conductor.
+
+### Raw conductor-driven tmux commands
+
+Rejected. It exposes brittle TUI transport and injection risk as public authority. OMS adapters may use tmux internally with typed validated inputs.
+
+### Path-scoped proposal files
+
+Rejected. A session-scoped stdio bridge keeps Edit/Write entirely disabled and passes freeform proposal fields through native JSON tool input instead of relying on dynamic filesystem permissions.
+
+### Custom orchestration service
+
+Rejected. Native CLIs, skills, one-shot commands, tmux, hooks, and user schedulers cover v1.
+
+### Webhook server
+
+Deferred. Sixty-second polling with durable watermarks is sufficient for v1 and avoids a listener/secret/deployment boundary.
+
+### Automatic merge or release
+
+Rejected for v1. It requires endurance evidence, explicit trust policy, and a separate reviewed ADR.
+
+## Consequences
+
+- The first human action remains explicit and visible.
+- The conductor can behave agentically without owning deterministic authority.
+- OMS must keep the four-tool session bridge narrow, implement one generation-safe event waiter with watchdog-owned recovery, and retain small provider/pane and schedule boundaries.
+- The operator-originated OMS-managed interactive worker policy must be checked against current official provider policy and CLI behavior; it remains distinct from headless/unattended eligibility and fails closed when uncertain.
+- Long runs depend on durable state, hooks, polling, and recovery rather than model context.
+- A successful run ends at a verified review-ready PR and negative-only release assessment.
+
+## Follow-ups
+
+- Promote this ADR and add a regression test in CD-01.
+- Consider webhooks, additional schedulers, automatic merge, package release, or unattended credential lanes only through separate reviewed changes after the 12-hour and fresh 24-hour proofs.

package/docs/adr/0003-mandatory-pre-dispatch-advice.md

@@ -0,0 +1,59 @@
+# ADR: Mandatory Pre-Dispatch Advice Authority
+
+Status: Accepted on 2026-07-13.
+
+## Context
+
+ADR 0002 established a read-only conductor and typed dispatch boundary, but an
+instruction to request advice was only prompt policy. Prompt policy cannot prove
+that a fresh advisor reviewed the exact executor-affecting intent, prevent advice
+from being reused after a change, or stop direct dispatch when the advisor
+recommends revision or vetoes the work.
+
+OMS needs mandatory cross-engine advice without adding a daemon, a generic
+command tool, or model-owned authority.
+
+## Decision
+
+1. The conductor bridge exposes version-bound `mcp__oms__prepare_dispatch`
+   followed by distinct `mcp__oms__advise_dispatch` before
+   `mcp__oms__propose_dispatch`. The complete bridge has seven narrow tools.
+2. Advice accepts the distinct dispatch-intent schema. OMS canonicalizes every
+   executor-affecting field, including the operation nonce, and computes the
+   exact SHA-256 digest.
+3. A fresh Codex contact requires a separate human-confirmed pre-dispatch-advice
+   authorization bound to the live-delivery authorization, conductor session,
+   and repository. OMS journals the contact before launching the provider.
+4. Model output contains only the intent digest, `approve | revise | veto`,
+   summary, recommendations, and risks. OMS owns provider-request,
+   fresh-session, contact-reference, and authorization identities and mints the
+   protected immutable evidence.
+5. Advice operations persist `prepared -> contacting -> completed | blocked`.
+   The contacting claim includes its OMS Linux process identity (PID, boot ID,
+   and process start ticks). A live owner remains in progress without mutation;
+   a dead, restarted, or PID-reused owner is ambiguous and never causes an
+   automatic second provider launch. At most three unique intents may be
+   advised for one ticket attempt. Only one intent for that ticket attempt and
+   lease may be prepared or contacting at a time.
+   A veto is terminal for the ticket attempt and lease. After `revise`, another
+   contact requires a substantive canonical-intent change; changing only the
+   operation nonce is not a revision.
+6. Dispatch admission recomputes the intent digest and requires exact immutable
+   `approve` evidence for the unchanged ticket and intent before creating a
+   dispatch record, worker reservation, or delivery event.
+7. The accepted dispatch stores the intent digest and evidence reference.
+   Worker delivery independently validates both before any provider probe or
+   pane creation. Historical resolved records remain readable; unresolved
+   historical records without this authority cannot advance.
+
+## Consequences
+
+- Advice is mandatory authority, not an optional prompt convention.
+- Any substantively revised intent requires fresh advice; veto, nonce-only
+  resubmission, missing evidence, tampering, replay ambiguity, or changed
+  authority fails closed.
+- Deterministic verification remains the final vote after execution, and the
+  opposite-engine grader remains supplemental.
+- The conductor remains read-only and agentic through seven narrow tools. OMS
+  still adds no daemon, generic workflow engine, shell tool, or merge/release
+  authority.

package/docs/compatibility/claude-code-2.1.207.md

@@ -0,0 +1,25 @@
+# Claude Code 2.1.207 conductor compatibility proof
+
+Date: 2026-07-11
+Scope: CD-01, human-started interactive conductor only
+
+## Environment
+
+- Claude Code `2.1.207` using first-party Claude Max subscription auth
+- tmux `3.6`
+- OMS launched with `bin/oms conductor start`; no print/headless Claude mode
+- Model resolved from policy to Opus; Fable was shown only as an optional Claude UI notice and was not selected
+
+## Observed results
+
+1. The command created the `oms:conductor` pane and attached an interactive TTY.
+2. `/mcp` showed exactly one server, `oms`, connected with two tools. The launch uses `--strict-mcp-config` and `--no-chrome`.
+3. `propose_goal` persisted a version-0 canonical goal containing repository/queue scope, stopping condition, `until-empty`, `subscription-only`, `default`, and a stable nonce.
+4. The literal objective text `$(touch /tmp/oms-conductor-injection)` remained data. The named file was not created.
+5. A schema-valid `propose_dispatch` call returned `{"status":"dispatch-not-enabled"}` and created no ticket, lease, worker, or worktree state.
+6. After killing and recreating the tmux session, `oms conductor start` reused the persisted Claude session UUID and resumed the prior conversation.
+7. The launch advertises only `Read`, `Glob`, `Grep`, `mcp__oms__propose_goal`, and `mcp__oms__propose_dispatch`; provider-plan tests reject Edit, Write, Bash, raw tmux, web, agent, print, and background authority.
+
+The smoke exposed one real-client detail before passing: Claude Code includes an MCP `_meta` envelope on tool calls. OMS now accepts that protocol metadata while continuing to validate the tool payload against a closed schema.
+
+This is compatibility evidence for the pinned version, not a general certification of later Claude Code versions, billing behavior, unattended execution, worker dispatch, merge, or release readiness.

package/loop/contract.md

@@ -0,0 +1,102 @@
+# OMS Runtime Contract
+
+This contract describes the implemented local TypeScript control plane. It does
+not certify a live provider run, unattended endurance, or production readiness.
+
+## MUST
+
+- Keep `.agents/` as the tracked source of truth and preserve user-owned text
+  around generated managed blocks.
+- Keep runtime automation in Node.js/TypeScript; do not add tracked shell
+  automation scripts as an orchestration layer.
+- Initialize runtime data only below one validated absolute state root with
+  restrictive permissions. Make `init` idempotent and read-only surfaces
+  non-creating.
+- Keep `doctor`, `verify`, tests, HUD, release status, and the local trace fixture
+  offline and deterministic.
+- Keep raw ticket content in immutable blobs and pass only opaque IDs or
+  absolute file paths across process and future tmux boundaries.
+- Require expected versions, attempts, actors, operation nonces, and lease
+  tokens at ticket mutation boundaries.
+- Validate exact event schemas and consume immutable outbox events through
+  idempotent per-consumer receipts.
+- Bind session and quota changes to canonical hook events, session versions,
+  timestamps, policy identity, and active ticket authority.
+- Let deterministic verification vote before and finally; treat grader output as
+  supplemental evidence only.
+- Keep trust reports review-only and derive canonical trust runs only from live,
+  ticket-bound deterministic evidence.
+- Keep one canonical OMS goal record; treat native goal, Team, Ultragoal, HUD,
+  and report state as checkpoint evidence or projections.
+- Persist audit manifests, conductor decisions, goal artifacts, Team plans, and
+  service plans immutably and reject conflicting replay.
+- Freeze complete ticket admission identity before starting an audit; require
+  immutable completion evidence, continuity-safe run events, and an explicit
+  exact-generation operation for crashed controller-lock recovery.
+- Keep the initial conductor session human-started. Launch executor panes only
+  from accepted dispatch delivery after fresh policy, provider, ticket, and
+  worktree checks.
+- Admit open ready GitHub tickets before notifying the conductor. Keep role,
+  model, task, and routing judgment in the conductor skill, not the admission
+  command.
+- Journal every authorized provider/GitHub contact before contact. After a
+  protected pass, permit only the fixed secret-scanned non-force branch and
+  draft-PR handoff, then wait for typed PR/check events before
+  `READY_FOR_HUMAN`.
+- Keep all merge dispositions on human hold and release status fixed to the
+  negative-only `not_stable` schema.
+- Require a named live confirmation to persist contact/spend disclosure before
+  any provider or GitHub contact.
+
+## MUST NOT
+
+- Contact a provider or GitHub from `doctor`, `verify`, tests, HUD, release
+  status, the trace fixture, or any command without an explicit named live
+  confirmation.
+- Use interactive panes to evade metering, authentication, usage limits, or
+  provider policy.
+- Evaluate untrusted text or send raw issue/model content as tmux keystrokes,
+  shell source, service-manager source, a branch name, or a path.
+- Let an unaccepted conductor decision invoke a provider, pass untrusted content
+  through tmux keys, or claim delivery without a bound receipt.
+- Install, enable, start, stop, or remove generated cron, systemd, or launchd
+  artifacts.
+- Send Slack messages or interpret a request-only event as delivery evidence.
+- Let the watchdog resume quota-parked work, retry an external provider, or
+  convert a stall report into success.
+- Let a grader, trust assessment, HUD, Team plan, or goal projection grant queue,
+  execution, release, or merge authority.
+- Claim a live GitHub ticket, elapsed canary, provider session, executor-group
+  checkpoint, or stable release without independent matching
+  evidence.
+- Merge automatically, overwrite active queue state from GitHub, or parse a
+  positive release state in the current release.
+- Mark a draft ready-for-review, merge, force-push, tag, publish, or release
+  through the review-delivery path.
+
+## IMPLEMENTATION DONE WHEN
+
+- `make verify` passes from a clean checkout with no network or provider call.
+- Unsafe state roots are rejected and read-only commands do not create missing
+  runtime state.
+- Generated `AGENTS.md`, `CLAUDE.md`, native agents, and skills are idempotent
+  while preserving user-owned content.
+- The offline ticket fixture reaches human-held completion with deterministic
+  evidence before supplemental grading and without tracked source mutation.
+- Duplicate hook, outbox, queue, scheduler, watchdog, audit, goal, trust, and
+  Team operations replay or fail closed according to their authority.
+- Service artifacts are generated immutably but never installed; audit runs and
+  conductor routes remain truthful about whether an accepted dispatch produced
+  a provider delivery receipt.
+- HUD and release status remain read-only and report `not_stable`.
+- Runtime, secret, temporary, and log files remain untracked.
+
+## RELEASE REMAINS BLOCKED UNTIL
+
+- one real live GitHub ticket has reviewed evidence;
+- an elapsed 12-hour canary and a fresh elapsed 24-hour canary have reviewed
+  evidence;
+- a real executor-group delivery plus normal per-ticket deterministic checks and
+  opposite-engine grade are captured; and
+- a future reviewed positive-release design, if one is wanted, explicitly
+  grants authority. The current implementation intentionally cannot do so.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "oh-my-super-agent",
+  "version": "0.1.0",
+  "description": "A simple-first harness for supported Claude Code and Codex CLI ticket workflows.",
+  "type": "module",
+  "homepage": "https://www.npmjs.com/package/oh-my-super-agent",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {},
+  "bin": {
+    "oh-my-super-agent": "dist/src/cli.js",
+    "oms": "dist/src/cli.js"
+  },
+  "files": [
+    ".agents",
+    "dist",
+    "docs/ARCHITECTURE.md",
+    "docs/PLAN.md",
+    "docs/REFERENCES.md",
+    "docs/ROADMAP.md",
+    "docs/SECURITY.md",
+    "docs/adr",
+    "docs/compatibility",
+    "loop",
+    "schemas",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit",
+    "test": "npm run build && vitest run",
+    "verify": "npm run typecheck && npm test && node dist/src/cli.js verify",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run verify"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "agents",
+    "claude-code",
+    "codex",
+    "orchestration",
+    "tmux"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^26.0.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  }
+}