instar 1.3.0 → 1.3.2

package/upgrades/side-effects/fix-codex-intel-clean-call.md

@@ -0,0 +1,108 @@
+# Side-Effects Review — Codex Intelligence-Provider Clean-Call Fix
+
+**Version / slug:** `fix-codex-intel-clean-call`
+**Date:** 2026-05-26
+**Author:** Echo
+**Spec:** `docs/specs/CODEX-INTELLIGENCE-PROVIDER-CLEAN-CALL-SPEC.md` (converged + approved)
+
+## Summary of the change
+
+`CodexCliIntelligenceProvider.evaluate()` ran `codex exec --cd <agent project dir>` for
+every internal LLM "judgment" call (message classification, terminal-output analysis,
+arc extraction, usher, coherence, etc.). Running in the project dir made Codex load the
+full ~26 KB `AGENTS.md` identity AND fire the project's `.codex/hooks.json`
+(session_start / user_prompt_submit / stop) on **every** call — ~1,550 such calls/day,
+causing notification spam (session_start firing constantly) and spawn-storm delivery
+failures (12 heavyweight spawns/minute saturating the machine).
+
+The fix runs these calls in an empty, owner-only scratch dir instead — the Codex analog
+of `ClaudeCliIntelligenceProvider`'s `--setting-sources user`. No identity, no project
+hooks.
+
+**Files changed (source):**
+- `src/core/CodexCliIntelligenceProvider.ts` — `evaluate()` now uses an `mkdtempSync`
+  scratch dir for `--cd` (not the project dir) + `-c project_doc_max_bytes=0`; added the
+  `resolveIntelligenceScratchDir()` helper; removed the now-dead `workingDirectory` field
+  (kept on the options type for API compat).
+
+**Files changed (tests):**
+- `tests/unit/CodexCliIntelligenceProvider.test.ts` — updated the `--cd` assertion (it
+  previously asserted the buggy project-dir behavior) + added 7 cases covering the
+  scratch-dir contract, 0700 perms, unguessable name, and tmp-reaper recovery (12 total).
+
+**Files changed (spec / report / release notes):**
+- `docs/specs/CODEX-INTELLIGENCE-PROVIDER-CLEAN-CALL-SPEC.md` (+ `.eli16.md`)
+- `docs/specs/reports/codex-intelligence-provider-clean-call-convergence.md`
+- `upgrades/NEXT.md`
+
+## Decision-point inventory
+
+- **Scratch dir, not the project dir** — the core fix. Judgment calls are cwd-independent
+  (per the existing code comment), so an empty cwd is correct.
+- **`mkdtempSync` (random suffix, 0700), not a fixed name** — convergence security finding:
+  a fixed `/tmp` name on Linux is plantable (`.codex/hooks.json` squatting; not gated by
+  `project_doc_max_bytes`). The unguessable, owner-only dir closes that vector.
+- **Re-verify-before-use** — recreate the dir if a tmp-reaper deleted it during a
+  long-lived process.
+- **`-c project_doc_max_bytes=0`** — belt-and-suspenders for an `AGENTS.md` on the cwd
+  walk-up; real key, already used in `contextScopeControl.ts`.
+- **Drop `workingDirectory` as exec cwd** — verified only `route.ts` passes it, and only
+  for its own PreferenceStore DB path, never the codex cwd.
+
+## Over-block / under-block analysis
+
+- **Over-block:** none. The provider gates nothing; it only changes the cwd of a spawn.
+  Judgment calls that worked before continue to work (the fake-codex unit tests confirm
+  the full arg contract).
+- **Under-block:** the *intended* behavioral subtraction is "stop loading identity + firing
+  hooks for judgment calls." There is no path where a judgment call legitimately needed the
+  identity or hooks — they are stateless classifications/extractions. If a future caller
+  did need project context, it must pass it in the prompt (as all current callers do), not
+  rely on cwd.
+
+## Level-of-abstraction fit
+
+The fix lives in the single provider that owns the `codex exec` invocation — the same layer
+where the Claude sibling already solves the identical problem with `--setting-sources user`.
+No higher-level orchestration or config knob is introduced; the concern is local to the
+spawn, so the fix is local to the spawn. Correct altitude.
+
+## Signal-vs-authority compliance
+
+N/A in the gate sense — this change neither detects nor blocks anything. It is a pure
+invocation-hygiene fix. It does not touch any sentinel/gate authority boundary.
+
+## Interactions
+
+- **Claude provider:** untouched; asymmetry (flag vs scratch-cwd) is intentional and
+  documented — Codex has no single equivalent flag.
+- **Callers (`reflect.ts`, `route.ts`, `server.ts`):** none depend on the codex cwd
+  content; verified during integration review. No behavior change for them beyond the
+  intended one.
+- **Concurrency:** `mkdtempSync` once + cached + `existsSync` re-check; no race under the
+  high call volume (idempotent, read-only dir).
+- **Monitoring layer:** positive interaction — the session_start hook no longer fires on
+  judgment spawns, so PresenceProxy/standby stops mistaking them for real sessions
+  (the notification-spam root cause).
+
+## Rollback cost
+
+Trivial and isolated. Revert the single source file (and its test). No persisted state, no
+schema, no config/hook/template/migration to unwind — the only on-disk footprint is an
+empty 0700 tmp dir that the OS reaps on its own. Reverting restores the prior (buggy but
+functional) behavior with zero data implications.
+
+## Migration parity
+
+Code-only change inside the compiled provider. No agent-installed file
+(settings/hooks/config/templates/skills) references the old behavior, so **no
+`PostUpdateMigrator` entry is required** — existing Codex agents receive the fix via the
+normal package update path. Verified by grep during integration review.
+
+## Testing evidence
+
+- Unit: 12 tests in `CodexCliIntelligenceProvider.test.ts` pass; sibling env-allowlist (4)
+  + factory (10) tests unaffected; clean `tsc` build.
+- Live / bug-fix evidence bar: the before/after rollout reproduction on a real Codex agent
+  (identity-loaded before, bare after) is run as the post-merge test-as-self gate and
+  recorded before the fix is declared shipped.

