agent-bios 0.13.0 → 0.14.0

package/codex/guides/tooling-gotchas.md

@@ -40,28 +40,47 @@ depends on it, pin it explicitly instead of trusting the environment.
   shells resolve functions/aliases first, programmatic spawns resolve raw
   PATH, and a same-named package can shadow a system tool with silent empty
   output. Before trusting a result across execution contexts, confirm the
-  resolved target (`type -a`, absolute path).
+  resolved target (`type -a`, absolute path). A missing prefix wrapper fails
+  the same silent way — GNU `timeout` is routinely absent on BSD-derived
+  systems — so confirm the wrapper too.
 - **Cloud CLI context**: gcloud/aws/kubectl/terraform carry mutable ambient
   context (active project, profile, cluster) that drifts between sessions.
   Before the first environment-affecting command — or right after a resume —
   verify it against intent, then pin the target explicitly on every command
   (`--project`, `--profile`, `--context`) rather than fixing the global
-  default once.
+  default once. A forge CLI (`gh`/`glab`) reads its repository from the
+  checkout's remotes too: with a fork plus an upstream it can answer for the
+  wrong repo, so pass `--repo` wherever the answer feeds a decision.
 - **Installed is not running**: a live process keeps its old code until
   restarted or reloaded. When confirming an update, config change, or
   dependency bump took effect, don't stop at the on-disk artifact — confirm
   the running process's actual version/behavior or force a restart.
+- **Producer newer than consumer**: when a deployed binary validates an
+  artifact you produce (a signed config or manifest), produce and verify it
+  with the producer tooling checked out at the exact commit that binary was
+  built from — a local verify with current-tree tooling proves only that
+  newer tooling accepts it. Confirm the consumer's build commit from image
+  provenance, not the current branch; any version mismatch is a release
+  blocker. A consumer rebuilt from the same commit needs only ordinary
+  verification.
+- **A dev-labelled datastore target is a claim**: a localhost URL or
+  exported override is no evidence of a non-production target — a local port
+  can proxy into the only real instance, and a tool's config loader can
+  re-load a dotenv over your exported value. Before the first writing
+  command (migration, seeder), print what the connection reaches from inside
+  the tool's own path and assert it is the intended target; where the loader
+  is untrustworthy, extract the DDL and apply it yourself.
 
 ## Shell execution traps
 
 - **Pipe exit masking**: `$?` after a pipeline reflects only the last stage;
-  a real failure in the command under test is masked by a successful
-  `tail`/`grep`/`jq` and reads as a false green. Capture the tested stage's
-  own status: run it unpiped, store `$?` immediately, or use
-  `set -o pipefail`/`PIPESTATUS` — noting pipefail breaks legitimate
-  early-exit consumers (`cmd | head -1` → SIGPIPE 141), so it is a per-command
-  choice, not a global default. Does not apply when the final stage IS the
-  assertion (`cmd | grep -q pattern`).
+  a real failure upstream is masked by a successful `tail`/`grep`/`jq`,
+  reading green. Capture the tested stage's own status: run it unpiped,
+  store `$?` immediately, or use `set -o pipefail`/`PIPESTATUS` — a
+  per-command choice, since pipefail breaks early-exit consumers (`cmd |
+  head -1`, `grep -q` on a long producer → SIGPIPE 141). The
+  final-stage-assertion exemption (`cmd | grep -q pattern`) holds only
+  without pipefail; under it, capture output and check its status first.
 - **Passthrough arguments in a CLI you author**: an option meant to carry
   another command's own flags cannot use a greedy-but-dash-stopping arity —
   Python's `nargs="+"` ends at the first token starting with `-`, so the
@@ -71,6 +90,13 @@ depends on it, pin it explicitly instead of trusting the environment.
   second, separate trap: argparse consumes it as its own positional marker
   before the remainder sees it, so the form every caller reaches for first is
   the one that breaks — normalize it out of `argv` before parsing.
+- **CLI flag probes that execute**: probe a CLI only with invocations that
+  cannot do real work — a help form, or the candidate flag paired with a
+  control flag that forbids execution (dry-run, an invalid required
+  argument). Never run a subcommand bare, and assume a value after a flag
+  may be read as positional input: a boolean flag does not consume it, so it
+  falls through and runs. Tell a boolean from an unregistered flag by the
+  parser's error, not by the run succeeding.
 - **Reserved parameter names**: assigning to reserved shell names (`UID`,
   `EUID`, `GID`, `PPID`) can invoke the bound system behavior instead of
   storing a value — silently changing process credentials mid-script. Use
