agent-bios 0.9.7 → 0.9.9

package/{scripts → learn}/migrate-learnings.py

@@ -3,7 +3,7 @@
 
 After a push lands, a learning that was promoted into the shared corpus is now
 loaded from the corpus — its personal copy (written by `learn!`,
-scripts/collect-learning.py) would double-load. This user-side tool removes the
+learn/collect-learning.py) would double-load. This user-side tool removes the
 absorbed personal copy, and ONLY it (never the user's hand-written entry
 CLAUDE.md `## Personal` section).
 
@@ -21,10 +21,11 @@ irreversible act. Every uncertainty resolves to KEEP: a foreign package we
 cannot confirm, an audience miss, an anchor absent from the corpus, a v1 record
 with no anchor to verify.
 
-Candidate selection (mirrors scripts/assemble.py `kept`): full install (original
-single-zone / no selection) -> everything installed; universal tier (core/infra)
--> always installed; a domain key -> installed iff in the user's selection;
-anything else (env-personal / unclassified / unknown) -> KEEP.
+Candidate selection (mirrors compose/assemble.py `kept`): universal tier
+(core/infra) -> always installed; a domain key -> installed iff in the user's
+selection; anything else (env-personal / unclassified / unknown) -> KEEP. There
+is one install shape — what used to be a "full" install is every domain
+selected — so a selection always answers this.
 
 Run per host (mirrors collect-learning: --host + --config-dir); install.sh calls
 it after the corpus deploy. Manifest absent/empty -> no-op.
@@ -39,11 +40,14 @@ import shutil
 import sys
 import time
 
-sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
-import pkgid  # noqa: E402  (sibling module; scripts/ is a flat toolbox)
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1] / "compose"))
+import pkgid  # noqa: E402  (package-identity primitive owned by compose/)
 
 REPO = pathlib.Path(__file__).resolve().parent.parent
-MANIFEST = REPO / "config" / "promotions.json"
+# Same home compose/corpus-state.py uses; the canary writes its activation proof here.
+STATE_DIR = pathlib.Path(os.environ.get("AGENT_BIOS_STATE_DIR")
+                         or pathlib.Path.home() / ".local/share/agent-bios")
+MANIFEST = REPO / "learn" / "promotions.json"
 UNIVERSAL_TIERS = frozenset({"core", "infra"})  # == assemble.audience UNIVERSAL
 # learning_id inside a personal bullet's TRAILING comment (collect-learning
 # prose_bullet: "... <!-- learning_id: <uuid> created: <ts> -->"). Anchored to
@@ -58,7 +62,7 @@ def die(msg, code=1):
 
 
 def _load(name, filename):
-    path = REPO / "scripts" / filename
+    path = REPO / "learn" / filename
     spec = importlib.util.spec_from_file_location(name, path)
     module = importlib.util.module_from_spec(spec)
     spec.loader.exec_module(module)
@@ -78,16 +82,17 @@ def load_manifest(path=MANIFEST):
             if isinstance(p, dict) and isinstance(p.get("learning_id"), str)]
 
 
-def make_in_bundle(full, selection):
+def make_in_bundle(selection):
     """A promotion's placement AUDIENCE (tier + domains, derived by
     build-promotions from where the bullet actually landed) -> is it in THIS
     user's bundle? Mirrors assemble.py `kept`. Biased to KEEP on anything not
-    provably installed."""
+    provably installed.
+
+    There is one install shape now: what used to be a "full" install is every domain
+    selected, so a selection always answers this and there is no mode to branch on."""
     selection = set(selection or ())
 
     def in_bundle(tier, domains):
-        if full:
-            return True
         if tier in UNIVERSAL_TIERS:
             return True
         if tier == "domain":
@@ -104,8 +109,8 @@ def corpus_surfaces(home):
     learning quotes the same lesson, so searching it would find the very thing
     we are deciding whether to delete and always answer yes.
     """
-    texts = [home / "central" / "bundle.md",   # packaged install
-             home / "CLAUDE.md", home / "AGENTS.md"]  # full install (entry is the corpus)
+    texts = [home / "central" / "bundle.md",          # the assembled corpus
+             home / "CLAUDE.md", home / "AGENTS.md"]  # entry files, for a pre-convergence layout
     dirs = [home / "central" / d for d in ("guides", "hooks", "agents")]
     dirs += [home / d for d in ("guides", "hooks", "agents")]
     return texts, dirs
