agent-bios 0.11.0 → 0.12.1

package/codex/guides/cli-multi-model-workflow.md

@@ -154,6 +154,50 @@ How much independence a review actually bought, as an ordinal grade per reviewer
 - After resume/clear/relocation, verify pwd, branch, and HEAD against the pinned handoff before acting.
 - Attribute a parallel session's action (commit, branch, resource) by execution evidence in that session's own transcript, never by token mentions — shared handoff/memory files inject the same tokens into every session's context.
 
+## Context Budget And Reset
+
+Context growth is a property of the work, not of the host: over 1,075 sessions of 50+
+requests across both CLIs it runs ~2,400 tokens per request (IQR 1,850-2,950), the two
+hosts within 7% of each other (2,280 Claude, 2,450 Codex); the longest sessions (400+
+requests) run lower, ~1,800. One budget therefore serves both, and what differs per host
+is the price of ignoring it. The figure is a prior; the live session is measured below.
+
+- **Automatic compaction fires only when the window is nearly full** — Claude at 84-87%
+  (windows cluster at 200K and 1M), Codex at ~95% of the window its transcript records as
+  `model_context_window` (258,400 on the sessions measured; a later Codex/model pair
+  records 353,400 — read the value, never assume it). Cache read is charged per
+  request against the whole loaded context, so leaving the reset to the host pays the
+  maximum on every request before it. Measured: input is 92-94% of session cost and
+  output 6-8%, at a 95-97% cache hit rate — the context is the bill, and uncached input
+  is 0.0% of it.
+- Reset deliberately instead. Cost per request falls ~4x from an 867K auto-compact point
+  to 200K. The cost-theoretic optimum is ~65K, but it buys a compaction every ~32
+  requests at 2-3 minutes each, so 150-250K is the working range and the tail below it is
+  not worth chasing.
+- **What bounds the budget is what survives the reset, not the token count.** A compaction
+  keeps a ~14K summary plus 3-4 recent messages and discards the rest — unguided when it
+  fires on its own. Anything already written to a file survives every reset, so the
+  earliest safe threshold is the one where durable state is already on disk. That is what
+  decouples cost from loss: without it, resetting more often loses proportionally more.
+- Choose the mechanism by what is known, not by how large the context grew:
+
+| Situation | Mechanism |
+|---|---|
+| Stage finished, what to keep is known | clear + dated handoff file — cheapest, and the loss is not a loss |
+| Mid-stage, what to keep is known | write the handoff first, then compact with explicit instructions |
+| Mid-stage, the needed detail is not yet identifiable | compact with instructions; a summary spans what a file cannot yet name |
+| Original detail likely wanted later | clear, and record the transcript path in the handoff — transcripts persist on disk |
+| The next question is unknown | new session plus messaging; only this keeps a round trip available |
+| Growth is tool output | offload to subagents instead — measured ~20x cheaper (tier ~5x, context isolation ~4x) |
+| The judgement trail itself is load-bearing | keep the session and pay the 2-5x resume |
+
+- Measure rather than estimate: `agent-bios cost --context <transcript>` (the installed
+  entry to `session-cost.py`) reads either
+  host's transcript and reports current context, growth rate, compactions, and requests
+  remaining against a budget. Codex records `model_context_window` directly; Claude does
+  not, so the tool reports its observed auto-compaction point instead of assuming a
+  window.
+
 ## Handoff Contract
 
 Write for the next agent and re-verification, not narrative. Required content:
@@ -223,3 +267,5 @@ Single owner of numeric defaults; one production environment, 2026-07. Recalibra
 | two live delegation sessions | tiering saved ~3.3×; discarded prefixes made fresh respawn cheaper; unpinned reviewers inherited FRONTIER |
 | Codex reach contrast | inherit ~16.5K vs hermetic ~8.7K tokens; schema and stdout/stderr contract verified |
 | Codex native-spawn probe + HELM E2E | requested max/Ultra native children recorded xhigh/role null; separate read-only roots recorded max and Ultra successfully |
+| 1,075 sessions of 50+ requests, both hosts (2026-08-16; the earlier 62-session top-by-size sample gave ~1,800-2,000) | context grows ~2,400 tok/request (IQR 1,850-2,950), hosts within 7%, ~1,800 in 400+-request sessions; auto-compaction fires at 84-95% of window, never earlier |
+| 2 sessions decomposed by cost component (2026-08) | input 92-94% of cost, output 6-8%, cache hit 95-97%, uncached input 0.0%; an 867K→200K budget cuts cost per request ~4x |

package/codex/guides/coding-staged-workflow.md

@@ -80,6 +80,7 @@ patching them one at a time is a queue that refills.
 
 - At each stage, run review loops as appropriate: self review, subagent review when available, and structured multi-lens review when the repository or domain supports one (concrete tool: Environment Binding below).
 - Iterate until material issues reach zero: review, identify material issues, fix them, and review again.
