instar 1.2.76 → 1.2.78

package/upgrades/side-effects/codex-parity-p0-hook-arm.md

@@ -0,0 +1,50 @@
+# Side-Effects Review: P0 hook-arming orchestration (codexHookArm)
+
+## Change
+New `src/core/codexHookArm.ts` + unit tests — the P0 arming orchestration (the half that decides
+whether/what to arm and verifies the outcome), per the approved+converged spec (P0 / G2 verdict +
+§7 gates F1-F3):
+
+- `armCodexHooks({projectDir, codexHome?, trustDriver?})` — idempotent: returns `already-armed`
+  (no spawn) when all of the agent's project hook slots are already trusted+enabled (F2); `skipped`
+  when the project hooks.json is NOT instar-owned (F1 manifest verify — never blind-trust); else
+  drives Codex's trust flow then READS BACK config.toml to confirm (`armed` / `partial` with the
+  still-untrusted + the user-disabled slots surfaced, F3 — never silently re-enables).
+- `projectHooksAreInstarOwned(projectDir)` — F1: the project `.codex/hooks.json` must match
+  buildInstarCodexHookGroups (expected instar hooks present) AND carry no instar-marker command
+  pointing outside THIS project's hooks dir (anti-injection).
+- `makeTmuxTrustDriver({tmuxPath, codexBinary, model})` — the default driver: spawns interactive
+  Codex in tmux (CODEX_HOME scoped, **NO `--dangerously-bypass-*` flags** — F1), polls capture-pane
+  (bounded ~40s) for the trust prompt, sends Down+Enter to pick "Trust all and continue", then
+  exits + kills the pane. The fragile keystroke step is INJECTED so the orchestration is unit-tested
+  without a real codex; the driver itself is validated by test-as-self on a live agent.
+
+## Why
+G2 verdict: arming the agent's own project hooks via Codex's trust state is inherently per-agent
+(path-keyed) and avoids the rejected machine-wide managed-config. This module makes that arming
+idempotent, safe (manifest-verified, no bypass flags), and verifiable (readback) — the F1-F3 gates
+the convergence review demanded.
+
+## Scope / blast radius
+- New code; the orchestration is pure-ish (fs reads + an injected driver). `armCodexHooks` is NOT
+  yet wired into install/migrate (next increment) — no runtime behavior change until then.
+- When wired, it only ever arms the agent's OWN project hooks (path-scoped); the operator's
+  personal Codex (other cwd) is untouched. The tmux driver runs without sandbox/approval bypass.
+- No migration impact yet (new code, ships with dist). The B2 atomic-with-migration wiring is the
+  next step. <!-- tracked: codex-full-parity -->
+
+## Signal vs Authority / Over-block
+- N/A — this arms safety hooks (makes them run); it adds no new gate authority. The hooks
+  themselves keep their existing signal/authority split.
+
+## Rollback
+- Delete the module + test. Not yet referenced by any call path.
+
+## Tests
+- `tests/unit/codexHookArm.test.ts`: 7 — manifest-owned true/false; already-armed skips the driver
+  (idempotent); manifest-mismatch refuses to drive; arms+readback; partial when readback incomplete;
+  user-disabled surfaced not re-enabled. Green. tsc clean.
+- Live test-as-self of the tmux keystroke driver: batched with the P0 joint live-proof on codey.
+
+## Publish
+- Feature branch `echo/codex-parity-audit`. Ships atomic with P1 (spec §7 B2).

package/upgrades/side-effects/codex-parity-p0-hook-trust-core.md

