instar 1.2.56 → 1.2.58

package/upgrades/1.2.58.md

@@ -0,0 +1,77 @@
+# Instar Upgrade Guide — vNEXT (Codex agents can reply over Threadline)
+
+<!-- bump: patch -->
+
+## What Changed
+
+Codex-framework instar agents couldn't *reply* to Threadline messages — they
+received fine, but every reply silently failed. Two framework-integration bugs,
+both fixed.
+
+### Fix A — reply workers can now use MCP tools (targeted)
+
+When a Threadline message arrives, instar spawns a one-shot worker prompted to
+reply via the `threadline_send` MCP tool. For Codex, instar launched that worker
+under `-s workspace-write`, where `codex exec` defaults its approval policy to
+`never` — and `never` *cancels* MCP tool calls (`"user cancelled MCP tool
+call"`) AND the sandbox blocks the MCP server's localhost transport. So the
+worker called the tool correctly and the call was killed every time.
+
+Verified on codex 0.133 that there is **no** sandboxed mode that permits the MCP
+call — only `--dangerously-bypass-approvals-and-sandbox` works. So the headless
+launch now selects in tiers: explicit sandbox mode → that mode; Threadline
+**reply** workers (`codexAllowMcpTools`) → full bypass (the only mode that lets
+them send); everything else, including scheduled **jobs** → `-s workspace-write`
+unchanged. Jobs stay sandboxed; only reply workers take the bypass.
+
+### Fix B — each agent uses its own threadline MCP (no shared-config collision)
+
+Every Codex agent registered `[mcp_servers."threadline"]` into the SHARED
+`~/.codex/config.toml` with its own identity baked in — last-writer-wins, so on a
+machine with several Codex agents, all but the last-booted one would reply using
+the WRONG agent's threadline identity. New single-source-of-truth resolver
+(`src/threadline/mcpEntry.ts`) + a per-spawn `-c mcp_servers.threadline.*`
+override pin each agent's codex session to ITS OWN threadline MCP, regardless of
+the shared file. Both reply paths (full-session and the lightweight "pipe" path)
+are wired.
+
+## What to Tell Your User
+
+If you run a Codex-based agent, it can now actually answer messages other agents
+send it over Threadline — before, it could hear but not reply. And on a machine
+running several Codex agents, each now replies as itself instead of accidentally
+borrowing whichever agent started last. Scheduled background jobs stay sandboxed
+as before; only the reply step runs with the access it needs to send. No action
+needed.
+
+## Summary of New Capabilities
+
+- **Codex agents reply over Threadline** — reply workers launch in the one mode
+  that permits the `threadline_send` MCP call; scheduled jobs stay sandboxed.
+- **Per-agent codex threadline MCP** — a per-spawn `-c` override + shared
+  resolver (`resolveThreadlineMcpEntry`) end the shared `~/.codex/config.toml`
+  last-writer-wins collision; both reply paths covered.
+
+## Evidence
+
+- **Reproduced + fixed (mechanism):** a `codex exec --dangerously-bypass-
+  approvals-and-sandbox` run completed a real `threadline_send` call
+  (codey→echo, reply received); under `-s workspace-write`/`--full-auto` the same
+  call was cancelled / the tool was unavailable. The collision was observed live
+  (shared config pointed at `inspec` while `instar-codey` was running).
+- **Unit:** `frameworkSessionLaunch.test.ts` (workspace-write job default;
+  `codexAllowMcpTools`→bypass; explicit sandbox wins; `-c` override emission +
+  JSON validity), `threadline-mcp-entry.test.ts` (resolver). 75-test sweep green.
+- **Convergence:** two-reviewer pass (correctness + adversarial) →
+  docs/specs/reports/codex-multiagent-threadline-convergence.md. The adversarial
+  reviewer caught the job-sandbox regression and the second reply path; both
+  resolved before merge.
+- Full deployed round-trip with a Codex agent is the post-merge Tier-3 check.
+
+## Rollback
+
+Code-only, no migration or state changes. Revert
+`src/core/frameworkSessionLaunch.ts`, `src/threadline/mcpEntry.ts`, the
+`ThreadlineBootstrap` refactor, and the `server.ts`/`SessionManager`/`types.ts`/
+`PipeSessionSpawner` wiring. The shared-config registration is untouched, so a
+revert cannot strand `~/.codex` or `.instar` state.

