instar 1.3.121 → 1.3.123

package/upgrades/1.3.123.md

@@ -0,0 +1,105 @@
+# Instar Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Codex usage is now readable over HTTP — the codex `/status` rate-limit
+windows, without the interactive TUI.** Codex has no public usage API, but the
+codex CLI persists the authoritative account rate-limit windows it gets back
+from OpenAI — primary (5h rolling) and secondary (weekly) — into each session
+rollout's `token_count` events. A new reader
+(`readLatestCodexUsage`) finds the newest rollout, reads only its tail (the
+windows are appended per-turn, so the freshest is near the end), and returns a
+structured snapshot. A new read-only route, `GET /codex/usage`, surfaces it:
+
+```
+{ "available": true,
+  "usage": {
+    "primary":   { "usedPercent": 13, "remainingPercent": 87, "windowMinutes": 300,   "resetsAtIso": "…", "resetsInSeconds": … },
+    "secondary": { "usedPercent": 93, "remainingPercent": 7,  "windowMinutes": 10080, "resetsAtIso": "…", "resetsInSeconds": … },
+    "model": "gpt-5.5", "planType": "plus", "rateLimitReachedType": null } }
+```
+
+`available:false` (still HTTP 200, never 503 — it is a disk reader) means there
+is simply no codex session data on disk yet (e.g. a pure-Claude agent). This is
+the data an agent needs to answer "how much codex usage is left?" and to drive a
+model-swap when a window is exhausted (`rateLimitReachedType` non-null, or
+`secondary.remainingPercent` low).
+
+The route is classified in the capability index (discoverable via
+`GET /capabilities`), surfaced in the CLAUDE.md template for new agents, and
+back-filled into existing agents' CLAUDE.md by the migrator (so deployed agents
+learn it on update). Also restores the feature-delivery-completeness test to
+green by tracking two prior dark/operational migrator sections
+(`Autonomous-fix loop`, `Multi-Machine Session Pool`) that had not been
+registered.
+
+**Codex agents can auto-swap to a fallback model when their weekly window is
+exhausted (ships DARK).** Building on the usage reader above: at codex session
+launch, if the main model's weekly window is spent (or codex flags a limit hit),
+the next session launches on a configured fallback model that draws on a separate
+quota bucket — instead of stalling. The decision is a pure policy
+(`resolveCodexLaunchModel`) wired into both codex launch paths in
+`SessionManager` (headless + interactive). Gated behind
+`codex.rateLimitModelSwap.{enabled,fallbackModel,weeklyRemainingThreshold}`;
+off by default with zero spawn-path overhead. The fallback model id is operator
+config — never hardcoded — because the exact id and its subscription
+availability are the account owner's to confirm.
+
+## Summary of New Capabilities
+
+- `GET /codex/usage` — the freshest codex account rate-limit snapshot (primary
+  5h + secondary weekly windows, with used/remaining percent, window length,
+  absolute + relative reset, plan type, and which window — if any — is
+  exhausted). Read-only; never mutates session state.
+- An optional `?codexHome=` query parameter targets a specific `$CODEX_HOME`
+  (defaults to `~/.codex`).
+- Agent-awareness: the capability appears in `GET /capabilities`, the CLAUDE.md
+  template, and is migrated into existing agents.
+- Codex rate-limit model-swap (dark): `codex.rateLimitModelSwap` —
+  auto-launch the next codex session on `fallbackModel` when the weekly window's
+  remaining percent is at or below `weeklyRemainingThreshold` (default 10) or
+  codex reports a limit hit. Off by default; best-effort and fail-safe (a usage
+  read never blocks a launch).
+
+## What to Tell Your User
+
+You can now ask me how much codex usage is left and I can answer directly,
+without opening the codex status screen myself — I read the same five-hour and
+weekly limit windows the codex tool reports. I can tell you the percent used and
+remaining on each window, when each one resets, which model is in effect, and
+whether either window is currently maxed out. This also gives me the signal I
+need to switch models before the weekly limit runs out. Nothing changes for you
+on update; the capability is simply there when you need it.
+
+And if you want it, I can now do that switch automatically: when a codex agent's
+weekly model quota is nearly spent, the next session it starts can launch on a
+backup model that has its own separate budget, so it keeps working instead of
+stalling. This is off until you turn it on and tell me which backup model to use
+— the exact name and whether it works on your subscription is something only you
+can confirm — so nothing changes by default.
+
+## Evidence
+
+**Source of truth.** Inspected a live codex rollout
+(`~/.codex/sessions/2026/05/30/rollout-…jsonl`) and confirmed each
+`token_count` event carries `payload.rate_limits` with `primary`
+(window_minutes 300) and `secondary` (window_minutes 10080) sub-objects, each
+with `used_percent` and `resets_at`, plus `plan_type` and
+`rate_limit_reached_type`. The observed `secondary.used_percent` of 93 (i.e. 7%
+weekly remaining) matched the codex `/status` screen at the same moment —
+verifying the on-disk windows equal the TUI's.
+
+**Before:** there was no way for an agent to read codex usage programmatically —
+the only surface was the interactive TUI (`UsageMeterProvider.isAuthoritative()`
+returns false and only does local token accounting), so an agent could not
+answer "where does codex usage sit?" or react to an exhausted window.
+
+**After:** `GET /codex/usage` returns the structured snapshot above. Verified by
+a 3-tier test suite (16 tests, all green): unit tests parse the latest
+`token_count` (newest event wins; malformed lines skipped; missing-window
+tolerated; reached-type surfaced), an integration test drives the route over
+HTTP against a rollout fixture (data → `available:true`; none → `available:false`
++ 200), and a Tier-3 lifecycle test boots the real AgentServer and confirms the
+route is alive (200, Bearer-gated, read-only POST→404).

