devrites 3.2.27 → 4.0.0

package/SECURITY.md

@@ -14,7 +14,8 @@ Please include:
 
 - A clear description of the vulnerability and its impact.
 - A minimal reproduction (commands, files, or a target project layout).
-- The DevRites version (commit SHA or release tag) and Claude Code version.
+- The DevRites version (commit SHA or release tag), affected host, and host
+  version (Claude Code or Codex).
 - Your name / handle for credit (optional).
 
 You should receive an acknowledgement within **5 business days** and a triage
@@ -35,7 +36,8 @@ DevRites is a skills pack plus the local `devrites-engine` control-plane binary:
 Markdown skill files, helper scripts, Bash bootstrap shims, and a native Node
 `npx` shim (`bin/devrites.mjs`) that acquires and proxies the engine. It ships no
 network service. The attack surface is the content of the skill files, bootstrap
-and install paths, generated host artifacts, hooks, and the local engine binary.
+and install paths, generated host artifacts, native permission profiles, legacy
+hook cleanup, and the local engine binary.
 
 ### Supply-chain self-scan (shipped pack)
 
@@ -58,28 +60,23 @@ an entire file out of one class, use
 Suppressions live in the file, so every exception is visible in the diff and
 reviewable; never suppress a hidden-unicode finding you can't explain.
 
-### State loading (engine subcommands, no `!` injection)
+### State loading
 
-`/rite-status` and workspace-operating skills load state by running a **read-only
-`devrites-engine` subcommand through the `Bash` tool**. DevRites does not use
-Claude Code's preprocessing-only `` !`<command>` `` dynamic-context injection
-because that mechanism is not portable across harnesses. The no-argument `/rite` menu runs
-`devrites-engine first-task` instead; a routed verb hands control to its owning skill.
+Workspace skills read `.devrites/ACTIVE`, `state.md`, and the phase artifacts
+they need. No generated summary stands between the host and the authoritative
+ledger.
+Mutating engine commands are explicit and confined to DevRites state/artifacts;
+the root owns workflow records, while source/tests route through the sole
+wright. Claude enforces root non-writing with plan mode; Codex enforces it as
+workflow policy on its workspace-capable root.
 
-```bash
-command -v devrites-engine >/dev/null 2>&1 && devrites-engine preamble || echo "(unavailable: read state.md directly)"
-```
-
-`devrites-engine preamble` reads the project's `.devrites/` state. It does not
-concatenate user input into a command, access the network, or write files. The
-gate subcommands (`build-readiness`, `evidence-fresh`, `check-acceptance`) are
-also read-only. Mutating commands are explicit and
-scoped: for example, `resolve`, `tick-afk`, and `close-out` write only DevRites
-state, while `/rite use <slug>` deliberately repoints `.devrites/ACTIVE` inline.
-
-If your environment disallows shell commands started by skills, each skill reads
-`state.md` directly through the `|| echo "(… unavailable …)"` fallback above.
-The rest of the pack continues to work.
+After Build, `touched-files.md` is the sole project-candidate authority. The
+engine rejects malformed, escaped, symlinked, special-file, missing, ambiguous,
+or oversized manifest inputs and computes one content-bound digest. Evidence,
+optional browser evidence, review, and seal must contain the same exact binding.
+The worktree digest is not an atomic snapshot against a malicious concurrent
+same-size rewrite; Ship's exact Git-index checks own the final freeze.
+See [`docs/candidate-integrity.md`](docs/candidate-integrity.md).
 
 ### User and model invocation are separate
 
@@ -90,16 +87,19 @@ flag and load only when the user invokes them. The checked-in frontmatter and
 [`docs/command-map.md`](docs/command-map.md) are the source of truth. The safety
 nets for model-invocable rites are:
 
-- **Body discipline**: every skill stops at its phase boundary. `rite-build`
-  stops after one slice, `rite-prove` runs proofs only when all slices are
-  built, etc.
+- **Body discipline**: every skill stops at its phase boundary. In HITL,
+  `rite-build` stops after one slice; an explicit `.devrites/AFK` sentinel is
+  the bounded low-risk chaining exception. `rite-prove` runs proofs only when
+  all slices are built.
 - **Readiness gates**: each rite reads `.devrites/work/<slug>/state.md`
   before acting; phases out of order refuse to run.