@@ -105,6 +131,14 @@ depends on it, pin it explicitly instead of trusting the environment.
   timestamp resolution (mutation testing). Clear the cache or run no-cache
   per iteration, and re-confirm the unmutated baseline still passes after a
   cache clear.
+- **Transport limits are measured on the wire payload, in the provider's
+  unit**: take the unit and value from the provider's rejection or a live
+  probe, never from docs or a variable's name, and measure the serialized
+  payload the consumer receives — after encoding and wrappers — not the
+  object you assembled. A character count against a byte limit undercounts
+  multibyte text, hiding while inputs are ASCII; an item count bounds no
+  size. Enforce at one dispatch chokepoint, deriving every budget from that
+  constant.
 
 ## Git operations
 
@@ -131,12 +165,31 @@ depends on it, pin it explicitly instead of trusting the environment.
   restore from that. The same asymmetry makes the restore step fragile: if the
   probe can time out or abort, the restore must not be the next command in the
   same invocation — put it where a failure cannot skip it.
+- **An ignore rule can swallow a durable record**: before treating a path as
+  durable — a new ledger, a cited authority — run `git check-ignore -v
+  <path>` and `git ls-files --error-unmatch <path>`. Broad runtime-state
+  patterns (`*.jsonl`, `runs/`, `out/`) absorb a new file, and a tracked
+  file pointing at an ignored path is an authority that exists in one
+  checkout only. Fix with a negation rule proven by a sibling that stays
+  ignored; genuinely ephemeral output stays ignored.
 - **Dirty-worktree pulls**: before pulling into a worktree with
   staged/unstaged/untracked changes, fetch first and compare incoming paths
   against every dirty path; on overlap or a non-fast-forward, stop and clear
   the conflict risk (stash, commit, ask). Otherwise pull `--ff-only`, confirm
   dirty changes survived, and regenerate any local derived artifacts whose
   inputs were updated.
+- **A split series is proven commit by commit**: order them by dependency
+  and check each out into a throwaway worktree to run the build, tests, and
+  gates before pushing. Green only at the tip hides a broken bisect point
+  and a commit that cannot be reverted alone — usually a rename or shared
+  hunk in the wrong commit. If a handoff cites the branch's hashes, merge
+  with a merge commit: squash and rebase rewrite every hash.
+- **A shared tree holds other operators' work**: a commit you did not make, a file the
+  editor reports changed on disk, a staged path you never added, one more field than
+  your predicted post-state — treat an unexplained delta as someone else's work, not
+  noise. Before a sweeping write (`git add -A`/`.`, `commit -a`, `stash`, `clean`,
+  `reset --hard`), attribute it (`git status`, reflog timestamps, other live sessions)
+  and then act only on what you can prove is yours — add by name.
 
 ## Config, secrets, and managed services
 
@@ -151,6 +204,13 @@ depends on it, pin it explicitly instead of trusting the environment.
   leaving stale, unreferenced definitions live. After updating, re-read the
   resource, check definitions and active references separately, and remove
   the orphans explicitly.
+- **Derive a new revision from the live one, not from a template**: a
+  replace-semantics update drops every field the command does not restate,
+  and wrappers commonly default mounted secrets to off. Render the exact set
+  the command will send, derived from the live resource, and diff it field
+  by field; a field that disappears, or an operational value that moves
+  backward, is a blocker to explain, not a default to accept. Re-read the
+  resource afterwards, since a command rarely labels its semantics.
 - **A new revision is not live traffic**: on a runtime that pins traffic to a
   named revision (e.g. Cloud Run with a fixed split), `gcloud run deploy` (or
   the equivalent) creates the new revision but shifts no traffic to it — the