package/upgrades/side-effects/threadline-open-this-deterministic.md

@@ -0,0 +1,45 @@
+# Side-Effects Review — Deterministic "open this" (CMT-529)
+
+**Version / slug:** `threadline-open-this-deterministic`
+**Date:** 2026-05-26
+**Author:** Echo
+**Second-pass reviewer:** (pending — required; message-routing intercept)
+
+## Summary of the change
+
+Makes "open this" / "tie this to <topic>" in the Threadline hub topic a DETERMINISTIC structural intercept instead of agent-interpreted (which failed — the agent rambled instead of binding). New `src/threadline/hubCommands.ts`: `parseHubCommand` (pure, tightly-anchored) + `bindHubConversation` (shared logic extracted from the route; discriminated result; readable+scrubbed topic name; `autoPick`). The intercept lands in `telegram.onTopicMessage` (`wireTelegramRouting`, src/commands/server.ts) — the convergence point BOTH inbound paths reach — via a late-bound `getHubDeps()` accessor (deps constructed after wiring). `POST /threadline/hub/bind` refactored to call the same helper (autoPick=false → 409 preserved for the API). `CollaborationSurfacer.load()` legacy migration now stamps `surfacedAt` by index (was epoch) so ordering works. Decision point: the hub-command intercept (routing, not block/allow).
+
+## Decision-point inventory
+
+- `telegram.onTopicMessage` hub-command intercept — **add** — for the hub topic + a matched command, bind structurally + return before session injection.
+- `POST /threadline/hub/bind` — **modify** (refactor to shared helper; behavior unchanged for the API).
+- `CollaborationSurfacer.load()` legacy `surfacedAt` — **modify** — index-based ordering.
+
+## 1. Over-block
+No block/allow surface. The intercept only fires when `topicId === hub` AND `parseHubCommand` matches a tightly-anchored command (`/^open(?:\s+this)?\s*[.!]?$/i`, `/^(?:tie|bind)\s+this\s+to\s+.../i`). Ordinary hub chat ("can you open this and explain?") returns null → falls through to the agent. FAIL-OPEN: any intercept error logs + falls through.
+
+## 2. Under-block
+A creatively-phrased command ("open it please") won't match → falls through to the agent (who still has the #392 CLAUDE.md guidance as backstop). Acceptable; common forms covered.
+
+## 3. Level-of-abstraction fit
+Correct: the intercept sits at `onTopicMessage` alongside the existing `/new`/slash/fix-command interceptions — the single seam both the lifeline-forward and server-polling paths converge on (avoids the dual-path dead-code trap that bit the sentinel + warrants-reply gate). `bindHubConversation` composes existing primitives (ConversationStore.mutate, findOrCreateForumTopic, CommitmentTracker.mutate, surfacer.markBound/noteInHub) — no re-implementation.
+
+## 4. Signal vs authority compliance
+No new blocking authority. The intercept is a deterministic router (match → bind → return), the bind is an authoritative state mutation on explicit operator action, parseHubCommand is a pure classifier. Per `docs/signal-vs-authority.md`: routers/sinks, not gates.
+
+## 5. Interactions
+- **No double-bind/post:** `bindHubConversation` posts to the new topic + one `noteInHub`; the intercept does NOT add a third message (reuses the helper's confirmation), and `return`s so no session injection. One bind per command (markBound makes a re-issued "open this" pick the next unbound).
+- **Order vs other intercepts:** sits after `/new` + slash + (and, on the forward path, the sentinel) — emergency-stop still wins. No shadowing.
+- **autoPick split:** intercept (human) autoPick=true → most-recent; API path autoPick=false → 409. Distinct, intentional.
+
+## 6. External surfaces
+New `getHubDeps` param on `wireTelegramRouting` (internal). Hub stays silent. Topic name from gist is **capped ~40 chars, charset-scrubbed, and falls back to `<peer> · <threadId8>` on empty/credential-like gist** (a cold first message could contain a secret — never splash it into a chat-list-visible title). Template + `migrateClaudeMd` note that "open this" is now structural (Agent Awareness + Migration Parity).
+
+## 7. Rollback cost
+Localized: new hubCommands module, one route refactor, one intercept block + a param threaded to two call sites, one load() timestamp line, the naming helper. Clean `git revert`. The legacy `surfacedAt` change is read-time + idempotent (no data migration). `getHubDeps` is an optional param (older callers unaffected).
+
+## Second-pass review
+
+**Concur with the review** (independent reviewer, 2026-05-26). All seven checks verified against the diff: (1) `getHubDeps` late-bind is TDZ/null-safe — the closure only runs at message-time, long after the `const` deps initialize; the `&& telegram` guard narrows `TelegramAdapter|undefined`; `commitmentTracker` is unconditionally constructed + null-guarded internally; tsc clean. (2) Intercept gates on `getHubTopicId()` match, falls through otherwise, whole block try/catch fail-open. (3) `parseHubCommand` anchoring verified empirically across 15 inputs — "open this"/"open"/"Open This." fire; "can you open this and explain?" / "open this conversation please" fall through. (4) `bindHubConversation` returns a discriminated result, never touches res/req; route maps 400/404/409/500. (5) Early `return` skips no essential side-effect — consistent with the adjacent `/`/`/new` intercepts (no message logging in this handler). (6) `topicNameFor` caps 40 / scrubs / credential-fallback. (7) The CMT-529 migrator re-patch is idempotent + correctly scoped (matches only OLD CMT-519 agents; non-greedy anchored regex; 2nd run no-op).
+
+Non-blocking notes (no action needed): an 18-digit "tie this to <huge number>" would be treated as a name not an id (unrealistic, harmless); legacy `surfacedAt=new Date(index+1)` ISO strings stay lexicographically monotonic well past realistic array sizes.