@@ -227,17 +232,32 @@ def prune_codex_prose(home, remove_ids, collect, dry):
     return removed
 
 
-def claude_corpus_loaded(home, full):
-    """Is the shared corpus actually LOADED for this claude home? Removing a
-    personal copy while the corpus copy is not loaded would make the rule vanish
-    (Review F2). Non-packaged (`full`): the corpus IS the entry monolith the
-    deploy wrote -> loaded. Packaged: loads only via the entry's
-    `@central/bundle.md` import; a user-owned entry that lacks it (assemble exit
-    2) is NOT loading central -> keep the personal copy."""
-    if full:
-        return True
+def claude_corpus_loaded(home, state_dir=None):
+    """Is the shared corpus actually LOADED for this claude home?
+
+    Removing a personal copy while the corpus copy is not loaded makes the rule
+    vanish (Review F2). The entry import line is necessary and NOT sufficient. Testing
+    whether the file contains `@central/bundle.md` also passes on the string in a
+    fenced block or in prose, and no reading of the file can see an import the
+    harness was told not to load — the case PU-13 exists to name. So the
+    authorization is the activation canary's proof, written only after a live
+    session echoed the deployed bundle's rev back, and only for THAT rev: a later
+    reassembly invalidates it rather than inheriting it.
+
+    No proof means KEEP, not prune. A plain `install` runs no canary, so it now
+    prunes nothing and the next run after `onboard` does it — a kept duplicate is
+    redundant, a wrong removal is data loss.
+    """
     entry = home / "CLAUDE.md"
-    return entry.is_file() and collect_central_import() in entry.read_text(encoding="utf-8")
+    if not (entry.is_file() and collect_central_import() in entry.read_text(encoding="utf-8")):
+        return False
+    bundle = home / "central" / "bundle.md"
+    proof = (state_dir or STATE_DIR) / "activation.txt"
+    if not (bundle.is_file() and proof.is_file()):
+        return False
+    rev = next((ln for ln in bundle.read_text(encoding="utf-8").splitlines()
+                if ln.startswith("agent-bios-bundle-rev: ")), None)
+    return bool(rev) and rev.strip() == proof.read_text(encoding="utf-8").strip()
 
 
 def collect_central_import():
@@ -311,13 +331,12 @@ def main():
     ap.add_argument("--host", choices=("claude", "codex"))
     ap.add_argument("--config-dir", default=None,
                     help="config home (default: $CLAUDE_CONFIG_DIR / $CODEX_HOME by host)")
-    ap.add_argument("--full", action="store_true",
-                    help="non-packaged install: the full corpus is installed")
+
     ap.add_argument("--selection-file",
                     help="packaged install: selection.json ({\"domains\":[...]})")
     ap.add_argument("--domains", help="packaged: comma-separated selection (overrides --selection-file)")
     ap.add_argument("--manifest", default=None,
-                    help="promotion manifest (default: config/promotions.json)")
+                    help="promotion manifest (default: learn/promotions.json)")
     ap.add_argument("--dry-run", action="store_true")
     ap.add_argument("--self-test", action="store_true")
     args = ap.parse_args()
@@ -328,10 +347,8 @@ def main():
 
     if not args.host:
         die("--host claude|codex is required")
-    if not args.full and args.selection_file is None and args.domains is None:
-        die("pass --full (non-packaged) or --selection-file/--domains (packaged)")
-    if args.full and (args.selection_file is not None or args.domains is not None):
-        die("--full is mutually exclusive with --selection-file/--domains")
+    if args.selection_file is None and args.domains is None:
+        die("pass --selection-file or --domains")
 
     promotions = load_manifest(pathlib.Path(args.manifest) if args.manifest else MANIFEST)
     if not promotions:
@@ -344,19 +361,16 @@ def main():
     # F2 gate: only prune where the shared corpus is actually loaded. Codex always
     # loads AGENTS.md's central region; claude loads central only via the entry
     # import (or inline in a full install).