+- "Material issues reach zero" is counted over the declared defect criterion's stop-relevant class; choosing and declaring that criterion is owned by `${CODEX_HOME:-$HOME/.codex}/guides/review-defect-criteria.md`.
 - Use the severity contract for materiality — the canonical definition is the ladder below; external review tools map their levels onto it: blocker, high, and medium are material; low and info are non-material.
 - Treat blocker as primary happy-path or core-contract failure.
 - Treat high as supported user, environment, data, or execution path failure.

package/codex/guides/review-defect-criteria.md

@@ -0,0 +1,205 @@
+---
+guide_id: review-defect-criteria
+language: en
+status: active
+use_when:
+  - declaring what counts as a defect before dispatching any review
+  - choosing or writing the defect criterion for a system type × work goal
+  - a review loop plateaus, diverges, or its "material 0" stop never arrives
+  - a finding's class is contested at the boundary, or two lenses class it differently
+core_rules:
+  - choose and declare the criterion before the review starts — undeclared, every reviewer substitutes its own
+  - the severity ladder answers how bad; the criterion answers whether it is a defect, of which class, and what "zero" is counted over
+  - a criterion with an empty cell is a hunch, not a criterion — do not start the review
+  - paste the goldens into the packet verbatim; a definition alone does not classify consistently at the boundary
+  - put the class enum on the accepting channel where one exists; on prose routes, run the fold procedure
+  - a mixed packet is split — never run two observers in one trajectory
+verification_focus:
+  - every dispatched packet names its criterion and carries its goldens
+  - each round audits reported class against post-measurement class; repeated disagreement mints the next golden
+  - the stop condition is evaluated over the stop-relevant class only, never the whole finding count
+---
+
+# Review Defect Criteria
+
+A defect criterion is chosen, not assumed. This guide is a scoped extension of
+`${CODEX_HOME:-$HOME/.codex}/guides/review-request.md`: before that guide's
+request composition starts, this one decides what the review is hunting. The
+evidence: one codebase, two stop criteria, opposite trajectories.
+
+| Rounds | Criterion | Trajectory |
+|---|---|---|
+| early | material = contract violation **or** unprotected contract sentence, small frozen surface | 10 → 4 → 1 → 0 |
+| late | same, scoped to client-observable behavior | 17 → 19 → 21 → 23 → 19 — **plateau** |
+| final | split classes: behavioral_defect / coverage_gap / doc_gap; stop = behavioral 0 | behavioral 10 → 5 — falling again |
+
+The plateau was the criterion, not the code: counting "a contract sentence no test
+protects" as a defect means every fix adds contract rows, each a potential defect
+next round — a self-refilling criterion cannot reach zero while its surface grows.
+Yet that same criterion is exactly right for a library, where an unprotected promise
+is a first-class defect. Neither is wrong; starting without choosing is.
+
+The **severity ladder** (in `${CODEX_HOME:-$HOME/.codex}/guides/coding-staged-workflow.md`)
+answers *how bad* a finding is. The **criterion** answers *whether* it is a defect at
+all, of which class, and what "zero" is counted over. The plateau happened entirely
+inside "material" — no severity adjustment could have ended it. Ordering: system type
++ goal → defect criterion → classification → defect? → severity → materiality → stop.
+
+## The criterion schema
+
+One entry carries all of these. An empty cell makes it a hunch, not a criterion — do
+not start the review on it.
+
+| Field | Meaning |
+|---|---|
+| observer | whose eyes judge — client, caller, operator, a model reading the output |
+| defect | what the observer must experience |
+| classes | the enum, exactly ONE class stop-relevant; the others are relief valves that keep the stop class honest |
+| evidence | what one finding must present |
+| non-defects | defect-lookalikes excluded by this criterion — named explicitly |
+| stop condition | what "0" means, counted over the stop class, and WHY it is reachable — how a growing surface is pinned |
+| misclassification cost | which error is expensive — the direction to tell the reviewer to lean |
+| goldens | ≥2 positive, ≥2 negative, ≥1 boundary; each with why, date, and provenance: `measured` (dated incident) or `constructed` (authored to pin a boundary) |
+
+## The catalog
+
+Four system types. A starting set, not a census.
+
+### Web service / API surface (contract compliance)
+
+- **Observer**: the HTTP client.
+- **Defect**: a client today receives a response that differs from the contract — status code, envelope, stream terminal frames, the model actually run, isolation, resource caps.
+- **Classes**: `behavioral_defect` (stop-relevant) · `coverage_gap` · `doc_gap`.
+- **Evidence**: the concrete request and observed vs promised response.
+- **Non-defects**: internal lifecycle (unless a request sequence shows two different responses), absence of a test, documentation wording.
+- **Stop**: behavioral 0 — reachable: the code surface is finite and shrinks monotonically unless a fix creates a new behavioral defect.
+- **Misclassification cost**: false negatives (a client actually breaks); but inflating coverage gaps into defects destroys the stop condition — audit category creep separately.
+- **Goldens** (all `measured`, 2026-08-13–15):
+  - **+** `GET` on a nonexistent path returned 405, not 404 — an existing-method complaint attached to a path that does not exist.
+  - **+** a streaming endpoint's terminal delta carried only `output_tokens`, so cache/input token counts never reach a streaming client — non-streaming was correct, which is why nobody saw it.
+  - **−** "no test catches a one-line flip of this default": today's behavior is correct — `coverage_gap` here, a defect only under the library criterion.
+  - **−** child-process kill grace period — out of scope until a request sequence shows a client-visible difference; pins the observer to the client.
+  - **±** rejecting a documented-as-valid boundary value (compression 100, docs say "below 100 requires jpeg/webp") — the documentation is what makes it a defect; without that sentence it is taste.
+
+### Library / SDK / contract-first system
+
+- **Observer**: the caller **and** the future maintainer.
+- **Defect**: a promise violated today, or a promise unprotected — a one-line change breaks it and nothing catches it. The API criterion's `coverage_gap` is first-class here.
+- **Classes**: `contract_defect` (stop-relevant) · `style_note` · `internal_change`.
+- **Evidence**: for a violation, as above; for an unprotected promise, the promise sentence + the one-line change that breaks it + the absence of any catching test.
+- **Non-defects**: style, internal structure.
+- **Stop**: caution — this criterion self-refills while the contract grows. Declare "0" only over a surface whose growth has stopped; on a growing surface, narrow the stop to "every promise this change added is protected."
+- **Misclassification cost**: balanced — miss an unprotected promise and the next refactor breaks it silently; over-report and the loop never ends.
+- **Goldens**:
+  - **+** a streaming-image event test matched only `.completed`, so an edit stream misnamed `image_generation.completed` still passed — mutation survival showed the promise unprotected. (`measured`, 2026-08-13–15)
+  - **+** the contract promised "storage serves a large image at least once"; the code evicted it on the next request — resolved by fixing the **contract**: the disagreement is the defect, whichever side moves. (`measured`, 2026-08-13–15)
+  - **−** renaming an internal helper no document promises — the observer holds the contract; undocumented internals carry no promise. (`measured`, 2026-08-13–15)
+  - **−** a caller breaking on undocumented iteration order — no promise existed; the rename boundary pinned from the caller's side. (`constructed`, 2026-08-19)
+  - **±** an inventory-listed test turns out vacuous — asserts nothing about its promise. "A test exists" is a claim about names until the assertion is read; hand the reviewer "check the assertion, not the name." (`measured`, 2026-08-13–15)
+
+### AI workbench / harness (agent orchestration, review loops, verification pipelines)
+
+- **Observer**: the operator, and any model consuming the harness's output.
+- **Defect**: **a false signal that looks true** — a wrong PASS, a vacuous test, a silent fallback, a packet missing the call site, a wrong denominator. Being wrong is not the defect; being wrong while *looking right* is. Second form: a run claimed without provable dispatch — no receipt.
+- **Classes**: `false_signal` (stop-relevant) · `detected_miss`. An unproven dispatch — a run or PASS claimed with no receipt — is classed `false_signal`, not given its own relief valve: a signal that cannot be shown true is counted false, or a round could declare completion while every dispatch stayed unproven.
+- **Evidence**: the input on which the instrument gave a false verdict, plus the known correct answer. The standard probe: run the instrument against an input whose answer is known to be the opposite.
+- **Non-defects**: one output's style; a false positive the harness itself **detected** — a caught error is the harness working.
+- **Stop**: every PASS emitted this run survives a known-opposite check and evidences its own dispatch. The unit is "this run's signals are trustworthy," not a standing zero.
+- **Misclassification cost**: false passes dominate. An instrument bug reporting failure dies in minutes because someone looks; one reporting success survives — a selection effect.
+- **Goldens**:
+  - **+** a shell test runner received one nonexistent path (zsh does not word-split an unquoted variable), so every run exited 1 and every mutation reported KILLED — a green instrument that never ran its subject. (`measured`, 2026-08-13–15)
+  - **+** a test-inventory grep matched only `^test('...'` and missed every parameterized name; three reviewers judged a populated file empty — nothing tied the inventory's denominator to the source's own count. (`measured`, 2026-08-13–15)
+  - **+** a negative control kept passing after a faithful revert of the fix it was written against — a guard satisfied by an absence, a false PASS about the gate itself; found only by re-running reverts. (`measured`, 2026-08)
+  - **+** a review round returned "clean" with no receipt evidencing that the declared packet was dispatched on the exact seat — `false_signal` although nothing observed was wrong: what the stop refuses is absence of proof of dispatch, not proof of falsity. (`constructed`, 2026-08-19, pinned after a classification dispute at exactly this boundary)
+  - **−** one reviewer over-classed an item as material; another lens plus measurement filtered it — the harness caught it, so it worked: `detected_miss`, not a defect. (`measured`, 2026-08-13–15)
+  - **−** five review rounds returned 8 → 9 → 10 → 5 → 12 findings, refusing to converge — and every count was true. A truthful unpleasant signal is not a false signal; the defect lived in the undeclared criterion. (`measured`, 2026-08-16–17)
+  - **±** a surviving mutation proved equivalent — the platform already normalized what the mutated guard checked. Neither a harness defect nor a test gap; but a harness that auto-reads "survived = gap" has a defect in that rule. (`measured`, 2026-08-13–15)
+
+### Decision ontology (an ontology a model decides from)
+
+- **Observer**: a model or agent deciding from the ontology alone.
+- **Defect**: a representation that produces a wrong decision or blocks a right one: overlapping concept boundaries, a missing distinction the decision needs, an instance contradicting reality, a wrong relation direction or cardinality, a name implying what the definition does not say.
+- **Classes**: `decision_defect` (stop-relevant) · `representation_note` · `out_of_scope_gap`.
+- **Evidence**: a **decision scenario** — "answered from the ontology alone, this question yields X; reality is Y" — with the question, the path taken, and the ground truth.
+- **Non-defects**: representation format, completeness as such, a question the model would get wrong without the ontology too.
+- **Stop**: zero wrong decisions over the agreed scenario set. The set is the scope — fix it first, or this criterion self-refills like the library one.
+- **Misclassification cost**: situational — feeding a hard gate makes false negatives expensive; exploratory aid makes false positives expensive. Filling this cell is mandatory at declaration.
+- **Goldens** (all `constructed`, 2026-08-19, authored to pin boundaries the source loop's decision-scenario framing left open):
+  - **+** `Customer` and `Account` both define "the paying party"; a refund-routing question resolves through both paths — overlap is a decision defect even when each definition is individually correct.
+  - **+** `Order —hasOne→ Payment` while split payments exist — cardinality is a claim, and a false claim misleads the deciding model.
+  - **−** a verbose concept description — no decision changes; form is outside this observer's sight.
+  - **−** a domain absent that no scenario in the agreed set needs — completeness is scoped by the set, not the world.
+  - **±** the distinction exists but the model cannot find it (name or link missing) — with the observer fixed as "a model seeing only the ontology," unreachable is a representation defect, not a search defect. The observer clause decides the class.
+
+## Before any review
+
+1. Write one sentence: the system type and this work's goal. ("API surface — make the responses clients receive today match the contract." / "Harness — make this run's PASS signals trustworthy.")
+2. Pick a criterion from the catalog, or fill the schema fresh. A cell you cannot fill means the review does not start.
+3. Paste the goldens into the packet verbatim. Never the definition alone.
+4. Declare the stop condition and why it is reachable — or how the scope was pinned to make it so.
+5. Put the classification on the accepting channel (next section).
+6. Audit every round: reported class vs the class confirmed after measurement. A repeated disagreement is the next golden.
+
+## Enforcing the enum, by channel
+
+Ranked by how much the channel refuses for you:
+
+1. **A route with a submit schema**: classification is a required enum field. The
+   measured precedent is anchors — 2,466 of 2,466 findings carried one, because the
+   schema refuses output without it. Where this channel exists, use it.
+2. **Prose-packet routes** (the shipped deep-review methods): the packet header
+   declares `Criterion: <name>` with the goldens pasted verbatim, and the dispatching
+   agent runs this fold procedure on what comes back:
+   1. For each returned finding row, look up its class against the declared enum.
+   2. A row carrying a class from the enum enters the findings ledger under that class.
+   3. A row with no class, or a class outside the enum, is **not admitted**: send it
+      back once for classification, or record it as refused with the reason. Never
+      admit it unclassified, and never guess its class for it.
+   4. Count the stop condition over the stop-relevant class only.
+   5. Record the audit pair (reported class, confirmed class) for procedure step 6.
+
+   Stated honestly: on a prose route this is steering, not control — the fold is
+   performed by an agent following this guide, and nothing structural refuses a
+   class-less row for it. That is the known weaker result of a request-only rule.
+3. A structural criterion slot in the review dispatch machinery is deliberately not
+   part of this guide: a criterion is per-review while dispatch config is per-launch,
+   and a slot with no schema-backed consumer would be an inert value. Until such a
+   channel exists, ranks 1–2 are the real ones.
+
+## Golden lifecycle
+
+- **Admission**: only a golden that decides a boundary the definition leaves open,
+  evidenced by a recorded classification disagreement or an audited misclassification;
+  provenance labeled `measured` or `constructed`, each with its why and date.
+- **Overturn**: only by a measured counterexample. Correct the golden in place — this
+  guide describes the present — plus a dated decision record, in whatever channel the
+  repo keeps decisions, naming the closed golden and the counterexample. Silent
+  deletion is forbidden: a wrong golden makes reviewers systematically wrong, and an
+  untracked fix hides that it ever did.
+
+## Declaring, switching, and mixed packets
+
+- Every dispatched packet names its criterion. A harness round declares `AI harness`;
+  a round whose system type has no catalog entry declares a **task-local criterion**,
+  written in the packet itself, conforming to the schema above and labeled task-local
+  — repeated use is what earns a catalog entry.
+- A mixed packet is split into one packet per criterion. Two observers in one
+  trajectory produce findings no single stop condition can count.
+- When a criterion changes mid-loop: re-classify only the findings still open; rounds
+  already recorded are dated history. Never splice pre- and post-switch counts into
+  one series — they count different things.
+
+## Evidence base
+
+Derived from a 39-round adversarial review loop (3 lenses × a frontier reviewer) on a
+peer OAuth CLI-API adapter, 2026-08-13–15: the same codebase plateaued at
+17→19→21→23→19 findings under a self-refilling criterion and resumed falling
+(behavioral 10→5) the round the classes were split and the stop counted over
+`behavioral_defect` alone. The boundary evidence is from the same loop: a packet
+instruction saying "do not inflate coverage gaps" still left two lenses classing one
+finding `doc_gap` and `behavioral_defect`, both defensibly — one golden would have
+decided it. The non-convergence golden (8→9→10→5→12, every count true) is this
+environment's own launcher-review loop, 2026-08-16–17, run under an undeclared
+"material" criterion; the two series are two populations under two criteria and are
+cited separately for exactly the reason the migration section gives. Re-derive when
+the review routes or the bound models change.

package/codex/guides/review-request.md

@@ -26,7 +26,11 @@ verification_focus:
 This guide is a scoped extension of the global Coding Guidelines. Use it when
 composing what you ask a reviewer for — the request, the evidence bar, the
 verdict shape. It does not cover when to review, how deep, or what counts as
-material (the severity ladder and review loop in `${CODEX_HOME:-$HOME/.codex}/guides/coding-staged-workflow.md` own that),
+material — that last question splits in two: the severity ladder and review loop in
+`${CODEX_HOME:-$HOME/.codex}/guides/coding-staged-workflow.md` own *how bad*,
+while whether something is a defect at all, of which class, and what "zero" is
+counted over is the defect criterion, owned by
+`${CODEX_HOME:-$HOME/.codex}/guides/review-defect-criteria.md`. Nor
 which reviewer kind to route to — the convergence heuristic in
 `${CODEX_HOME:-$HOME/.codex}/guides/verification-discipline.md` owns that. Phrasing a prompt for a specific model
 family is out of scope here; where that guidance ships, the rule that needs it
@@ -38,6 +42,16 @@ is a per-model claim; these are the failures that persist regardless of who
 reviews. Every rule names the evidence behind it, because a review guide that
 asserts without evidence would fail its own bar.
 
+## Declare the criterion
+
+Before composing anything else, name the defect criterion the review runs under —
+the per-system-type definition of what a defect is, its class enum, and what "zero"
+is counted over. `${CODEX_HOME:-$HOME/.codex}/guides/review-defect-criteria.md`
+owns choosing it; this guide assumes one is declared. Put `Criterion: <name>` at the
+top of the packet with that criterion's goldens pasted verbatim — a definition
+without goldens does not classify consistently at the boundary, and an undeclared
+criterion means every reviewer substitutes its own.
+
 ## Demand a failure path, not a gap
 
 The dominant reviewer failure is not hallucination. Across 372 rejected

package/compose/assemble.py

@@ -22,8 +22,10 @@ env-personal is never assembled. The domains gate must be green first.
 """
 import argparse
 import json
+import os
 import pathlib
 import re
+import shlex
 import shutil
 import subprocess
 import sys
@@ -37,6 +39,14 @@ PERSONAL_IMPORT_LINE = "@personal/learnings.md"
 CLAUDE_VAR = "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
 CODEX_VAR = "${CODEX_HOME:-$HOME/.codex}"
 CODEX_ONLY_PREFIX = "- Codex-only standing authorization:"
+# Where that bullet belongs. Owned here because the payload cannot import from gates/,
+# and `gates/emit-mirrors.py` — which pins the same position in the STATIC projection —
+# imports it from this module instead, the same direction check-package.sh already takes
+# for `author_only`. The two were independent before, and they disagreed: the projection
+# put the bullet under this heading while the assembler appended it to the end of the
+# bundle, so the deployed AGENTS.md filed a multi-model rule under whatever section
+# happened to come last.
+CODEX_ONLY_ANCHOR = "## Multi-Model Workflow"
 
 ENTRY_SEED = f"""# CLAUDE.md
 
@@ -99,6 +109,30 @@ def parse_monolith(text):
     return title, sections
 
 
+def place_codex_only(bundle, bullet):
+    """Put the Codex-only bullet first under CODEX_ONLY_ANCHOR, or refuse.
+
+    Appending was the old behaviour and it is what put a multi-model rule under Session
+    Learning in every deployed AGENTS.md: the bundle's sections are whatever the selection
+    kept, so "the end" is a different heading depending on what the user installed.
+
+    Refuses rather than falling back to appending. The bullet is only added when
+    `multi-agent-orchestration` is selected, and that domain is what carries the anchor
+    heading, so a missing anchor means the bundle is not the shape this rule assumes —
+    quietly filing the rule somewhere else is how the defect looked in the first place.
+    """
+    lines = bundle.split("\n")
+    hits = [i for i, line in enumerate(lines) if line == CODEX_ONLY_ANCHOR]
+    if len(hits) != 1:
+        die(f"codex bundle must hold exactly one {CODEX_ONLY_ANCHOR!r} to place "
+            f"{CODEX_ONLY_PREFIX!r} under; found {len(hits)}")
+    index = hits[0] + 1
+    while index < len(lines) and not lines[index].strip():
+        index += 1
+    lines.insert(index, bullet)
+    return "\n".join(lines)
+
+
 def build_bundle(monolith_text, manifest, selection, tool):
     entry_of = {}
     for e in manifest["bullets"]:
@@ -226,12 +260,58 @@ def copy_filtered(src_dir, names, dest, rewrite=None, dry=False, backup=None):
         target.write_text(body, encoding="utf-8")
 
 
+def replace_atomically(path, text):
+    """Write via a temp file + os.replace, so a write that fails partway cannot truncate.
+
+    Every file this is used on is one the USER owns and edits — their settings.json, their
+    AGENTS.md — and a plain write_text truncates first and fills after. A short write (a full
+    disk, a crash) left AGENTS.md holding a fragment of our marker and none of their text,
+    with no copy in reach: the backup taken beside these calls is of the PREVIOUS content,
+    which is exactly what a half-written file destroys the value of.
+
+    learn/migrate-learnings.py has had this discipline and states the reason; it now shares
+    this one implementation rather than keeping a second. The temp file is a sibling so the
+    replace stays on one filesystem, where os.replace is atomic.
+
+    An existing target's permission bits ride through the swap: the temp is born with
+    umask mode, so replacing a user-restricted file — a 0600 AGENTS.md — silently widened
+    it to world-readable. Ownership is not copied; this never runs with the privilege to
+    change it, and a same-owner rename keeps it anyway.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(path.name + ".tmp-agent-bios")
+    try:
+        tmp.write_text(text, encoding="utf-8")
+        if path.exists():
+            tmp.chmod(path.stat().st_mode & 0o777)
+        os.replace(tmp, path)
+    finally:
+        if tmp.exists():
+            tmp.unlink()
+
+
 def hook_command_matches(command, name):
-    """A complete `/hooks/<name>` token: the command ends with it, or it is followed by an
-    argument. One matcher for the merge below AND the domain gate's settings leg — the gate
-    used a substring test, so `central/hooks/<name>.disabled` passed the gate while this
-    merge skipped it, and the install carried no hook under a green gate."""
-    return command.endswith("/hooks/" + name) or f"/hooks/{name} " in command + " "
+    """Does an argv TOKEN of this command end in `/hooks/<name>`?
+
+    One matcher for the merge below AND the domain gate's settings leg — the gate used a
+    substring test, so `central/hooks/<name>.disabled` passed the gate while this merge
+    skipped it, and the install carried no hook under a green gate.
+
+    Split as a shell would, not delimited by spaces. The registration this file writes is
+    `shlex.quote`d so a config home containing a space works, and the quoting puts a `'`
+    right after the filename — so a matcher wanting end-of-string or a following space
+    could not recognize the line it had just written, and every reinstall on a
+    `/Users/First Last` home appended another copy of the same hook. Splitting the way the
+    shell will is the only reading that survives its own quoting.
+
+    Still a PATH match and never a bare name: `wrap.py --inner <name>` passes the name as
+    an argument to somebody else's wrapper, and deleting a stranger's hook is not a right
+    this ownership rule ever claimed."""
+    try:
+        tokens = shlex.split(command)
+    except ValueError:            # unbalanced quotes: not a command we wrote
+        tokens = command.split()
+    return any(token.endswith("/hooks/" + name) for token in tokens)
 
 
 def merge_settings(claude_dir, hook_names, template_path, dry=False, owned_names=None):
@@ -250,15 +330,41 @@ def merge_settings(claude_dir, hook_names, template_path, dry=False, owned_names
     """
     owned = set(owned_names if owned_names is not None else hook_names)
     spath = claude_dir / "settings.json"
-    settings = json.loads(spath.read_text(encoding="utf-8")) if spath.exists() else {}
+    existed = spath.exists()
+    settings = json.loads(spath.read_text(encoding="utf-8")) if existed else {}
     template = json.loads(template_path.read_text(encoding="utf-8")) if template_path.exists() else {}
     hooks = settings.setdefault("hooks", {})
 
-    def ours(en):
-        return any(n in h.get("command", "") for h in en.get("hooks", []) for n in owned)
-
-    for event, entries in list(hooks.items()):  # drop every entry we own
-        hooks[event] = [en for en in entries if not ours(en)]
+    def ours(hook):
+        # The same matcher the re-add below uses, which `hook_command_matches` already
+        # describes itself as being ("one matcher for the merge below AND the domain
+        # gate"). Only the ADD half honoured that; removal asked whether the name appeared
+        # anywhere in the command, so a user's own entry was deleted for mentioning ours —
+        # `wrap.py --inner tooling-gotchas-hook.py`, a `.bak` copy, a directory named after
+        # it. Deleting a stranger's hook out of their settings is not something the
+        # ownership rule above ever claimed the right to do.
+        return any(hook_command_matches(hook.get("command", ""), n) for n in owned)
+
+    # Pruned per HOOK, not per entry. Ownership is a name on one command, and the entry is
+    # a matcher that can hold several — so `{"matcher": "Bash", "hooks": [ours, theirs]}`
+    # answered "ours" and took the stranger's hook with it. That is the same overreach the
+    # matcher above was narrowed to stop, one level up: the granularity of the removal has
+    # to match the granularity of the claim. An entry left with no hooks was only ever ours,
+    # so it still goes whole.
+    for event, entries in list(hooks.items()):
+        pruned = []
+        for en in entries:
+            children = en.get("hooks") if isinstance(en, dict) else None
+            if not isinstance(children, list):
+                pruned.append(en)          # not a shape we wrote; not ours to judge
+                continue
+            keep = [h for h in children if not (isinstance(h, dict) and ours(h))]
+            if len(keep) == len(children):
+                pruned.append(en)          # nothing of ours in it — untouched
+            elif keep:
+                en["hooks"] = keep         # ours dropped, their siblings stay where they are
+                pruned.append(en)
+        hooks[event] = pruned
     for event, entries in template.get("hooks", {}).items():  # re-add per selection
         for en in entries:
             cmds = [h.get("command", "") for h in en.get("hooks", [])]
@@ -268,16 +374,32 @@ def merge_settings(claude_dir, hook_names, template_path, dry=False, owned_names
                 continue
             clone = json.loads(json.dumps(en))
             for h in clone.get("hooks", []):
+                # Quoted, because this lands in a shell command line. A config home with a
+                # space in it — `/Users/First Last/.claude` — split into separate argv
+                # words, so the shell tried to run `/Users/First` and the deployed hook
+                # simply never fired. Nothing reported it: a hook that does not run looks
+                # exactly like a hook with nothing to say.
+                #
+                # A function replacement rather than a string one: shlex.quote emits
+                # backslashes for some paths and re.sub reads those as group references in
+                # a replacement string.
+                target = shlex.quote(str(claude_dir / "central" / "hooks" / owner))
                 h["command"] = re.sub(r"\S*/hooks/" + re.escape(owner),
-                                      str(claude_dir / "central" / "hooks" / owner),
+                                      lambda _match, value=target: value,
                                       h["command"])
             hooks.setdefault(event, []).append(clone)
     if dry:
         print(f"  [dry] merge settings.json ({len(hook_names)} central hooks)")
         return
-    if spath.exists():
+    if not existed and not any(hooks.values()):
+        # Nothing of ours to register and no file to preserve. Writing one would create a
+        # settings.json the user did not have — and this branch is reached by uninstall on a
+        # machine where the claude dir is gone, where creating the directory to hold it
+        # crashed on a missing parent instead.
+        return
+    if existed:
         shutil.copy2(spath, spath.with_suffix(f".json.bak-{time.strftime('%Y%m%d-%H%M%S')}"))
-    spath.write_text(json.dumps(settings, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    replace_atomically(spath, json.dumps(settings, indent=2, ensure_ascii=False) + "\n")
 
 
 def seed_personal_learnings(claude_dir, dry=False):
@@ -335,7 +457,21 @@ def seed_entry(claude_dir, legacy_monolith, prior_deployed=(), dry=False):
     return "needs-action"  # user content without the import line: report, never rewrite
 
 
-def merge_codex(codex_dir, central_text, dry=False):
+def merge_codex(codex_dir, central_text, prior_deployed=(), dry=False):
+    """Write the central region into AGENTS.md, and never silence a file the user wrote.
+
+    A missing marker pair used to mean "legacy whole-file deploy", so any AGENTS.md without
+    them had its active body replaced by the region plus an empty `## Personal`. Every Codex
+    user who wrote an AGENTS.md before installing has exactly that file, and their
+    instructions stopped loading on the first install — the backup made it recoverable, not
+    noticed. Absence of a marker is absence of evidence, in both directions.
+
+    So the same evidence seed_entry uses on the Claude side decides it here: `prior_deployed`
+    is the previous install's manifest, and a path in it is ours by record. Anything else is
+    theirs, and the markers are adopted ABOVE their text rather than over it — which is what
+    the marker pair is for, and it leaves nothing of theirs unloaded. Nothing is lost that
+    way, so that branch needs no backup; the by-record branch keeps the one it always had.
+    """
     agents = codex_dir / "AGENTS.md"
     region = f"{MARK_START}\n{central_text}{MARK_END}\n"
     if agents.exists():
@@ -344,17 +480,21 @@ def merge_codex(codex_dir, central_text, dry=False):
             pre, rest = body.split(MARK_START, 1)
             _, post = rest.split(MARK_END, 1)
             new = pre + region + post
-        else:  # legacy whole-file deploy: back up, adopt markers, keep nothing implicit
+        elif str(pathlib.Path(agents)) in prior_deployed:
+            # Ours by record: an earlier release deployed this file whole, so replacing it
+            # with the marked shape is the upgrade, not a loss.
             if not dry:
                 shutil.copy2(agents, agents.with_suffix(f".md.bak-legacy-{time.strftime('%Y%m%d-%H%M%S')}"))
             new = region + "\n## Personal\n"
+        else:
+            new = region + "\n" + body.lstrip("\n")
     else:
         new = region + "\n## Personal\n"
     if dry:
         print(f"  [dry] write AGENTS.md central region ({len(central_text)} bytes)")
         return
     codex_dir.mkdir(parents=True, exist_ok=True)
-    agents.write_text(new, encoding="utf-8")
+    replace_atomically(agents, new)
 
 
 def remove_owned(claude_dir, codex_dir, manifest, dry=False):
@@ -385,7 +525,7 @@ def remove_owned(claude_dir, codex_dir, manifest, dry=False):
     if dry:
         print("  [dry] strip AGENTS.md central region, keep everything outside the markers")
         return
-    agents.write_text((pre + post).lstrip("\n"), encoding="utf-8")
+    replace_atomically(agents, (pre + post).lstrip("\n"))
 
 
 def main():
@@ -402,6 +542,11 @@ def main():
                          "from it, so an earlier release's deployed CLAUDE.md is recognized as "
                          "ours instead of being reported as the user's.")
     ap.add_argument("--dry-run", action="store_true")
+    ap.add_argument("--selected-skills", action="store_true",
+                    help="print the names of the shipped skills the selection delivers, one "
+                         "per line, and write nothing. install.sh deploys skills itself (a "
+                         "skill is a tree the HOST scans, not a file under central/) and asks "
+                         "here which ones, so the selection rule keeps one owner")
     args = ap.parse_args()
 
     import os
@@ -409,13 +554,28 @@ def main():
     codex_dir = pathlib.Path(args.codex_dir or os.environ.get("CODEX_HOME") or pathlib.Path.home() / ".codex")
     state_dir = pathlib.Path(args.state_dir or pathlib.Path.home() / ".local/share/agent-bios")
 
-    manifest = json.loads((REPO / "compose" / "domains.json").read_text(encoding="utf-8"))
     if args.remove_owned:
         # No domains gate: removal does not depend on the manifest being well-formed, and an
         # uninstall that refuses to run because the corpus is mid-edit would strand the user.
+        # That was the claim; the parse sat ABOVE this branch and ran first, so a malformed
+        # domains.json raised out of uninstall before the branch that does not need it. The
+        # two halves of the removal need it differently: the Codex region is bounded by our
+        # markers and needs nothing, while the settings registrations are owned BY NAME and
+        # cannot be found without it. So the region goes either way, and a manifest we cannot
+        # read makes the registration half impossible rather than skippable — the caller has
+        # to hear that, not read a clean summary over it.
+        try:
+            manifest = json.loads((REPO / "compose" / "domains.json").read_text(encoding="utf-8"))
+        except (OSError, ValueError) as exc:
+            remove_owned(claude_dir, codex_dir, {"hooks": {}}, dry=args.dry_run)
+            die(f"the AGENTS.md central region was removed, but {REPO / 'compose' / 'domains.json'} "
+                f"could not be read ({exc}) — the hook registrations it names are STILL in "
+                f"settings.json. Restore that file and re-run uninstall.")
         remove_owned(claude_dir, codex_dir, manifest, dry=args.dry_run)
         return
 
+    manifest = json.loads((REPO / "compose" / "domains.json").read_text(encoding="utf-8"))
+
     gate = subprocess.run([sys.executable, str(REPO / "compose" / "check-domains.py")],
                           capture_output=True, text=True)
     if gate.returncode != 0:
@@ -431,6 +591,16 @@ def main():
     if unknown:
         die(f"unknown domains: {sorted(unknown)} (known: {sorted(manifest['domains'])})")
 
+    if args.selected_skills:
+        # The same two rules the guides get: the manifest's audience, then the file's own
+        # `audience: author` declaration — the gate that tolerates author-side paths in a
+        # declared file assumes the assembler withholds it, and a skill deployed by
+        # install.sh from this list must keep that assumption true.
+        for name in filtered_files(manifest, "skills", selection):
+            if not author_only(REPO / "claude" / "skills" / name / "SKILL.md"):
+                print(name)
+        return
+
     monolith = (REPO / "claude" / "CLAUDE.md").read_text(encoding="utf-8")
     bundle, n_bullets = build_bundle(monolith, manifest, selection, "claude")
     codex_src = (REPO / "codex" / "AGENTS.md").read_text(encoding="utf-8")
@@ -438,7 +608,7 @@ def main():
     if "multi-agent-orchestration" in selection:
         codex_only = next((ln for ln in codex_src.splitlines() if ln.startswith(CODEX_ONLY_PREFIX)), None)
         if codex_only:
-            codex_bundle += codex_only + "\n"
+            codex_bundle = place_codex_only(codex_bundle, codex_only)
 
     guides = filtered_files(manifest, "guides", selection)
     withheld = [n for n in guides if author_only(REPO / "claude" / "guides" / n)]
@@ -492,7 +662,7 @@ def main():
                               prior.read_text(encoding="utf-8").splitlines() if ln.strip()}
     entry_state = seed_entry(claude_dir, monolith, prior_deployed, dry=dry)
 
-    merge_codex(codex_dir, codex_bundle, dry=dry)
+    merge_codex(codex_dir, codex_bundle, prior_deployed, dry=dry)
     copy_filtered(REPO / "codex" / "guides", guides, codex_dir / "guides", dry=dry,
                   backup=run_backup)