@starci/hfs 4.7.32 → 4.7.34

package/runtime/packages/cli/src/catalog.generated.mjs

@@ -1,7 +1,7 @@
 // GENERATED by scripts/cli/gen-catalog.mjs — do not edit
 export const CATALOG = {
   "schema": "starci/cli-catalog@1",
-  "hash": "9ff398eeddb22776cc36e38b7206c0bfe03d3dec2c1e42614fabe349241b53ed",
+  "hash": "22aaaddc27f0ed4d795adfbd63deba5f0071f15dcab2a8456f852a20798b622b",
   "global": [
     {
       "name": "json",
@@ -615,7 +615,7 @@ export const CATALOG = {
             {
               "name": "no-types",
               "type": "boolean",
-              "summary": "skip regenerating the Supabase database types of a lite table"
+              "summary": "skip regenerating the Supabase database types after lite table and queue migrations"
             }
           ],
           "exit": {
@@ -986,6 +986,9 @@ export const CATALOG = {
             "requires Supabase db query --file and SOPS_AGE_KEY or SOPS_AGE_KEY_FILE",
             "reset keeps encrypted temporary recovery parts after a reset/restore failure and reports their directory; plaintext is always deleted",
             "baseline accepts --stamp; restamp requires --map; both preview without --apply",
+            "restamp: a map value is the new stamp, or { file, to?, applied? } when several active migrations share the old stamp",
+            "restamp file names the migration that moves (full name, or the name after the stamp with or without .sql); to defaults to the next free stamp",
+            "restamp applied: for a shared stamp it is read from the history (one SELECT of schema_migrations.name; unreadable refuses) and defaults to true otherwise",
             "plan is always read-only and supports --json; it compares migrations, cron, queues and Vault names",
             "linked/url-env migrate and post-cutover read application-stacks.yaml's database block and preview without --execute",
             "linked/url-env migrate skips an applied baseline and forward chain; held-back migrations belong to post-cutover",
@@ -1249,6 +1252,7 @@ export const CATALOG = {
             "green moves the branch and the tag in one atomic push; red refuses RELEASE_CANDIDATE_CI_RED naming the failing jobs",
             "no run, or no end in time, refuses RELEASE_CANDIDATE_CI_TIMEOUT; unreadable GitHub refuses RELEASE_CI_UNKNOWN; nothing reaches the branch",
             "a red candidate never passes: there is no override and no --no-ci-check flag",
+            "the gate tag is always <release.tagPrefix><package.json version>; a taken tag on another commit is red, never another patch number",
             "gate refuses a dirty tree, HEAD other than --source, a moved HEAD and a tree dirtied by the gates; record and tag only when all gates are green",
             "a gate with summary jest is red on failed tests and on a coverage threshold miss even when the process exits 0",
             "push needs the annotated tag and L4 record of HEAD, runs git push --dry-run --atomic first and never uses --no-verify"
@@ -1608,6 +1612,10 @@ export const CATALOG = {
           "impl": null,
           "conventions": [
             "the deploy actions read environments.<env>.deploy of .starcistacks/application-stacks.yaml and nothing app-specific is kept anywhere else",
+            "deploy runs deploy.postDeploy (names of deploy.tasks) after convergence and before verify, in order",
+            "a post-deploy task that exits non-zero or passes its timeoutSeconds (default 600) fails the deploy and rolls back",
+            "deploy never prints the output of a post-deploy task (secret custody); stack task <name> shows it",
+            "verify never writes: an idempotent write a release owes the data (a catalogue sync, a seed upsert) is a post-deploy task",
             "effectful actions are a dry run unless --execute is given; a placeholder (all-zero) image digest is always refused",
             "secret values are decrypted in memory, piped to docker on stdin and never printed or written",
             "docker swarm init runs once: --init-swarm, --execute and --owner-approved (or STARCI_SWARM_INIT_APPROVED=1); never on an active swarm",
@@ -1648,7 +1656,7 @@ export const CATALOG = {
           "runtimeSide": "host"
         },
         "upgrade": {
-          "summary": "upgrade a lite app to full (--edition full), or add the test world a full app lacks",
+          "summary": "add the test world a full app lacks; a lite app is refused because editions are fixed at scaffold",
           "owner": "@starci/hfs",
           "flags": [
             {
@@ -1658,14 +1666,13 @@ export const CATALOG = {
             }
           ],
           "exit": {
-            "0": "upgraded, completed, or the full app is already complete",
-            "2": "refusal or bad usage"
+            "0": "completed, or the full app is already complete",
+            "2": "refusal (a lite app: HFS_UPGRADE_EDITION_FIXED) or bad usage"
           },
           "json": "none",
           "examples": [
             "starci app upgrade",
-            "starci app upgrade --plan",
-            "starci app upgrade --edition full --plan"
+            "starci app upgrade --plan"
           ],
           "editions": [
             "full",
@@ -1673,6 +1680,7 @@ export const CATALOG = {
           ],
           "impl": null,
           "conventions": [
+            "editions are fixed at scaffold: a lite app refuses HFS_UPGRADE_EDITION_FIXED and there is no lite to full migration",
             "a full app without be/src/tests/world/global-setup.ts gets the test world of a new full app and the test devDependencies it lacks",
             "a world file that exists and differs refuses HFS_UPGRADE_FILE_CONFLICT; nothing is overwritten"
           ],
@@ -3092,6 +3100,16 @@ export const CATALOG = {
               "type": "string",
               "summary": "application root"
             },
+            {
+              "name": "tests",
+              "type": "string",
+              "summary": "Jest test-path regex for a scoped run; requires subjects"
+            },
+            {
+              "name": "subjects",
+              "type": "string",
+              "summary": "app-relative unit-subject regex covering the selected fix reach; requires tests"
+            },
             {
               "name": "out",
               "type": "string",
@@ -3105,7 +3123,8 @@ export const CATALOG = {
           },
           "json": "always",
           "examples": [
-            "starci gate unit --root <app> --out unit-run.json"
+            "starci gate unit --root <app> --out unit-run.json",
+            "starci gate unit --root <app> --tests orders --subjects 'be/src/modules/orders/' --out unit-run.json"
           ],
           "editions": [
             "full"
@@ -3255,6 +3274,7 @@ export const CATALOG = {
           },
           "effect": "local-write",
           "roles": [
+            "worker",
             "lead",
             "coordinator",
             "release",
@@ -4083,7 +4103,7 @@ export const CATALOG = {
             {
               "name": "reconcile",
               "type": "boolean",
-              "summary": "mode: record the re-verify of a stub sibling against the landed seam; needs --job and --exit-code"
+              "summary": "mode: verify a stub sibling against the landed seam; needs --job and --checks-file"
             },
             {
               "name": "job",
@@ -4126,9 +4146,9 @@ export const CATALOG = {
               "summary": "exit code of the sibling re-verify (--reconcile)"
             },
             {
-              "name": "command",
+              "name": "checks-file",
               "type": "string",
-              "summary": "the re-verify command that was run (--reconcile)"
+              "summary": "checks and checkSelection envelope for scoped reconcile (--reconcile)"
             },
             {
               "name": "evidence",
@@ -4145,7 +4165,7 @@ export const CATALOG = {
           "examples": [
             "starci kernel cut-seam --repo <path> --publish-interface --job <job> --files <files>",
             "starci kernel cut-seam --repo <path> --release --workflow <workflow> --op <op> --cut-id <cut> --reason <reason>",
-            "starci kernel cut-seam --repo <path> --reconcile --job <job> --exit-code 0"
+            "starci kernel cut-seam --repo <path> --reconcile --job <job> --checks-file <file>"
           ],
           "editions": [
             "full"
@@ -6490,7 +6510,7 @@ export const CATALOG = {
             {
               "name": "checks",
               "type": "string",
-              "summary": "JSON {checks:[{name,exitCode,command?,evidence?}]}; one of --checks or --checks-file is required"
+              "summary": "JSON checks and checkSelection envelope; one of --checks or --checks-file is required"
             },
             {
               "name": "checks-file",
@@ -6505,7 +6525,7 @@ export const CATALOG = {
           },
           "json": "flag",
           "examples": [
-            "starci kernel record-checks --repo <path> --job <job> --checks '{\"checks\":[{\"name\":\"build\",\"exitCode\":0}]}'",
+            "starci kernel record-checks --repo <path> --job <job> --checks-file <selection-and-checks.json>",
             "starci kernel record-checks --repo <path> --job <job> --checks-file <file> --json"
           ],
           "editions": [
@@ -8862,7 +8882,9 @@ export const CATALOG = {
             "the package phase rebinds code patterns, re-pins and installs examples, syncs them and proves every binding",
             "runtime-package publishes root package.json after package publication, committed bindings and finished notes; it proves the real archive and private install",
             "runtime-package refuses changed inputs or registry state after its cold proof and never performs rebind or example writes",
-            "publication never commits, pushes or tags; release cut owns those effects"
+            "runtime-package plans the upload channel and release-declared npm dist-tags, repairs stale tags without republishing, and reads every target back",
+            "runtime-package refuses an older release on its line and preserves tags pointing to newer releases on other lines",
+            "publication never commits, pushes or creates Git tags; release cut owns those effects"
           ],
           "runtimeSide": "tree"
         },
@@ -9205,50 +9227,6 @@ export const CATALOG = {
           ],
           "runtimeSide": "tree"
         },
-        "benchmark-snapshot": {
-          "summary": "append one model-pool snapshot file under benchmark/snapshots",
-          "owner": "runtime",
-          "flags": [
-            {
-              "name": "since-hours",
-              "type": "number",
-              "required": true,
-              "summary": "positive scorecard window in hours"
-            },
-            {
-              "name": "repo",
-              "type": "list",
-              "summary": "product ledger owner path"
-            },
-            {
-              "name": "date",
-              "type": "string",
-              "summary": "snapshot date as YYYY-MM-DD"
-            },
-            {
-              "name": "dir",
-              "type": "string",
-              "summary": "snapshot output directory"
-            }
-          ],
-          "exit": {
-            "0": "snapshot appended",
-            "1": "output exists or snapshot failed",
-            "2": "bad usage"
-          },
-          "json": "flag",
-          "examples": [
-            "starci runtime benchmark-snapshot --since-hours 24",
-            "starci runtime benchmark-snapshot --since-hours 24 --repo <path> --json"
-          ],
-          "editions": [
-            "full"
-          ],
-          "impl": {
-            "script": "scripts/agent/benchmark-snapshot.mjs"
-          },
-          "runtimeSide": "tree"
-        },
         "check": {
           "summary": "judge the runtime tree — node --check, the runtime HFS check, the retained self-checks",
           "owner": "runtime",
@@ -15764,5 +15742,14 @@ export const CATALOG = {
         }
       }
     }
+  },
+  "removedVerbs": {
+    "starci guard input": "starci guard input is removed (the reference-transaction hook reads prepared ref updates directly in its shell loop)",
+    "starci debug pass": "debug pass is removed (`starci debug digest` (read-only) and `starci debug run <probe>`)",
+    "starci test affected": "starci test affected is removed (the runtime has no specs of its own (owner ruling no-runtime-specs): `starci runtime verify` runs the check, `starci release clean-test --base <ref>` and `starci release scaffold-e2e`)",
+    "starci test run": "starci test run is removed (the L1 to L4 spec ladder is gone with the runtime specs; `starci runtime verify` proves a change, `starci release cut` runs the release rows)",
+    "starci gate runtime-coverage": "starci gate runtime-coverage is removed (the runtime measures no coverage of its own; the example apps keep their Codecov flags)",
+    "starci release env-test": "starci release env-test is removed (the release rows are the package clean-test (`starci release clean-test`), the scaffold e2e (`starci release scaffold-e2e`) and the runtime check)",
+    "starci runtime benchmark-snapshot": "starci runtime benchmark-snapshot is removed (routing evidence is read live from the ledgers: `starci machine op-metrics --by op` and the ledger view v_model_scorecard (modules/models/registry.yaml costPolicy))"
   }
 };

package/runtime/packages/grammar/scripts/build-stamp.mjs

@@ -0,0 +1,98 @@
+import { createHash } from "node:crypto"
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs"
+import { dirname, join, relative, resolve } from "node:path"
+import { fileURLToPath, pathToFileURL } from "node:url"
+
+/**
+ * The build stamp ties a built `dist/` to the exact source it was built from.
+ *
+ * `npm run build` ends by writing `dist/.build-stamp.json`: the package version, the source digest
+ * (below), a digest of the built files, and the build time. The root check
+ * `scripts/checks/check-grammar-dist.mjs` recomputes the source digest and refuses a dist whose stamp is
+ * missing or names other source, so a stale build can no longer pass for the current one.
+ *
+ * The source digest covers everything that decides what `dist/` contains: every file under `src/`
+ * except stories, test helpers, specs and tests (they never ship), `tsconfig.build.json`,
+ * `packages/grammar/scripts/copy-css.mjs`, and the `exports` and `files` fields of `package.json`. Line endings are
+ * normalised so a CRLF checkout of the same commit has the same digest.
+ */
+
+export const STAMP_FILE = ".build-stamp.json"
+export const STAMP_SCHEMA = "starci/grammar-build-stamp@1"
+export const DIGEST_ALGORITHM = "starci/grammar-source-digest@1"
+
+const DEV_ONLY_DIRS = new Set(["stories", "__test__"])
+const DEV_ONLY_FILE = /\.(?:stories|spec|test)\./
+
+const slash = (value) => value.replaceAll("\\", "/")
+const normalised = (buffer) => Buffer.from(buffer.toString("latin1").replaceAll("\r\n", "\n"), "latin1")
+
+function filesUnder(dir, keep = () => true) {
+    if (!existsSync(dir)) return []
+    return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+        const full = join(dir, entry.name)
+        if (entry.isDirectory()) return keep(entry, true) ? filesUnder(full, keep) : []
+        return entry.isFile() && keep(entry, false) ? [full] : []
+    })
+}
+
+/** The order `.sort()` gives without a compare function (UTF-16 code units): the stamp digest depends on it. */
+const byCodeUnit = (a, b) => (a < b ? -1 : a > b ? 1 : 0)
+
+function hashEntries(entries) {
+    const hash = createHash("sha256")
+    for (const [name, bytes] of entries.sort(([a], [b]) => byCodeUnit(a, b))) {
+        hash.update(name)
+        hash.update("\0")
+        hash.update(bytes === null ? "<absent>" : bytes)
+        hash.update("\0")
+    }
+    return `sha256:${hash.digest("hex")}`
+}
+
+/** The files the source digest reads, relative to the package root, in digest order. */
+export function sourceInputs(packageRoot) {
+    const src = filesUnder(join(packageRoot, "src"), (entry, isDir) =>
+        isDir ? !DEV_ONLY_DIRS.has(entry.name) : !DEV_ONLY_FILE.test(entry.name))
+    return [...src.map((file) => slash(relative(packageRoot, file))), "tsconfig.build.json", "scripts/copy-css.mjs"].sort(byCodeUnit)
+}
+
+/** The digest of everything that decides the content of `dist/`. */
+export function sourceDigest(packageRoot) {
+    const entries = sourceInputs(packageRoot).map((name) => {
+        const file = join(packageRoot, name)
+        return [name, existsSync(file) ? normalised(readFileSync(file)) : null]
+    })
+    const manifest = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"))
+    entries.push(["package.json#exports+files", Buffer.from(JSON.stringify({ exports: manifest.exports ?? null, files: manifest.files ?? null }))])
+    return hashEntries(entries)
+}
+
+/** The digest of the built files themselves (everything in `dist/` except the stamp). */
+export function distDigest(packageRoot) {
+    const dist = join(packageRoot, "dist")
+    const files = filesUnder(dist).map((file) => slash(relative(dist, file))).filter((name) => name !== STAMP_FILE)
+    return hashEntries(files.map((name) => [name, normalised(readFileSync(join(dist, name)))]))
+}
+
+export function writeStamp(packageRoot, { now = new Date() } = {}) {
+    const manifest = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"))
+    if (!existsSync(join(packageRoot, "dist"))) throw new Error("Cannot stamp a build that has no dist/ directory.")
+    const stamp = {
+        schema: STAMP_SCHEMA,
+        package: manifest.name,
+        version: manifest.version,
+        algorithm: DIGEST_ALGORITHM,
+        sourceDigest: sourceDigest(packageRoot),
+        distDigest: distDigest(packageRoot),
+        builtAt: now.toISOString(),
+    }
+    writeFileSync(join(packageRoot, "dist", STAMP_FILE), `${JSON.stringify(stamp, null, 2)}\n`)
+    return stamp
+}
+
+if (process.argv[1] && pathToFileURL(resolve(process.argv[1])).href === import.meta.url) {
+    const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..")
+    const stamp = writeStamp(packageRoot)
+    console.log(`dist/${STAMP_FILE}: ${stamp.package}@${stamp.version} ${stamp.sourceDigest.slice(0, 19)}`)
+}

package/runtime/scripts/agent/codex-app-server.mjs

@@ -0,0 +1,79 @@
+// scripts/agent/codex-app-server.mjs — the runtime's `codex app-server` client (kept out of trust.mjs, which is over
+// its size budget).
+//
+// Codex computes the hash it trusts a hook by; launch trust asks it through the app-server protocol the way Orca
+// trusts its own hooks (scripts/agent/trust.mjs trustCodexToolGuard). The client is a node one-shot: it spawns
+// `codex app-server`, sends initialize then each request, and prints one stdout line — the results array, or
+// {failed} when codex ended (or never started) before answering. Without that line an early exit only drained the
+// client's event loop: exit 0, nothing printed, and codex's stderr discarded — so "answered nothing (exit 0)" was
+// the client's exit, never codex's. The failure names codex's exit/signal, the request it left unanswered, its
+// stderr tail, `codex --version` and the CODEX_HOME it ran with; its text starts with APP_SERVER_FAILURE, which
+// scripts/agent/provider-outage.mjs reads as a worker-start strike of the codex circuit.
+//
+// The probe is a runtime-owned child: it gets the caller's env without the seat identity or the seat's guard-shim
+// PATH (scripts/lib/seat-env.mjs). A launch-trust call made under a Kernel seat otherwise inherits both — and
+// `codex`'s own launcher resolves `node` through PATH, so the seat's tool wrapper bound the seat's role to it and
+// refused the probe as a raw tool call (RIGHTS_RAW_TOOL, exit 2; `codex --version` printed the same refusal).
+import { runNode } from '../api/node/run-node.mjs';
+import { parseJson } from '../lib/json.mjs';
+import { withoutSeatEnv, withoutSeatShim } from '../lib/seat-env.mjs';
+
+// Every launch-trust app-server failure starts with this text; provider-outage.mjs classifies it.
+export const APP_SERVER_FAILURE = 'codex app-server answered nothing';
+
+const APP_SERVER_CLIENT = String.raw`
+const { spawn, spawnSync } = require('node:child_process');
+const reqs = JSON.parse(process.argv[1]);
+const p = spawn('codex app-server', { shell: true, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+const out = []; let buf = ''; let next = 0; let ready = false; let err = '';
+const send = (o) => p.stdin.write(JSON.stringify(o) + '\n');
+const ask = () => { if (next >= reqs.length) { console.log(JSON.stringify(out)); p.kill(); process.exit(0); } send({ id: 100 + next, ...reqs[next] }); };
+const fail = (exit, signal, spawnError) => {
+  const v = spawnSync('codex --version', { shell: true, encoding: 'utf8', timeout: 15000, windowsHide: true });
+  const version = String(v.stdout || v.stderr || '').trim() || null;
+  console.log(JSON.stringify({ failed: { exit, signal, spawnError, stage: ready ? reqs[next].method : 'initialize', stderr: err.trim(), version } }));
+  process.exit(3);
+};
+p.stdin.on('error', () => {});
+p.stderr.on('data', (d) => { err = (err + d).slice(-4000); });
+p.stdout.on('data', (d) => { buf += d; let i; while ((i = buf.indexOf('\n')) >= 0) { const line = buf.slice(0, i); buf = buf.slice(i + 1); let m; try { m = JSON.parse(line); } catch { continue; }
+  if (m.id === 1) { ready = true; send({ method: 'initialized' }); ask(); }
+  else if (m.id === 100 + next) { out.push(m.error ? { error: m.error } : m.result); next += 1; ask(); } } });
+p.on('error', (e) => fail(null, null, e.message));
+p.on('close', (code, signal) => fail(code, signal, null));
+send({ id: 1, method: 'initialize', params: { clientInfo: { name: 'starci-launch-trust', version: '1' } } });
+`;
+
+const tail = (text, n) => { const t = String(text ?? '').replace(/\s+/g, ' ').trim(); return t.length > n ? '...' + t.slice(-n) : t; };
+
+// The error of an app-server call that returned no results: what ended it (codex's exit/signal or the client's own),
+// codex's stderr tail and version, and the CODEX_HOME it ran with.
+function appServerFailure({ home, timeoutMs, r, failed }) {
+  const parts = [];
+  if (failed) {
+    parts.push(
+      failed.spawnError ? 'did not start: ' + failed.spawnError
+        : 'exited ' + (failed.exit ?? 'on ' + failed.signal) + ' before answering ' + failed.stage,
+      failed.stderr ? 'stderr: ' + tail(failed.stderr, 400) : 'no stderr',
+      failed.version ? 'codex --version: ' + tail(failed.version, 120) : 'codex --version printed nothing');
+  } else {
+    parts.push('client exit ' + r.status + (r.error ? ': ' + r.error.message : ''));
+    if (r.error?.code === 'ETIMEDOUT') parts.push('no answer within ' + timeoutMs + 'ms');
+    const stderr = tail(r.stderr, 400);
+    if (stderr) parts.push('client stderr: ' + stderr);
+  }
+  parts.push('CODEX_HOME ' + home);
+  return APP_SERVER_FAILURE + ' (' + parts.join('; ') + ')';
+}
+
+/**
+ * The app-server calls of one Codex home, in order: `requests` [{method, params}] -> results[] (an error result is
+ * {error}). No results throws the precise failure (appServerFailure).
+ */
+export function codexAppServer({ home, requests, timeoutMs = 60_000, env = process.env }) {
+  const r = runNode(['-e', APP_SERVER_CLIENT, JSON.stringify(requests)], { timeout: timeoutMs,
+    env: { ...withoutSeatShim(withoutSeatEnv(env)), CODEX_HOME: home } });
+  const last = parseJson(String(r.stdout ?? '').trim().split(/\r?\n/).pop() ?? '', null);
+  if (Array.isArray(last)) return last;
+  throw new Error(appServerFailure({ home, timeoutMs, r, failed: last?.failed ?? null }));
+}

package/runtime/scripts/agent/codex-mirror-source.mjs

@@ -0,0 +1,34 @@
+// scripts/agent/codex-mirror-source.mjs — the system Codex home a launch also trusts, beside Orca's managed Codex home.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * The system Codex home (<home>/.codex). Orca starts a Codex worker in one of two homes and the launch cannot know
+ * which until Orca spawns it: the managed home (<userData>/codex-runtime-home/home), whose config.toml Orca rebuilds
+ * from this home's at every launch keeping only its own `[projects.*]` and `[hooks.state.*]` tables (a
+ * `[[hooks.PreToolUse]]` block written to the managed file alone is gone seconds after `worker-start`, observed
+ * 2026-10-07 18:32), or this home itself, once Codex has approved Orca's status hook in it (Orca 1.4.221 on Windows,
+ * as on macOS and Linux). Launch trust therefore records the project, the notices and the guard in both.
+ *
+ * Null when the launch's Codex home is no Orca-chosen one (an explicit CODEX_HOME): Orca neither mirrors from nor
+ * starts the worker in the system home then. A trust home (specs) re-roots the source under `<root>/system`, a
+ * directory of its own beside the managed `<root>/.codex`.
+ */
+function codexMirrorSource({ env = process.env } = {}) {
+  const root = env.STARCI_AGENT_TRUST_HOME || null;
+  if (root) return path.join(root, 'system', '.codex');
+  return env.CODEX_HOME ? null : path.join(os.homedir(), '.codex');
+}
+
+/**
+ * The Codex homes one launch records trust in: the active home(s) plus the system home when it has a config.toml.
+ * A system home without one stays untouched: Orca refuses a blank mirror source, and a file created for the launch
+ * alone would replace the owner's settings in the mirror and mask them in the home Orca starts the worker in.
+ */
+export function codexLaunchHomes({ homes, env = process.env }) {
+  const source = codexMirrorSource({ env });
+  const key = (dir) => path.resolve(dir).toLowerCase();
+  const present = source && fs.existsSync(path.join(source, 'config.toml')) && !homes.some((h) => key(h.dir) === key(source));
+  return present ? [...homes, { kind: 'system-codex-home', dir: path.resolve(source) }] : homes;
+}

package/runtime/scripts/agent/host-agents.mjs

@@ -0,0 +1,80 @@
+// The host-agent preflight of one launch (contract change host-agent-preflight): before anything is trusted or started,
+// the agent the route names must be usable on THIS host. Three refusals, each typed:
+//   agent-disabled-on-host   Orca's own settings (orca-data.json of the active profile, settings.disabledTuiAgents) disable it;
+//   agent-binary-missing     its CLI binary (the card's start.cli, or Orca's agentCmdOverrides command) is not on PATH;
+//   agent-bypass-missing     Orca's settings.agentDefaultArgs for the agent lack the card's bypassFlag (an approval prompt no one answers);
+//   model-not-listed         the model is no model the runtime declares for that provider (a provider that declares none, like Cursor whose
+//                            models Orca lists dynamically, is not judged) (registry.yaml models + the pools' model pins);
+//                            a card with no model flag (Devin) takes no model.
+// No agent list is hard-coded: the card, Orca's settings and PATH decide. A test process reads none of them unless a spec passes
+// its own `settingsFile` / `pathDirs` (the host's real settings must not decide a spec's verdict).
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseYaml } from '../../engine/yaml.mjs';
+import { isSpecRun } from '../lib/env.mjs';
+import { appDataBase } from '../lib/app-data.mjs';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const readYaml = (rel) => { try { return parseYaml(fs.readFileSync(path.join(root, rel), 'utf8')); } catch { return null; } };
+const readJson = (file) => { try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; } };
+
+/** Orca's userData folder (STARCI_ORCA_USER_DATA re-roots it, as for Orca's CODEX_HOME in agent/trust.mjs). */
+export function orcaUserData({ env = process.env, platform = process.platform, home = os.homedir() } = {}) {
+  if (env.STARCI_ORCA_USER_DATA) return env.STARCI_ORCA_USER_DATA;
+  return path.join(appDataBase({ env, platform, home }), 'orca');
+}
+
+/** The settings file of Orca's active profile: <userData>/profiles/<activeProfileId>/orca-data.json. */
+function orcaSettingsFile(opts = {}) {
+  const data = orcaUserData(opts);
+  const profile = readJson(path.join(data, 'orca-profile-index.json'))?.activeProfileId ?? 'local-default';
+  return path.join(data, 'profiles', profile, 'orca-data.json');
+}
+
+/** The models the runtime declares for `provider`: the registry `models` entries plus every pool's pins. */
+function modelsOfProvider(provider) {
+  const found = new Set();
+  const registry = readYaml('modules/models/registry.yaml');
+  for (const [id, row] of Object.entries(registry?.models ?? {})) if (row?.provider === provider) found.add(id);
+  for (const pool of Object.values(registry?.pools ?? {})) {
+    if (pool?.provider !== provider) continue;
+    if (typeof pool.defaultModel === 'string') found.add(pool.defaultModel);
+    for (const v of Object.values(pool.models ?? {})) if (typeof v === 'string') found.add(v);
+  }
+  return found;
+}
+
+const onPath = (binary, { pathDirs, platform, env = process.env }) => {
+  const exts = platform === 'win32' ? ['', ...(env.PATHEXT || '.EXE;.CMD;.BAT').split(';').map((e) => e.toLowerCase())] : [''];
+  return pathDirs.some((dir) => exts.some((ext) => { try { return fs.statSync(path.join(dir, binary + ext)).isFile(); } catch { return false; } }));
+};
+
+/**
+ * {ok:true} or {ok:false, code, error}. `card` is the agent card (loadAdapter). Injectable for specs: settingsFile, pathDirs,
+ * platform, env, models (a Set replacing the declared models).
+ */
+export function hostAgentVerdict({ provider, model = null, card, env = process.env, platform = process.platform, settingsFile = null, pathDirs = null, models = null }) {
+  if (!settingsFile && !pathDirs && isSpecRun(env)) return { ok: true, skipped: 'a test process does not read the host agents' };
+  const agent = card?.start?.agentArgument ?? provider;
+  const settings = readJson(settingsFile ?? orcaSettingsFile({ env, platform }))?.settings ?? {};
+  if ((settings.disabledTuiAgents ?? []).includes(agent)) {
+    return { ok: false, code: 'agent-disabled-on-host', error: `agent '${agent}' is disabled in Orca's settings (disabledTuiAgents): enable it in Orca or route the role to another agent` };
+  }
+  const flag = card?.start?.bypassFlag;
+  if (flag && !String(settings.agentDefaultArgs?.[agent] ?? '').includes(flag)) {
+    return { ok: false, code: 'agent-bypass-missing', error: `agent '${agent}' has no '${flag}' in Orca's agentDefaultArgs: a worker would stop at an approval prompt no one answers; add it in Orca's settings` };
+  }
+  const override = settings.agentCmdOverrides?.[agent];
+  const binary = (typeof override === 'string' && override.trim() ? override.trim().split(/\s+/)[0] : null) ?? card?.start?.cli ?? agent;
+  const dirs = pathDirs ?? String(env.PATH || env.Path || '').split(path.delimiter).filter(Boolean);
+  if (!path.isAbsolute(binary) && !onPath(binary, { pathDirs: dirs, platform, env })) {
+    return { ok: false, code: 'agent-binary-missing', error: `agent '${agent}' needs the CLI binary '${binary}', which is not on PATH: install it or route the role to another agent` };
+  }
+  if (card?.start?.modelArgument !== false && model) {
+    const listed = models ?? modelsOfProvider(provider);
+    if (listed.size && !listed.has(model)) return { ok: false, code: 'model-not-listed', error: `model '${model}' is not a model the runtime declares for provider '${provider}' (modules/models/registry.yaml: models, pools)` };
+  }
+  return { ok: true };
+}

package/runtime/scripts/agent/launch-trust-policy.mjs

@@ -0,0 +1,53 @@
+// Current launch-root identity and owner-profile authorization. This module
+// resolves authority only; the trust writer keeps all provider file effects.
+import fs from 'node:fs';
+import path from 'node:path';
+import { revParseQuery } from '../api/git/rev-parse-query.mjs';
+import { launchTrustSettings } from '../../engine/config.mjs';
+
+/** The launch cwd as a directory, or null for an Orca selector ('active', 'id:…'). */
+function launchDirectory(worktree) {
+  if (typeof worktree !== 'string' || !worktree.trim()) return null;
+  const p = worktree.startsWith('path:') ? worktree.slice(5) : worktree;
+  try { return fs.statSync(p).isDirectory() ? path.resolve(p) : null; } catch { return null; }
+}
+
+/** Paths Codex keys trust by: the cwd, its git toplevel and the main worktree root. */
+export function codexTrustPaths(cwd) {
+  const out = [path.resolve(cwd)];
+  const git = (...args) => {
+    try {
+      const r = revParseQuery(args, { dir: cwd, timeout: 10000 });
+      return r.status === 0 ? r.stdout.trim() : null;
+    } catch { return null; }
+  };
+  const top = git('--show-toplevel');
+  if (top) out.push(path.resolve(top));
+  const common = git('--path-format=absolute', '--git-common-dir');
+  if (common && path.basename(common) === '.git') out.push(path.resolve(path.dirname(common)));
+  const seen = new Set();
+  return out.filter((p) => {
+    const k = process.platform === 'win32' ? p.toLowerCase() : p;
+    if (seen.has(k)) return false;
+    seen.add(k);
+    return true;
+  });
+}
+
+/** Resolve an existing checkout to exact current owner roots; never authorize by path prefix. */
+export function launchTrustVerdict({cwd,config,platform=process.platform,roots=codexTrustPaths}={}){
+  const dir=launchDirectory(cwd);
+  if(!dir)return {ok:false,status:'declined',reason:'automatic trust requires a resolved existing launch directory'};
+  let policy;try{policy=config===undefined?launchTrustSettings():launchTrustSettings(config);}catch(error){return {ok:false,status:'declined',reason:String(error.message)};}
+  if(policy?.profile!=='automatic')return {ok:false,status:'declined',reason:policy?.profile==='declined'?'owner declined automatic launch trust':'current owner launchTrust profile is not adopted'};
+  const key=p=>{const real=fs.realpathSync(p);return platform==='win32'?real.toLowerCase():real;};
+  try{
+    const paths=roots(dir);
+    const approved=new Map(policy.roots.map(root=>[key(root),root]));
+    // A worktree is authorized by its exact Git main root. A non-Git directory
+    // needs its own exact root entry; a child of an approved directory is insufficient.
+    const root=paths.at(-1);
+    if(!root||!approved.has(key(root)))return {ok:false,status:'declined',reason:'launch repository is outside the exact owner-approved roots'};
+    return {ok:true,dir,paths,approval:{approvedBy:policy.approvedBy,approvalRef:policy.approvalRef,root:approved.get(key(root))}};
+  }catch(error){return {ok:false,status:'declined',reason:`cannot verify launch roots: ${error.message}`};}
+}