-    corpus_loaded = True if args.host == "codex" else claude_corpus_loaded(home, args.full)
+    corpus_loaded = True if args.host == "codex" else claude_corpus_loaded(home)
 
-    if args.full:
-        in_bundle = make_in_bundle(True, ())
+    if args.domains is not None:
+        selection = [d for d in args.domains.split(",") if d]
     else:
-        if args.domains is not None:
-            selection = [d for d in args.domains.split(",") if d]
-        else:
-            sel_path = pathlib.Path(args.selection_file)
-            if not sel_path.is_file():
-                die(f"selection file not found: {sel_path} (pass --full for a non-packaged install)")
-            selection = json.loads(sel_path.read_text(encoding="utf-8")).get("domains", [])
-        in_bundle = make_in_bundle(False, selection)
+        sel_path = pathlib.Path(args.selection_file)
+        if not sel_path.is_file():
+            die(f"selection file not found: {sel_path}")
+        selection = json.loads(sel_path.read_text(encoding="utf-8")).get("domains", [])
+    in_bundle = make_in_bundle(selection)
 
     s = migrate(home, args.host, promotions, in_bundle, collect,
                 dry=args.dry_run, corpus_loaded=corpus_loaded)
@@ -370,6 +384,12 @@ def main():
           f"kept_not_in_bundle={s['kept_not_in_bundle']}")
 
 
