instar 1.3.121 → 1.3.122

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-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/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`).