@@ -158,23 +218,101 @@ depends on it, pin it explicitly instead of trusting the environment.
   update-traffic`. Read the "deploy succeeded" message as "a revision exists",
   not "the new code is serving"; verify the live traffic split before
   concluding the deploy took effect.
-- **Perimeter controls need the enforcement point's own logs**: an agent-side
-  fetch is not an independent external observer — its egress IP and caching
-  path are opaque, and it may share the protected network or serve a stale
-  cached response. Verify allow AND deny directions from the load balancer /
-  firewall's own logs, and check for a front-side cache/CDN separately.
+- **Job logs outlive the execution**: a managed job that has run more than
+  once under one name — including one deleted and recreated with the same
+  name — returns the earlier incarnations' output when its logs are read by
+  job name. Scope every read to the execution id you received at launch and
+  confirm the timestamp window covers that run. An unscoped read merges
+  prior runs into the present and yields confident false diagnoses that a
+  scoped read reverses.
+- **Dispatch status is not execution**: a CLI `--wait` returning or timing
+  out, a scheduler reporting success, a trigger accepted without error —
+  each reports what the dispatcher saw, not whether the target ran or what
+  state it reached. Before retrying or declaring done, re-derive the state
+  from the target's own record (its execution describe, the handler's logs),
+  matched to the run by id, and keep a manual probe distinguishable from the
+  scheduled one. A blind re-launch is a duplicate execution with side
+  effects.
+- **An apply cut off before confirmation is unconfirmed** — neither done nor
+  un-run: when a multi-statement side-effecting apply (migration, batch
+  write) loses its confirmation channel, enumerate which target objects
+  already exist in the store, and plan the rerun from that partial state; a
+  naive rerun half-fails on "already exists" and leaves a second partial
+  state. Where the runner surfaces only exit status, route the object list
+  out through a deliberate failure. A transactional or provably idempotent
+  apply needs only the confirmation.
+- **A traffic rollback is not a config rollback**: on a revision-pinned
+  runtime, sending traffic back to the previous revision restores behavior
+  but leaves the added env var or secret binding in the service template,
+  where the next deploy re-enables it silently. Count a rollback complete
+  only when the traffic split and the service spec are both back to the
+  prior state — re-read the spec and remove the change explicitly. Runtimes
+  that redeploy the prior spec itself (immutable-artifact, GitOps) have no
+  such gap.
+- **Perimeter controls need the enforcement point's own logs**: an
+  agent-side fetch is not an independent observer — its egress IP and
+  caching path are opaque, and it may share the protected network or serve a
+  stale cached response. Verify allow AND deny directions from those logs,
+  and check for a front-side cache/CDN separately. Aim the probe at an
+  in-unit sentinel the app answers without credentials: a denial the app
+  produces anyway passes with the control off, and a redirect into it is a
+  bypass.
+- **Tightening exposure is a behavior change for external clients**: switching
+  ingress mode, adding an allowlist, or requiring auth is not safe when
+  callers live outside your redeploy. Enumerate which clients reach the
+  endpoint and by which hostname, verify from a client's vantage, and
+  confirm inbound volume did not fall to zero — clients you cut off raise no
+  error on your side, so enforcement-point logs alone can sever ingestion
+  silently. Callers you redeploy in the same change need only the ordinary
+  deploy check.
 - **Smoke limits outlive the smoke test**: item caps, sample sizes, and row
   limits left in env vars/flags/config make a later "full-scale" run silently
   succeed on a slice. Clearing or explicitly verifying their absence is a
   precondition of declaring a full run.
+- **A remote handle is valid only when it was read**: a row index in a sheet
+  that auto-sorts, a downloaded copy of a hosted file — each moves between
+  your read and your write. Before writing, re-establish the target from the
+  live source: re-locate the row by its key column, not a remembered
+  position, and assert the key matches after the write; compare the remote's
+  version against the copy you edited, re-downloading and reapplying on a
+  move. Local single-writer files need none of this.
+- **Packaging and ignore rules are judged against paths and environments, not your tree**: before
+  a release, pack the real tarball, install it clean with lifecycle scripts
+  ON, and smoke it — a postinstall hook fine in the repo can delete the
+  shipped runtime where the build toolchain is absent. After moving or
+  renaming a directory, every ignore rule is void for the new paths:
+  re-check there and read the staged diff's file count, since old-path
+  patterns stop matching and excluded data enters the stage.
 - **Shared live config has concurrent writers**: before concluding your edit
   to a shared state/config file was lost or corrupting, rule out concurrent
   writers with a short live observation (mtime plus the fields you changed),
   and scope merge/union operations to the intended fields only.
+- **Uniform failure is structural — read the persisted reason, then check the built artifact**: when
+  every item in a batch fails and the per-item error is persisted outside
+  the log (a status column, a result record), read it before blaming keys,
+  quota, or model availability. And when code reads sibling files from its
+  working directory, prove they exist inside the built image by listing or
+  hashing them there: a selective copy passes every repo-side check and
+  fails only at runtime.
 - **Production probes expose data**: default diagnostic queries against
   production stores to read-only server-side aggregation (counts, types,
   presence, hashes) — never pull raw payloads into logs, prompts, or
   transcripts — and delete scratch probe resources after the decision.
+- **Build-context ignore patterns anchor at the root**: in a `.dockerignore`
+  or any root-anchored filter, a bare filename matches only at the context
+  root and never in a subdirectory, and an extension glob misses the
+  same-purpose credential file carrying another extension. Never conclude a
+  shipped image is secret-free from the patterns — list the built artifact's
+  own filesystem for credential-shaped files (env files, keys,
+  service-account JSON) as a named negative control, repeated whenever the
+  build context or ignore file changes.
+- **A revoke is grant-wide, not token-wide**: revoking anything issued under
+  a client id the user's live sessions share invalidates those sessions too,
+  and the failure surfaces later, elsewhere, with no re-auth prompt. A probe
+  may clean up only what it alone owns — use minimum scopes and a dedicated
+  client id, and let a probe token expire rather than revoking it. Where a
+  revoke on a shared grant is unavoidable, state the blast radius and time
+  it with the user.
 
 ## Own what you spawn
 
@@ -186,3 +324,32 @@ Instance of the global rule: own the full lifecycle of what you create.
   orphans the real child), and await exit. An unref'd child handle or open
   stdin pipe keeps the parent's event loop alive and hangs otherwise-complete
   commands.
+- **A handle issued to a human is a commitment**: once a consent URL is
+  handed over, the listener behind it must not be restarted, re-ported, or
+  replaced while the person may still act — keep it alive until the callback
+  lands, or say plainly that the link is dead. The handler captures the
+  credential write-once and ignores later hits, since a browser's favicon
+  request clears a naive one. Before asking a human to click again, drive
+  the handler with a simulated callback.
+- **A stop is confirmed at the sink, not in the process list**: a kill that
+  misses one descendant lets that stage finish and publish, and the process
+  list looks clean either way. After stopping a multi-stage run, list the
+  output sink for anything written after the stop instant and roll it back
+  as contaminated. Read the rollback path's retention — noncurrent-version
+  expiry is a recovery window, not a backup — and snapshot before a risky
+  run, choosing the restore point by timestamp.
+- **Detach what must outlive the call**: a process started inside a harness
+  tool call belongs to that call's process group: a trailing `&` is reaped
+  when the call returns, and the harness may signal the group when another
+  background task finishes. Launch anything meant to outlive one call
+  through the harness's background facility or fully detached
+  (nohup/setsid), writing progress to durable files a resume can read. A
+  zero-byte output file means it never survived. Detached still means owned
+  — PID file and stop path.
+- **Name-substring lookup is not a liveness check**: `pgrep -f <name>` and
+  `ps | grep <name>` match the argv of the shell running the query itself,
+  and match unrelated processes carrying the same name — another session, a
+  sibling dispatch, the launcher's own plan text. To decide whether a
+  dispatched job is alive, use the PID or handle captured at launch, its
+  process-group state, or growth of its own output artifact. Substring
+  lookup is for discovery only, confirmed against one of those first.

package/codex/guides/verification-discipline.md

@@ -34,11 +34,21 @@ the depth first:
   over persisted real artifacts rather than re-running the whole pipeline to observe it.
 - Probe at N=1 with the inputs precondition-checked. A single well-chosen case that reaches the
   real path outranks a hundred that stop short of it.
+- Bound the N=1 probe to reachability. One case settles whether a path works — never how often a
+  stochastic behavior holds. Before quoting a rate-shaped property (determinism, flake rate, an
+  A/B effect), confirm the mechanism honors your controls, establish the noise floor from runs on
+  hand, then sample enough to bound the rate against a no-treatment control on the real path. A
+  floor larger than the effect breaks the premise — record it before redesigning.
 - Reserve the full design-review-plus-live-verification treatment for first-of-kind work and for
   changes that move authority — who may decide, who may write, what is irreversible.
 - Proportion assurance to the deployment context. A single-user tool operating on its owner's own
   data does not warrant production-grade assurance, and treating it as if it did buys nothing
   while delaying delivery. Prefer shipping.
+- Census the population before a costed or irreversible batch. Read its current state cheaply and
+  deterministically — status distribution, version, presence of the artifacts the plan expects —
+  and compare that against the premise the batch rests on, halting to re-diagnose when the
+  distribution contradicts it. A probe validates the path; only the census validates that the
+  population is what the plan assumes. A cheap idempotent batch over a few items needs none.
 
 The failure this prevents is not under-testing. It is spending the verification budget on the
 cheap half of the risk and having nothing left for the part that could actually hurt.
@@ -62,10 +72,14 @@ cheapest one to write.
 - Config or data: real parsers, schema checks, fixture validation, and sample transformations.
 - Spreadsheets: static workbook checks, fixture-based output checks, cross-sheet flow checks, visual/layout checks, and real Microsoft Excel engine recalculation for formula-dependent results.
 - Docs: links, terminology, current behavior alignment, and references to isolated historical notes.
+- Multi-subject prose: when deliverables draw on material about different people, companies, or cases, bind every captured item to its subject and confirmation status at capture, and narrate nothing under a subject until that binding is confirmed. Cross-check subject-specific proper nouns and figures across all outputs before delivery — one subject's term under another is the signature of context bleed. Keep a figure in the same sentence as its composition, since a detached number is read at its worst.
 - Release or distribution: after publishing to multiple independently writable channels (signed manifest, object storage, release host, embedded updater), digest-verify every referenced object against the staging original per channel — publish success and upload order are not evidence — and run the real installer/updater through its default path.
 - A/B or on/off measurements: before accepting a null result, verify the arms actually received different treatment in the mechanism under test — a shared default or unconditional upstream step can silently apply the treatment to both arms.
+- Multi-stage pipelines with nondeterministic stages: a final-output diff cannot attribute an effect or a regression to a stage — it conflates the change with run-to-run variance. Persist every stage's output, tabulate what each creates, may edit, and only guards, restrict the suspects to the stages that edit the content in question, and find the first stage where the intended effect disappears or the defect appears. Fix there, preferring a structural recheck over another prompt-level instruction that already failed.
+- Before/after comparisons: pin the input to an immutable copy — a snapshot or versioned artifact — and run both arms against it, because a live artifact (a growing log, a regenerated upstream stage) drifts between runs and any diff over it, a matching one included, is evidence of nothing; when the arms are metered, restore the baseline's exact upstream inputs and re-run only the changed stage. This is input identity, not the separate unit-and-denominator basis rule.
 - Model-behavior guardrails: verify by changed behavior, not recitation — a staged battery from named-trigger cases through disguised, deconfounded, category-wide, and single-variable framings; a clean pass means "no known defect", so re-run the battery when the model changes.
 - Branch/version test builds against real data: explicitly separate every state sink the app touches (files, DB, OS-level stores that ignore env overrides), confirm the launch path propagates the isolation to child processes, and back up live data before the first run — a mismatched schema that drops unknown fields on write is data loss, not a no-op.
+- Sandbox, replay, or re-adjudication runs on production-derived config: enumerate every outbound channel the stage can reach — publish, upload, notify, external write — and disable or redirect each one before the run, proving each disarm fires as you would prove a path guard; a guard on the input or target path alone leaves egress armed. Fingerprint every external destination before the run and diff it after, so an escaped write is caught by the run rather than by a recipient.
 - Irreversible capture switches: when activation itself has unreproducible cost (a capture window that cannot be replayed), prove the downstream consumption path against existing samples before enabling — reversibility of the code path alone is not enough.
 
 ## Deriving the case space
@@ -108,6 +122,12 @@ someone typed once.
   interrupted, a restore sitting after it never runs and the plant survives into a
   commit. Plant in a copy where the shape allows it, and when it must be in place, snapshot
   first and restore from the snapshot as its own step rather than trusting the probe to finish.
+- Attribute a fault by a controlled contrast before choosing a remedy. Hold everything constant —
+  principal, path, input — vary only the candidate variable, and read a countable difference
+  (element dimensions, request count, status-code family). A missing error report is not
+  exoneration: channels can be suppressed, unobserved, or unwired from the mechanism at fault, so
+  "no violations logged" rules a cause out only when the contrast shows none either. Read the
+  contrast the evidence already holds before proposing a policy loosening.
 
 ## When a green means nothing
 
@@ -121,17 +141,65 @@ produce a green with no evidence behind it:
   confirm its inputs satisfy the live branch's entry guard. A copied fixture that fails the new
   guard routes silently into the about-to-be-deleted dead branch and stays green after the real
   behavior breaks.
+- **The fixture the producer never emits.** A test's input is evidence only when the thing that
+  produces it in production produced it. A wire fixture must be a raw response captured through
+  the same client that will parse it, never a rendered listing or a hand-written payload; a gated
+  feature's E2E must run with the gate in its production setting, on the state its real upstream
+  leaves. Replay against the live producer once, then probe every sibling built the same way.
 - **The permissive fallback in the checker.** A `a || b` inside a gate absorbs a wrong assumption
   and keeps passing. Checker code must assert the shape it expects and fail loud.
 - **The suspiciously fast or empty run.** When a check goes green unexpectedly quickly, or reports
   nothing at all, dump what it actually ran over before believing it. A harness that crashed early
   and one that found nothing produce the same exit code.
+- **The control that failed by crashing.** A negative control is evidence only when it fails
+  through the assertion it names: a traceback and a caught violation share an exit code, and an
+  early crash can pre-empt every control after it. Treat each traceback in a control run as a
+  defect until the run reports one named failure per planted violation. Run any unattended gate
+  with stdin closed, so a path reaching a prompt fails at once instead of hanging.
 - **The control that went quiet.** A negative control indexing a live list stops testing when that
   list empties, and says nothing about it. New controls build their own subject; resolving an item
   means re-reading the controls for ones that have gone silent.
-
-The discipline that covers all five: after adding a check, revert the fix it guards and watch the
-check fail. A control that survives a faithful revert was never testing the thing it names.
+- **The silent log.** Absence of activity is not evidence of non-use. Before retiring an
+  identity, key, or endpoint on a quiet log, show that the queried field is the one recording the
+  subject — delegated actions are attributed to the caller, with the target in another field, so
+  the wrong field returns clean silence — and that no live binding still references it, since a
+  reference proves use while emitting no traffic. Only a demonstrated "this use would have been
+  logged" evidences non-use.
+- **The population that shrank.** A gate scanning an explicit list of files sees only "listed but
+  empty": a subject that migrates to an unlisted surface leaves the scanned set smaller yet
+  non-empty, so the empty-subject guard never fires while coverage erodes. Retarget the gate in
+  the same change that moves the code, and pin a floor so any decrease fails loudly — proved by
+  moving one subject out. A floor is a ratchet: never lower it to pass a run.
+- **The mutant that never ran.** A mutation verdict counts only if the mutant is valid: it
+  compiled, sits on a path the exercised test traverses, and changes the guarded behavior, not
+  healed downstream or coinciding with a default. The runner must report build failure,
+  unreachable, and equivalent distinctly from KILLED and SURVIVED, and halt on a moved anchor.
+  More tests red than the mutation should touch indicts it; classify a survivor (rebuild,
+  discard, genuine gap) before writing a test.
+- **The probe that measured the original.** A copied script that derives its root or targets from
+  its own location (`$0`, `BASH_SOURCE`, a `cd` to its parent) scans the original tree, not the
+  copy, so its verdict says nothing about the mutation you planted. Pin the subject in the copy,
+  copy the whole tree, or plant in place with a snapshot-restore. The tell is a result identical
+  to the unmutated run; a script taking its subject as an argument is safe to copy.
+
+The discipline that covers every shape above: after adding a check, revert the fix it guards and
+watch the check fail. A control that survives a faithful revert was never testing the thing it
+names. Prove the plant landed: assert the altered input differs from the original and that the
+control's cases reach the mutated branch before asserting rejection. Construct corruption
+deterministically: scanning for a flip site yields no-op mutations reporting a rejection nothing
+exercised.
+
+## Before blaming code for a metric change
+
+When a live metric collapses or crosses a pre-declared threshold, localize the change in time
+before diagnosing the feature: confirm every inbound source is alive, compare only
+contemporaneous cohorts, never re-processed rows, then bracket the transition to the finest unit
+available and read the deploy log around that instant.
+
+A change landing seconds from the last-good point is the prime suspect; a step in a window with
+no deploys is an input-population shift, fixed by scoping the measured population, not the model
+or the code. Declare the threshold before looking, and confirm a failure from the fleet's vantage
+rather than your own — this does not replace fixing the comparison basis, which comes first.
 
 ## Keeping E2E honest
 

package/install.sh

@@ -68,6 +68,21 @@ PRIOR_MANIFEST="$STATE_DIR/manifest.prev.txt"
 ZSHRC="${ZDOTDIR:-$HOME}/.zshrc"
 ZSH_HOOK='[ -r "$HOME/.config/agent-launch/shell.zsh" ] && source "$HOME/.config/agent-launch/shell.zsh"'
 HOOK_MARK='agent-launch/shell.zsh'
+# .zshrc is the only file this installer WRITES, but it is not the only file zsh reads, and a
+# user who moves the line to .zshenv (where non-interactive shells see it too) had every
+# question about it answered wrongly: `status` said "zsh hook absent" while the integration was
+# demonstrably running, `uninstall` said there was nothing to remove, and the next `install`
+# appended a second copy to .zshrc. Detection therefore looks everywhere zsh would; ownership
+# stays with .zshrc alone.
+ZSH_HOOK_FILES="${ZDOTDIR:-$HOME}/.zshrc ${ZDOTDIR:-$HOME}/.zshenv ${ZDOTDIR:-$HOME}/.zprofile"
+
+# Echo every startup file that carries the hook line, one per line, or nothing.
+zsh_hook_locations() {
+  local f
+  for f in $ZSH_HOOK_FILES; do
+    if [ -f "$f" ] && grep -qF "$HOOK_MARK" "$f"; then printf '%s\n' "$f"; fi
+  done
+}
 
 DRY_RUN=0
 BACKUP_DIR=""
@@ -390,8 +405,11 @@ assemble_corpus() {
 }
 
 add_zsh_hook() {
-  if [ -f "$ZSHRC" ] && grep -qF "$HOOK_MARK" "$ZSHRC"; then
-    info "zsh hook present  $ZSHRC"
+  local found
+  found="$(zsh_hook_locations)"
+  if [ -n "$found" ]; then
+    # Appending beside an existing copy would source the integration twice per shell.
+    info "zsh hook present  $(printf '%s' "$found" | tr '\n' ' ')"
     return
   fi
   if [ "$DRY_RUN" = 1 ]; then info "[dry-run] append zsh hook to $ZSHRC"; return; fi
@@ -689,8 +707,13 @@ PY
 }
 
 remove_zsh_hook() {
+  local other
+  # Named, never edited: a line this installer did not write is the user's, and uninstall
+  # removing it would be editing a file it does not own.
+  other="$(zsh_hook_locations | grep -vF "$ZSHRC" || true)"
+  [ -n "$other" ] && info "zsh hook also in $(printf '%s' "$other" | tr '\n' ' ') — left in place (not written by this installer)"
   if [ ! -f "$ZSHRC" ] || ! grep -qF "$HOOK_MARK" "$ZSHRC"; then
-    info "no zsh hook to remove"
+    info "no zsh hook to remove  $ZSHRC"
     return
   fi
   if [ "$DRY_RUN" = 1 ]; then info "[dry-run] remove zsh hook from $ZSHRC"; return; fi
@@ -975,6 +998,13 @@ cmd_verify() {
   verify_match "$REPO/launch/agent-launch.py" "$BIN_DIR/agent-launch"        || fail=1
   verify_match "$REPO/launch/agent-launch.toml" "$LAUNCH_DIR/profiles.toml"   || fail=1
   verify_match "$REPO/launch/agent-launch.zsh"  "$LAUNCH_DIR/shell.zsh"        || fail=1
+  # Evidence, never a verdict: a shadow that was repaired is the mechanism working.
+  shell_shadow_summary
+  # Not `whence -v`: a function redefined at preexec carries no "from FILE" annotation,
+  # so in exactly the shell the reassert repaired, whence reads as "not ours". And not a
+  # substring of the body either — a foreign body can quote it. Byte-equality with the
+  # body the interception captured when it was sourced is the same test the reassert runs.
+  info "live check (run in the terminal you use): [[ \"\$functions[claude]\" == \"\$_agent_launch_body[claude]\" ]] && print OURS   → expect OURS"
   # The catalogs were the one deploy-managed artifact nothing verified, which is
   # the state that renders key names on screen: the deployed launcher keeps no
   # catalog beside itself, so whatever is here IS the UI text. Byte-identity, the
@@ -1055,7 +1085,19 @@ PY
     fi
   fi
   # Repo-internal mirror parity is a maintainer gate; only meaningful from a clone.
-  if [ -d "$REPO/ko" ] && [ -x "$REPO/gates/check-parity.sh" ]; then
+  #
+  # Not from inside the install-scenario suite, though. That suite points REPO at its own
+  # checkout and writes only into a sandbox HOME, so the tree this gate would judge is the
+  # very tree the umbrella that launched the suite already judged — and the suite performs
+  # twelve verifies. Measured 2026-08-31: 3m37s each, 43m22s of a 50m26s commit, 86% of it,
+  # for twelve re-derivations of one unchanged answer that no assertion in
+  # gates/test-install-guides.sh reads. The skip announces itself, because a leg that goes
+  # quiet is how a suite reports clean over something it never ran. The payload and
+  # prompting-target gates above are deliberately NOT skipped: at 0.16s together they buy
+  # back no time, and running them keeps proving that verify still wires its gates up.
+  if [ "${AGENT_BIOS_IN_INSTALL_TEST:-0}" = 1 ]; then
+    info "SKIP: repo mirror parity — the umbrella running this suite already judged this tree"
+  elif [ -d "$REPO/ko" ] && [ -x "$REPO/gates/check-parity.sh" ]; then
     # Output kept, not discarded — the third place in this repo where a gate's own
     # explanation went to /dev/null and left "it failed" as the entire report. The umbrella
     # and the install-scenario harness each learned this after a failure cost an eleven-
@@ -1273,6 +1315,9 @@ archive_and_purge() {
     # the file keeps the thing that names it. Everything else goes either way.
     if [ "${UNBACKED:-0}" -eq 0 ]; then
       rm -rf "$STATE_DIR"
+    else
+      # The dir survives for the manifest's sake; the shell-shadow evidence is not that.
+      rm -f "$STATE_DIR/shell-shadow.log"
     fi
     rm -rf "$HOME/.cache/agent-launch" \
            "${AGENT_LAUNCH_VENV:-$HOME/.local/share/agent-launch}"
@@ -1528,7 +1573,44 @@ cmd_status() {
            "$LAUNCH_DIR/profiles.toml" "$LAUNCH_DIR/shell.zsh"; do
     if [ -e "$p" ]; then info "present  $p"; else info "MISSING  $p"; fi
   done
-  if [ -f "$ZSHRC" ] && grep -qF "$HOOK_MARK" "$ZSHRC"; then info "zsh hook present"; else info "zsh hook absent"; fi
+  zsh_found="$(zsh_hook_locations)"
+  if [ -z "$zsh_found" ]; then
+    info "zsh hook absent"
+  elif printf '%s\n' "$zsh_found" | grep -qxF "$ZSHRC"; then
+    info "zsh hook present  $(printf '%s' "$zsh_found" | tr '\n' ' ')"
+  else
+    # Present and working, but somewhere this installer will neither update nor remove.
+    info "zsh hook present  $(printf '%s' "$zsh_found" | tr '\n' ' ')  (unmanaged location: not $ZSHRC)"
+  fi
+  shell_shadow_summary
+}
+
+# The interception in launch/agent-launch.zsh reasserts `claude`/`codex` at preexec when a
+# tool redefined them after the rc files (cmux does, on its first precmd) and appends one
+# line per shadowed host per shell to $STATE_DIR/shell-shadow.log. That log is the only
+# evidence of shadowing status/verify can read: a child shell cannot reproduce the
+# terminal's own bootstrap, so a canary run from here would report PASS while the live
+# shell is shadowed — which is why there is none.
+shell_shadow_summary() {
+  local f="$STATE_DIR/shell-shadow.log" n last
+  # A dir that cannot be written records nothing, and "nothing" must not read as "clean" —
+  # so this branch is exclusive: no "no shadowing observed" beside it.
+  if [ -L "$f" ] || { [ -e "$f" ] && [ ! -f "$f" ]; }; then
+    info "shell interception: evidence log is not a regular file ($f) — nothing is recorded there, so absence here is not evidence"
+  elif { [ -d "$STATE_DIR" ] && [ ! -w "$STATE_DIR" ]; } || { [ -e "$f" ] && [ ! -w "$f" ]; }; then
+    info "shell interception: evidence log not writable ($f) — a shadowing cannot be recorded, so absence here is not evidence"
+  elif [ -s "$f" ]; then
+    # One line is one host's FIRST observation in one shell, never a count of repairs: a
+    # tool that redefines on every prompt is repaired on every command and logged once.
+    n=$(wc -l <"$f" | tr -d ' ')
+    # Control bytes are stripped again on display: the log is written by a shell the
+    # user does not fully own, and a terminal-control sequence in a "foreign body" field
+    # could repaint this very line.
+    last=$(tail -n 1 "$f" | tr -d '\000-\010\013-\037\177')
+    info "shell interception: shadowing observed $n time(s) (first observation per host per shell), last $(printf '%s' "$last" | cut -f1) — $(printf '%s' "$last" | cut -f2) was shadowed by: $(printf '%s' "$last" | cut -f4-)"
+  else
+    info "shell interception: no shadowing observed"
+  fi
 }
 
 cmd_update() {