+# What a "full" install now means: every domain selected. The fixtures that used to
+# pass `full=True` say it this way, because that is the shape the code has.
+ALL_DOMAINS = ["builder-base", "llm-pipeline-dev", "multi-agent-orchestration",
+               "office-work", "visualization-docs"]
+
+
 def _self_test():
     """Temp-home verification: the safety gate (keep a promotion not in the
     user's bundle), removal of an in-bundle promotion from BOTH prose + jsonl,
@@ -425,7 +445,7 @@ def _self_test():
     # 1) Packaged, selection={builder-base}: core (universal) + builder-base
     #    removed; office-work KEPT (the silent-loss guard).
     home = seed_claude()
-    in_bundle = make_in_bundle(False, ["builder-base"])
+    in_bundle = make_in_bundle(["builder-base"])
     s = migrate(home, "claude", promos, in_bundle, collect)
     ids = local_ids(home)
     checks.append(("packaged: removed core+builder-base", s["removed"] == 2 and s["kept_not_in_bundle"] == 1))
@@ -443,7 +463,7 @@ def _self_test():
     #     metadata-only rule deletes here and loses the learning; presence keeps.
     #     If placed_here() ever returns True unconditionally, this check fails.
     home = seed_claude(placed=("core",))
-    s = migrate(home, "claude", promos, make_in_bundle(False, ["builder-base"]), collect)
+    s = migrate(home, "claude", promos, make_in_bundle(["builder-base"]), collect)
     checks.append(("audience says yes but corpus lacks it -> KEEP",
                    s["removed"] == 1 and s["kept_not_placed"] == 1
                    and L["bb"] in local_ids(home) and md_has(home, L["bb"])))
@@ -452,7 +472,7 @@ def _self_test():
     #     never acted on (stage 3 resolves package selections).
     home = seed_claude()
     foreign = [dict(promos[1], package_id="@acme/security")]
-    s = migrate(home, "claude", foreign, make_in_bundle(True, ()), collect)
+    s = migrate(home, "claude", foreign, make_in_bundle(ALL_DOMAINS), collect)
     checks.append(("foreign package -> KEEP",
                    s["removed"] == 0 and s["kept_foreign_package"] == 1))
 
@@ -468,13 +488,13 @@ def _self_test():
 
     # 2) Full (non-packaged) install: everything in bundle -> all removed.
     home = seed_claude()
-    s = migrate(home, "claude", promos, make_in_bundle(True, ()), collect)
+    s = migrate(home, "claude", promos, make_in_bundle(ALL_DOMAINS), collect)
     checks.append(("full install: all 3 removed", s["removed"] == 3 and not local_ids(home)))
 
     # 3) dry-run changes nothing on disk.
     home = seed_claude()
     before = (home / "personal" / "learnings.jsonl").read_text(encoding="utf-8")
-    migrate(home, "claude", promos, make_in_bundle(True, ()), collect, dry=True)
+    migrate(home, "claude", promos, make_in_bundle(ALL_DOMAINS), collect, dry=True)
     checks.append(("dry-run writes nothing",
                    (home / "personal" / "learnings.jsonl").read_text(encoding="utf-8") == before))
 
@@ -486,7 +506,7 @@ def _self_test():
         r = rec(L["bb"], "builder-base")
         f.write(json.dumps(r, ensure_ascii=False) + "\n")
         collect.apply_codex(chome, collect.prose_bullet(r), dry=False)
-    s = migrate(chome, "codex", promos, make_in_bundle(True, ()), collect)
+    s = migrate(chome, "codex", promos, make_in_bundle(ALL_DOMAINS), collect)
     agents_txt = (chome / "AGENTS.md").read_text(encoding="utf-8")
     checks.append(("codex: bullet removed from AGENTS.md region",
                    s["prose_removed"] == 1 and L["bb"] not in agents_txt))
@@ -495,17 +515,38 @@ def _self_test():
     #    corpus is NOT loaded -> keep everything (never orphan a personal copy).
     home = seed_claude()  # apply_claude writes an entry WITHOUT @central/bundle.md
     checks.append(("F2: unwired packaged entry -> corpus not loaded",
-                   claude_corpus_loaded(home, full=False) is False))
-    s = migrate(home, "claude", promos, make_in_bundle(False, ["builder-base"]),
+                   claude_corpus_loaded(home) is False))
+    s = migrate(home, "claude", promos, make_in_bundle(["builder-base"]),
                 collect, corpus_loaded=False)
     checks.append(("F2: corpus-not-loaded keeps ALL",
                    s.get("skipped") == "corpus-not-loaded"
                    and local_ids(home) == {L["core"], L["bb"], L["off"]}))
     entry = home / "CLAUDE.md"
     entry.write_text(entry.read_text(encoding="utf-8") + "\n@central/bundle.md\n", encoding="utf-8")
-    checks.append(("F2: wired entry -> corpus loaded",
-                   claude_corpus_loaded(home, full=False) is True))
-    checks.append(("F2: full install always loaded", claude_corpus_loaded(home, full=True) is True))
+    # The import line is necessary and NOT sufficient. Reading the file cannot see an import the
+    # harness declined, which is what the canary exists to detect, so the authorization is its
+    # recorded proof — and the proof is bound to a rev, so a reassembly does not inherit it.
+    checks.append(("F2: wired entry, no activation proof -> KEEP",
+                   claude_corpus_loaded(home, state_dir=home / "state") is False))
+    bundle = home / "central" / "bundle.md"
+    bundle.write_text(bundle.read_text(encoding="utf-8") + "\nagent-bios-bundle-rev: deadbeef\n",
+                      encoding="utf-8")
+    state = home / "state"
+    state.mkdir(parents=True, exist_ok=True)
+    (state / "activation.txt").write_text("agent-bios-bundle-rev: deadbeef\n", encoding="utf-8")
+    checks.append(("F2: wired entry + matching proof -> corpus loaded",
+                   claude_corpus_loaded(home, state_dir=state) is True))
+    (state / "activation.txt").write_text("agent-bios-bundle-rev: 00000000\n", encoding="utf-8")
+    checks.append(("F2: proof for a different rev -> KEEP",
+                   claude_corpus_loaded(home, state_dir=state) is False))
+    # CONTRAST CONTROL for the substring hole: the import string inside a fenced block is not an
+    # import, and before the proof requirement this alone authorized the delete.
+    fenced = pathlib.Path(tempfile.mkdtemp(prefix="migrate-fenced-"))
+    (fenced / "CLAUDE.md").write_text("# CLAUDE.md\n```\n@central/bundle.md\n```\n", encoding="utf-8")
+    checks.append(("F2: import string with no activation proof -> KEEP",
+                   claude_corpus_loaded(fenced, state_dir=fenced) is False))
+    # (The old "full install is always loaded" case is gone with full mode: there is no shape
+    # whose corpus loads without the entry import, so nothing is exempt from the proof.)
 
     # 6) F5: the TRAILING comment's id wins; a learning_id quoted in the lesson
     #    body must never shadow it (else a jsonl/prose desync).

package/{scripts → learn}/redact.py

@@ -3,8 +3,8 @@
 
 Both flows that egress session-derived text redact through here, so the floor
 is single-sourced (concept economy) rather than duplicated per call site:
-  * heavy flow  — scripts/session-distill/digest.py (per-session digests);
-  * light flow  — scripts/collect-learning.py (`learn!` prose + upload + the
+  * heavy flow  — session-distill/digest.py (per-session digests);
+  * light flow  — learn/collect-learning.py (`learn!` prose + upload + the
     curator export downstream, since the server stores the payload verbatim).
 
 `design/corpus-domain-packaging.md` declares this floor as an inherited
@@ -15,8 +15,8 @@ the `key: value` / `key=value` form and well-known token shapes, keep prose. A
 touched, so lessons ABOUT tokens (e.g. "trust the X-Hook-Token header") survive.
 
 This module has no side effects on import and is safe to load by path.
-scripts/redact.py is shipped in the npm package (package.json `files`) because
-the shipped scripts/collect-learning.py imports it at runtime.
+learn/redact.py is shipped in the npm package (package.json `files`) because
+the shipped learn/collect-learning.py imports it at runtime.
 """
 import re
 import sys

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "agent-bios",
-  "version": "0.9.7",
+  "version": "0.9.9",
   "releaseDate": "2026-07-26",
   "description": "A thin, low-level instruction layer for LLM CLI agents: one set of principles and behavior whichever model you run. Deploys into $HOME by copy via an explicit `agent-bios install`.",
   "bin": {
-    "agent-bios": "scripts/install.sh"
+    "agent-bios": "install.sh"
   },
   "files": [
     "claude/CLAUDE.md",
@@ -16,27 +16,29 @@
     "codex/guides/",
     "codex/agents/",
     "codex/config-additions.toml",
-    "config/agent-launch.toml",
-    "config/domains.json",
-    "config/learning.schema.json",
-    "config/promotions.json",
-    "shell/agent-launch.zsh",
-    "scripts/agent-launch.py",
-    "scripts/pkgid.py",
-    "scripts/assemble.py",
-    "scripts/check-domains.py",
-    "scripts/canary.sh",
-    "scripts/check-parity.sh",
-    "scripts/check-prompting-targets.sh",
-    "scripts/check-learning.py",
-    "scripts/collect-learning.py",
-    "scripts/migrate-learnings.py",
-    "scripts/redact.py",
-    "scripts/codex-run.sh",
-    "scripts/codex-helm.sh",
-    "scripts/install.sh",
-    "scripts/provision-venv.sh",
-    "scripts/session-cost.py",
+    "launch/agent-launch.toml",
+    "compose/domains.json",
+    "learn/learning.schema.json",
+    "learn/promotions.json",
+    "launch/agent-launch.zsh",
+    "launch/agent-launch.py",
+    "compose/pkgid.py",
+    "compose/register-hooks.py",
+    "compose/assemble.py",
+    "compose/prune-backups.py",
+    "compose/check-domains.py",
+    "compose/canary.sh",
+    "launch/check-prompting-targets.sh",
+    "learn/check-learning.py",
+    "learn/collect-learning.py",
+    "learn/migrate-learnings.py",
+    "learn/redact.py",
+    "wrappers/codex-run.sh",
+    "wrappers/codex-helm.sh",
+    "wrappers/claude-run.sh",
+    "install.sh",
+    "launch/provision-venv.sh",
+    "session-cost.py",
     "README.md",
     "DEPENDENCIES.md"
   ],