package/upgrades/side-effects/codex-multiagent-threadline.md

@@ -0,0 +1,69 @@
+# Side-Effects Review — Codex Multi-Agent Threadline Robustness
+
+Spec: docs/specs/CODEX-MULTIAGENT-THREADLINE-SPEC.md (approved, converged)
+Change: let Codex-framework agents reply to Threadline messages — (A) targeted
+MCP-permitting launch for reply workers, (B) per-agent threadline MCP override,
+(C) wire both reply paths.
+
+## 1. Over-block — what legitimate inputs does this reject that it shouldn't?
+
+None new. The launch-profile selector is additive: jobs keep `-s
+workspace-write` (unchanged); reply workers add bypass; explicit
+`codexSandboxMode` still wins. The `-c` MCP override only ever points codex at
+THIS agent's own threadline entry — it cannot reject anything.
+
+## 2. Under-block — what failure modes does this still miss?
+
+- Codex agents without threadline configured: no override emitted (correct — no
+  threadline to reply through). Not a miss.
+- The reply worker still depends on the deployed relay / local delivery being
+  reachable — out of scope here (transport already works).
+- A future THIRD reply path that calls `buildHeadlessLaunch` directly would need
+  the same two flags. Mitigated by routing all reply spawns through the two
+  known paths; documented in the spec.
+
+## 3. Level-of-abstraction fit
+
+Correct layer. The launch-profile + MCP-override are properties of HOW a codex
+session is launched → they belong in `frameworkSessionLaunch` (the builder) with
+the data computed once at boot in `server.ts`. The single-source-of-truth
+resolver (`mcpEntry.ts`) is shared with `ThreadlineBootstrap` so registration and
+per-spawn override cannot drift.
+
+## 4. Signal vs authority compliance
+
+Compliant. No blocking authority added. The selectors (`codexAllowMcpTools`,
+`codexThreadlineMcp`, `config.threadline`-present) are capability/launch choices,
+not gates that block information flow. See docs/signal-vs-authority.md.
+
+## 5. Interactions
+
+- Fix A ↔ Fix B: independent (sandbox profile vs MCP entry); both emitted in the
+  same codex argv, no conflict.
+- Fix B ↔ existing shared-config registration: intentional — `-c` wins per spawn;
+  the shared `~/.codex/config.toml` entry stays (Claude parity / discovery) but
+  is non-authoritative for codex spawns. No double-fire (one MCP server named
+  "threadline" results).
+- Jobs/dispatch (routes.ts generic spawn, JobScheduler): do NOT set
+  `codexAllowMcpTools` → unchanged (`workspace-write`). No shadowing.
+- ThreadlineBootstrap refactor is behavior-preserving (`resolveThreadlineMcpEntry`
+  returns the identical `{command,args}`; `absDir` still declared for downstream
+  ~/.claude.json registration).
+
+## 6. External surfaces
+
+- Other agents: a codex agent can now actually reply over Threadline — net new
+  outbound it previously couldn't send. Bounded by the trust gate (replies only
+  to trusted peers, who already messaged it).
+- Security posture: codex reply workers run unsandboxed (full bypass) — the only
+  mode that permits the MCP call (verified, finding 2). Scheduled jobs remain
+  sandboxed. Operator signed off (topic 12304).
+- Timing/runtime: none introduced; the override is computed once at boot.
+
+## 7. Rollback cost
+
+Code-only, no migration/state. Revert `frameworkSessionLaunch.ts`, `mcpEntry.ts`,
+`ThreadlineBootstrap` refactor, `server.ts`/`SessionManager`/`types.ts`/
+`PipeSessionSpawner` wiring. The shared-config registration is untouched, so a
+revert cannot strand `~/.codex` or `.instar` state. Existing agents pick up the
+launch fix on normal update (no config rewrite).

package/upgrades/side-effects/goal-completion-evaluator.md