@@ -0,0 +1,43 @@
+# Side-Effects Review: P0 hook-trust core (parse + idempotency)
+
+## Change
+New pure-function module `src/core/codexHookTrust.ts` + unit tests — the testable
+foundation of P0 (Codex hook auto-arming), per the approved+converged master spec
+(`docs/specs/codex-full-parity-fixes.md`, P0 / G2 verdict):
+
+- `parseCodexHookTrust(configTomlBody, hooksJsonPath)` — line-based parse of the
+  `[hooks.state]` entries that belong to a specific project hooks.json path (no TOML dep,
+  matching instar's deliberate no-TOML-parser stance). Returns per-slot trusted_hash + enabled.
+- `codexHooksArmingStatus(...)` — F2 idempotency: which of the agent's project hooks are
+  still untrusted vs explicitly disabled (so the arming step is skippable when already armed,
+  and never silently re-enables a user-disabled hook — F3).
+- `expectedHookSlots(hooks)` — derives `<state_event>:<group>:<idx>` slots from a Codex
+  hooks.json config (the shape buildInstarCodexHookGroups produces), with the event→state-key
+  lowercase/snake_case map Codex uses.
+
+## Why
+P0's G2 verdict (spec §P0): per-agent scoping comes from trust entries being keyed by the
+project hooks.json PATH, so instar arms only its own project hooks. This module is the
+read/verify half — it lets the arming step be idempotent (skip a TUI spawn when already
+trusted) and lets a post-arm readback confirm trust actually took (F2). Pure functions, fully
+unit-testable; the fragile spawn/keystroke driver is a separate later module (codexHookArm).
+
+## Scope / blast radius
+- Pure, side-effect-free parsing. Not yet wired into any call path (building block). No runtime
+  behavior change until the arming driver + wiring land. No migration impact (new code, ships
+  with dist).
+
+## Signal vs Authority / Over-block
+- N/A — read/verify only; no gating, no authority.
+
+## Rollback
+- Delete the module + test. Nothing references it yet.
+
+## Tests
+- `tests/unit/codexHookTrust.test.ts`: 8 tests — path-scoped parsing, enabled default-true +
+  explicit-false, arming-status (untrusted/disabled/allArmed), fresh-agent = fully untrusted,
+  slot derivation. Green. tsc clean. Sample config mirrors the real codey [hooks.state] shape.
+
+## Publish
+- Feature branch `echo/codex-parity-audit` (rebased onto JKHeadley/main before PR). Part of the
+  P0 bundle, which ships atomic with P1 (spec §7 B2).

package/upgrades/side-effects/codex-parity-stop-trio-and-deferral.md

@@ -0,0 +1,76 @@
+# Side-Effects Review: Codex parity P1 — correct Stop trio + deferral-detector on PreToolUse (Codex-aware)
+
+## Change
+From the APPROVED master spec (`docs/specs/codex-full-parity-fixes.md`, P1):
+
+1. **`installCodexHooks.ts` — fix the Codex Stop review trio.** Codex `Stop` now wires
+   `response-review + claim-intercept-response + scope-coherence-checkpoint`, MIRRORING
+   the Claude Stop trio (`settings-template.json`). Previously it wrongly wired
+   `response-review + deferral-detector + scope-coherence` — it had dropped
+   `claim-intercept-response` (the anti-confabulation Stop hook) and substituted
+   `deferral-detector`, a PreToolUse hook whose `tool_name==='Bash'` guard makes it a
+   silent no-op on a Stop payload (PROVEN dead via payload replay, ledger §1).
+2. **`installCodexHooks.ts` — deferral-detector moved to Codex `PreToolUse`** (where it
+   lives on Claude), joining dangerous-command-guard + external-operation-gate +
+   grounding-before-messaging.
+3. **`PostUpdateMigrator.getDeferralDetectorHook()` — Codex-aware payload.** The script
+   now accepts `tool_name` ∈ {`Bash`, `exec_command`} and reads
+   `tool_input.command || tool_input.cmd` — the same fix class already applied to
+   dangerous-command-guard and grounding-before-messaging. Previously Claude-only.
+4. **`codexHookContractCanary.ts` — corrected invariant lock.** Now asserts the correct
+   Stop trio (with claim-intercept-response), asserts deferral-detector is on PreToolUse,
+   and FAILS if deferral-detector ever appears on Stop again (locks out the regression).
+   The canary previously asserted the WRONG trio — it had encoded the bug as correct.
+
+## Why
+- The Stop trio must match Claude's so Codex agents get the same end-of-turn review
+  (coherence + anti-confabulation + scope). deferral-detector on Stop did nothing; the
+  real anti-confabulation hook (claim-intercept-response) was absent.
+- deferral-detector on PreToolUse + Codex-aware means it actually inspects Codex shell
+  (`exec_command`) messaging commands, not just Claude `Bash` — so its false-blocker /
+  orphan-TODO checklist fires on Codex too.
+
+## Scope / blast radius
+- `claim-intercept-response.js` is already installed for Codex agents (PostUpdateMigrator
+  hook-install set + on codey on disk), so wiring it onto Stop references an installed
+  script (no dangling reference; `validateHookReferences` guards this).
+- Migration parity: `migrateHooks` re-runs `installCodexHooks` for codex-cli agents
+  (always-overwrite for instar-owned groups), so existing Codex agents pick up the
+  corrected wiring on update. deferral-detector.js is always-overwrite, so existing
+  agents get the Codex-aware payload reading too. NOTE: rewriting hooks.json changes the
+  hashes → Codex marks them "needs review" until trusted; the trust-activation gap is
+  P0 (separate fix). This change makes the wiring CORRECT; P0 makes it ACTIVE.
+- Claude agents unaffected — the deferral-detector payload change is purely additive
+  (still reads Bash/command; now ALSO exec_command/cmd).
+
+## Signal vs Authority
+- Unchanged. All three Stop hooks remain low-context signal emitters that POST to the
+  server's review endpoints for the authoritative decision; deferral-detector still only
+  injects a checklist (`decision:'approve'` + additionalContext), never blocks.
+
+## Over-block / autonomy risk
+- None added. scope-coherence retains its self-throttle; claim-intercept-response and
+  response-review behave on Codex as on Claude (PENDING the payload-field confirmation —
+  see "Known follow-up").
+
+## Known follow-up (tracked) <!-- tracked: codex-full-parity -->
+- response-review.js and claim-intercept-response.js both read `input.last_assistant_message`
+  on Stop. Whether Codex's Stop payload populates that exact field is being confirmed by
+  capturing a real Codex Stop payload (next P1 commit). If Codex names it differently,
+  those two get the same multi-field-accept treatment. The WIRING here is correct
+  regardless; this is about the two scripts' payload-field reads.
+
+## Rollback
+- Revert the installCodexHooks Stop/PreToolUse arrays, the canary edits, and the
+  deferral-detector generator edit. No data migration, no config change.
+
+## Tests
+- `installCodexHooks.test.ts`: trio assertion updated to claim-intercept-response; +1 test
+  that deferral-detector is on PreToolUse and NOT Stop. 9 green.
+- `codexHookContractCanary.test.ts`: invariant assertions updated (+ deferralOnPreToolUse). 6 green.
+- `deferral-detector-orphan-todo.test.ts`: +2 Codex `exec_command`/`cmd` cases (fires on
+  orphan-TODO; ignores clean). 16 green. tsc clean.
+- Live test-as-self: batched with the rest of the build before merge.
+
+## Publish
+- Feature branch `echo/codex-parity-audit` (rebased onto JKHeadley/main before PR). Patch release.