repo-harness 0.12.1 → 0.12.2

package/README.es.md

@@ -466,8 +466,8 @@ repositorio adopte la misma política.
 
 ## Versión actual
 
-- Paquete npm: `repo-harness@0.12.1`
-- Sello de workflow generado: `repo-harness@0.12.1+template@0.12.1`
+- Paquete npm: `repo-harness@0.12.2`
+- Sello de workflow generado: `repo-harness@0.12.2+template@0.12.2`
 - Repositorio de GitHub: `Ancienttwo/repo-harness`
 - Notas de versión e historial: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.fr.md

@@ -461,8 +461,8 @@ adopte la même policy.
 
 ## Release actuelle
 
-- Package npm : `repo-harness@0.12.1`
-- Generated workflow stamp : `repo-harness@0.12.1+template@0.12.1`
+- Package npm : `repo-harness@0.12.2`
+- Generated workflow stamp : `repo-harness@0.12.2+template@0.12.2`
 - Dépôt GitHub : `Ancienttwo/repo-harness`
 - Notes et historique de release : [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.ja.md

@@ -469,8 +469,8 @@ commit script や hooks に組み込まないでください。
 
 ## 現在の Release
 
-- npm package：`repo-harness@0.12.1`
-- Generated workflow stamp：`repo-harness@0.12.1+template@0.12.1`
+- npm package：`repo-harness@0.12.2`
+- Generated workflow stamp：`repo-harness@0.12.2+template@0.12.2`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release notes and history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.md

@@ -441,8 +441,8 @@ repo-harness commit scripts or hooks unless that repo adopts the same policy.
 
 ## Current Release
 
-- npm package: `repo-harness@0.12.1`
-- Generated workflow stamp: `repo-harness@0.12.1+template@0.12.1`
+- npm package: `repo-harness@0.12.2`
+- Generated workflow stamp: `repo-harness@0.12.2+template@0.12.2`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release notes and history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.zh-CN.md

@@ -448,8 +448,8 @@ policy。
 
 ## 当前 Release
 
-- npm package：`repo-harness@0.12.1`
-- Generated workflow stamp：`repo-harness@0.12.1+template@0.12.1`
+- npm package：`repo-harness@0.12.2`
+- Generated workflow stamp：`repo-harness@0.12.2+template@0.12.2`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release notes 和 history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/agents/fleet/gatekeeper.md

@@ -1,9 +1,9 @@
 ---
 name: gatekeeper
-description: Read-only acceptance and ship gate on Fable at xhigh effort. Use after execution workers deliver work: it reviews the diff against the goal, runs the project's real verification, and returns PASS/FAIL/BLOCKED with evidence and a ship recommendation. It never edits, commits, pushes, opens or merges PRs, or decides to ship; fixes and terminal actions stay with the orchestrator.
+description: Read-only acceptance and ship gate on Opus at high effort. Use after execution workers deliver work: it reviews the diff against the goal, runs the project's real verification, and returns PASS/FAIL/BLOCKED with evidence and a ship recommendation. It never edits, commits, pushes, opens or merges PRs, or decides to ship; fixes and terminal actions stay with the orchestrator.
 tools: ["Read", "Grep", "Glob", "Bash"]
-model: fable
-effort: xhigh
+model: opus
+effort: high
 ---
 
 You are the read-only acceptance and ship gate. Execution workers deliver work; you judge whether it is fit to ship and recommend. The orchestrator decides and owns every side effect. You never edit code, commit, push, open or merge PRs, or execute a release order.

package/assets/reference-configs/external-tooling.md

@@ -443,19 +443,19 @@ mapping.
 | `sonnet`, `haiku` | `gpt-5.6-luna` | `low`, `medium`, `high`, `xhigh`, `max` | same string, unchanged |
 | `fable` | `gpt-5.6-sol` | `low`, `medium`, `high`, `xhigh`, `max` | same string, unchanged |
 
-Two per-agent target overrides are applied after tuple validation, on top of
+Three per-agent target overrides are applied after tuple validation, on top of
 the family row above, and are the only effort remaps in the generator:
 `fast-worker` (`opus`/`medium`) targets `gpt-5.6-luna` at `max` reasoning
 instead of the opus family's `gpt-5.6-terra`/`medium`; `deep-worker`
-(`opus`/`high`) keeps the opus family's `gpt-5.6-terra` model but bumps
-reasoning to `xhigh` instead of `high`. Every other agent's Codex model and
-effort follow the family row unchanged.
+(`opus`/`high`) and `gatekeeper` (`opus`/`high`) keep the opus family's
+`gpt-5.6-terra` model but bump reasoning to `xhigh` instead of `high`. Every
+other agent's Codex model and effort follow the family row unchanged.
 
 `fast-worker`, `deep-worker`, `root-cause-prover`, and `harness-evaluator`
 receive `sandbox_mode = "workspace-write"`; every other role receives
 `sandbox_mode = "read-only"`. Current assignments are explorer
 (`sonnet/high`), deep-reasoner (`opus/xhigh`), fast-worker (`opus/medium`),
-deep-worker (`opus/high`), gatekeeper (`fable/xhigh`), root-cause-prover
+deep-worker (`opus/high`), gatekeeper (`opus/high`), root-cause-prover
 (`opus/high`), and harness-evaluator (`opus/high`). Root-cause-prover's prompt further limits
 writes to bugfix evidence inside the active contract's allowed paths;
 harness-evaluator runs existing skill/adoption surfaces only when both repo and
@@ -467,7 +467,7 @@ profiles scrub inherited repo-harness source/helper overrides. The guard rejects
 checkout and real HOME in either argument position; the role returns BLOCKED
 when the guard fails and must not access the independent `evals/bdd2/**` authority. The opus
 family projects to Terra by default with effort carried through unchanged; the only effort
-remaps are the two explicit per-agent overrides above, and any unmapped model/effort
+remaps are the three explicit per-agent overrides above, and any unmapped model/effort
 combination remains a hard error.
 
 The Codex generator also rewrites the exact upstream provider label in the
@@ -475,10 +475,17 @@ description (for example, `Opus at max effort` or `Sonnet at high effort`) to th
 mapped GPT-5.6 model and reasoning level. A missing label fails closed so the
 installed metadata cannot claim a different model from the TOML settings.
 
-These files define the desired installed role configuration. They do not by
-themselves prove that every native MultiAgentV2 spawn surface selects a named
-role instead of inheriting the parent model; keep runtime selection claims
-behind a real subagent canary.
+These files define the desired installed role configuration and feed both Codex
+dispatch surfaces: native MultiAgentV2 `agent_type` selection, and Codex App
+Thread dispatch, where `model` and `model_reasoning_effort` are read back out of
+the installed TOML and passed explicitly to `codex_app__create_thread`. App
+Thread dispatch is the default Codex path because the flat native spawn schema
+carries only a task name, a message, and `fork_turns`: it cannot select a model
+per role, so a `gpt-5.6-luna` role dispatched natively silently inherits the
+parent model. These files do not by themselves prove that either surface honored
+the configured model; keep runtime selection claims behind a real canary — a
+SubagentStart observation on the native path, an official thread read on the
+thread path.
 
 ### Local merge gate
 
@@ -540,6 +547,34 @@ readiness separate:
 SubagentStart does not expose `model_reasoning_effort`, so repo-harness never
 claims that per-role reasoning effort is verified from this gate.
 
+`native_role_routing` evidence stays scoped to the native fallback path; it says
+nothing about App Thread dispatch, and an absent native canary is not a failure
+of the default thread path. Thread-path model evidence comes from official
+thread reads instead: the requested `model`/`thinking` passed to
+`codex_app__create_thread` and the model observed on the materialized thread are
+recorded separately, and a thread whose runtime model was never read back stays
+unverified. A post-merge live canary on 2026-08-02 requested
+`gpt-5.6-luna`/`max`, materialized a worktree thread, and completed a bounded
+read-only task at the shipped main SHA. The host-owned rollout `turn_context`
+observed `model = gpt-5.6-luna` and `effort = max`, which proves the host-local
+execution matched the request. It does not close the orchestrator contract: the
+current `codex_app__read_thread` response omitted model and effort fields, so
+portable runtime readiness remains unverified and must not be inferred from
+create-call acceptance or private rollout parsing.
+
+The readback contract is version-bound and fail-closed. On Codex CLI
+`0.146.0-alpha.9.2`, `codex app-server generate-json-schema` shows that
+`ThreadReadResponse` contains only `thread`, while its `Thread` object exposes
+`modelProvider` but neither `model` nor `reasoningEffort`. The same generated
+schema exposes `model` and nullable `reasoningEffort` on `ThreadStartResponse`
+and `ThreadResumeResponse`, but the App Thread tools do not propagate those
+fields across the pending-worktree materialization path. Runtime readiness is
+closed only when a public App Thread response exposes the materialized thread's
+observed `model` and reasoning effort separately from the requested tuple. A
+missing or mismatched observed tuple keeps the role-routed result unverified and
+selects the declared fallback; repo-harness must not scrape rollout JSONL or
+SQLite as a compatibility path.
+
 `developer_instructions` is the packaged `.md` body plus the canonical
 EXECUTION_BOUNDARY anti-extras clause, kept byte-identical to the
 `EXECUTION_BOUNDARY` constant in `scripts/contract-run.ts` so every generated
@@ -621,10 +656,16 @@ reports packaged files as `up-to-date`.
 
 `repo-harness run check-agent-tooling --host both --strict-readiness` reports
 `agent_fleet` alongside `codegraph`. With `--check-updates`, it compares each
-installed Claude-side `.md` against the packaged source hash and reports
-`drift`/`synced` per agent without network access. The Codex `.toml` side is a
-generated artifact and is checked for presence; installer golden tests prove
-the deterministic generation.
+installed Claude-side `.md` against the packaged source hash without network
+access. When a file differs from that source, it consults the
+`--accept-user-managed` receipt (`~/.repo-harness/agent-fleet-user-managed.json`):
+an entry whose SHA-256 still matches the file's current installed content
+reports `user-managed` on its own report line instead of drift, while a
+missing or malformed receipt, an absent entry for that path, or a stale hash
+still reports `drift`, fail-closed. The per-host rollup is `up-to-date` once
+nothing is left in drift. The Codex `.toml` side is a generated artifact and
+is checked for presence; installer golden tests prove the deterministic
+generation.
 
 ### Uninstall
 

package/assets/skill-version.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.12.1",
-  "templateVersion": "0.12.1",
+  "version": "0.12.2",
+  "templateVersion": "0.12.2",
   "skillName": "repo-harness",
   "contractId": "tasks-first-harness-v1",
   "compatibility": {
@@ -231,6 +231,10 @@
     {
       "version": "0.12.1",
       "description": "Threads a single SessionStart-minted run identity through hook telemetry and evidence correlation, restructures the five-language README into a get-started-first layout, and refreshes the CodeGraph dev dependency line to latest"
+    },
+    {
+      "version": "0.12.2",
+      "description": "Makes agent-fleet drift checks receipt-aware, hardens verifier environment and provenance boundaries, and routes Codex delegation through model-pinned App Threads with fail-closed fallbacks"
     }
   ],
   "generatedProjectStamp": {

package/assets/templates/helpers/check-agent-tooling.sh

@@ -105,6 +105,7 @@ const AGENT_FLEET_SOURCE_DIR = process.env.REPO_HARNESS_AGENT_FLEET_SOURCE_DIR;
 const AGENT_FLEET_SOURCE_LABEL = "package:agents/fleet";
 const AGENT_FLEET_DEFAULT_MANAGED = ["explorer", "deep-reasoner", "fast-worker", "deep-worker", "gatekeeper", "root-cause-prover", "harness-evaluator"];
 const AGENT_FLEET_INSTALL_COMMAND = "repo-harness run install-agent-fleet";
+const AGENT_FLEET_USER_MANAGED_RECEIPT_PATH = path.join(HOME, ".repo-harness", "agent-fleet-user-managed.json");
 const CODEGRAPH_PACKAGE = "@colbymchenry/codegraph";
 const CODEGRAPH_GLOBAL_INSTALL_COMMAND = `bun add -g ${CODEGRAPH_PACKAGE} && repo-harness tools configure codegraph --target codex --location global`;
 const CODEGRAPH_MCP_CONFIGURE_COMMAND = "repo-harness tools configure codegraph --target <codex|claude|both> --location global";
@@ -248,6 +249,10 @@ function sha1Buffer(buffer) {
   return crypto.createHash("sha1").update(buffer).digest("hex");
 }
 
+function sha256Buffer(buffer) {
+  return `sha256:${crypto.createHash("sha256").update(buffer).digest("hex")}`;
+}
+
 function parseSkillVersion(text) {
   const match = text.match(/^\s*version:\s*["']?([^"'\n]+)["']?/m);
   return match ? match[1].trim() : null;
@@ -872,6 +877,37 @@ function readAgentFleetSource(agent) {
   return { status: "read", path: sourcePath, hash: source.hash };
 }
 
+// Read-only mirror of install-agent-fleet.sh's loadUserManagedReceipt(): this
+// checker never writes ~/.repo-harness/agent-fleet-user-managed.json, it only
+// consults it so an operator-accepted customized file is not misreported as
+// drift. Any malformation invalidates the whole receipt (fail-closed) rather
+// than exempting individual entries.
+function loadAgentFleetUserManagedReceipt() {
+  if (!fs.existsSync(AGENT_FLEET_USER_MANAGED_RECEIPT_PATH)) return { ok: true, hashes: new Map() };
+  try {
+    const parsed = JSON.parse(fs.readFileSync(AGENT_FLEET_USER_MANAGED_RECEIPT_PATH, "utf8"));
+    if (
+      parsed?.protocol !== 1
+      || parsed?.authority !== "user-managed-agent-fleet"
+      || !Array.isArray(parsed.files)
+    ) return { ok: false, hashes: new Map() };
+    const hashes = new Map();
+    for (const entry of parsed.files) {
+      if (
+        !entry
+        || typeof entry.path !== "string"
+        || typeof entry.sha256 !== "string"
+        || !/^sha256:[a-f0-9]{64}$/.test(entry.sha256)
+        || hashes.has(entry.path)
+      ) return { ok: false, hashes: new Map() };
+      hashes.set(entry.path, entry.sha256);
+    }
+    return { ok: true, hashes };
+  } catch (_error) {
+    return { ok: false, hashes: new Map() };
+  }
+}
+
 function detectAgentFleetHost(host, managedAgents) {
   const meta = HOSTS[host];
   const files = managedAgents.map((agent) => inspectAgentFleetFile(host, agent));
@@ -884,9 +920,11 @@ function detectAgentFleetHost(host, managedAgents) {
   const driftAgents = [];
   const syncedAgents = [];
   const sourceMissingAgents = [];
+  const userManagedAgents = [];
 
   if (checkUpdates) {
     if (host === "claude") {
+      const receipt = loadAgentFleetUserManagedReceipt();
       for (const entry of files) {
         if (!entry.present) continue;
         const source = readAgentFleetSource(entry.name);
@@ -896,9 +934,25 @@ function detectAgentFleetHost(host, managedAgents) {
         }
         if (source.hash === entry.hash) {
           syncedAgents.push(entry.name);
-        } else {
-          driftAgents.push(entry.name);
+          continue;
         }
+        // Differs from the packaged source: only a valid receipt entry whose
+        // sha256 matches the file's *current* installed content exempts it.
+        // A missing/invalid receipt, a path with no entry, or a hash mismatch
+        // (edited again after acceptance) all fall through to drift.
+        if (receipt.ok && receipt.hashes.get(entry.path) !== undefined) {
+          let installedHash = null;
+          try {
+            installedHash = sha256Buffer(fs.readFileSync(entry.path));
+          } catch (_error) {
+            installedHash = null;
+          }
+          if (installedHash === receipt.hashes.get(entry.path)) {
+            userManagedAgents.push(entry.name);
+            continue;
+          }
+        }
+        driftAgents.push(entry.name);
       }
 
       if (driftAgents.length > 0) {
@@ -907,9 +961,11 @@ function detectAgentFleetHost(host, managedAgents) {
       } else if (sourceMissingAgents.length > 0) {
         updateStatus = "unknown";
         updateReason = `Packaged repo-harness fleet source is missing files for: ${sourceMissingAgents.join(", ")}.`;
-      } else if (syncedAgents.length > 0) {
-        updateStatus = "synced";
-        updateReason = "Installed Claude agent definitions match the packaged repo-harness fleet source.";
+      } else if (syncedAgents.length > 0 || userManagedAgents.length > 0) {
+        updateStatus = "up-to-date";
+        updateReason = userManagedAgents.length > 0
+          ? `Installed Claude agent definitions match the packaged repo-harness fleet source, with user-managed exemptions accepted via receipt for: ${userManagedAgents.join(", ")}.`
+          : "Installed Claude agent definitions match the packaged repo-harness fleet source.";
       } else {
         updateStatus = "not-checked";
         updateReason = "No installed Claude agent definitions to compare.";
@@ -931,6 +987,7 @@ function detectAgentFleetHost(host, managedAgents) {
     drift_agents: driftAgents,
     synced_agents: syncedAgents,
     source_missing_agents: sourceMissingAgents,
+    user_managed_agents: userManagedAgents,
   };
 }
 
@@ -1631,6 +1688,9 @@ function printText(result) {
     if (entry.update_status !== "not-checked") {
       console.log(`    updates: ${entry.update_status} (${entry.update_reason})`);
     }
+    if (entry.user_managed_agents.length) {
+      console.log(`    user-managed (receipt): ${entry.user_managed_agents.join(", ")}`);
+    }
   }
   console.log(`  - Install: ${agentFleet.install_command}`);
   if (SELECTED_HOSTS.includes("codex")) {

package/assets/templates/helpers/ensure-task-workflow.sh

@@ -1171,10 +1171,10 @@ ARCHITECTURE_INDEX_EOF
     "allow_parallel_writers": false,
     "stop_fallback": true,
     "state_file": ".ai/harness/delegation/latest.json",
-    "preferred_runners": ["subagent", "codex-subagent", "codex-exec", "main-thread"],
+    "preferred_runners": ["subagent", "codex-app-thread", "codex-subagent", "codex-exec", "main-thread"],
     "fallback_runner": "main-thread",
     "brief_source": "tasks/contracts/<stem>.contract.md",
-    "runner_rule": "the active task contract is the authoritative execution brief consumed by contract-run; native subagent (Claude) or codex-subagent (Codex's own native subagent) is an optional parallelism accelerator, preferred first per host. Degrade to codex-exec, then sequential main-thread, on the SAME contract when spawn is unavailable, sandboxed, or unreliable. Runner-availability fallback MUST be recorded in the contract-run manifest and MUST NOT silently succeed; it is a runner-availability fallback, not a product-semantics compatibility fallback.",
+    "runner_rule": "the active task contract is the authoritative execution brief consumed by contract-run; the preferred parallelism accelerator is native subagent on the Claude host and Codex App Thread dispatch via codex_app__create_thread on the Codex host, each thread created with the role's exact model and reasoning effort read from the installed ~/.codex/agents/<role>.toml. Native codex-subagent (spawn_agent) is a declared fallback only when the App Thread tools are unavailable AND the live spawn schema accepts the role's exact model/effort combination; a role whose exact model/effort that schema does not accept MUST NOT fall back to native spawn, because native spawn silently inherits the parent model. Otherwise degrade to codex-exec, then sequential main-thread, on the SAME contract. Runner-availability fallback MUST be recorded in the contract-run manifest and MUST NOT silently succeed; it is a runner-availability fallback, not a product-semantics compatibility fallback.",
     "rule": "UserPromptSubmit.delegation only injects bounded subagent context after explicit user authorization such as /delegate, /parallel, spawn subagents, or parallel investigation, regardless of delegation.mode. When delegation.mode resolves to \"auto\", the in-process session-context builder (src/cli/hook/session-context.ts) instead injects one standing bounded-delegation authorization block at SessionStart (Codex host only) for the whole session; UserPromptSubmit.delegation does not re-assert it on later prompts. The global ~/.repo-harness/config.json delegation.mode value, when exactly \"auto\" or \"explicit\", takes precedence over this repo policy value when resolving that SessionStart mode."
   },
   "sidecar_research": {

package/assets/templates/helpers/install-agent-fleet.sh

@@ -145,10 +145,12 @@ const MODEL_EFFORT_MAP = {
 
 // Per-agent Codex target overrides — the only effort remaps in the fleet.
 // fast-worker trades the opus/terra default down to Luna at max; deep-worker
-// bumps terra effort to xhigh. Everything else follows the family default.
+// and gatekeeper bump terra effort to xhigh. Everything else follows the
+// family default.
 const AGENT_TARGET_OVERRIDES = {
   "fast-worker": { model: "gpt-5.6-luna", effort: "max", targetDescription: "GPT-5.6 Luna at max reasoning" },
   "deep-worker": { model: "gpt-5.6-terra", effort: "xhigh", targetDescription: "GPT-5.6 Terra at xhigh reasoning" },
+  gatekeeper: { model: "gpt-5.6-terra", effort: "xhigh", targetDescription: "GPT-5.6 Terra at xhigh reasoning" },
 };
 
 function readSource(agent) {

package/assets/templates/helpers/run-bounded-verifier-command.ts

@@ -39,6 +39,23 @@ if (!Number.isFinite(deadlineMs)) usage();
 // process group) outlive this wrapper undetected.
 const FORCED_TERMINATION_CONFIRM_MS = 500;
 
+// A verification command must observe the project's real behaviour in a clean
+// environment. The package-dispatched helper mechanism injects `REPO_HARNESS_*`
+// wiring (helper source path, target repo root, trusted tool binaries) into its
+// child, and that set inherits all the way down verify-sprint -> verify-contract
+// -> a nested test run, where it can silently override a fixture's own repo
+// root or tool resolution. Strip the whole prefix -- not a curated subset --
+// so harness-internal wiring never reaches the command under verification.
+// This runner reads no `REPO_HARNESS_*` variable itself.
+function scrubHarnessEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const scrubbed: NodeJS.ProcessEnv = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (key.startsWith('REPO_HARNESS_')) continue;
+    scrubbed[key] = value;
+  }
+  return scrubbed;
+}
+
 const startedAt = Date.now();
 let timedOut = false;
 let terminating = false;
@@ -49,6 +66,7 @@ const logFd = openSync(logPath, 'w');
 const child = spawn(command, args, {
   detached: process.platform !== 'win32',
   stdio: ['ignore', logFd, logFd],
+  env: scrubHarnessEnv(process.env),
 });
 
 function terminate(signal: NodeJS.Signals): void {

package/assets/templates/helpers/verify-sprint.sh

@@ -545,13 +545,25 @@ finalize_prepared_acceptance() {
     --contract "$contract_file" --verification "$checks_file" --review "$review_file" >/dev/null
 
   finalized_checks="$(mktemp)"
+  # `$checks_file` is a materialized projection, not a run trace: the
+  # materializer (src/effects/evidence/checks-materializer.ts) appends its own
+  # `provenance` block to whatever run trace it projects. Re-emitting that
+  # block as payload would make the next materialization record
+  # `content_hash = sha256(run_trace including the previous provenance)` while
+  # publishing a file whose consumer-facing content excludes it, so the
+  # published projection could no longer be recomputed from its own bytes
+  # (tests/evidence-projection-drift.test.ts's live self-consistency check).
+  # `provenance` is materializer-owned derived metadata; strip it here so the
+  # emitted run trace is a run trace again and the next projection is
+  # self-consistent by construction -- no second hash implementation.
   jq \
     --arg reviewer "$acceptance_reviewer" \
     --arg source "$acceptance_source" \
     --arg disposition "$acceptance_disposition" \
     --arg message "$acceptance_message" \
     '
-      .acceptance_receipt = {
+      del(.provenance)
+      | .acceptance_receipt = {
         status: "pass",
         disposition: $disposition,
         reviewer: $reviewer,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repo-harness",
-  "version": "0.12.1",
+  "version": "0.12.2",
   "description": "Installs, migrates, audits, and repairs repo-local agentic development harnesses",
   "license": "MIT",
   "repository": {

package/scripts/check-agent-tooling.sh

@@ -105,6 +105,7 @@ const AGENT_FLEET_SOURCE_DIR = process.env.REPO_HARNESS_AGENT_FLEET_SOURCE_DIR;
 const AGENT_FLEET_SOURCE_LABEL = "package:agents/fleet";
 const AGENT_FLEET_DEFAULT_MANAGED = ["explorer", "deep-reasoner", "fast-worker", "deep-worker", "gatekeeper", "root-cause-prover", "harness-evaluator"];
 const AGENT_FLEET_INSTALL_COMMAND = "repo-harness run install-agent-fleet";
+const AGENT_FLEET_USER_MANAGED_RECEIPT_PATH = path.join(HOME, ".repo-harness", "agent-fleet-user-managed.json");
 const CODEGRAPH_PACKAGE = "@colbymchenry/codegraph";
 const CODEGRAPH_GLOBAL_INSTALL_COMMAND = `bun add -g ${CODEGRAPH_PACKAGE} && repo-harness tools configure codegraph --target codex --location global`;
 const CODEGRAPH_MCP_CONFIGURE_COMMAND = "repo-harness tools configure codegraph --target <codex|claude|both> --location global";
@@ -248,6 +249,10 @@ function sha1Buffer(buffer) {
   return crypto.createHash("sha1").update(buffer).digest("hex");
 }
 
+function sha256Buffer(buffer) {
+  return `sha256:${crypto.createHash("sha256").update(buffer).digest("hex")}`;
+}
+
 function parseSkillVersion(text) {
   const match = text.match(/^\s*version:\s*["']?([^"'\n]+)["']?/m);
   return match ? match[1].trim() : null;
@@ -872,6 +877,37 @@ function readAgentFleetSource(agent) {
   return { status: "read", path: sourcePath, hash: source.hash };
 }
 
+// Read-only mirror of install-agent-fleet.sh's loadUserManagedReceipt(): this
+// checker never writes ~/.repo-harness/agent-fleet-user-managed.json, it only
+// consults it so an operator-accepted customized file is not misreported as
+// drift. Any malformation invalidates the whole receipt (fail-closed) rather
+// than exempting individual entries.
+function loadAgentFleetUserManagedReceipt() {
+  if (!fs.existsSync(AGENT_FLEET_USER_MANAGED_RECEIPT_PATH)) return { ok: true, hashes: new Map() };
+  try {
+    const parsed = JSON.parse(fs.readFileSync(AGENT_FLEET_USER_MANAGED_RECEIPT_PATH, "utf8"));
+    if (
+      parsed?.protocol !== 1
+      || parsed?.authority !== "user-managed-agent-fleet"
+      || !Array.isArray(parsed.files)
+    ) return { ok: false, hashes: new Map() };
+    const hashes = new Map();
+    for (const entry of parsed.files) {
+      if (
+        !entry
+        || typeof entry.path !== "string"
+        || typeof entry.sha256 !== "string"
+        || !/^sha256:[a-f0-9]{64}$/.test(entry.sha256)
+        || hashes.has(entry.path)
+      ) return { ok: false, hashes: new Map() };
+      hashes.set(entry.path, entry.sha256);
+    }
+    return { ok: true, hashes };
+  } catch (_error) {
+    return { ok: false, hashes: new Map() };
+  }
+}
+
 function detectAgentFleetHost(host, managedAgents) {
   const meta = HOSTS[host];
   const files = managedAgents.map((agent) => inspectAgentFleetFile(host, agent));
@@ -884,9 +920,11 @@ function detectAgentFleetHost(host, managedAgents) {
   const driftAgents = [];
   const syncedAgents = [];
   const sourceMissingAgents = [];
+  const userManagedAgents = [];
 
   if (checkUpdates) {
     if (host === "claude") {
+      const receipt = loadAgentFleetUserManagedReceipt();
       for (const entry of files) {
         if (!entry.present) continue;
         const source = readAgentFleetSource(entry.name);
@@ -896,9 +934,25 @@ function detectAgentFleetHost(host, managedAgents) {
         }
         if (source.hash === entry.hash) {
           syncedAgents.push(entry.name);
-        } else {
-          driftAgents.push(entry.name);
+          continue;
         }
+        // Differs from the packaged source: only a valid receipt entry whose
+        // sha256 matches the file's *current* installed content exempts it.
+        // A missing/invalid receipt, a path with no entry, or a hash mismatch
+        // (edited again after acceptance) all fall through to drift.
+        if (receipt.ok && receipt.hashes.get(entry.path) !== undefined) {
+          let installedHash = null;
+          try {
+            installedHash = sha256Buffer(fs.readFileSync(entry.path));
+          } catch (_error) {
+            installedHash = null;
+          }
+          if (installedHash === receipt.hashes.get(entry.path)) {
+            userManagedAgents.push(entry.name);
+            continue;
+          }
+        }
+        driftAgents.push(entry.name);
       }
 
       if (driftAgents.length > 0) {
@@ -907,9 +961,11 @@ function detectAgentFleetHost(host, managedAgents) {
       } else if (sourceMissingAgents.length > 0) {
         updateStatus = "unknown";
         updateReason = `Packaged repo-harness fleet source is missing files for: ${sourceMissingAgents.join(", ")}.`;
-      } else if (syncedAgents.length > 0) {
-        updateStatus = "synced";
-        updateReason = "Installed Claude agent definitions match the packaged repo-harness fleet source.";
+      } else if (syncedAgents.length > 0 || userManagedAgents.length > 0) {
+        updateStatus = "up-to-date";
+        updateReason = userManagedAgents.length > 0
+          ? `Installed Claude agent definitions match the packaged repo-harness fleet source, with user-managed exemptions accepted via receipt for: ${userManagedAgents.join(", ")}.`
+          : "Installed Claude agent definitions match the packaged repo-harness fleet source.";
       } else {
         updateStatus = "not-checked";
         updateReason = "No installed Claude agent definitions to compare.";
@@ -931,6 +987,7 @@ function detectAgentFleetHost(host, managedAgents) {
     drift_agents: driftAgents,
     synced_agents: syncedAgents,
     source_missing_agents: sourceMissingAgents,
+    user_managed_agents: userManagedAgents,
   };
 }
 
@@ -1631,6 +1688,9 @@ function printText(result) {
     if (entry.update_status !== "not-checked") {
       console.log(`    updates: ${entry.update_status} (${entry.update_reason})`);
     }
+    if (entry.user_managed_agents.length) {
+      console.log(`    user-managed (receipt): ${entry.user_managed_agents.join(", ")}`);
+    }
   }
   console.log(`  - Install: ${agentFleet.install_command}`);
   if (SELECTED_HOSTS.includes("codex")) {

package/scripts/ensure-task-workflow.sh

@@ -1171,10 +1171,10 @@ ARCHITECTURE_INDEX_EOF
     "allow_parallel_writers": false,
     "stop_fallback": true,
     "state_file": ".ai/harness/delegation/latest.json",
-    "preferred_runners": ["subagent", "codex-subagent", "codex-exec", "main-thread"],
+    "preferred_runners": ["subagent", "codex-app-thread", "codex-subagent", "codex-exec", "main-thread"],
     "fallback_runner": "main-thread",
     "brief_source": "tasks/contracts/<stem>.contract.md",
-    "runner_rule": "the active task contract is the authoritative execution brief consumed by contract-run; native subagent (Claude) or codex-subagent (Codex's own native subagent) is an optional parallelism accelerator, preferred first per host. Degrade to codex-exec, then sequential main-thread, on the SAME contract when spawn is unavailable, sandboxed, or unreliable. Runner-availability fallback MUST be recorded in the contract-run manifest and MUST NOT silently succeed; it is a runner-availability fallback, not a product-semantics compatibility fallback.",
+    "runner_rule": "the active task contract is the authoritative execution brief consumed by contract-run; the preferred parallelism accelerator is native subagent on the Claude host and Codex App Thread dispatch via codex_app__create_thread on the Codex host, each thread created with the role's exact model and reasoning effort read from the installed ~/.codex/agents/<role>.toml. Native codex-subagent (spawn_agent) is a declared fallback only when the App Thread tools are unavailable AND the live spawn schema accepts the role's exact model/effort combination; a role whose exact model/effort that schema does not accept MUST NOT fall back to native spawn, because native spawn silently inherits the parent model. Otherwise degrade to codex-exec, then sequential main-thread, on the SAME contract. Runner-availability fallback MUST be recorded in the contract-run manifest and MUST NOT silently succeed; it is a runner-availability fallback, not a product-semantics compatibility fallback.",
     "rule": "UserPromptSubmit.delegation only injects bounded subagent context after explicit user authorization such as /delegate, /parallel, spawn subagents, or parallel investigation, regardless of delegation.mode. When delegation.mode resolves to \"auto\", the in-process session-context builder (src/cli/hook/session-context.ts) instead injects one standing bounded-delegation authorization block at SessionStart (Codex host only) for the whole session; UserPromptSubmit.delegation does not re-assert it on later prompts. The global ~/.repo-harness/config.json delegation.mode value, when exactly \"auto\" or \"explicit\", takes precedence over this repo policy value when resolving that SessionStart mode."
   },
   "sidecar_research": {

package/scripts/install-agent-fleet.sh

@@ -145,10 +145,12 @@ const MODEL_EFFORT_MAP = {
 
 // Per-agent Codex target overrides — the only effort remaps in the fleet.
 // fast-worker trades the opus/terra default down to Luna at max; deep-worker
-// bumps terra effort to xhigh. Everything else follows the family default.
+// and gatekeeper bump terra effort to xhigh. Everything else follows the
+// family default.
 const AGENT_TARGET_OVERRIDES = {
   "fast-worker": { model: "gpt-5.6-luna", effort: "max", targetDescription: "GPT-5.6 Luna at max reasoning" },
   "deep-worker": { model: "gpt-5.6-terra", effort: "xhigh", targetDescription: "GPT-5.6 Terra at xhigh reasoning" },
+  gatekeeper: { model: "gpt-5.6-terra", effort: "xhigh", targetDescription: "GPT-5.6 Terra at xhigh reasoning" },
 };
 
 function readSource(agent) {

package/scripts/lib/project-init-lib.sh

@@ -1859,10 +1859,10 @@ pi_write_harness_policy() {
     "allow_parallel_writers": false,
     "stop_fallback": true,
     "state_file": ".ai/harness/delegation/latest.json",
-    "preferred_runners": ["subagent", "codex-subagent", "codex-exec", "main-thread"],
+    "preferred_runners": ["subagent", "codex-app-thread", "codex-subagent", "codex-exec", "main-thread"],
     "fallback_runner": "main-thread",
     "brief_source": "tasks/contracts/<stem>.contract.md",
-    "runner_rule": "the active task contract is the authoritative execution brief consumed by contract-run; native subagent (Claude) or codex-subagent (Codex's own native subagent) is an optional parallelism accelerator, preferred first per host. Degrade to codex-exec, then sequential main-thread, on the SAME contract when spawn is unavailable, sandboxed, or unreliable. Runner-availability fallback MUST be recorded in the contract-run manifest and MUST NOT silently succeed; it is a runner-availability fallback, not a product-semantics compatibility fallback.",
+    "runner_rule": "the active task contract is the authoritative execution brief consumed by contract-run; the preferred parallelism accelerator is native subagent on the Claude host and Codex App Thread dispatch via codex_app__create_thread on the Codex host, each thread created with the role's exact model and reasoning effort read from the installed ~/.codex/agents/<role>.toml. Native codex-subagent (spawn_agent) is a declared fallback only when the App Thread tools are unavailable AND the live spawn schema accepts the role's exact model/effort combination; a role whose exact model/effort that schema does not accept MUST NOT fall back to native spawn, because native spawn silently inherits the parent model. Otherwise degrade to codex-exec, then sequential main-thread, on the SAME contract. Runner-availability fallback MUST be recorded in the contract-run manifest and MUST NOT silently succeed; it is a runner-availability fallback, not a product-semantics compatibility fallback.",
     "rule": "UserPromptSubmit.delegation only injects bounded subagent context after explicit user authorization such as /delegate, /parallel, spawn subagents, or parallel investigation, regardless of delegation.mode. When delegation.mode resolves to \"auto\", the in-process session-context builder (src/cli/hook/session-context.ts) instead injects one standing bounded-delegation authorization block at SessionStart (Codex host only) for the whole session; UserPromptSubmit.delegation does not re-assert it on later prompts. The global ~/.repo-harness/config.json delegation.mode value, when exactly \"auto\" or \"explicit\", takes precedence over this repo policy value when resolving that SessionStart mode."
   },
   "sidecar_research": {

package/scripts/run-bounded-verifier-command.ts

@@ -39,6 +39,23 @@ if (!Number.isFinite(deadlineMs)) usage();
 // process group) outlive this wrapper undetected.
 const FORCED_TERMINATION_CONFIRM_MS = 500;
 
+// A verification command must observe the project's real behaviour in a clean
+// environment. The package-dispatched helper mechanism injects `REPO_HARNESS_*`
+// wiring (helper source path, target repo root, trusted tool binaries) into its
+// child, and that set inherits all the way down verify-sprint -> verify-contract
+// -> a nested test run, where it can silently override a fixture's own repo
+// root or tool resolution. Strip the whole prefix -- not a curated subset --
+// so harness-internal wiring never reaches the command under verification.
+// This runner reads no `REPO_HARNESS_*` variable itself.
+function scrubHarnessEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const scrubbed: NodeJS.ProcessEnv = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (key.startsWith('REPO_HARNESS_')) continue;
+    scrubbed[key] = value;
+  }
+  return scrubbed;
+}
+
 const startedAt = Date.now();
 let timedOut = false;
 let terminating = false;
@@ -49,6 +66,7 @@ const logFd = openSync(logPath, 'w');
 const child = spawn(command, args, {
   detached: process.platform !== 'win32',
   stdio: ['ignore', logFd, logFd],
+  env: scrubHarnessEnv(process.env),
 });
 
 function terminate(signal: NodeJS.Signals): void {

package/scripts/verify-sprint.sh

@@ -545,13 +545,25 @@ finalize_prepared_acceptance() {
     --contract "$contract_file" --verification "$checks_file" --review "$review_file" >/dev/null
 
   finalized_checks="$(mktemp)"
+  # `$checks_file` is a materialized projection, not a run trace: the
+  # materializer (src/effects/evidence/checks-materializer.ts) appends its own
+  # `provenance` block to whatever run trace it projects. Re-emitting that
+  # block as payload would make the next materialization record
+  # `content_hash = sha256(run_trace including the previous provenance)` while
+  # publishing a file whose consumer-facing content excludes it, so the
+  # published projection could no longer be recomputed from its own bytes
+  # (tests/evidence-projection-drift.test.ts's live self-consistency check).
+  # `provenance` is materializer-owned derived metadata; strip it here so the
+  # emitted run trace is a run trace again and the next projection is
+  # self-consistent by construction -- no second hash implementation.
   jq \
     --arg reviewer "$acceptance_reviewer" \
     --arg source "$acceptance_source" \
     --arg disposition "$acceptance_disposition" \
     --arg message "$acceptance_message" \
     '
-      .acceptance_receipt = {
+      del(.provenance)
+      | .acceptance_receipt = {
         status: "pass",
         disposition: $disposition,
         reviewer: $reviewer,

package/src/cli/hook/session-context.ts

@@ -1312,12 +1312,35 @@ function codexDelegationAutoContext(repoRoot: string, env: NodeJS.ProcessEnv): s
     '# Delegation Standing Authorization',
     '',
     'delegation.mode=auto is standing user authorization for bounded native',
-    'subagent delegation for this session. Spawn only when at least two',
-    `independent, bounded workstreams exist; spawn no more than ${maxAgents}`,
-    'agents; never give concurrent writers overlapping write ownership; pass',
-    'fork_turns="none" on spawn_agent calls that select an agent_type; close',
-    'finished agent threads; do not spawn for a trivial or strictly sequential',
-    'task.',
+    'subagent and Codex App Thread delegation for this session. Dispatch only',
+    'when at least two independent, bounded workstreams exist;',
+    `spawn no more than ${maxAgents} agents; never give concurrent writers`,
+    'overlapping write ownership; do not spawn for a trivial or strictly',
+    'sequential task.',
+    '',
+    'Prefer Codex App Thread dispatch: one codex_app__create_thread per',
+    'workstream, created with the exact model and reasoning effort read from the',
+    'installed ~/.codex/agents/<role>.toml. Use a unique task id per creation',
+    'attempt; a pendingWorktreeId is not a thread id, so confirm materialization',
+    'with an official thread read before counting the worker as running; record',
+    'the requested model and effort separately from the observed runtime model;',
+    'adopt a result only after reading the final turn of that thread; archive',
+    'completed threads one at a time; thread workers must not create further',
+    'threads, agents, or background tasks.',
+    '',
+    'If the live create_thread surface cannot carry that exact model and',
+    'reasoning effort, the thread is inherited-model and must not be adopted as a',
+    'role-routed worker; degrade to codex-exec, then the sequential main thread,',
+    'on the SAME contract and record the degradation.',
+    '',
+    'Native spawn_agent is a declared fallback only when the App Thread tools are',
+    'unavailable and the live spawn schema accepts the exact model and reasoning',
+    'effort of that role; a role whose exact model/effort that schema does not',
+    'accept must not fall back to native spawn, because native spawn silently',
+    'inherits the parent model. Otherwise degrade to codex-exec, then the',
+    'sequential main thread, on the SAME contract and record the degradation. On',
+    'the native fallback pass fork_turns="none" on spawn_agent calls that select',
+    'an agent_type and close finished agent threads.',
   ].join('\n');
 }
 

package/src/cli/hook/subagent-handler.ts

@@ -322,12 +322,19 @@ function runDelegationAdvisor(repoRoot: string, input: JsonObject, env: NodeJS.P
       '- Never give two agents overlapping write ownership.',
       `- Keep max spawn depth at ${maxDepth}.`,
       '- Give every agent a precise scope and required return format.',
-      '- Pass fork_turns="none" on every spawn_agent call that selects an agent_type: the default fork_turns="all" copies the full parent conversation into the child. A named-role child works from its self-contained packet and the contract brief, not inherited parent history.',
+      '- On the native spawn_agent fallback path, pass fork_turns="none" on every spawn_agent call that selects an agent_type: the default fork_turns="all" copies the full parent conversation into the child. A named-role child works from its self-contained packet and the contract brief, not inherited parent history.',
+      '- Use a unique task id for every thread creation attempt; never reuse one across retries.',
+      '- A pendingWorktreeId is not a thread id: confirm the thread materialized with an official thread read before counting the worker as running.',
+      '- Record the requested model and reasoning effort separately from the observed runtime model; an unread model claim stays unverified.',
+      '- Adopt a thread worker result only after reading the final turn of that thread.',
+      '- Archive completed threads one at a time.',
+      '- Thread workers must not create further threads, agents, or background tasks.',
       '- Wait for all requested agents.',
       '- Reconcile contradictory findings in the parent.',
       '- Close completed agent threads.',
       '- Do not spawn for a trivial or strictly sequential task.',
-      '- The role labels above describe responsibilities only; they do not prove that Codex selected a same-name custom-agent profile or its configured model.',
+      '- The role labels above describe responsibilities only; on both the thread path and the native path they do not prove that Codex selected a same-name custom-agent profile or its configured model.',
+      "- Treat a thread as inherited-model whenever the live create_thread surface cannot carry that role's exact model and reasoning effort; such a thread MUST NOT be adopted as a role-routed worker. Degrade to codex-exec, then sequential main-thread, on the SAME contract and record the degradation.",
       '- Treat native children as inherited-model until the SubagentStart hook records matching non-default agent_type and model evidence. If it records unavailable or mismatch, report runner degradation and use the contract runner fallback instead of claiming role-specific routing.',
     ];
     const permissionContext = [
@@ -348,7 +355,7 @@ function runDelegationAdvisor(repoRoot: string, input: JsonObject, env: NodeJS.P
       '',
       `The current user turn is the execution authority. The active task contract (${activeContract?.contract}) constrains the implementation scope authorized by the current turn, but does not by itself authorize resuming prior implementation or completing Exit Criteria.`,
       '',
-      `Runner preference (policy delegation.preferred_runners): ${preferredRunners.join(', ')}. Native subagent (spawn_agent) is the preferred parallelism accelerator that consumes the contract brief. When spawn_agent is unavailable, sandboxed, or unreliable, degrade to ${fallbackRunner || 'main-thread'} on the SAME contract via contract-run. Runner-availability degradation MUST be recorded in the contract-run manifest and MUST NOT silently succeed; it is a runner-availability fallback, not a product-semantics change.`,
+      `Runner preference (policy delegation.preferred_runners): ${preferredRunners.join(', ')}. Codex App Thread dispatch (codex_app__create_thread) is the preferred parallelism accelerator that consumes the contract brief: one thread per bounded workstream, created with the exact model and reasoning effort read from the installed ~/.codex/agents/<role>.toml, with that TOML developer_instructions plus the contract brief inlined as the first message of the thread. If the live create_thread schema cannot carry that exact model and reasoning effort, the resulting thread is inherited-model and MUST NOT be adopted as a role-routed worker. Native spawn_agent is a declared fallback only when the App Thread tools are unavailable AND the live spawn schema accepts the exact model and reasoning effort of that role; a role whose exact model/effort that schema does not accept MUST NOT fall back to native spawn, because native spawn silently inherits the parent model. Otherwise degrade to codex-exec, then sequential ${fallbackRunner || 'main-thread'}, on the SAME contract via contract-run. Runner-availability degradation MUST be recorded in the contract-run manifest and MUST NOT silently succeed; it is a runner-availability fallback, not a product-semantics change.`,
       '',
       'If this task contains at least two independent, bounded workstreams, dispatch per the contract before doing the corresponding work in the parent; otherwise run it sequentially.',
       '',