package/upgrades/side-effects/codex-exec-json-silence-signal.md

@@ -0,0 +1,64 @@
+# Side-Effects Review — silence sentinel recognizes codex exec --json sessions
+
+**Version / slug:** `codex-exec-json-silence-signal`
+**Date:** `2026-05-30`
+**Author:** `instar-echo`
+**Second-pass reviewer:** `instar-echo second-pass checklist`
+
+## Summary of the change
+
+The ActiveWorkSilenceSentinel only watches sessions that `looksActivelyWorking`;
+an idle frame is marked `paused` and skipped. The codex activity signatures in
+`frameworkActivitySignals.ts` matched only the interactive TUI. Codex job and
+autonomous-spawn sessions run `codex exec --json`, which emits a JSON event
+stream (`{"type":"thread.started"}`, `{"type":"turn.started"}`,
+`{"type":"item.completed"}`, ...) that matched nothing — so a working exec-json
+session read as not-active, was marked paused, and the silence watchdog never
+considered it. A wedged exec-json job (frozen mid-turn ~8.5h, 2026-05-30) was
+invisible.
+
+The change adds the event-stream namespaces to
+`CODEX_CLI_SIGNAL.toolCallOrSpinner` (`"type":"thread."`/`"turn."`/`"item."`),
+keeping every existing TUI pattern. A working exec-json session is now active and
+silence-eligible; when it freezes the sentinel detects the output gap.
+
+## Decision-point inventory
+
+- `CODEX_CLI_SIGNAL.toolCallOrSpinner` — modify — extends the "is codex actively
+  working" signature to cover the exec-json event stream, not just the TUI.
+
+---
+
+## 1. Over-block
+
+"Over-block" here would mean flagging a session as frozen when it is fine. The
+change cannot cause that: it only makes a session ELIGIBLE for silence checking
+(by counting it as active). The actual freeze decision is still the
+output-silence threshold plus the tracker's observed-change requirement — both
+unchanged. A live, still-streaming exec-json session keeps advancing
+`lastChangeAt` and is never flagged.
+
+## 2. Under-block
+
+A truly-idle exec-json pane that happens to contain a stale event marker could
+read as active. This does not cause a false alarm (the tracker requires an
+observed active→silent transition; a pane frozen before first sighting stays
+`lastOutputAt: 0` and is skipped). The critical 2026-05-23 guard — never match
+the idle model-name status line — is preserved and explicitly tested.
+
+## 3. Level-of-abstraction fit
+
+The codex event-stream signature belongs in `frameworkActivitySignals.ts`, the
+single module that owns per-framework activity patterns. The framework-agnostic
+detection in `sentinelWiring`/`ActiveWorkSilenceSentinel` is untouched — only the
+codex signature it consumes is extended, so every framework's detection path
+stays uniform.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] This is a detector signature, not authority. It feeds the existing silence
+  detector; it issues no kill and no block. Its only effect is to let the
+  detector SEE codex exec-json sessions it was previously blind to. The
+  downstream nudge/escalation policy is unchanged and already tone-gated.

