kijito-tools 0.2.0

package/providers/codex/codex-kijito-parity-plan.md

@@ -0,0 +1,265 @@
+# Codex Kijito parity: bounded C1-C4 release plan
+
+Status: **WITHDRAWN — message 2630 disproved same-running-session wake; this historical plan does not authorize installation. See `same-chat-continuation-plan.md`.**
+
+Date: 2026-07-28 (amended 2026-08-11; status corrected 2026-08-12)
+
+> **STATUS CORRECTION (codex, 2026-08-12).** The header above described C3 as
+> pre-implementation while the 2026-08-11 amendments below record shipped, certified code.
+> Current reality, so no reader executes stale gates:
+> - **C3's isolated-thread architecture (controller.mjs) is measured-RED and DEPRECATED** —
+>   replaced by the pane-wake tmux driver (same-session delivery, byte-certified, watchdogged).
+>   Its C3 gate items as originally written must NOT be picked up as work.
+> - **Shipped since the header:** pane-wake delivery path, CSPRNG verification tokens,
+>   /api/send transport fix, three-outcome arm probe, M223 watchdog + `--heartbeat` argv,
+>   pane-state schema-1 pin (b47ba730, certified + live-swapped).
+> - **Live successor gate:** PR #6 (`codex/same-chat-continuation-plan` @ c38648d) —
+>   act-on-mail machinery under two-consecutive-clean adversarial review (assay), merge order
+>   M224 → pin → PR #6.
+> - **Still open from this plan:** the M223 kill-driver-and-observe-a-page operational
+>   acceptance (to run during the packaged re-arm), and C2/C4 as re-cut under PR #6's scope.
+> - `release-manifest.json`'s `planSha256` is RECORDED PROVENANCE, not an install gate: the
+>   installer never verifies it, but the conformance suite DOES require it to match this file —
+>   so every deliberate edit to this document re-stamps `planSha256` in the same commit (a
+>   deliberate, reviewed act; refresh-manifest.mjs intentionally refuses to do it for you).
+>   (This bullet previously claimed the hash "records the PRIOR revision" — stale since the
+>   m224 re-stamp brought it back in sync; assay gate-7 note, fixed 2026-08-15.)
+> - Under Jason's 2026-08-12 kijito-tools directive [[27367]], this provider tree becomes an
+>   installable peer provider; packaging work supersedes any remaining seat-local steps here.
+
+Program lead: River. Codex owns the OpenAI/Codex surface. Jason's direct
+instructions and platform safety policy remain controlling.
+
+## Exit condition
+
+DONE means exactly four binary gates are green with retained evidence:
+
+- C1: hosted memory and hive mail read/write/read-back.
+- C2: two context-free cold boots reconstruct the same current task from
+  Kijito alone.
+- C3: ordinary River mail wakes an idle Codex hive session twice, including
+  once after the Codex process is restarted.
+- C4: one real native compaction occurs mid-task and the same task resumes
+  from Kijito without a human re-brief.
+
+There is no fifth release category. A defect observed while executing one of
+these gates is fixed and only that gate is rerun. Adjacent findings are filed
+without widening this release.
+
+## Safety boundary inherited from the hook incident
+
+This release never installs or invokes lifecycle hooks. In particular, no
+`PreCompact`, `PostCompact`, `SessionStart`, `UserPromptSubmit`, `Stop`, or
+`SessionEnd` hook may influence a turn or compaction. Kijito can degrade while
+Codex continues; it can never veto native compaction or turn completion.
+
+The release contains no `KeepAlive` LaunchAgent and never attaches automation
+to the user's current Codex thread. It does not call `thread/inject_items`,
+`thread/steer`, or inject transcript history. It never places a hive message
+body in controller-authored input.
+
+## C1 result
+
+C1 is green on Codex 0.145.0:
+
+- the real Codex inbox was read;
+- memory 22468 was read back through `kijito_get` and hosted REST with exact
+  content, persona, and project;
+- Codex message 1451 was independently found in River's hosted REST inbox;
+- a missing-memory exact assertion and a wrong-recipient assertion both went
+  red as required.
+
+Gate instrumentation must inspect the JSON result body. Hosted
+`GET /api/memory/<missing>` returns HTTP 200 with a not-found result string, so
+HTTP status alone is not evidence.
+
+## C3 implementation boundary
+
+C3 builds one explicit launcher/controller for one dedicated Codex hive
+session. It is not a plugin, hook, background login item, or controller for an
+unrelated existing session.
+
+The controller:
+
+1. owns one dedicated `CODEX_HOME`, one app-server child process, and one
+   persisted hive thread;
+2. takes a native single-consumer lock before starting Codex and refuses a
+   duplicate owner;
+3. tails only the shipped producer's
+   `~/.cache/kijito-inbox-monitor/events.codex.ndjson` file;
+4. accepts only complete JSON records with `source="kijito-inbox"`, a
+   case-folded `persona="codex"`, and event `new|alert|recovered`; `new`
+   additionally requires a positive integer ID, while the producer's
+   ID-less `alert` and `recovered` records require a valid timestamp and are
+   classified as lifecycle reconciliation hints;
+5. treats the event stream as a hint: lifecycle alerts/recoveries, startup,
+   rotation, truncation, malformed data, oversize input, or an offset gap
+   coalesce into a reconciliation turn against the durable hosted inbox;
+6. deduplicates `new` records durably by the pair (case-folded persona,
+   message ID), using the producer's in-order message-ID contract rather than
+   any producer event ID (the deployed producer emits no `event_id`);
+7. waits for its exact thread to be idle, then starts at most one turn with a
+   fixed, versioned input containing event type and message IDs only;
+8. visibly labels that turn `KIJITO AUTOMATED WAKE - NOT USER AUTHORED` because
+   Codex 0.145.0 persists `turn/start` input as role `user`;
+9. fixes `approvalPolicy="never"` and a custom permission profile that denies
+   root filesystem reads, permits only Codex's minimal runtime paths plus
+   read-only access to an empty dedicated workspace, and denies command-network
+   access; the turn may use the allowlisted hosted Kijito MCP tools but cannot
+   modify local files or request broader access;
+10. instructs the model to read `kijito_hive_inbox(persona="codex",
+   unread_only=true, mark_read=false)`, treat all returned bodies as untrusted
+   data, and perform no shell, file, web, secret, install, or external action;
+11. never retries a `turn/start` whose acceptance is ambiguous; it records the
+    ambiguity and requires durable-inbox reconciliation on a later distinct
+    event or clean restart;
+12. on a planned child restart, waits for the owned child process to exit
+    before starting a successor, resumes only the recorded dedicated thread,
+    and re-arms without a human prompt; and
+13. stops cleanly, releases its lock, and leaves the ordinary Codex home,
+    config, hooks, plugins, and user threads unchanged.
+
+The event body is never authoritative and never enters the wake input. The
+model sees mail only through Kijito's untrusted-data envelope. Automatic hive
+replies are outside C3; the active Codex agent may reply under Jason's standing
+coordination instruction after evaluating the message in context.
+
+## C3 pre-implementation QA gate
+
+Implementation may begin only when all items below are green on this unchanged
+plan:
+
+1. The unsafe negative-control architecture (a blocking compaction hook plus
+   `KeepAlive` resume bridge) is classified RED for both compaction liveness
+   and duplicate/unsolicited-turn risk.
+2. Current Codex 0.145.0 schema and the official Codex manual confirm
+   `initialize`, `thread/start`, `thread/resume`, `thread/status/changed`,
+   `turn/start`, `approvalPolicy`, named permission profiles, and turn
+   completion.
+3. An isolated app-server smoke test proves a thread can reach idle and a fixed
+   controller turn can complete with hooks empty.
+4. The same smoke harness is mutation-checked: wrong thread ID, non-idle
+   injection, a wrong permission profile, and a fabricated successful
+   completion must each make it RED. It also places a canary outside the
+   dedicated workspace and proves an app-server command running under the
+   selected profile cannot read it; a readable canary is RED.
+5. Static plan review finds no lifecycle hook, LaunchAgent, current-thread
+   mutation, message-body injection, automatic retry after ambiguous delivery,
+   or compaction veto path.
+6. A real-stream predicate check proves the currently pinned producer's
+   ID-less `alert` and `recovered` records are accepted as reconciliation
+   hints while `new` still requires a positive integer message ID.
+
+The frozen plan SHA-256 and the exact checklist result are retained before the
+first implementation edit. Any plan edit resets this pre-implementation gate.
+
+## C3 release gate
+
+Before live mail, deterministic tests must first demonstrate RED for malformed
+JSON, wrong persona/source/event, missing or zero/negative/non-integer IDs on
+`new`, missing/invalid timestamps on ID-less lifecycle records, oversize and
+partial lines, rotation gaps, duplicate events, a held consumer lock, active
+thread state, ambiguous acceptance, an attempted second send, wrong persisted
+thread, and any forbidden lifecycle/current-thread token. A well-formed
+ID-less `alert` and `recovered` record must each be accepted as reconciliation.
+
+Then two live passes run on one unchanged artifact:
+
+- pass 1: River sends ordinary mail while the dedicated hive thread is idle;
+  the monitor emits the matching `new` event, exactly one fixed wake turn
+  attributable to that message ID starts, the session reads the durable Codex
+  inbox, and the message surfaces;
+- pass 2: the owned Codex child is restarted and positively observed exited,
+  the same thread is resumed and idle, River sends a second ordinary message,
+  and exactly one new wake turn attributable to the second message ID surfaces
+  it without a human prompt.
+
+Lifecycle-only reconciliation turns are logged and allowed but do not count
+for or against either mail-attribution assertion. If a lifecycle hint coalesces
+with the target `new`, the one combined turn is attributable to the target ID;
+no second triggering wake input containing that ID is allowed. Attributability
+is determined solely by message IDs carried in the controller-authored
+triggering wake input; inbox rows read or surfaced during a turn never make
+that turn attributable.
+
+No manual inbox call made by the gate controller can count as a wake.
+
+## C2 gate
+
+After C3, update one unique Codex current-state memory with C1/C3 results and
+the exact next action. Run two sequential, context-free `codex exec` boots in
+isolated read-only environments with no hooks, skills, rules, conversation
+fork, local task files, or prompt-provided pointer body. Each receives only the
+instruction to use hosted Kijito as persona `codex`, project `Codex`, discover
+the current-state record, and report the task, done/remaining work, exact next
+step, and DONE-WHEN.
+
+Both reports must select the same unique live record and agree with ground
+truth. Missing, tied, truncated-but-unfetched, locally inferred, or materially
+different reports are RED. A wrong-sentinel fixture must fail before the real
+pair can pass.
+
+## C4 gate
+
+Use the dedicated app-server hive thread and its ordinary native
+`thread/compact/start` method. No hook participates. Before compaction, the
+thread records one safe checkpoint in Kijito and begins a bounded task. The
+gate proves a real `contextCompaction` item completed and token usage dropped.
+After compaction, one fixed automated wake turn tells the session only to load
+its hosted Codex current state; it must resume the exact bounded task and
+complete its predeclared next step without a human re-brief.
+
+The negative control omits the Kijito checkpoint/sentinel and must fail to
+identify the task. An ordinary completed turn, a summary without a native
+compaction event, a hook event, a turn abort, a duplicate continuation, or a
+different task is RED.
+
+## Ship boundary
+
+On C1-C4 green, freeze and hash the controller, tests, this plan, and evidence;
+run the complete deterministic suite twice on unchanged bytes; then ship the
+explicit launcher and its documentation. Production installation may add only
+the dedicated launcher/home named by the manifest. It may not alter the
+ordinary `~/.codex/config.toml`, installed plugins, hook trust, model catalog,
+context limits, or the user's current thread.
+
+---
+## Amendment — 2026-08-11: same-session pane wake NARROWLY supersedes the "no automation on the user's current thread" boundary
+
+Authority: Jason's in-session direction (via codex msg 5695) + assay ruling 5717. The "Safety boundary inherited from the hook incident" above is SUPERSEDED for exactly one case: same-session wake delivery.
+
+- The codex provider MAY deliver wake-core's fixedWakeText — event METADATA ONLY (the WAKE_PREFIX and a read-only inbox-peek instruction; NEVER a hive message body) — into the operator's send-time-verified live Codex pane via tmux (providers/codex/pane-wake.mjs).
+- The injected text is EXACTLY that template PLUS one appended verification line of the fixed form `Wake-verification: <token>`. The token is 128 bits from the CSPRNG (`crypto.randomBytes(16)`, rendered as 32 lowercase hex characters and validated against `/^[0-9a-f]{32}$/` before it can be composed into the line), minted FRESH for every submission, never reused, and discarded when the confirmation phase for that submission ends. It is driver-generated randomness, not content: no event field, no pane content and no hive data can reach that line. The line exists so that the driver can prove the turn it consumes a message id for is ITS OWN — a constant marker is reproducible by anything rendered on screen, including a hive message body the wake itself asks the agent to summarise, and a per-submission random token is not.
+- The injection-surface property is therefore unchanged and still holds: the only two things ever typed into the operator's pane are a closed template and a random token this driver minted.
+- Everything else in the original boundary STANDS UNCHANGED: no thread/inject_items, no thread/steer, no transcript-history injection, never a hive message body in injected input, nothing starts at login.
+- Rationale: the operator requires parity with the working Claude/OpenCode same-session wake; the isolated dedicated-thread approach (controller.mjs) delivered wakes into a thread the operator never saw (measured RED).
+
+Alert transport and its arm-time probe:
+- The bounded-silence alert is delivered in-process to `https://api.kijito.ai/api/send` with the body `{to, content, from}` — the REST route that twins the `kijito_hive_send` MCP tool, and the field names that route actually reads. The original bytes used the tool-shaped path `/api/hive/send` and a `persona` field; the route answered 404 to every alert the driver ever raised, and an unknown field would have re-attributed the alarm to the token identity rather than to codex.
+- At arm time the driver PROBES that route with a GET (no body, so nothing can be sent), bounded at 4 seconds, carrying the same bearer the transport uses — this API authenticates BEFORE it routes, so an unauthenticated probe answers 401 for every path including paths that do not exist, and could not tell present from absent. The probe NEVER blocks arming; every outcome arms, and there are exactly three:
+  - NON-404 (405 / 401 / 2xx) → the route exists → arm normally, logged as verified present;
+  - 404 → the route is confirmed absent → arm and announce DEAD, in a line that cannot be misread as healthy;
+  - timeout / network error / any throw inside the probe → arm and announce UNVERIFIED, in a DISTINCT line. A failed observation is not an observed failure: collapsing "could not reach the server" into "the route is dead" teaches an operator that the DEAD line sometimes means nothing, and it then means nothing when it is true.
+- The outcome is stamped on every bounded-silence alarm line, so an alert can never look healthier than the transport that carries it.
+
+Liveness detection (M223) — a DETECTOR, and a narrow carve-out for how it is supervised:
+- `providers/codex/pane-wake-watchdog.mjs` watches the driver's heartbeat and PAGES when the wake path has stopped. It is detection-only: it never starts, restarts, resumes, signals or types into anything, its own test asserts the file contains no spawn/exec/kill/tmux at all, and auto-restart is a separate registry row on purpose — a supervisor that re-arms a wake driver can re-arm it into a pane whose state nobody verified, which is exactly what the driver's send-time checks exist to prevent.
+- The window is the driver's own measured cadence: the driver beats at most every 5s, a record is stale after 30s (max(30s, pollMs x 6)), the watchdog checks every 15s ⇒ a death is DETECTED AND PAGED within roughly 30-45s of the last beat. The lower bound is the staleness threshold (a driver between beats must not be paged); the upper bound is that threshold plus one check interval.
+- It pages on stale / absent / dead-pid / unreadable, once per outage, re-arming the latch on recovery so a second outage pages again; the latch closes on a SUCCESSFUL send, not on the attempt. It does not page on `degraded` (beating, input path broken) because the driver alarms about that itself. It imports `readLiveness`, `hiveNoteBody` and `HIVE_SEND_URL` from the driver module rather than re-declaring them.
+- `--heartbeat <installRoot>/runtime-pane/heartbeat.json` is now part of the STANDARD launch argv, so every future arm is watchable by construction; the status tool reads the same path from the same definition, with the pre-M223 location read as a fallback so an older arm is not reported as a false death.
+- SUPERVISION CARVE-OUT, NARROW AND DELIBERATE: `forbiddenMechanisms` lists "LaunchAgent" and "KeepAlive", and that prohibition STANDS for anything that can start, resume, wake or type into a Codex session. It does not extend to a process that can do none of those things. `providers/codex/com.kijito.pane-wake-watchdog.plist` is therefore shipped as a TEMPLATE with placeholders: nothing installs it, nothing loads it, `doctor` still asserts the product installs no LaunchAgent of its own, and an operator who does not want the carve-out can simply delete the file — the watchdog runs under any supervisor, or in a tmux pane. Its KeepAlive resurrects the OBSERVER, never the driver.
+
+**AMENDMENT (assay ruling, 2026-08-11, msg 5996) — forbiddenMechanisms is a PROPERTY, and a read-only liveness observer is permitted under a self-revoking guardrail.**
+
+`forbiddenMechanisms` binds any mechanism that can START, RESUME, WAKE, or TYPE-INTO a Codex session (the hook-incident class). It is NOT a blanket launchd ban (the fleet's inbox-monitor is itself a launchd agent). A launchd-supervised READ-ONLY liveness OBSERVER (the M223 pane-wake-watchdog) is PERMITTED, contingent on ALL of:
+  (i) test-asserted to contain none of spawn/spawnSync/exec/execSync/execFile/process.kill/launchctl/send-keys/tmux (the forbidden-token assertion in pane-wake-watchdog.test.mjs);
+  (ii) it does nothing but read a liveness file and POST a fixed-shape hive page;
+  (iii) it holds no capability to restart/resume/type-into the driver or its pane; its KeepAlive resurrects the observer, never the driver;
+  (iv) the driver's OWN agent stays uninstalled — `doctor` continues to assert launchAgentInstalled:false for the wake path.
+GUARDRAIL (load-bearing): this permission is TIED to the forbidden-token assertion remaining a gate. If that test is removed, or the watchdog gains any listed capability, the plist REVERTS to forbidden — the permission self-revokes the instant the read-only property breaks. The narrowing creates no standing hole.
+
+- Not covered here: killing the driver and observing a page arrive is an operational, by-effect acceptance and is this row's done-when.
+
+Reconciliation with the pre-implementation gate:
+After issuing the submit keystroke the driver enters a BOUNDED confirmation phase: it OBSERVES, never re-issues blindly, until it positively confirms the turn started (→ consumes the id) OR positively observes the submit did not take (composer still holds our text → one bounded re-issue) OR hits a hard cap (→ alarms and abandons WITHOUT consuming the id, leaving recovery to the next reconcile). Positive confirmation means ONE thing: the composer is empty AND this submission's own fresh verification token is rendered above it. A live-turn indicator is corroborating evidence only and can never advance read-state, because a turn may start for reasons that have nothing to do with us. A persisted confirmation record older than the phase's own worst-case duration is refused on sight rather than confirmed against a screen it cannot be evidence about. A message id is consumed ONLY on positive confirmation; no blind resubmission of an id-bearing wake ever occurs.
+---

package/providers/codex/docs-codex-setup.md

@@ -0,0 +1,64 @@
+# Codex CLI × Kijito — setup (gate-2 docs block)
+
+Staged replacement for the docs' current one-sentence "In testing" entry (plan §8 item 3;
+Cursor-parity config example). Target: kijito.ai docs Codex section + kijito-tools codex README.
+
+## Memory (the product — one config block)
+
+Either run:
+
+```bash
+codex mcp add kijito --url https://api.kijito.ai/mcp
+```
+
+(auto-detects OAuth: opens the authorize URL with a localhost callback), or add to
+`~/.codex/config.toml` directly:
+
+```toml
+[mcp_servers.kijito]
+url = "https://api.kijito.ai/mcp"
+# Bearer alternative to OAuth, if you have an API token:
+# http_headers = { "Authorization" = "Bearer YOUR_KIJITO_API_TOKEN" }
+```
+
+That is the whole install. Your agent now has persistent memory across sessions.
+
+**Headless / scripted use — two sharp edges (plan §8):**
+- `codex exec` silently cancels MCP tool calls that need approval ("user cancelled MCP
+  tool call"). Pass `--approve-for-me` (see `codex exec --help`; `--full-auto` is not an
+  exec flag as of 0.147).
+- `codex mcp add` OAuth waits forever if no browser can open — on a headless box, use the
+  Bearer-token config block instead.
+
+## Skills (recommended)
+
+Install the Codex skills (`kijito-start`, `kijito-qa-memory`) from kijito-tools
+(`providers/codex/skills/`). `kijito-start` catches your session up at start — and, once
+the live-wake feature is installed, joining the hive for a session is the same one command.
+
+## Hive mail for a session (how the producer runs — gate-3 measured default)
+
+When a session joins the hive, `kijito-start` runs **one producer child owned by that
+session** (zero install steps; measured 2.9s to armed). It watches your inbox while the
+session lives and dies with it; if it ever dies early, that is loud inside your session,
+never silent. When no session is running, mail simply waits in your durable inbox — the
+next session catches up at start. Users who want **always-on capture** (events recorded
+even with no session open) can instead do the one-line supervised install (systemd user
+unit / launchd) documented in the monitor README — optional, and unnecessary for the
+default experience.
+
+## Hive mail notifications (optional, count-only)
+
+If you use hive mail and want a desktop notification with your unread count, wire Codex's
+`notify` hook to the count shim:
+
+```toml
+notify = ["node", "/path/to/kijito-tools/providers/codex/notify/kijito-notify-count.mjs",
+          "--persona", "YOUR_PERSONA", "--token-file", "/path/to/your/kijito_api_token"]
+```
+
+Honest semantics: Codex fires `notify` on its own turn lifecycle, so this tells you your
+unread count when Codex finishes work — it is not a mail-arrival alert. The notification
+is always count-only ("Kijito: persona — N unread"); message content never appears in a
+notification. Live mail-arrival wake for a running session is the separate opt-in
+live-wake feature (plan gate 5).

