oh-my-super-agent 0.1.0

package/dist/src/worktrees/manager.js

@@ -0,0 +1,315 @@
+import { existsSync, lstatSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, normalize } from "node:path";
+import { acquireDirectoryLock } from "../runtime/lock.js";
+import { assertActorId, assertOpaqueId, assertTransitionNonce } from "../domain/records.js";
+import { isRecord, readJsonFileNoFollow, validateExistingDirectory, writeJsonAtomic, } from "../utils/fs.js";
+const COMMIT_PATTERN = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const BASE_REF_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,254}$/;
+const GIT_TIMEOUT_MS = 30_000;
+const GIT_MAX_BUFFER_BYTES = 256 * 1024;
+/**
+ * Creates one isolated branch/worktree. This boundary deliberately has no merge
+ * or removal operation: cleanup and integration remain explicit operator acts.
+ */
+export function createTicketWorktree(options) {
+    const ticketId = assertOpaqueId(options.ticketId, "ticket id");
+    const actorId = assertActorId(options.actorId, "worktree actor id");
+    const transitionNonce = assertTransitionNonce(options.transitionNonce, "worktree transition nonce");
+    const requestedBase = validateBaseRef(options.baseRef ?? "HEAD");
+    const repositoryRoot = validateExistingDirectory(options.repositoryRoot, "repository root");
+    const worktreesRoot = validateExistingDirectory(options.worktreesRoot, "worktrees root");
+    const recordsRoot = validateExistingDirectory(options.recordsRoot, "worktree records root");
+    const locksRoot = validateExistingDirectory(options.locksRoot, "locks root");
+    const worktreesRootIdentity = captureDirectoryIdentity(worktreesRoot);
+    const recordsRootIdentity = captureDirectoryIdentity(recordsRoot);
+    const worktreeRoot = join(worktreesRoot, ticketId);
+    const recordPath = join(recordsRoot, `${ticketId}.json`);
+    const intentPath = join(recordsRoot, `${ticketId}.intent.json`);
+    const branch = `oms-ticket-${ticketId}`;
+    const env = safeGitEnvironment(options.env ?? process.env);
+    assertRepositoryRoot(repositoryRoot, env, options.runner);
+    const readCompletedReplay = () => {
+        validateDirectoryIdentity(worktreesRootIdentity, "worktrees root");
+        validateDirectoryIdentity(recordsRootIdentity, "worktree records root");
+        if (!existsSync(recordPath))
+            return undefined;
+        const record = parseTicketWorktreeRecord(readJsonFileNoFollow(recordPath), recordPath);
+        validateDirectoryIdentity(recordsRootIdentity, "worktree records root");
+        const intent = readRequiredRecord(intentPath, recordsRootIdentity, "worktree create intent");
+        assertRecordsEqual(intent, record, "worktree record does not match its create intent");
+        assertReplayMatches(record, {
+            ticketId,
+            repositoryRoot,
+            worktreeRoot,
+            branch,
+            requestedBase,
+            transitionNonce,
+        });
+        assertMaterializedWorktree(record, env, options.runner);
+        validateDirectoryIdentity(worktreesRootIdentity, "worktrees root");
+        return { record, replayed: true, recovered: false };
+    };
+    const completedReplay = readCompletedReplay();
+    if (completedReplay)
+        return completedReplay;
+    const lock = acquireDirectoryLock({
+        locksRoot,
+        lockId: `worktree-${ticketId}`,
+        ownerId: actorId,
+        note: ticketId,
+    });
+    try {
+        validateDirectoryIdentity(worktreesRootIdentity, "worktrees root");
+        validateDirectoryIdentity(recordsRootIdentity, "worktree records root");
+        const lockedReplay = readCompletedReplay();
+        if (lockedReplay)
+            return lockedReplay;
+        if (existsSync(intentPath)) {
+            const intent = readRequiredRecord(intentPath, recordsRootIdentity, "worktree create intent");
+            assertReplayMatches(intent, {
+                ticketId,
+                repositoryRoot,
+                worktreeRoot,
+                branch,
+                requestedBase,
+                transitionNonce,
+            });
+            validateDirectoryIdentity(worktreesRootIdentity, "worktrees root");
+            if (existsSync(worktreeRoot)) {
+                const entry = lstatSync(worktreeRoot);
+                if (entry.isSymbolicLink())
+                    throw new Error(`worktree path collision is a symbolic link: ${ticketId}`);
+                assertMaterializedWorktree(intent, env, options.runner, true);
+            }
+            else {
+                assertBranchAbsent(repositoryRoot, branch, env, options.runner);
+                addWorktree(repositoryRoot, intent, env, options.runner);
+                validateDirectoryIdentity(worktreesRootIdentity, "worktrees root");
+                assertMaterializedWorktree(intent, env, options.runner, true);
+            }
+            persistNewRecord(recordPath, intent, recordsRootIdentity, "worktree record");
+            return { record: intent, replayed: false, recovered: true };
+        }
+        if (existsSync(worktreeRoot)) {
+            const entry = lstatSync(worktreeRoot);
+            if (entry.isSymbolicLink())
+                throw new Error(`worktree path collision is a symbolic link: ${ticketId}`);
+            throw new Error(`worktree path collision without a create intent: ${ticketId}`);
+        }
+        const baseCommit = resolveCommit(repositoryRoot, requestedBase, env, options.runner);
+        assertBranchAbsent(repositoryRoot, branch, env, options.runner);
+        validateDirectoryIdentity(worktreesRootIdentity, "worktrees root");
+        validateDirectoryIdentity(recordsRootIdentity, "worktree records root");
+        const record = {
+            schema_version: 1,
+            ticket_id: ticketId,
+            repository_root: repositoryRoot,
+            worktree_root: worktreeRoot,
+            branch,
+            requested_base: requestedBase,
+            base_commit: baseCommit,
+            create_nonce: transitionNonce,
+        };
+        persistNewRecord(intentPath, record, recordsRootIdentity, "worktree create intent");
+        addWorktree(repositoryRoot, record, env, options.runner);
+        validateDirectoryIdentity(worktreesRootIdentity, "worktrees root");
+        validateDirectoryIdentity(recordsRootIdentity, "worktree records root");
+        assertMaterializedWorktree(record, env, options.runner, true);
+        persistNewRecord(recordPath, record, recordsRootIdentity, "worktree record");
+        return { record, replayed: false, recovered: false };
+    }
+    finally {
+        lock.release();
+    }
+}
+function addWorktree(repositoryRoot, record, env, runner) {
+    runGit(repositoryRoot, [
+        "-c",
+        "core.hooksPath=/dev/null",
+        "worktree",
+        "add",
+        "-b",
+        record.branch,
+        record.worktree_root,
+        record.base_commit,
+    ], env, runner, "git worktree add");
+}
+function persistNewRecord(path, record, recordsRootIdentity, label) {
+    parseTicketWorktreeRecord(record);
+    validateDirectoryIdentity(recordsRootIdentity, "worktree records root");
+    if (existsSync(path))
+        throw new Error(`${label} path collision`);
+    writeJsonAtomic(path, record);
+    validateDirectoryIdentity(recordsRootIdentity, "worktree records root");
+    const stored = parseTicketWorktreeRecord(readJsonFileNoFollow(path), path);
+    validateDirectoryIdentity(recordsRootIdentity, "worktree records root");
+    assertRecordsEqual(stored, record, `stored ${label} does not match input`);
+}
+function readRequiredRecord(path, recordsRootIdentity, label) {
+    validateDirectoryIdentity(recordsRootIdentity, "worktree records root");
+    if (!existsSync(path))
+        throw new Error(`${label} is missing`);
+    const record = parseTicketWorktreeRecord(readJsonFileNoFollow(path), path);
+    validateDirectoryIdentity(recordsRootIdentity, "worktree records root");
+    return record;
+}
+function assertRecordsEqual(left, right, message) {
+    if (JSON.stringify(left) !== JSON.stringify(right))
+        throw new Error(message);
+}
+export function parseTicketWorktreeRecord(value, label = "worktree record") {
+    if (!isRecord(value))
+        throw new Error(`${label} must be an object`);
+    const expectedKeys = new Set([
+        "schema_version",
+        "ticket_id",
+        "repository_root",
+        "worktree_root",
+        "branch",
+        "requested_base",
+        "base_commit",
+        "create_nonce",
+    ]);
+    for (const key of Object.keys(value)) {
+        if (!expectedKeys.has(key))
+            throw new Error(`${label} has unexpected property: ${key}`);
+    }
+    if (value.schema_version !== 1)
+        throw new Error(`${label} schema_version must be 1`);
+    if (typeof value.repository_root !== "string" || typeof value.worktree_root !== "string") {
+        throw new Error(`${label} paths must be strings`);
+    }
+    if (!isAbsolute(value.repository_root)
+        || !isAbsolute(value.worktree_root)
+        || normalize(value.repository_root) !== value.repository_root
+        || normalize(value.worktree_root) !== value.worktree_root) {
+        throw new Error(`${label} paths must be normalized absolute paths`);
+    }
+    if (typeof value.branch !== "string")
+        throw new Error(`${label} branch must be a string`);
+    const requestedBase = validateBaseRef(value.requested_base);
+    if (typeof value.base_commit !== "string" || !COMMIT_PATTERN.test(value.base_commit)) {
+        throw new Error(`${label} base_commit is invalid`);
+    }
+    const ticketId = assertOpaqueId(value.ticket_id, "worktree record ticket id");
+    const record = {
+        schema_version: 1,
+        ticket_id: ticketId,
+        repository_root: value.repository_root,
+        worktree_root: value.worktree_root,
+        branch: value.branch,
+        requested_base: requestedBase,
+        base_commit: value.base_commit,
+        create_nonce: assertTransitionNonce(value.create_nonce, "worktree record create nonce"),
+    };
+    if (record.branch !== `oms-ticket-${ticketId}`)
+        throw new Error(`${label} branch does not match ticket id`);
+    if (record.worktree_root !== join(dirname(record.worktree_root), ticketId)) {
+        throw new Error(`${label} path does not match ticket id`);
+    }
+    return record;
+}
+function assertReplayMatches(record, expected) {
+    if (record.ticket_id !== expected.ticketId
+        || record.repository_root !== expected.repositoryRoot
+        || record.worktree_root !== expected.worktreeRoot
+        || record.branch !== expected.branch
+        || record.requested_base !== expected.requestedBase
+        || record.create_nonce !== expected.transitionNonce) {
+        throw new Error(`worktree replay does not match the committed record: ${expected.ticketId}`);
+    }
+}
+function validateBaseRef(value) {
+    if (typeof value !== "string" || !BASE_REF_PATTERN.test(value) || value.includes("..")) {
+        throw new Error("invalid worktree base ref");
+    }
+    return value;
+}
+function resolveCommit(repositoryRoot, baseRef, env, runner) {
+    const result = runGit(repositoryRoot, ["rev-parse", "--verify", "--end-of-options", `${baseRef}^{commit}`], env, runner, "git base commit resolution");
+    const commit = result.stdout.trim();
+    if (!COMMIT_PATTERN.test(commit))
+        throw new Error("git base commit resolution returned an invalid commit");
+    return commit;
+}
+function assertRepositoryRoot(repositoryRoot, env, runner) {
+    const result = runGit(repositoryRoot, ["rev-parse", "--show-toplevel"], env, runner, "git repository probe");
+    const reported = result.stdout.trim();
+    if (!reported || realpathSync.native(reported) !== repositoryRoot) {
+        throw new Error("repository root does not match git top level");
+    }
+}
+function assertBranchAbsent(repositoryRoot, branch, env, runner) {
+    const request = gitRequest(repositoryRoot, ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], env);
+    const result = runner(request);
+    if (result.error)
+        throw new Error("git branch collision probe failed to start");
+    if (result.status === 0)
+        throw new Error(`worktree branch collision without a matching record: ${branch}`);
+    if (result.status !== 1)
+        throw new Error(`git branch collision probe exited ${result.status ?? "without status"}`);
+}
+function assertMaterializedWorktree(record, env, runner, requireBaseCommit = false) {
+    const root = validateExistingDirectory(record.worktree_root, "ticket worktree");
+    if (root !== record.worktree_root)
+        throw new Error("ticket worktree path changed after creation");
+    const result = runGit(root, ["rev-parse", "--path-format=absolute", "--show-toplevel", "--git-common-dir", "--abbrev-ref", "HEAD"], env, runner, "git worktree validation");
+    const [reportedRoot, commonGitDirectory, branch, ...extra] = result.stdout.trim().split(/\r?\n/);
+    if (!reportedRoot || !commonGitDirectory || !branch || extra.length > 0) {
+        throw new Error("git worktree validation returned invalid output");
+    }
+    if (realpathSync.native(reportedRoot) !== record.worktree_root)
+        throw new Error("git worktree root mismatch");
+    const repositoryCommonDirectory = runGit(record.repository_root, ["rev-parse", "--path-format=absolute", "--git-common-dir"], env, runner, "git common directory probe").stdout.trim();
+    if (realpathSync.native(commonGitDirectory) !== realpathSync.native(repositoryCommonDirectory)) {
+        throw new Error("ticket worktree belongs to a different repository");
+    }
+    if (branch !== record.branch)
+        throw new Error("ticket worktree branch mismatch");
+    const head = runGit(root, ["rev-parse", "--verify", "HEAD^{commit}"], env, runner, "git worktree HEAD probe").stdout.trim();
+    if (!COMMIT_PATTERN.test(head))
+        throw new Error("ticket worktree HEAD is invalid");
+    if (requireBaseCommit && head !== record.base_commit)
+        throw new Error("ticket worktree did not start at the frozen base commit");
+}
+function runGit(cwd, args, env, runner, label) {
+    const result = runner(gitRequest(cwd, args, env));
+    if (result.error)
+        throw new Error(`${label} failed to start`);
+    if (result.status !== 0)
+        throw new Error(`${label} exited ${result.status ?? "without status"}`);
+    return result;
+}
+function gitRequest(cwd, args, env) {
+    return {
+        command: "git",
+        args,
+        cwd,
+        env,
+        timeoutMs: GIT_TIMEOUT_MS,
+        maxBufferBytes: GIT_MAX_BUFFER_BYTES,
+    };
+}
+function safeGitEnvironment(source) {
+    const env = {};
+    for (const key of ["PATH", "HOME", "TMPDIR", "TMP", "TEMP", "LANG", "LC_ALL", "SYSTEMROOT"]) {
+        if (source[key] !== undefined)
+            env[key] = source[key];
+    }
+    env.GIT_TERMINAL_PROMPT = "0";
+    env.GIT_CONFIG_NOSYSTEM = "1";
+    env.GIT_CONFIG_GLOBAL = "/dev/null";
+    return env;
+}
+function captureDirectoryIdentity(path) {
+    const entry = lstatSync(path);
+    return { path, device: entry.dev, inode: entry.ino };
+}
+function validateDirectoryIdentity(expected, label) {
+    const path = validateExistingDirectory(expected.path, label);
+    const entry = lstatSync(path);
+    if (path !== expected.path || entry.dev !== expected.device || entry.ino !== expected.inode) {
+        throw new Error(`${label} changed`);
+    }
+}
+//# sourceMappingURL=manager.js.map