@@ -0,0 +1,69 @@
+# Side-Effects Review — autonomous completion evaluator (independent /goal-style judge)
+
+**Version / slug:** `goal-completion-evaluator`
+**Date:** 2026-05-24
+**Author:** echo
+**Second-pass reviewer:** internal conformance pass
+
+## Summary of the change
+
+Replaces the autonomous stop-hook's self-declared `<promise>` completion check (agent grades
+itself) with an **independent** judgment: when a verifiable `completion_condition` is set, a
+small/fast model judges each turn whether it's met against what the agent surfaced (same
+contract as the framework `/goal`). Phase 1 of `docs/specs/goal-completion-evaluator.md`. The
+self-declared promise remains as a legacy fallback. `src/` touched: `CompletionEvaluator.ts`
+(new), `routes.ts` (+RouteContext field + `/autonomous/evaluate-completion`), `AgentServer.ts`
+(thread-through), `commands/server.ts` (construct from sharedIntelligence), `CapabilityIndex.ts`
+(endpoint), `PostUpdateMigrator.ts` (marker bump). Non-src: the hook, setup script, SKILL.md, tests.
+
+## Decision-point inventory
+
+- `CompletionEvaluator.evaluate` — **add**: the loop's continue/stop authority. Judges
+  condition vs transcript; returns met/reason. The one new decision point.
+- `autonomous-stop-hook.sh` — **modify**: when a condition is set, ask the evaluator instead of
+  trusting the promise; promise path demoted to fallback; fail-safe on unreachable.
+- `setup-autonomous.sh` — **modify**: `--completion-condition` flag + state field. (`.claude/`.)
+- `POST /autonomous/evaluate-completion` — **add**: thin route over CompletionEvaluator.
+- `PostUpdateMigrator` marker — **modify**: bumped so prior installs upgrade.
+
+## 1. Over-block (trapping a session that should exit)
+- The evaluator returns met:true only on an explicit MET verdict; on met:true the run exits.
+  Over-block would mean never confirming a truly-met condition. Mitigated by a well-formed
+  condition + the reason-feedback loop. Same risk class `/goal` accepts.
+
+## 2. Under-block (false "done" / premature exit) — the critical direction
+- The evaluator **fails safe to met:false** on empty/ambiguous/error/unreachable — it can never
+  emit a false "done" from a failure. Tested (unit: empty/ambiguous/throw; hook: unreachable →
+  keep working). Server-down does NOT premature-exit. This is the strongest safety property.
+
+## 3. Level-of-abstraction fit
+- Correct. CompletionEvaluator mirrors existing IntelligenceProvider-backed evaluators
+  (DiscoveryEvaluator, CoherenceReviewer); reuses sharedIntelligence + LlmQueue spend cap.
+
+## 4. Blocking authority
+- [x] The evaluator IS the autonomous loop's continue/stop authority — appropriate, because it
+  is a **full-context model judgment** (condition + transcript), exactly like `/goal`, not a
+  brittle low-context filter. It only gates the autonomous loop, nothing else.
+
+## 5. Interactions
+- **Legacy promise:** preserved as fallback; runs with no condition behave exactly as before.
+- **Multi-session:** per-topic; the evaluator reads/clears the same per-topic state file.
+- **Cost:** one small/fast call per turn (matches `/goal`) — bounded by the LlmQueue daily cap.
+- **Restart/recovery/duration/emergency-stop:** unchanged; the condition check sits in the
+  terminal-checks block alongside them.
+
+## 6. External surfaces
+- **HTTP:** one new authed route `POST /autonomous/evaluate-completion` (under the already-claimed
+  `/autonomous` capability prefix). The hook calls it best-effort (port+auth from config); failure
+  is swallowed → keep working.
+- **LLM:** one small/fast `IntelligenceProvider.evaluate` per turn, attributed `CompletionEvaluator`,
+  spend-capped. No new external credential.
+
+## 7. Rollback cost
+- Low. Reverting restores the promise-only path; the migration marker is content-sniffed (a
+  rollback re-ships the prior hook, which lacks the new marker, and re-deploys cleanly). A
+  `completion_condition` left in a state file is simply ignored by an older hook.
+
+## 8. Test evidence
+- 7 unit (CompletionEvaluator incl. fail-safe), 8 integration (incl. 3 evaluate-completion route),
+  4 hook behavioral (met/not-met/unreachable-fail-safe/legacy). tsc clean; 61 affected tests green.