package/upgrades/side-effects/codex-model-swap.md

@@ -0,0 +1,134 @@
+# Side-Effects Review — Codex rate-limit model-swap (directive #4b)
+
+**Version / slug:** `codex-model-swap`
+**Date:** 2026-05-30
+**Author:** Echo (instar-dev agent)
+**Second-pass reviewer:** REQUIRED (touches session spawn / lifecycle) — see verdict at end
+
+## Summary of the change
+
+At codex session launch, if the agent's main model has exhausted its weekly
+window, launch the next session on a configured fallback model (separate quota
+bucket) instead of stalling. New pure policy
+(`src/providers/adapters/openai-codex/observability/codexModelSwapPolicy.ts`) +
+a private `SessionManager.resolveCodexLaunchModel` helper wired into BOTH codex
+launch paths (`spawnSession`→`buildHeadlessLaunch`,
+`spawnInteractiveSession`→`buildInteractiveLaunch`). Consumes the on-disk
+`readLatestCodexUsage` reader (shipped in CODEX-USAGE-VISIBILITY). Ships DARK
+behind `config.codex.rateLimitModelSwap.{enabled,fallbackModel,weeklyRemainingThreshold}`.
+
+## Decision-point inventory
+
+- `SessionManager.resolveCodexLaunchModel` (NEW decision) — picks the launch
+  model for a codex spawn. Add. It is a model SELECTION, not a block/allow gate:
+  the only outcomes are "requested model" or "configured fallback model". Both
+  spawn paths consume it (pass-through for non-codex / disabled).
+
+---
+
+## 1. Over-block
+
+**No block/allow surface — over-block not applicable.** The policy never rejects
+or cancels a launch. Its worst "wrong" outcome is launching on the fallback
+model when it didn't strictly need to (e.g. weekly at exactly the threshold) —
+which still produces a working session, just on the other quota bucket.
+
+## 2. Under-block
+
+**Not a blocker.** The closest "miss": the swap only takes effect at the NEXT
+launch — a session already mid-turn on an exhausted model still fails that turn
+(it can't change model mid-flight). That is inherent to how model selection
+works and is the correct scope; the RateLimitSentinel covers the in-flight
+throttle messaging separately. Also: if usage can't be read, no swap happens
+(fail-safe) — a genuinely-exhausted agent with an unreadable rollout would not
+swap. Acceptable: it degrades to today's behavior (launch on the main model).
+
+## 3. Level-of-abstraction fit
+
+Right layer. The decision lives in the openai-codex observability namespace
+(beside the reader it consumes) as a pure function; the WIRING lives in
+SessionManager at the single point where the launch model is finalized for each
+spawn path. It does not belong in the reader (that's a pure read surface) nor in
+a separate poller (a poller would have to persist an override and re-apply it —
+more state, more drift; deciding at launch is stateless and exact).
+
+## 4. Signal vs authority compliance
+
+**Compliant.** Pure signal-driven decision, zero blocking authority (ref
+`docs/signal-vs-authority.md`). It consumes the authoritative usage signal and
+selects a model. No brittle gate, no veto. Fails safe (read failure → requested
+model). The signal producer (the reader) and this consumer are cleanly split.
+
+## 5. Interactions
+
+- **Shadowing / double-fire:** none. It's the only thing that selects the codex
+  launch model; it runs once per spawn. The two call sites are mutually
+  exclusive (headless vs interactive spawn of a given session).
+- **RateLimitSentinel:** complementary, not conflicting. The sentinel handles an
+  IN-FLIGHT throttle (backoff + notify + verify recovery); this picks the model
+  for the NEXT launch. They operate at different moments and don't race.
+- **`/local-model` + `frameworkDefaultModels`:** the swap takes `options.model`
+  / `defaultModel` (already resolved from those) as its INPUT and only overrides
+  when armed + exhausted, so an explicit per-call/local model still flows through
+  untouched when the feature is off (default) or the window is healthy.
+- **Shared `~/.codex/config.toml`:** unaffected — the model flows via the launch
+  flag (`-c model=` / `--model`), the per-spawn override that already wins over
+  the shared config (same mechanism as `codexThreadlineMcpFlags`). No multi-agent
+  config collision.
+- **Spawn-path latency:** when DISABLED (default) the fast-path guards return
+  before any disk read — zero added latency. When enabled, the read is the same
+  bounded path the shipped `/codex/usage` route uses: a recursive walk of
+  `$CODEX_HOME/sessions` (`listAllRollouts`, capped to the newest few) plus a
+  tail-read of the newest rollout. All async fs, wrapped best-effort (never
+  throws, never blocks the spawn). Only runs when the feature is armed.
+
+## 6. External surfaces
+
+- **Behavioral, opt-in:** when an operator enables it with a verified
+  `fallbackModel`, a codex session may launch on a different model than the
+  configured default once the weekly window is low. That is the intended,
+  operator-armed behavior. A `[SessionManager]` log line records every swap with
+  the reason.
+- No new HTTP surface, no new message, no change visible to other agents.
+- Off by default → no change for any existing agent on update.
+
+## 7. Rollback cost
+
+Low. Pure additive + dark. Back-out = revert the policy module + the
+SessionManager helper/wiring + tests; no data migration, no agent-state repair.
+In the field, neutralise instantly by not setting (or removing)
+`codex.rateLimitModelSwap.enabled` — no redeploy of code required.
+
+---
+
+## Phase 5 — Second-pass reviewer verdict
+
+**Concur with the review.** An independent reviewer subagent audited this artifact
+AND the actual code (not just the claims), verifying each risk with file:line
+citations:
+
+- **Never blocks/delays/breaks a launch:** the single new
+  `await this.resolveCodexLaunchModel(...)` on each spawn path delegates to
+  `resolveCodexLaunchModelWithUsage`, whose disk read is `try/catch`-wrapped and
+  returns no-swap on any throw (`codexModelSwapPolicy.ts:125-129`); the helper
+  always returns `string | undefined`, never throws (`SessionManager.ts`).
+- **Zero disk I/O when disabled:** the three fast-path guards (non-codex /
+  disabled-or-no-fallback / already-on-fallback) all return BEFORE the
+  `read(...)` call; unit tests assert `read===0` for each.
+- **Disabled/default path is byte-identical:** on every fast-path the helper
+  returns the requested model unchanged, so the builder input is unchanged for
+  non-codex agents and codex agents with no config block.
+- **Swap-decision correctness:** swaps only on the documented conjunction; uses
+  the weekly (`secondary`) window not `primary`; `<=` threshold off-by-one
+  covered both ways; never swaps to an empty model.
+- **Both spawn paths covered**, enforced by source-assertion tests.
+- **No conflict** with RateLimitSentinel (different moment), the shared
+  `~/.codex/config.toml` (per-spawn flag override wins), or `/local-model`
+  (its model is the helper's input, passes through when off).
+
+Reviewer notes addressed: §5's spawn-path-latency wording was corrected to
+acknowledge the `listAllRollouts` directory walk (not just a single tail-read).
+One non-blocking nit noted for a future graduation-out-of-dark: the config is
+read via an inline cast rather than a typed `codex?` field on
+`SessionManagerConfig` — intentional to keep the feature dark without a schema
+change; can be promoted to a typed field if/when it ships on by default.

package/upgrades/side-effects/codex-resume-jsonl-exists.md

@@ -0,0 +1,68 @@
+# Side-Effects Review — jsonlExists resolves codex rollout files
+
+**Version / slug:** `codex-resume-jsonl-exists`
+**Date:** `2026-05-30`
+**Author:** `instar-echo`
+**Second-pass reviewer:** `instar-echo second-pass checklist`
+
+## Summary of the change
+
+`ThreadResumeMap.jsonlExists` and `TopicResumeMap.jsonlExists` decided a saved
+session UUID was missing unless a Claude flat-layout transcript
+(`~/.claude/projects/<encoded>/<uuid>.jsonl`) existed. Codex writes rollout files
+at `$CODEX_HOME/sessions/YYYY/MM/DD/rollout-<ts>-<uuid>.jsonl`, so both
+predicates returned `false` for every codex session — `get()` returned null and
+resume broke fleet-wide for codex agents (~9 consumers).
+
+The change adds `findRolloutFileSync` to the openai-codex `sessionPaths` helper
+(a synchronous sibling of the existing async `findRolloutFile`, since the resume
+guards are synchronous) and makes both `jsonlExists` predicates check the Claude
+layout first (unchanged, early-return on hit) then fall back to the codex layout.
+Returns true if either exists. Reuses the codex session-path seam `TokenLedger`
+already uses.
+
+## Decision-point inventory
+
+- `findRolloutFileSync` — add — sync codex rollout lookup; chooses whether a
+  codex thread has an on-disk rollout.
+- `ThreadResumeMap.jsonlExists` — modify — now resolves codex rollouts in
+  addition to the Claude layout.
+- `TopicResumeMap.jsonlExists` — modify — same codex fallback.
+
+---
+
+## 1. Over-block
+
+A false "missing" would now require BOTH the Claude layout and the codex layout
+to lack the uuid. The change can only make `jsonlExists` return true in MORE
+cases than before (it adds a second place to look, never removes the first), so
+it cannot newly over-block a session that previously resolved. The only residual
+over-block is the pre-existing one: a genuinely-deleted transcript correctly
+reads as missing in both layouts.
+
+## 2. Under-block
+
+The codex fallback could in principle resolve a uuid collision — a rollout file
+whose name contains the uuid substring but belongs to a different session. This
+mirrors the existing async `findRolloutFile` matching (`rollout-*-<uuid>.jsonl`)
+and uuids are effectively unique, so the risk is the same as the established
+codex path. The match also requires the `rollout-` prefix and `.jsonl` suffix, so
+an unrelated file merely containing the uuid is not matched (covered by test).
+
+## 3. Level-of-abstraction fit
+
+The sync lookup lives in the openai-codex `sessionPaths` module, alongside the
+async `findRolloutFile` it mirrors — the one place that owns the codex on-disk
+session layout. The resume predicates consume it rather than reimplementing the
+walk, so the codex layout knowledge stays in exactly one module. No framework
+state is threaded into the predicate; it simply consults both layouts.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No LLM judgment. This is a deterministic filesystem existence check feeding
+  an existing guard. It exercises no new authority — it only makes the existing
+  "does this transcript exist" predicate correct for codex agents. Its single
+  effect is to let a codex session resume that previously could not; it never
+  blocks, kills, or messages.

package/upgrades/side-effects/codex-usage-visibility.md

@@ -0,0 +1,107 @@
+# Side-Effects Review — Codex usage over HTTP (GET /codex/usage)
+
+**Version / slug:** `codex-usage-visibility`
+**Date:** 2026-05-30
+**Author:** Echo (instar-dev agent)
+**Second-pass reviewer:** not required (no block/allow/lifecycle decision surface)
+
+## Summary of the change
+
+Adds a read-only way to see codex account rate-limit usage (the codex `/status`
+windows) without the interactive TUI. A new reader
+(`src/providers/adapters/openai-codex/observability/codexRateLimitReader.ts`)
+finds the newest codex rollout, tail-reads its freshest `token_count`
+`rate_limits`, and returns a structured snapshot. A new route
+(`src/server/routes.ts` → `GET /codex/usage`) surfaces it. Discoverability +
+awareness via `src/server/CapabilityIndex.ts` (capabilities entry),
+`src/scaffold/templates.ts` (new-agent CLAUDE.md section), and
+`src/core/PostUpdateMigrator.ts` (existing-agent back-fill). Also registers two
+prior dark/operational migrator sections in
+`tests/unit/feature-delivery-completeness.test.ts` that were untracked
+(pre-existing red on main). No runtime decision point is touched.
+
+## Decision-point inventory
+
+- No decision point. The reader returns data; the route returns it over HTTP.
+  Nothing is gated, blocked, filtered, or routed based on the result. The route
+  is read-only (GET) and Bearer-gated by the existing auth middleware (not new
+  logic).
+
+---
+
+## 1. Over-block
+
+**No block/allow surface — over-block not applicable.** The route is a read-only
+GET that returns 200 with either the snapshot or `available:false`. It rejects
+nothing.
+
+## 2. Under-block
+
+**No block/allow surface — under-block not applicable.** There is no failure
+mode the change is meant to catch-and-stop; it only reports.
+
+The closest "miss" is data freshness: the snapshot reflects the last
+`token_count` codex wrote, which can lag the true account state by up to one
+codex turn. This is acceptable and documented — it is the same data the `/status`
+screen shows, which is also turn-stamped. Callers that need to react to a hard
+exhaustion should treat `rateLimitReachedType` as the authoritative "we are
+limited now" flag (codex sets it when a window is actually hit).
+
+## 3. Level-of-abstraction fit
+
+Correct layer. It sits in the openai-codex observability namespace alongside
+`sessionPaths`/`usageMeterProvider` (it reuses `listAllRollouts`), and is exposed
+through the same HTTP routes layer as the other read-only observability surfaces
+(`/tokens/*`, `/sessions/reap-log`). It does NOT belong in the
+`UsageMeterProvider` interface, because that interface's `read()` is a generic
+token-accounting contract and this is codex-specific authoritative rate-limit
+data — conflating them would muddy the `isAuthoritative()` semantics (the meter
+is correctly non-authoritative; these windows ARE authoritative). A future
+refactor could expose this through a dedicated authoritative-windows method, but
+the standalone reader is the right minimal surface now.
+
+## 4. Signal vs authority compliance
+
+**Compliant.** This is a pure signal producer with zero blocking authority (ref
+`docs/signal-vs-authority.md`). It reads on-disk data and returns it. The
+model-swap policy that will *consume* this signal is a separate change; keeping
+the reader authority-free is exactly the prescribed split (brittle/cheap signal
+at the edge, decisions made by a downstream consumer).
+
+## 5. Interactions
+
+- **Shadowing:** none. No other route serves `/codex/usage`; no existing reader
+  parses `rate_limits`. It reuses `listAllRollouts` (read-only) but does not
+  change it.
+- **Double-fire / race:** none. Stateless per-request disk read; no writes, no
+  locks, no shared mutable state. Concurrent requests each open + close their own
+  file handles.
+- **Adjacent cleanup:** the codex rollout files it reads are owned/rotated by the
+  codex CLI; this reader never deletes or mutates them, so it cannot race
+  rollout rotation destructively (a rotated-away file just yields the next
+  newest, or `null`).
+- **Capabilities lint:** the new `/codex` prefix is now classified in
+  `CapabilityIndex`, satisfying the capabilities-discoverability lint (verified
+  green).
+
+## 6. External surfaces
+
+- **New HTTP route** visible to any Bearer-authenticated caller: `GET
+  /codex/usage`. It exposes the account's codex rate-limit percentages, reset
+  times, plan type, and active model — the same information the account owner
+  already sees on the codex `/status` screen. No secrets, tokens, or message
+  content are exposed.
+- **CLAUDE.md** gains a "Codex Usage" section for new agents (templates.ts) and
+  existing agents (migrator back-fill, idempotent content-sniff). This changes
+  agent-visible instructions, handled per Migration Parity.
+- **Timing dependence:** only freshness (see §2) — bounded by codex's per-turn
+  write cadence. No dependence on conversation state or uncontrolled runtime
+  conditions.
+
+## 7. Rollback cost
+
+Low. Pure additive feature. Back-out = revert the route + reader + the
+CapabilityIndex/template/migrator/test entries. No data migration, no agent-state
+repair, no release coordination beyond a normal patch. The migrator block is
+idempotent (content-sniffed on `/codex/usage`), so partial application or re-run
+is safe.

package/upgrades/side-effects/ship-gate-sha-mismatch-error.md

@@ -0,0 +1,54 @@
+# Side-Effects Review — ship-gate sha-mismatch error becomes self-service
+
+**Version / slug:** `ship-gate-sha-mismatch-error`
+**Date:** `2026-05-30`
+**Author:** `instar-echo`
+**Second-pass reviewer:** `instar-echo second-pass checklist`
+
+## Summary of the change
+
+`scripts/instar-dev-precommit.js` blocks a commit when the staged side-effects
+artifact's sha256 differs from the sha recorded in the trace. The old message
+("artifact content has changed ... sha mismatch") never printed the correct sha,
+so authors regenerated the artifact — whose volatile `Date:` field changed the
+bytes and thus the sha — and chased the hash forever (a ~2h grind 2026-05-30,
+worst for codex agents). The hook already computes the correct sha to do the
+comparison; it just was not showing it. The change prints the recorded sha
+(truncated), the EXACT computed sha to write, and the freeze/re-stage/no-amend
+recipe. Failure-path text only; pass/fail logic unchanged.
+
+## Decision-point inventory
+
+- sha-mismatch error string in `instar-dev-precommit.js` — modify — turns a dead
+  end into an actionable self-service fix; does not change which commits block.
+
+---
+
+## 1. Over-block
+
+None changed. The gate blocks exactly the same set of commits (a mismatching
+sha). No commit that passed before now fails, and none that failed now passes —
+the comparison is byte-identical. Only the message emitted on an existing block
+changes.
+
+## 2. Under-block
+
+None changed. The change cannot let a genuinely-mismatched artifact through; the
+`continue` on mismatch is unchanged, so a bad bundle still fails to produce a
+valid trace and the commit is still blocked. Printing the computed sha does not
+weaken the check — the author still has to actually set it and re-stage.
+
+## 3. Level-of-abstraction fit
+
+The message lives exactly where the mismatch is detected, in the pre-commit
+validator, beside the sha computation it already performs. No new module, no new
+data flow — the fix uses a value the function already holds.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No LLM, no new authority. This is a developer-experience improvement to an
+  existing deterministic gate's error output. The gate's blocking authority is
+  unchanged; the change only makes its existing refusal explainable and fixable.
+  The printed sha is a checksum of a public review artifact (not sensitive).

package/upgrades/side-effects/threadline-relay-content-dedup.md

@@ -0,0 +1,93 @@
+# Side-Effects Review — Content-hash dedup for the relay-agent ingress
+
+**Version / slug:** `threadline-relay-content-dedup`
+**Date:** `2026-05-30`
+**Author:** `instar-echo`
+**Second-pass reviewer:** `instar-echo second-pass checklist`
+
+## Summary of the change
+
+This change stops duplicate agent-to-agent replies. The handler at
+`POST /messages/relay-agent` accepts an inbound message, then spawns or resumes
+the receiving agent's session before responding. When that spawn is slow (a
+loaded box), the sender times out and retries the same message with a fresh
+`message.id`. The existing dedup in `MessageRouter.relay` keys on `message.id`,
+so the retry slips through and the receiver spawns/replies twice (observed six
+times in one evening, 2026-05-30).
+
+A new module `src/messaging/relayContentDedup.ts` (`RelayContentDedup`) provides
+a bounded, in-memory, fixed-window dedup keyed on the stable triple
+`(senderAgent, threadId, normalized content)`. `src/server/routes.ts` creates
+one instance per server inside `createRoutes` and checks it in the relay-agent
+handler, after envelope validation and before the relay accept. A duplicate
+within the window short-circuits with an idempotent `200`
+(`{ ok: true, deduped: true }`) and no spawn. Tests cover the unit logic (both
+sides of every boundary) and the real HTTP route on a booted `AgentServer`.
+
+This ships the dedup alone. The accept-boundary change (respond on inbox-accept
+rather than after the spawn) is the root fix but touches response semantics and
+the warrants-reply gate in the same handler, so it is a separately-reviewed
+follow-up.
+
+## Decision-point inventory
+
+- `RelayContentDedup` — add — the dedup engine; chooses whether an inbound relay
+  message is a fresh send or a duplicate retry.
+- `relayContentDedup` instance in `createRoutes` — add — per-server-process
+  dedup state, scoped to one server instance for test isolation.
+- relay-agent handler guard — add — runs the dedup check on the ingress path and
+  short-circuits duplicates before the relay accept and the session spawn.
+
+---
+
+## 1. Over-block
+
+The guard drops an inbound only when the exact same sender, thread, and content
+recur within the window (default 60 s). The realistic over-block is a legitimate
+rapid identical resend — an agent sending the same short text (for example a bare
+acknowledgement) twice in the same thread within a minute would have the second
+collapsed. The window is intentionally short and the match is exact, so this is
+narrow; identical back-to-back content on one thread is far more likely a retry
+than two distinct intents.
+
+A subtler case: the guard records a key when it passes the check, before the
+downstream spawn outcome is known. If the first attempt's spawn genuinely failed
+and the sender resent identical content to retry it, that resend would be
+dropped. In practice the retry trigger is a sender timeout while the original
+spawn is still in flight (so the retry is genuinely redundant), not a spawn
+failure — a failed spawn already returns `200` today, so it does not provoke a
+retry. The limitation is documented rather than papered over.
+
+## 2. Under-block
+
+A retry whose content was modified (for example the sender appends text) hashes
+differently and is not collapsed — correct, it is a different message. Messages
+missing a `threadId` or body content are passed through unchanged, because there
+is no stable key for them and they are not part of the observed failure.
+
+The dedup is per-server-process in-memory state. Across a multi-machine failover
+the new holder starts with an empty window, so a duplicate that straddles the
+handoff could slip through. This is acceptable: the durable per-message ledger
+and the `message.id` relay dedup still apply, and the straddle window is seconds
+wide.
+
+## 3. Level-of-abstraction fit
+
+The dedup lives at the relay-agent ingress as a small local module, not inside
+`MessageRouter.relay`. The relay funnel's dedup is the `message.id` identity
+layer with redelivery semantics; the content-hash layer is a distinct identity
+(what the message *is*, not its id) for the specific retry-with-fresh-id failure.
+Keeping it a separate module checked at the route keeps the change local to where
+the failure manifests and leaves the relay funnel's contract unchanged.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No LLM judgment is involved. This is a deterministic mechanical guard — an
+  exact content-hash match within a fixed time window — exercising the same kind
+  of narrow, idempotent authority the existing `message.id` relay dedup already
+  holds. It never interprets meaning; it only recognizes an exact repeat. A
+  false match requires identical sender, thread, and bytes within seconds, and
+  its only effect is to withhold a second spawn (no data is lost; the message is
+  still acknowledged with `200`).