package/dist/src/worktrees/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../../src/worktrees/manager.ts"],"names":[],"mappings":"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"}

package/docs/ARCHITECTURE.md

@@ -0,0 +1,323 @@
+# Architecture
+
+## System boundary
+
+OMS is a TypeScript-first coordinator around supported local CLI workflows. It
+does not proxy model traffic, emulate a model API, or keep a custom long-running
+daemon. Native CLI sessions, goals, hooks, and subagents remain the execution
+primitives. OMS supplies validated local authorities, immutable evidence,
+idempotent event handling, and operator-facing plans around those primitives.
+
+The executable control plane is local and durable, not a daemon: a human starts
+the read-only conductor, and accepted dispatches may start policy-eligible
+interactive worker panes through OMS. Exact user schedules are explicitly
+managed without an OMS daemon, Slack stops at request intent, and every merge remains on human
+hold. No shipped test or artifact proves a live GitHub ticket or an elapsed
+12h/24h canary.
+
+All runtime automation is TypeScript. The repository contains no tracked shell
+automation scripts; the extensionless `bin/oms` file is a Node.js compatibility
+shim for a source checkout.
+
+## Sources of truth
+
+Each field has exactly one authoritative owner:
+
+| Concern | Authority |
+| --- | --- |
+| Agent policy and roster | tracked `.agents/` files |
+| Project defaults | tracked `.agents/config/oms-config.json` and endurance policy |
+| Ticket content | immutable materialized file below `OMS_STATE_ROOT` |
+| Ticket lifecycle and lease | one canonical versioned queue record per ticket |
+| Session lifecycle | canonical session registry record |
+| Quota freshness | hook-derived quota observation bound to a canonical session version |
+| Events and delivery | immutable typed outbox event plus per-consumer receipt |
+| Audit run | immutable manifest plus append-safe audit ledger |
+| Conductor route | immutable opaque decision file |
+| Goal lifecycle status | one canonical OMS goal record; native goal state is immutable checkpoint evidence |
+| Pre-dispatch advice | canonical intent digest plus immutable protected advisor evidence and operation record |
+| Verification and trust | deterministic evidence and ticket-bound immutable trust records |
+| User schedule | exact generated plan plus user-scoped installation record |
+| Release status | negative-only tracked release assessment |
+
+Cached views must be reconstructible and must not compete with these
+authorities. Native goal state, Team state, HUD state, and reports are projections or evidence only.
+A leader may checkpoint a fresh native goal snapshot into evidence, but a mismatch with the canonical OMS goal record parks the goal and blocks mutation until explicit reconciliation.
+
+## Runtime root
+
+The CLI keeps three paths separate: its read-only package root, the caller's
+workspace root, and `OMS_STATE_ROOT`. The state root is resolved once to an
+explicit absolute path and passed to every worktree and generated service job.
+`state.json` binds that root to one canonical workspace, so another checkout
+cannot reuse its events, conductor, or authorities. Runtime state never depends
+on the package installation directory.
+
+For a single-checkout smoke run, the CLI defaults to the caller workspace's
+ignored `.oms/` directory. Any multi-worktree or resumed run should set one
+explicit absolute `OMS_STATE_ROOT`. Initialization rejects the filesystem root,
+home directory, and workspace root. Read-only status surfaces do not initialize
+a missing root.
+
+Interactive bare `oms` starts the conductor. When `OMS_STATE_ROOT` is absent, it
+may reuse the single valid repository-authorized state root found at `.oms/` or
+one immediate child; zero matches use `.oms/`, while multiple matches fail
+closed. Discovery itself never creates live-delivery authorization. When either
+required authority is absent, bare `oms` performs the one-time human terminal
+confirmation before initialization or provider contact; it never widens a
+running conductor.
+
+Bare startup recognizes a workspace only when it contains the exact tracked OMS
+configuration and a non-symbolic Git marker. If the current directory is not
+such a workspace, a source-linked installation uses its OMS Git checkout. A
+generic `.agents/` directory is never a workspace marker; if neither location
+is valid, startup fails before state initialization or provider contact.
+
+The initialized runtime tree includes private directories for:
+
+```text
+$OMS_STATE_ROOT/
+  locks/                 queue/                 tickets/
+  worktrees/             worktree-records/      trace-operations/
+  sessions/              quota/                 workers/
+  conductor-{activity,notifications,waiters}/   outbox/{events,receipts}/
+  audit/                 run-manifests/         run-decisions/
+  run-start-intents/     run-completion-proofs/ run-aborts/
+  goals/                 goal-artifacts/        team-plans/
+  service-plans/         schedule-installations/ evidence/             tmp/
+  live-contacts/         review-deliveries/     review-proofs/         secret-scan/
+  dispatch-advice/       codex-structured-results/
+```
+
+Tracked configuration contains no secrets. Runtime records use restrictive
+permissions and reject unsafe path, symlink, authority-copy, version, and schema
+conditions at their mutation boundaries.
+
+## Ticket lifecycle and local tracer
+
+The implemented queue states are:
+
+```text
+pending -> leased -> running -> verifying -> completed
+             |          |          |
+             +------> retryable <---+
+             +------> parked
+             +------> blocked
+```
+
+Legal edges are enforced by the lifecycle service rather than inferred from a
+diagram. Every mutation supplies the opaque ticket ID, expected version, state,
+attempt, actor, operation nonce, and lease token when ownership is required.
+Replaying an accepted operation returns the existing outcome; stale or
+conflicting authority fails closed. The attempt budget is bounded.
+
+The one-ticket tracer composes ticket materialization, a dedicated git
+worktree, executor result, deterministic verification, and supplemental grader
+evidence. Its shipped fixture uses a local no-op executor and grader, performs
+no network or provider call, changes no tracked source, and is non-certifying.
+A successful fixture remains `verifying`; only the protected live result gate
+can complete a ticket. Passing the fixture is not evidence of a live ticket or
+provider run.
+
+GitHub Issues supply untrusted ticket intent only. The named queue probe first
+persists and emits a contact/spend disclosure and requires explicit
+confirmation before invoking `gh`. Queue lifecycle authority stays local; sync
+cannot overwrite active execution state.
+
+Normal GitHub sync is projection-only: it materializes open `oms:ready` issues
+as pending tickets and assigns an opaque conductor notification. It never
+freezes the plan, creates a worktree, leases a ticket, or selects a route.
+After a persisted human goal, the conductor selects one exact ticket version
+and calls `prepare_dispatch`. OMS first writes an immutable request journal,
+then freezes the plan, creates or replays the `oms-ticket-*` worktree from
+`main`, leases the ticket, validates the server-derived intent, and writes its
+immutable result. Exact replay can recover a crash between those writes;
+changed or stale requests fail before advice.
+
+## Pre-dispatch advice boundary
+
+The conductor passes the exact intent returned by `mcp__oms__prepare_dispatch`
+through `mcp__oms__advise_dispatch`. OMS re-reads current goal, ticket, lease, role,
+policy, budget, and worktree authority, canonicalizes every executor-affecting
+field including the operation nonce, and computes the intent SHA-256.
+
+Before contacting Codex, OMS requires the separate human-confirmed
+pre-dispatch-advice authorization, writes the live-contact disclosure, and
+records a `prepared -> contacting` operation. A fresh schema-bound Codex exec
+may return only the intent digest, `approve | revise | veto`, summary,
+recommendations, and risks. OMS—not the model—adds provider request, fresh
+session, contact, and authorization identities and writes protected immutable
+advisor evidence. The contacting record also stores the owning OMS Linux
+process identity (PID, boot ID, and process start ticks). Another OMS process
+leaves a live owner untouched; a dead, restarted, or PID-reused owner makes the
+contact ambiguous, blocks the operation, and never launches a second provider
+session. While one intent is prepared or contacting, another intent for the
+same ticket attempt and lease is rejected before provider contact.
+
+`mcp__oms__propose_dispatch` then recomputes the exact intent digest and accepts
+only an `approve` evidence reference for that unchanged ticket and digest before
+creating a dispatch, worker reservation, or delivery event. Worker delivery
+independently revalidates the same evidence before any provider probe or pane
+creation. A veto is terminal for that ticket attempt and lease. A revision
+requires a substantive canonical-intent change and fresh advice; changing only
+the operation nonce cannot reopen advice. Missing, stale, tampered,
+cross-ticket, veto, or revision evidence fails closed.
+
+## Atomic records and immutable artifacts
+
+Mutable records are protected by exclusive locks, schema validation, expected
+versions, and same-filesystem atomic replacement. Append-style history uses
+serialized, hash-linked records or immutable one-file-per-event artifacts.
+Digest-addressed evidence is written once and a replay must match its original
+bytes. Stable-directory checks and no-follow reads prevent a path or symlink
+swap from silently changing the authority being read.
+
+## Event, hook, session, and quota flow
+
+The typed event bus accepts only registered event kinds and exact schema-valid
+payloads. Immutable outbox events are processed per consumer through
+idempotent receipts. The event set covers pinned provider observations, typed
+GitHub changes, native-hook observations, schema-bound Claude grader/dreamer
+completion, due ticket resumes, audit heartbeats, watchdog reports, and Slack
+notification requests. A structured-role completion event carries only its
+exact result-gate, dispatch, ticket, fresh-session, and result-digest bindings;
+it has no grade/reflection content and no terminal authority.
+Projection is serialized per structured request and recovery isolates failures,
+so one malformed or live-locked request cannot prevent another waiting gate
+from being repaired. A dead projector lock is recovered only for its exact
+generation after its owner process is no longer alive. Already committed
+outbox, notification, and worktree replays bypass mutation locks, keeping the
+60-second polling path from growing lock history for unchanged state.
+
+`hook ingest` reads one bounded JSON object from stdin. It computes its source
+digest, publishes a typed event, and projects the event into canonical session,
+quota, and ticket authorities. Session identity binds role, engine, mode, run,
+ticket, native-session reference, pane ID, version, and lifecycle state. Live
+quota gates can be created only from the canonical bus event and matching
+session registry; stale, ambiguous, cross-policy, copied, or unrelated evidence
+is rejected. A quota-parked ticket resumes only from newer, fresh availability
+evidence for the same session.
+
+OMS injects only pinned, fixed-argument native hooks into the interactive Claude
+and Codex launch settings. Hook JSON arrives on bounded stdin; raw prompt,
+completion, quota, and GitHub content is discarded before event publication.
+Each GitHub poll durably stages one validated snapshot batch before projection.
+Restart recovery replays that exact generation before any refetch, advances the
+watermark only after projection, and then removes the stage.
+
+## Reconciliation and watchdog
+
+The minute reconciler is a single idempotent pass. It:
+
+- consumes pending resume and run-heartbeat events;
+- emits due ticket-resume events using the original ticket authority;
+- requires a current time or quota gate before resuming parked work;
+- records an audit heartbeat against the expected hash-chain head;
+- reports overdue, conflicting, failed, or superseded lanes without converting
+  them into success.
+
+The watchdog is a separate recovery pass. It recovers expired ticket leases,
+marks sessions stalled, reports stalled internal delivery, supersedes dead
+waiters, repairs a persisted structured-role result whose completion event,
+receipt, or notification was interrupted, and may resume the same conductor
+without attaching. It sends only one opaque notice ID to a proven idle pane and
+never interrupts `working` state or performs ordinary routing.
+
+The tracked policy specifies a 60-second minute interval, a 15-minute watchdog
+interval, a 15-minute session heartbeat horizon, and bounded quota freshness.
+These policies and deterministic tests do not constitute elapsed endurance
+evidence.
+
+## Schedule boundary
+
+`schedule generate|install|status|remove` manages one exact user schedule for
+cron, systemd, or launchd. It contains only GitHub polling (60 seconds by
+default) and recovery watchdog reconciliation (900 seconds). Installation is
+user-scoped, fixed-argv, drift-detecting, idempotent, and recorded only after
+native activation succeeds. Legacy digest-addressed service plans remain
+internal evidence for non-certifying audit runs.
+
+## Audit run and conductor boundary
+
+`run start` first persists an immutable start intent, then freezes each admitted
+ticket's ID, version, attempt, state, source digest, content digest, policy, and
+verification gate together with the service plan, run kind (`until-empty`,
+`12h`, or `24h`), workspace, and state root. A crash can replay that intent
+without recapturing a changed queue. Every manifest fixes
+`provider_started: false`, `manual_conductor_start_required: true`,
+`certifying: false`, `release: not_stable`, and `merge_disposition: human_hold`.
+It generates service files but neither installs them nor launches a provider.
+
+`run tick` records a continuity observation, projects admitted ticket state, and
+may complete an `until-empty` audit only after every admitted ticket has
+deterministic and grader evidence. A new or drifted unresolved ticket produces
+a human hold. Completion requires a digest-bound immutable proof. `run close`
+applies the same proof gate to a fully elapsed same-boot 12h/24h audit; it does
+not certify a canary. `run abort` records an immutable reason, while
+`run recover-controller` is an exact-generation, dead-owner-only recovery for a
+crashed global controller lock. `run status` is read-only and revalidates the
+start intent, service artifacts, manifest/ledger binding, and any terminal
+proof on every read.
+
+`conductor next` reads the canonical run and queue, chooses the next legal
+opaque route, and persists a decision containing IDs, versions, role IDs, and
+evidence file paths. Raw ticket text is excluded. The decision can say that a
+human start, native hook, resume wait, human hold, or empty queue is next. It
+does not invoke Claude, Codex, tmux, or a shell.
+
+The conductor's existing `process_result` tool is also the only review-delivery
+entry point. A canonical completed result triggers pinned secret scanning,
+fresh remote branch/draft-PR readback, one exact non-force push, and at most one draft
+PR. Ambiguous push or PR outcomes recover by readback only. The delivery remains
+waiting until existing typed PR/check events bind the exact verified commit;
+then an immutable proof reports `READY_FOR_HUMAN`. No merge, ready-for-review,
+tag, publish, release, or positive-stability operation exists.
+
+## Goal, trust, and Team authorities
+
+One canonical OMS goal record owns `active`, `parked`, or `completed` lifecycle
+state. The CLI can create a goal from bounded JSON and read its status. Native
+goal snapshots, Team checkpoints, Ultragoal checkpoints, and regression
+requests are immutable evidence. Stale, inconsistent, or mismatched evidence
+parks the goal; only matching terminal native and executor-group checkpoint
+evidence can complete it through the internal authority API.
+
+Trust runs require ticket, attempt, result, role-policy identity, and
+verification-gate identity from one protected live deterministic verdict. OMS
+ships that writer only inside the result gate: installed checks run with the
+candidate worktree and isolated temp writable, OMS state and installed code
+protected, and one fresh opposite-engine grade bound to its durable request and
+session. The local trace fixture cannot create canonical trust evidence. Daily trust reports cover one closed UTC
+interval and are review-only; their output grants no merge, queue, or execution
+authority.
+
+`team start --dispatch-id ID ...` writes one immutable executor-group manifest
+over already accepted dispatches and sends every member through the same OMS
+worker delivery path. The manifest contains no task text, provider command,
+model choice, verifier lane, or release authority.
+
+## HUD and release truth
+
+The HUD reconstructs read-only counts from queue, session, quota, and outbox
+authorities and always displays `release=not_stable`. It is not a dashboard
+server and has no mutation authority.
+
+`release status` is offline, read-only, and negative-only. Its schema can express
+only `not_stable`, human hold, automatic merge disabled, and the canonical list
+of unproven obligations: live GitHub ticket, elapsed 12h canary, fresh elapsed
+24h canary, and executor-group evidence. There is no positive
+release or automatic-merge parser in the shipped design.
+
+## Verification boundary
+
+`doctor` performs offline executable, version, JSON, path, permissions, git,
+exact Gitleaks-version, and native verification-sandbox prerequisite checks. `oms verify` validates
+shipped and workspace configuration plus the offline doctor. `make verify` runs
+strict TypeScript typecheck, a clean TypeScript build, Vitest, and the installed
+offline gate.
+
+Pre-dispatch advice runs before execution. Deterministic project verification
+runs after execution and before the supplemental grader; neither model advice
+nor grading can override tests. Local tests do
+not prove network access, provider authentication, billing policy, current
+remote GitHub state, an actual provider session, or elapsed endurance.