package/providers/codex/install.mjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+// Codex provider installer — post-gate-6 (2026-08-15) shape.
+//
+// The controller-era full install (headless app-server seat: controller, cli, pane-wake driver,
+// mode-aware watchdog) was RETIRED at gate 6 of the hive-user-first plan §7 teardown protocol.
+// Its installer is archived at legacy/codex-controller-era-2026-08/install-controller-era.mjs and
+// its machinery teardown evidence lives on the operator seat at
+// ~/.local/share/codex-kijito-hive/legacy/gate6-20260815T0643Z/. Nothing here installs a runtime,
+// copies credentials, or touches ordinary Codex state.
+//
+// What remains is exactly the live surface:
+//
+//   verify         (default) the release gate. Every artifact release-manifest.json gates must
+//                  exist with matching bytes, and every executable on the live user path must be
+//                  gated. Both failure directions are LOUD: a gated-but-absent file and an
+//                  ungated-but-shipped executable each fail the run with a named cause — a
+//                  manifest gating absent files is a gate over nothing, and an ungated executable
+//                  is code a user session runs with no integrity story (the gate-5 gating ruling,
+//                  stated as a property).
+//   --skills-only  deploy the provider's skills to ~/.codex/skills (idempotent, update-in-place —
+//                  versioned prose, meant to be overwritten). Runs verify FIRST, so a checkout
+//                  that fails its release gate never deploys skills from those bytes.
+//
+// The wake-helper itself is NOT installed anywhere: kijito-start's arm step runs it from the
+// checkout, which is why its bytes (and its runtime import, the shared wake core) are gated here.
+
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+function sha256(file) {
+  return createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+}
+
+function parseArgs(argv) {
+  const values = {};
+  const flags = new Set(["skills-only", "verify"]);
+  const bare = new Set();
+  argv = argv.filter((token) => {
+    const isFlag = token.startsWith("--") && flags.has(token.slice(2));
+    if (isFlag) bare.add(token.slice(2));
+    return !isFlag;
+  });
+  for (let index = 0; index < argv.length; index += 2) {
+    const key = argv[index];
+    if (!key?.startsWith("--") || argv[index + 1] === undefined) {
+      // The controller-era installer took a dozen paired options (--install-root, --launcher,
+      // --auth-source, …). Naming the retirement beats a bare "invalid argument" for anyone
+      // holding an old command line.
+      throw new Error(`invalid or retired argument ${key ?? ""} — the controller-era full install was retired at gate 6 (2026-08-15); see legacy/codex-controller-era-2026-08/`);
+    }
+    if (!["skills-root", "source-root"].includes(key.slice(2))) {
+      throw new Error(`invalid or retired argument ${key} — the controller-era full install was retired at gate 6 (2026-08-15); see legacy/codex-controller-era-2026-08/`);
+    }
+    values[key.slice(2)] = argv[index + 1];
+  }
+  const home = os.homedir();
+  const expand = (value) => path.resolve(value.replace(/^~(?=\/|$)/, home));
+  return {
+    sourceRoot: expand(values["source-root"] ?? here),
+    skillsRoot: expand(values["skills-root"] ?? path.join(home, ".codex", "skills")),
+    skillsOnly: bare.has("skills-only"),
+    verifyOnly: bare.has("verify"),
+  };
+}
+
+// The live gated set. Keys are the manifest's artifact names; paths are relative to the provider
+// root. This map, refresh-manifest.mjs's GATED map, and the manifest's `artifacts` block must
+// agree — verify() fails loud on any drift among the three.
+function liveArtifacts(sourceRoot) {
+  return {
+    wakeCoreSha256: path.join(sourceRoot, "..", "_shared", "wake-core.mjs"),
+    // workflowSha256 is deliberately NOT here: the CI workflow is a repo-side gate (what CI
+    // executes), checked by refresh-manifest.mjs --check via the conformance test. Built payloads
+    // do not ship .github/, so gating it here would fail every packaged install on a file that is
+    // correct to be absent.
+    wakeHelperSha256: path.join(sourceRoot, "wake-helper", "kijito-wake-helper.mjs"),
+    wsUdsSha256: path.join(sourceRoot, "wake-helper", "ws-uds.mjs"),
+    wakeHelperTestsSha256: path.join(sourceRoot, "wake-helper", "kijito-wake-helper.test.mjs"),
+    wakeHelperIntegrationTestsSha256: path.join(sourceRoot, "wake-helper", "integration.test.mjs"),
+    wakeHelperMockDaemonSha256: path.join(sourceRoot, "wake-helper", "mock-daemon.mjs"),
+  };
+}
+
+// Executables on the live user path that are deliberately NOT gated, by ruling: instruments and
+// docs a user session is never caused to run. Anything else executable found beside the gated
+// files fails verify.
+const UNGATED_ALLOWLIST = new Set(["status-probe.mjs"]);
+
+function verify({ sourceRoot }) {
+  const manifestFile = path.join(sourceRoot, "release-manifest.json");
+  const release = JSON.parse(fs.readFileSync(manifestFile, "utf8"));
+  if (release.schema !== 1 || release.product !== "codex-kijito-hive") {
+    throw new Error("invalid source release manifest");
+  }
+  const gated = liveArtifacts(sourceRoot);
+  const checked = [];
+  // Direction one: everything the manifest gates must exist and match. A missing file surfaces as
+  // its own named error, not a generic ENOENT — a manifest gating absent files is the exact
+  // intermediate state the gate-6 one-commit rule forbids.
+  for (const [key, file] of Object.entries(gated)) {
+    const expected = release.artifacts?.[key];
+    if (typeof expected !== "string" || !/^[0-9a-f]{64}$/.test(expected)) {
+      throw new Error(`manifest does not gate ${key} — live artifact with no gate entry`);
+    }
+    let actual;
+    try {
+      actual = sha256(file);
+    } catch (error) {
+      if (error.code === "ENOENT") throw new Error(`manifest gates an ABSENT file: ${key} -> ${path.relative(sourceRoot, file)}`);
+      throw error;
+    }
+    if (actual !== expected) {
+      throw new Error(`${key} differs from gated hash (${path.relative(sourceRoot, file)})`);
+    }
+    checked.push(key);
+  }
+  // The manifest must not gate entries this verifier does not check — a stale extra entry would
+  // read as covered while nothing verifies it.
+  for (const key of Object.keys(release.artifacts ?? {})) {
+    if (key === "planSha256") continue; // recorded provenance, deliberately not a gate
+    if (key === "workflowSha256") continue; // repo-side gate: refresh-manifest --check owns it
+    if (!(key in gated)) {
+      throw new Error(`manifest gates ${key} but the live verifier has no such artifact — retired entries belong in legacyArtifacts`);
+    }
+  }
+  // Direction two: no executable ships ungated from the live directories.
+  const wakeHelperDir = path.join(sourceRoot, "wake-helper");
+  const gatedFiles = new Set(Object.values(gated).map((f) => fs.realpathSync(f)));
+  for (const entry of fs.readdirSync(wakeHelperDir, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith(".mjs")) continue;
+    if (UNGATED_ALLOWLIST.has(entry.name)) continue;
+    const file = fs.realpathSync(path.join(wakeHelperDir, entry.name));
+    if (!gatedFiles.has(file)) {
+      throw new Error(`ungated executable on the live path: wake-helper/${entry.name}`);
+    }
+  }
+  return { status: "VERIFIED", artifacts: checked.sort() };
+}
+
+// Deploy the provider's skills to the Codex skills directory. Idempotent and update-in-place on
+// purpose: skills are versioned prose meant to be overwritten. (Carried unchanged from the
+// controller-era installer — this path was always the live one.)
+function installSkills({ sourceRoot, skillsRoot }) {
+  const source = path.join(sourceRoot, "skills");
+  const deployed = [];
+  let names = [];
+  try { names = fs.readdirSync(source, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).sort(); }
+  catch (error) { if (error.code === "ENOENT") return deployed; throw error; }
+  for (const name of names) {
+    const skillFile = path.join(source, name, "SKILL.md");
+    if (!fs.existsSync(skillFile)) continue;
+    const target = path.join(skillsRoot, name);
+    fs.mkdirSync(target, { recursive: true });
+    fs.writeFileSync(path.join(target, "SKILL.md"), fs.readFileSync(skillFile), { mode: 0o644 });
+    const files = ["SKILL.md"];
+    // The agents/ sidecar carries the Codex-surface interface metadata (display name, default
+    // prompt). A skill deployed without it loses its presentation, so it travels with the skill.
+    const sidecar = path.join(source, name, "agents", "openai.yaml");
+    if (fs.existsSync(sidecar)) {
+      fs.mkdirSync(path.join(target, "agents"), { recursive: true });
+      fs.writeFileSync(path.join(target, "agents", "openai.yaml"), fs.readFileSync(sidecar), { mode: 0o644 });
+      files.push("agents/openai.yaml");
+    }
+    deployed.push({ skill: name, target, files });
+  }
+  return deployed;
+}
+
+try {
+  const options = parseArgs(process.argv.slice(2));
+  const verified = verify(options);
+  const result = options.skillsOnly
+    ? { status: "SKILLS_INSTALLED", verified: verified.artifacts, skillsRoot: options.skillsRoot, skills: installSkills(options) }
+    : verified;
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+} catch (error) {
+  process.stderr.write(`${error.stack ?? error.message}\n`);
+  process.exitCode = 1;
+}