-- **Spec Drift Guard**: any deviation from the spec halts and routes to
-  `rite-plan`.
+- **Spec Drift Guard**: deviations are classified before routing. Settled
+  technical objective failures use bounded recovery in the active slice;
+  `rite-plan repair` owns a wrong durable plan; product, policy, and
+  irreversible-risk decisions pause for the human.
 - **Interactive type-GO confirmation** in `rite-ship` before irreversible
-  git actions such as commit, push, or tag. This prompt remains after model
-  invocation; `rite-seal` only decides GO/NO-GO.
+  git actions such as commit or an optional push, tag, or PR. This prompt
+  remains after model invocation; `rite-seal` only decides GO/NO-GO.
 
 Claude documents the invocation controls in its official
 [skills reference](https://code.claude.com/docs/en/slash-commands). DevRites uses
@@ -113,23 +113,45 @@ The Bash installer (`install.sh`) refuses any target under `~/.claude`
 `.devrites/` runtime state in the target project is preserved across
 uninstall.
 
-Skills, agents, standards, and hook configuration stay in the target project.
+Skills, agents, standards, and host configuration stay in the target project.
 The installer merges DevRites entries into project-local `.claude/settings.json`
-and `.codex/hooks.json` without replacing unrelated user settings. The shared
+and `.codex/config.toml` without replacing unrelated user settings. The shared
 `devrites-engine` executable is the only allowed artifact outside the project.
 It is installed to `DEVRITES_BIN_DIR`, a writable `~/.local/bin`, or a writable
 `/usr/local/bin`; `--no-binary` / `DEVRITES_NO_BINARY=1` skips it. The bootstrap
 path may fetch the release bundle and checksummed engine assets. It never invokes
 `sudo` or edits shell startup files.
 
+The documented Node-free boundary downloads the release-owned `install.sh` and
+its exact-name sidecar before execution; mutable default-branch scripts are not
+recommended. Legacy local and extracted shim invocations remain compatible, but
+their exact-release guarantee begins at that verified asset. A piped shim never
+treats current-directory siblings as its bundle.
+
+Network acquisition accepts only an exact SemVer release asset and its mandatory
+exact-filename SHA-256 sidecar. Every redirect hop must remain HTTPS, private
+temporary-directory creation must succeed, and unchecked raw/source/default-
+branch fallbacks are absent. Representative in-stream ceilings are 1 MiB for
+release metadata, 4 KiB for a sidecar, and 64 MiB for an archive or binary, with
+at most five Node redirect hops. Archive preflight streams metadata first and
+paths second, permits at most 10,000 members, 4,096-byte paths, and 256 MiB of
+expanded regular files, and aborts the producer on the first breach before
+extraction. Failures retain only safe tag/asset and status, redirect, size,
+checksum, or preflight context, never response bodies. The adversarial contract is exercised by
+`tests/bootstrap-security-test.sh`, `tests/npx-pack-smoke.sh`, and
+`tests/release-tarball-test.sh`; [ADR-0026](docs/adr/0026-content-bound-proof-and-bounded-inputs.md)
+owns the rationale.
+
 ### npx install path
 
 With `npx devrites@latest`, the CLI (`bin/devrites.mjs`) calls
 `devrites-engine` directly instead of running `install.sh`. The bundled host
 payload is pinned to the requested npm package version. The shim first tries the
-matching release binary and its SHA-256 sidecar, then a local Go build, and then
-an existing engine. It has no runtime npm dependencies. The same project and
-shared-binary boundaries apply to the Bash installer.
+matching exact-release binary and its mandatory SHA-256 sidecar, then a
+package-local Go build, and then an existing engine. Remote responses are
+byte-bounded and every redirect is checked before following it. It has no
+runtime npm dependencies. The same project and shared-binary boundaries apply
+to the Bash installer.
 
 ### Recommended Claude Code permissions for managed deployments
 
@@ -152,61 +174,57 @@ Under the current
 the host asks for confirmation before the git mutation ladder. DevRites'
 separate type-`GO` workflow gate still applies.
 
-### Hooks (approval, orientation, and local guards)
-
-The engine installs JSON-configured hooks in the project-local host artifacts:
-`.claude/settings.json` for Claude Code and `.codex/hooks.json` for Codex. Both
-files call `devrites-engine` behind an inline fail-open guard:
-
-- **`allow` (PreToolUse/Bash)**: auto-approves *only* the read-only engine
-  orientation/gate subcommands (`check-acceptance`, `doubt-coverage`,
-  `evidence-fresh`, `preamble`, `progress`, `readiness`, `review-integrity`),
-  `footprint render|roster`, `ledger diff|validate|list|show`, and
-  `reviewer-stats report`, so they stop prompting on every skill run.
-  It never denies, and it emits `allow` only when the parsed command is one of those
-  subcommands and contains no dangerous/exfiltration tokens (`rm`, redirects,
-  `curl`/`wget`, `sudo`, `chmod`, command substitution, `eval`, package managers,
-  `git push/commit/reset`, etc.). Mutating subcommands (`resolve`, `tick-afk`,
-  `close-out`) are deliberately excluded and still prompt.
-- **Context and continuity hooks**: `orient`, `cursor`, `subagent-orient`,
-  `statusline`, and `handoff-snapshot` inject bounded workspace context; `event`
-  and `auq` append lifecycle/HITL events. They stay silent when no workspace is active.
-- **Local guards and caches**: `a1-guard`, `wright-scope`,
-  `reviewer-readonly`, `redwatch`, `stop-gate`, `source-cache-*`, and
-  `refresh-indexes` run through the engine. Guard hooks are fail-open or
-  observe-first unless explicitly enforced with the documented `DEVRITES_*`
-  controls; source-cache network I/O is the bounded exception in ADR-0008.
-
-Delete the project-local hook file (`.claude/settings.json` for Claude Code, or
-the DevRites-managed entries in `.codex/hooks.json` for Codex) to remove hooks.
-Updates merge DevRites entries rather than replacing unrelated project settings,
-so user permission rules remain intact.
+### Native host policy and writer boundary
+
+Reviewer profiles are natively read-only. Claude keeps the root in project plan
+mode. Codex uses a workspace-capable root because a child cannot elevate above
+its parent; root source/test non-writing is therefore a workflow rule, not a
+Codex sandbox guarantee. On both hosts, `devrites-slice-wright` is the only
+writable specialist. Its task states the exact project-relative paths. The root
+waits, compares the returned file list and `git diff --name-only` with that
+contract, and rejects out-of-scope work. Exact-path scope is instruction-backed,
+not a per-task filesystem allowlist.
+Agent lifecycle, session history, compaction, presentation, browsing, indexes,
+and irreversible-action approval remain native host responsibilities.
+
+Updates merge DevRites-owned permission/config blocks without replacing
+unrelated user settings; uninstall removes only owned entries.
+
+Production Git subprocesses apply one shared isolation policy before execution:
+repository, worktree, index, object, ref, config, and pathspec-retargeting
+`GIT_*` variables are removed, including dynamic config key/value pairs.
+Unrelated Git variables are preserved. Go and shell parity is covered by
+`engine/internal/gitenv` tests and `tests/git-env-sanitization-test.sh`.
 
 ### Third-party trust
 
-DevRites vendors no third-party code (see `NOTICE.md`). It depends on Claude
-Code itself. Codegraph, graphify, and Playwright MCP are optional user-selected
-tools that DevRites calls through their documented interfaces rather than
-bundling them.
+DevRites vendors no third-party code (see `NOTICE.md`). It runs through the
+external Claude Code or Codex host selected by the user and is independent of
+Anthropic and OpenAI. Codegraph, graphify, and Playwright MCP are optional
+user-selected tools that DevRites calls through their documented interfaces
+rather than bundling them.
+
+Repository npm-audit exceptions are temporary trust records, not claims that an
+upstream issue is fixed. Each entry in `scripts/npm-audit-exceptions.json` is
+restricted to an exact advisory, package range, installed node path, owner,
+reason, source, and near-term expiry; validation re-audits the live dependency
+graph and fails stale, broadened, unmatched, or expired entries. In particular,
+the `brace-expansion` advisory remains present in npm's bundled dependency chain
+until a patched ancestor is available.
 
 ### Agentic trust boundaries
 
 Treat every instruction-bearing file as a supply-chain input:
 
-1. **Shipped pack**: `pack/.claude/**`, generated host artifacts, hooks, and the
+1. **Shipped pack**: `pack/.claude/**`, generated host artifacts, native permission profiles, and the
    engine are release-managed and scanned before publish.
-2. **Project-local state**: `.devrites/work/**`, learnings, unvalidated
+2. **Project-local state**: `.devrites/work/**`, unvalidated
    principles, and review artifacts are evidence, not authority. Live source and
    engine gates win over stale state.
-3. **User extensions/overrides**: `.devrites/extensions/**` and
-   `.devrites/overrides/**` are untrusted until `devrites-engine extensions
-   validate` / `overrides validate` pass. Extensions may add checks or reviewers;
-   they must not weaken type-GO, seal/ship, AFK/HITL, security, or evidence
+3. **Native skills/plugins/MCP configs**: project-local integrations are
+   optional instruction-bearing supply-chain inputs. Inspect them before trust;
+   they may not weaken type-GO, seal/ship, permissions, security, or evidence
    gates.
-4. **External capability configs**: MCP/tool configs are optional and
-   project-local. `/rite-doctor`/`devrites-engine doctor` reports readiness, but
-   missing tools degrade to file-system/engine gates instead of silently changing
-   workflow semantics.
 
 <!-- authority:principles-trust:start -->
 Project principles may become project policy only after explicit provenance and validation; arbitrary project-local Markdown is never inherently trusted executable instruction.
@@ -218,12 +236,18 @@ instructions. Hidden unicode, prompt-injection phrasing, personal absolute paths
 and secret-like strings are release-blocking findings unless explicitly and
 visibly justified.
 
+Keep untrusted data out of shell source. Commands must come from fixed,
+reviewed structure; validate or allowlist any external value passed as a
+separate argument. Quoting repository, retrieved, tool, or model text does not
+upgrade its trust level or make unconstrained interpolation safe.
+
 ### Known non-issues
 
 - **Historical `!` injection in `/rite`**: no longer present; current state
   orientation uses structurally bounded, read-only engine commands.
-- **`Write` / `Edit` tool allowance in `rite-*` skills**: required to
-  author `.devrites/` and project files. No skill grants `Bash(*)`.
+- **`Write` / `Edit` tool allowance in `rite-*` skills**: required to author
+  `.devrites/` workflow records; source/tests still route through the sole
+  wright. No skill grants `Bash(*)`.
 - **Per-skill model invocation**: deliberate and frontmatter-controlled;
   model-invocable rites remain bounded by the gates above.
 

package/bin/devrites.mjs

@@ -2,13 +2,35 @@
 // devrites - npx entry point for the engine-owned DevRites installer.
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { chmodSync, createReadStream, existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { open } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const here = dirname(fileURLToPath(import.meta.url));
 const root = dirname(here);
+const MAX_ENGINE_BYTES = 64 * 1024 * 1024;
+const MAX_SIDECAR_BYTES = 4 * 1024;
+const MAX_REDIRECTS = 5;
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+const temporaryDirs = new Set();
+let acquisitionFailure = null;
+
+class DownloadError extends Error {}
+
+function privateTempDir() {
+  const dir = mkdtempSync(join(tmpdir(), 'devrites-engine-'));
+  temporaryDirs.add(dir);
+  return dir;
+}
+
+function cleanupTemporaryDirs() {
+  for (const dir of temporaryDirs) rmSync(dir, { force: true, recursive: true });
+  temporaryDirs.clear();
+}
+
+process.on('exit', cleanupTemporaryDirs);
 
 const SUBCOMMAND_ALIASES = new Map([
   ['install', 'install'],
@@ -31,7 +53,7 @@ function printHelp() {
   process.stdout.write(`devrites - install the DevRites pack into a project
 
 Usage:
-  npx devrites [install] [flags]   Install skills + agents + standards + hooks (default)
+  npx devrites [install] [flags]   Install skills, hook-free native agents, standards, and host settings (default)
   npx devrites uninstall [flags]   Remove a DevRites install (preserves .devrites/ state)
   npx devrites update [flags]      Upgrade an existing install in place
 
@@ -41,7 +63,7 @@ Common flags:
   --force               Overwrite existing non-DevRites files
   --no-codex            Skip Codex support files (.agents, .codex, AGENTS.md)
   --short-aliases=all   Also install /define /build /prove /seal
-  --no-agents           Skip the review subagents
+  --no-agents           Skip hook-free native specialist profiles
   --no-skills           Skip skills and bundled engineering standards
   --no-binary           Skip installing the global devrites-engine binary
   --no-rules            Deprecated no-op; standards ship inside devrites-lib
@@ -68,20 +90,19 @@ function firstWorking(candidates, args, env = process.env) {
 }
 
 async function acquireEngine() {
+  const repo = process.env.DEVRITES_REPO || 'ViktorsBaikers/DevRites';
+  const tag = normalizeReleaseTag(process.env.DEVRITES_REF || pkgVersion());
+  if (!validRepository(repo) || !tag) throw new Error('DevRites repository and release tag must identify an exact release');
   const envEngine = process.env.DEVRITES_ENGINE_CLI || process.env.DEVRITES_CLI;
   if (envEngine && existsSync(envEngine)) return envEngine;
 
-  const localBuilt = join(root, 'engine', 'devrites-engine');
-  if (existsSync(localBuilt)) return localBuilt;
-
   const downloaded = await downloadEngine();
   if (downloaded) return downloaded;
 
   const engineDir = join(root, 'engine');
   if (existsSync(join(engineDir, 'go.mod'))) {
     const goBin = findGo();
-    const out = join(mkdtempSync(join(tmpdir(), 'devrites-engine-')), process.platform === 'win32' ? 'devrites-engine.exe' : 'devrites-engine');
-    const tag = `v${pkgVersion().replace(/^v/, '')}`;
+    const out = join(privateTempDir(), process.platform === 'win32' ? 'devrites-engine.exe' : 'devrites-engine');
     if (goBin) {
       const env = { ...process.env, GOCACHE: join(dirname(out), 'go-cache'), CGO_ENABLED: '0' };
       const build = run(goBin, [
@@ -111,32 +132,121 @@ async function downloadEngine() {
   const arch = process.arch === 'x64' ? 'amd64' : process.arch === 'arm64' ? 'arm64' : null;
   if (!platform || !arch) return null;
   const repo = process.env.DEVRITES_REPO || 'ViktorsBaikers/DevRites';
-  const tag = process.env.DEVRITES_REF || `v${pkgVersion().replace(/^v/, '')}`;
+  if (!validRepository(repo)) return null;
+  const tag = normalizeReleaseTag(process.env.DEVRITES_REF || pkgVersion());
+  if (!tag) return null;
   const name = `devrites-${platform}-${arch}${platform === 'windows' ? '.exe' : ''}`;
-  const dir = mkdtempSync(join(tmpdir(), 'devrites-engine-'));
+  const dir = privateTempDir();
   const out = join(dir, platform === 'windows' ? 'devrites-engine.exe' : 'devrites-engine');
   const url = `https://github.com/${repo}/releases/download/${tag}/${name}`;
-  if (!await downloadURL(url, out, 0o755)) return null;
-  if (!await downloadURL(`${url}.sha256`, `${out}.sha256`)) return null;
-  const want = readFileSync(`${out}.sha256`, 'utf8').trim().split(/\s+/)[0];
-  const got = createHash('sha256').update(readFileSync(out)).digest('hex');
+  const assetFailure = await downloadURL(url, out, MAX_ENGINE_BYTES, 120_000, 0o755);
+  if (assetFailure) {
+    acquisitionFailure = `release ${tag} asset ${name}: ${assetFailure}`;
+    return null;
+  }
+  const sidecarFailure = await downloadURL(`${url}.sha256`, `${out}.sha256`, MAX_SIDECAR_BYTES, 30_000);
+  if (sidecarFailure) {
+    acquisitionFailure = `release ${tag} asset ${name}.sha256: ${sidecarFailure}`;
+    rmSync(out, { force: true });
+    return null;
+  }
+  let want;
+  let got;
+  try {
+    const match = readFileSync(`${out}.sha256`, 'utf8').match(/^([0-9A-Fa-f]{64})[ \t]+([^\r\n]+)\r?\n?$/);
+    want = match && match[2] === name ? match[1].toLowerCase() : null;
+    got = await hashFile(out);
+  } catch {
+    acquisitionFailure = `release ${tag} asset ${name}: checksum read failed`;
+    rmSync(out, { force: true });
+    rmSync(`${out}.sha256`, { force: true });
+    return null;
+  }
   if (!want || got !== want) {
+    acquisitionFailure = `release ${tag} asset ${name}: checksum failed`;
+    rmSync(out, { force: true });
+    rmSync(`${out}.sha256`, { force: true });
+    return null;
+  }
+  try {
+    chmodSync(out, 0o755);
+  } catch {
+    acquisitionFailure = `release ${tag} asset ${name}: executable preparation failed`;
     rmSync(out, { force: true });
+    rmSync(`${out}.sha256`, { force: true });
     return null;
   }
-  chmodSync(out, 0o755);
   return out;
 }
 
-async function downloadURL(url, out, mode = 0o644) {
+function normalizeReleaseTag(value) {
+  const version = String(value).replace(/^v/, '');
+  const semver = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+  const match = version.match(semver);
+  if (!match || (match[4] && match[4].split('.').some((part) => /^\d+$/.test(part) && part.length > 1 && part.startsWith('0')))) return null;
+  return `v${version}`;
+}
+
+function validRepository(value) {
+  return /^[A-Za-z0-9][A-Za-z0-9_.-]*\/[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(value);
+}
+
+async function hashFile(path) {
+  const hash = createHash('sha256');
+  for await (const chunk of createReadStream(path)) hash.update(chunk);
+  return hash.digest('hex');
+}
+
+async function downloadURL(url, out, maxBytes, timeoutMs, mode = 0o644) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  let file;
   try {
-    const res = await fetch(url);
-    if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
-    writeFileSync(out, Buffer.from(await res.arrayBuffer()), { mode });
-    return true;
-  } catch {
+    let currentURL = new URL(url);
+    let res;
+    for (let redirects = 0; ; redirects += 1) {
+      if (currentURL.protocol !== 'https:') throw new DownloadError('redirect failed');
+      res = await fetch(currentURL.href, { redirect: 'manual', signal: controller.signal });
+      if (!REDIRECT_STATUSES.has(res.status)) break;
+      const location = res.headers.get('location');
+      await res.body?.cancel();
+      if (!location) throw new DownloadError('redirect failed');
+      if (redirects >= MAX_REDIRECTS) throw new DownloadError('redirect limit failed');
+      currentURL = new URL(location, currentURL);
+    }
+    if (!res.ok) throw new DownloadError(`HTTP status ${res.status} failed`);
+    const contentLength = Number(res.headers.get('content-length'));
+    if (Number.isFinite(contentLength) && contentLength > maxBytes) throw new DownloadError('size limit failed');
+    if (!res.body) throw new DownloadError('response body failed');
+    try {
+      file = await open(out, 'wx', mode);
+    } catch {
+      throw new DownloadError('local write failed');
+    }
+    let bytes = 0;
+    for await (const chunk of res.body) {
+      bytes += chunk.byteLength;
+      if (bytes > maxBytes) throw new DownloadError('size limit failed');
+      try {
+        await file.writeFile(Buffer.from(chunk));
+      } catch {
+        throw new DownloadError('local write failed');
+      }
+    }
+    try {
+      await file.close();
+      file = undefined;
+    } catch {
+      throw new DownloadError('local write failed');
+    }
+    return null;
+  } catch (error) {
+    await file?.close().catch(() => {});
     rmSync(out, { force: true });
-    return false;
+    if (error instanceof DownloadError) return error.message;
+    return controller.signal.aborted ? 'timeout failed' : 'network failed';
+  } finally {
+    clearTimeout(timeout);
   }
 }
 
@@ -162,7 +272,13 @@ if (first && SUBCOMMAND_ALIASES.has(first)) {
   rest = argv.slice(1);
 }
 
-const engine = await acquireEngine();
+let engine;
+try {
+  engine = await acquireEngine();
+} catch (error) {
+  console.error(`devrites: ${error.message}`);
+  process.exit(1);
+}
 const payloadDir = process.env.DEVRITES_HOST_ARTIFACT_DIR || join(root, 'pack', 'generated');
 const installerCommand = command === 'install' || command === 'update' || command === 'uninstall';
 const engineEnv = { ...process.env, DEVRITES_ENGINE_CLI: engine };
@@ -180,6 +296,6 @@ const lastError = firstWorking(candidates, args, engineEnv);
 if (lastError && lastError.code !== 'ENOENT') {
   console.error('devrites: failed to launch devrites-engine:', lastError.message);
 } else {
-  console.error('devrites: devrites-engine was not found and could not be acquired.');
+  console.error(`devrites: devrites-engine was not found and could not be acquired${acquisitionFailure ? ` (${acquisitionFailure})` : ''}.`);
 }
 process.exit(127);

package/docs/adr/0003-gate-model-hitl-pause.md

@@ -33,6 +33,6 @@ completion with empty proof, or with `.red` set, cannot end the turn.
 ## Consequences
 
 - Exit 3 is a reserved, load-bearing contract — the harness and hooks branch on
-  it. Its guard test (`tests/adr_0003_gate_exit_code_test.go`) locks it.
+  it. Its guard test (`engine/tests/adr_0003_gate_exit_code_test.go`) locks it.
 - Blocks are legible: the agent (and human) see exactly which section is missing.
 - Gate authors must classify a stop as "incomplete" (exit 3) vs a true error.

package/docs/adr/0013-native-codex-agent-orchestration.md

@@ -0,0 +1,74 @@
+# ADR-0013: Native Codex agent orchestration
+
+- **Status:** Accepted
+- **Date:** 2026-07-29
+
+## Context
+
+ADR-0010 established fresh, depth-one specialist agents with one write-capable
+slice wright. At the time, Codex custom-agent routing varied across MultiAgent
+versions, so DevRites added a Go state machine that parsed prompts and rollout
+files, rewrote generic `explorer`/`worker` spawns, and tracked spawn, start,
+wait, stop, and result receipts.
+
+Current Codex releases load project agents from `.codex/agents/*.toml`, apply
+their `developer_instructions` and sandbox settings, and own the
+spawn/wait/result lifecycle. Keeping a second lifecycle in DevRites caused
+false failures when the native child started correctly but the synthetic
+receipt did not match.
+
+Codex still cannot infer DevRites workflow state or the slice wright's
+per-window exact file allowlist.
+
+## Decision
+
+For Codex, DevRites uses the host's named custom-agent orchestration directly:
+
+- skills request the exact `devrites-<role>` agent with a fresh context and
+  wait for its result;
+- Codex loads the role's generated `.codex/agents/*.toml` profile;
+- read-only roles use native `sandbox_mode = "read-only"`; and
+- an unavailable named role stops for human intervention instead of switching
+  to a version-specific or generic compatibility lane.
+
+Generated Codex skills and agents translate the canonical Claude-authored
+paths and file formats, but do not receive a repeated compatibility preamble.
+Codex-wide operating guidance lives once in the installed project
+`AGENTS.md`, which Codex loads natively.
+
+The engine does not parse Codex rollout files or track parallel
+spawn/start/wait/stop receipts. `required-agent-roles` and `dispatch-waive`
+metadata exist only for that deleted receipt system and are removed. The skill
+body is the source of truth for when a specialist is required.
+
+DevRites hooks remain only where they enforce DevRites-owned state or policy.
+In particular, the slice wright keeps its engine-backed exact allowlist and
+reconcile boundary. A wright-only start hook captures canonical state before
+writer work begins. Typed `agent-packet/v1` and `agent-result/v1` envelopes,
+root-owned reconciliation, lifecycle gates, and destructive-action policy also
+remain.
+
+ADR-0010 still governs fresh-context ownership, depth, typed results, and the
+single-writer model. This record replaces its generic Codex fallback and
+receipt-based identity implementation.
+
+## Alternatives considered
+
+| Option | Why not |
+|---|---|
+| Keep the V1/V2 receipt state machine | It duplicates the host lifecycle, depends on unstable rollout internals, and can reject a correctly started native agent. |
+| Keep generic `explorer`/`worker` fallback | It weakens exact role identity and preserves version-specific branches after named custom agents became the supported interface. |
+| Remove all agent-related hooks | Codex cannot derive the active reconcile snapshot or enforce the wright's dynamic exact file allowlist. |
+| Author separate Claude and Codex agent rosters | It creates two mutable sources of truth; generated Codex TOML remains the smaller dual-host adapter. |
+
+## Consequences
+
+- Codex agent dispatch has one path: the exact named custom agent.
+- DevRites no longer blocks completion on synthetic collaboration receipts.
+- Reviewer safety relies on Codex's native sandbox rather than a duplicative
+  Codex engine hook.
+- Codex host guidance has one project-level copy instead of being injected
+  into every generated skill and agent.
+- The engine surface and its tests shrink substantially.
+- A future Codex API change is handled in generated profiles and guidance, not
+  by adding another runtime-version state machine.