package/wrappers/claude-run.sh

@@ -0,0 +1,162 @@
+#!/usr/bin/env bash
+# claude-run.sh — thin, controllable raw adapter around `claude -p`.
+#
+# The claude-side twin of codex-run. Both exist for the same reason: a review
+# dispatch has to name the seat it actually ran on, and a raw CLI call does not.
+# Until this file existed the asymmetry was silent — the codex host dispatched
+# reviews through our adapter while the claude host dispatched the bare binary,
+# so half of every cross-family review had no place to report from.
+#
+# It is an adapter, not a policy boundary. Callers passing expert overrides after
+# `--` are making expert decisions, exactly as with codex-run.
+#
+#   (1) seat            --model + --effort, both REQUIRED (see below)
+#   (2) mutation reach  --permission-mode, defaulting to a no-edit posture
+#   (3) prompt          read from stdin; the final message goes to stdout
+#
+# --model and --effort are required rather than optional, which is the one place
+# this diverges from codex-run. codex-run tolerates an unpinned dispatch and warns,
+# and that warning goes to a channel nobody reads; an unpinned review is the exact
+# failure the receipt contract exists to catch, so here it is refused up front.
+#
+# NOT A SANDBOX. codex-run's `--sandbox read-only` is enforced by the OS; Claude Code
+# has no equivalent, so the default here denies the mutating TOOLS and nothing more.
+# A reviewer reading a self-contained packet on stdin needs no more reach than that,
+# but do not read the two adapters' defaults as equivalent guarantees.
+#
+# Receipts: when REVIEW_RECEIPT_DIR is set, this adapter records what it observed —
+# argv-independent facts only: exit status, a hash of the packet it fed the tool, a
+# hash of the bytes the tool returned, and the seat it actually sent. Unset, it
+# behaves exactly as it would without this block and writes nothing.
+#
+# Verified against claude 2.1.221.
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage: claude-run.sh --model M --effort E [--permission-mode MODE] [--cd DIR]
+                     [-- ARG ...]  < packet
+  --model M    model to pin (required)
+  --effort E   reasoning effort to pin (required)
+  --permission-mode MODE
+               claude permission mode (default: the no-edit posture below)
+  --cd DIR     working root
+  --           everything after is passed to claude verbatim (expert override)
+
+Environment (the adapter calling convention; all optional):
+  REVIEW_RECEIPT_DIR   directory to write one ReviewReceipt/v1 into
+  REVIEW_METHOD_ID     the review method this dispatch serves
+  REVIEW_ORDERING_SEED, REVIEW_SWAP_GROUP
+                       the orchestrator's panel controls, copied into the receipt
+USAGE
+}
+
+model=""
+effort=""
+permission_mode=""
+cd_dir=""
+passthrough=()
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --model)  model="${2:?--model needs a value}"; shift 2 ;;
+    --effort) effort="${2:?--effort needs a value}"; shift 2 ;;
+    --permission-mode) permission_mode="${2:?--permission-mode needs a value}"; shift 2 ;;
+    --cd)     cd_dir="${2:?--cd needs a value}"; shift 2 ;;
+    --)       shift; while [ $# -gt 0 ]; do passthrough+=("$1"); shift; done ;;
+    -p|--print) shift ;;   # already implied; a caller carrying it over is not an error
+    -)        shift ;;
+    -h|--help) usage; exit 0 ;;
+    # Forwarded rather than refused. This adapter is on the dispatch path now, and a
+    # caller that reached for one of claude's own flags should get claude's behaviour
+    # and claude's error message — not exit 2 from the wrapper, which reads as "the
+    # reviewer is broken" and takes the review down with it.
+    *) passthrough+=("$1"); shift ;;
+  esac
+done
+
+if [ -z "$model" ] || [ -z "$effort" ]; then
+  # Warn and dispatch, matching codex-run. Refusing outright was right while nothing
+  # called this file; on the live path it converts "the review ran unpinned" into "the
+  # review did not run", and the honest signal already exists — an unpinned dispatch
+  # can name no seat, so no receipt is emitted and the method adjudicates to UNKNOWN.
+  echo "claude-run: WARNING: no --model/--effort pin; the seat cannot be named and this" >&2
+  echo "            dispatch will produce no receipt." >&2
+fi
+
+# Built conditionally: an empty pin must be ABSENT, not passed as `--model ""`, which
+# claude rejects — that would turn the warning above back into the hard failure it
+# deliberately stopped being.
+args=(-p)
+if [ -n "$model" ];  then args+=(--model "$model"); fi
+if [ -n "$effort" ]; then args+=(--effort "$effort"); fi
+if [ -n "$permission_mode" ]; then
+  args+=(--permission-mode "$permission_mode")
+else
+  # Deny the mutating tools rather than picking a permission mode: `plan` would also
+  # reframe the task as planning, and a reviewer asked for a plan writes one.
+  args+=(--disallowed-tools Edit Write NotebookEdit)
+fi
+if [ -n "$cd_dir" ]; then args+=(--add-dir "$cd_dir"); fi
+if [ "${#passthrough[@]}" -gt 0 ]; then args+=("${passthrough[@]}"); fi
+
+cleanup_paths=()
+cleanup_all() {
+  if [ "${#cleanup_paths[@]}" -gt 0 ]; then
+    for p in "${cleanup_paths[@]}"; do rm -rf "$p"; done
+  fi
+}
+trap cleanup_all EXIT
+
+# Dispatch audit, mirroring codex-run: the line goes to the log file only, because
+# stdout carries the review result and stderr carries claude's own progress.
+log_home="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
+mkdir -p "$log_home/log" 2>/dev/null || true
+printf '%s dispatch model=%s effort=%s permission=%s\n' \
+  "$(date +%Y-%m-%dT%H:%M:%S%z)" "$model" "$effort" \
+  "${permission_mode:-no-edit-tools}" \
+  >> "$log_home/log/claude-run-dispatch.log" 2>/dev/null || true
+
+emit_receipt() {
+  # Recording never breaks dispatch: every failure here is a warning and the tool's
+  # own exit status is what this script returns. A missing receipt adjudicates to
+  # UNKNOWN, which is the honest outcome — silence is not evidence of failure.
+  local status="$1" packet="$2" result="$3" launcher
+  launcher="${AGENT_LAUNCH_BIN:-$HOME/.local/bin/agent-launch}"
+  if [ ! -x "$launcher" ]; then
+    launcher="$(command -v agent-launch 2>/dev/null || true)"
+  fi
+  if [ -z "$launcher" ]; then
+    echo "claude-run: WARNING: agent-launch not found; no receipt emitted" >&2
+    return 0
+  fi
+  if [ -z "${REVIEW_METHOD_ID:-}" ]; then
+    echo "claude-run: WARNING: REVIEW_METHOD_ID unset; the receipt will name no method" >&2
+  fi
+  # The provider is core knowledge and not a flag: this adapter reaches exactly one
+  # family, so letting a caller name a different one would only ever be a false claim.
+  "$launcher" --emit-receipt "${REVIEW_METHOD_ID:-}" "anthropic:$model/$effort" \
+    "$status" "$packet" "$result" >/dev/null \
+    || echo "claude-run: WARNING: receipt not emitted" >&2
+}
+
+if [ -n "${REVIEW_RECEIPT_DIR:-}" ]; then
+  work="$(mktemp -d "${TMPDIR:-/tmp}/claude-run-XXXXXX")"
+  cleanup_paths+=("$work")
+  # stdin is captured rather than inherited ONLY on this branch: hashing the packet
+  # requires holding it, and teeing stdout requires a pipe. Both change the channel
+  # shape, so neither is reached unless a receipt was actually asked for.
+  cat > "$work/packet"
+  set +e
+  claude "${args[@]}" < "$work/packet" | tee "$work/result"
+  status=${PIPESTATUS[0]}
+  set -e
+  emit_receipt "$status" "$work/packet" "$work/result"
+else
+  set +e
+  claude "${args[@]}"
+  status=$?
+  set -e
+fi
+
+exit "$status"

package/{scripts → wrappers}/codex-run.sh

@@ -22,6 +22,12 @@
 # (with --schema, JSON conforming to the schema) and progress to stderr directly.
 # Exit status mirrors `codex exec`.
 #
+# Receipts: when REVIEW_RECEIPT_DIR is set, this adapter records what it observed —
+# exit status, a hash of the packet it fed codex, a hash of the bytes codex returned,
+# and the seat it actually sent. Unset, it behaves exactly as it did before that block
+# existed and writes nothing. The dispatch-audit line below predates receipts and stays:
+# it is a human-readable trail, not an adjudicable record.
+#
 # Verified against codex-cli 0.144.1.
 set -euo pipefail
 
@@ -53,6 +59,12 @@ Usage: codex-run.sh [--profile inherit|hermetic|custom] [--home DIR]
   -c k=v      expert pass-through config override (repeatable); may override
               wrapper defaults, e.g. -c model_verbosity="low"
   -           optional explicit stdin marker
+
+Environment (the adapter calling convention; all optional):
+  REVIEW_RECEIPT_DIR   directory to write one ReviewReceipt/v1 into
+  REVIEW_METHOD_ID     the review method this dispatch serves
+  REVIEW_ORDERING_SEED, REVIEW_SWAP_GROUP
+                       the orchestrator's panel controls, copied into the receipt
 USAGE
 }
 
@@ -174,9 +186,18 @@ fi
 sandbox_label="$sandbox"
 if [ "$bypass_sandbox" -eq 1 ]; then sandbox_label="bypass"; fi
 cmodel=""
+ceffort=""
 if [ "${#extra_c[@]}" -gt 0 ]; then
   for kv in "${extra_c[@]}"; do
-    case "$kv" in model=*) cmodel="${kv#model=}" ;; esac
+    case "$kv" in
+      model=*) cmodel="${kv#model=}" ;;
+      # An expert -c may override the effort too, and the seat a receipt reports has to
+      # be the one actually SENT — reading only --effort would report the requested seat
+      # while the dispatch ran on another, which is the drift the receipt exists to catch.
+      model_reasoning_effort=*)
+        ceffort="${kv#model_reasoning_effort=}"
+        ceffort="${ceffort%\"}"; ceffort="${ceffort#\"}" ;;
+    esac
   done
 fi
 dispatch_note="dispatch profile=$profile model=${model:-INHERITED_DEFAULT}${cmodel:+ c-model-override=$cmodel} effort=${effort:-config-default} sandbox=$sandbox_label"
@@ -186,10 +207,45 @@ fi
 mkdir -p "$real_home/log" 2>/dev/null || true
 printf '%s %s\n' "$(date +%Y-%m-%dT%H:%M:%S%z)" "$dispatch_note" >> "$real_home/log/codex-run-dispatch.log" 2>/dev/null || true
 
-# stdin, stdout, and stderr already match this adapter's channel contract.
-set +e
-CODEX_HOME="$run_home" codex "${args[@]}"
-status=$?
-set -e
+emit_receipt() {
+  # Recording never breaks dispatch: every failure here is a warning and codex's own
+  # exit status is what this script returns. A missing receipt adjudicates to UNKNOWN,
+  # which is the honest outcome — silence is not evidence of failure.
+  status="$1"; packet="$2"; result="$3"
+  launcher="${AGENT_LAUNCH_BIN:-$HOME/.local/bin/agent-launch}"
+  if [ ! -x "$launcher" ]; then
+    launcher="$(command -v agent-launch 2>/dev/null || true)"
+  fi
+  if [ -z "$launcher" ]; then
+    echo "codex-run: WARNING: agent-launch not found; no receipt emitted" >&2
+    return 0
+  fi
+  # The seat as SENT: an expert -c override beats the flag it overrode, and an
+  # unpinned dispatch names no seat at all, so the receipt is refused rather than
+  # invented — which is the same failure the warning above already reports.
+  "$launcher" --emit-receipt "${REVIEW_METHOD_ID:-}" \
+    "openai:${cmodel:-$model}/${ceffort:-$effort}" "$status" "$packet" "$result" >/dev/null \
+    || echo "codex-run: WARNING: receipt not emitted" >&2
+}
+
+if [ -n "${REVIEW_RECEIPT_DIR:-}" ]; then
+  # stdin is captured rather than inherited ONLY on this branch: hashing the packet
+  # requires holding it, and teeing stdout requires a pipe. Both change the channel
+  # shape, so neither is reached unless a receipt was actually asked for.
+  work="$(mktemp -d "${TMPDIR:-/tmp}/codex-run-receipt-XXXXXX")"
+  cleanup_paths+=("$work")
+  cat > "$work/packet"
+  set +e
+  CODEX_HOME="$run_home" codex "${args[@]}" < "$work/packet" | tee "$work/result"
+  status=${PIPESTATUS[0]}
+  set -e
+  emit_receipt "$status" "$work/packet" "$work/result"
+else
+  # stdin, stdout, and stderr already match this adapter's channel contract.
+  set +e
+  CODEX_HOME="$run_home" codex "${args[@]}"
+  status=$?
+  set -e
+fi
 
 exit "$status"