instar 1.2.57 → 1.2.59

package/upgrades/1.2.59.md

@@ -0,0 +1,67 @@
+# Upgrade Guide — NEXT (autonomous mode delegates to native /goal)
+
+<!-- bump: minor -->
+<!-- minor = new capability, backward compatible -->
+
+## What Changed
+
+**New: where the framework has a native /goal loop, autonomous mode hands the finish-line to it.**
+
+Phase 2 of `docs/specs/goal-completion-evaluator.md`. When an autonomous job is started with a
+completion condition AND the framework provides native /goal (Claude Code >= 2.1.139), instar
+now **injects `/goal <condition>` into the session** — using its core session-input mechanism
+(`SessionManager.sendInput` / tmux send-keys, the same way it injects any message) — and marks
+the job `goal_mode: native`. The framework's own /goal loop (with its own independent evaluator)
+then drives completion, and instar's stop-hook **defers** the continue/stop decision to it
+(approves each turn so native /goal stays in control). Where native /goal is absent, instar's
+own completion evaluator (shipped previously) drives — works everywhere.
+
+instar stays in charge of what native /goal doesn't cover: it still enforces **emergency-stop**
+and **duration expiry** on a native-goal job by injecting `/goal clear` first, then standing the
+job down. Multi-topic orchestration, cap/quota, and messaging remain instar's.
+
+- Endpoints: `POST /autonomous/native-goal/set {topicId, condition}` (inject + mark native),
+  `POST /autonomous/native-goal/clear {topicId}`.
+- `setup-autonomous.sh` auto-detects Claude Code >= 2.1.139 and activates native /goal when a
+  condition is set; otherwise falls back to instar's own evaluator.
+
+## What to Tell Your User
+
+When the tool I'm running already has its own "keep going until done" feature (Claude Code and
+Codex both added one called goal), I now hand my finish-line straight to it instead of running
+my own judge on top — no double-checking, and I use the tool's native machinery. Where the tool
+doesn't have it, my own judge still does the job. Either way I keep the safety controls (stop
+everything, time limits) and the ability to run several jobs at once. Nothing to set up.
+
+## Summary of New Capabilities
+
+- Native /goal delegation: instar injects `/goal <condition>` into the session and lets the
+  framework's loop own completion (`goal_mode: native`).
+- `POST /autonomous/native-goal/set` and `/autonomous/native-goal/clear`.
+- Auto-detection of Claude Code >= 2.1.139 in `setup-autonomous.sh`.
+- Stop-hook defers completion to native /goal while still enforcing emergency-stop + duration
+  (clears the native goal first).
+
+## Migration Notes
+
+Existing agents receive the updated hook + setup via
+`PostUpdateMigrator.migrateAutonomousStopHookTopicKeyed` (marker bumped to the native-/goal
+signature). No action required.
+
+## Evidence
+
+- **Hook (behavioral):** `autonomous-completion-condition.test.ts` — `goal_mode: native` defers
+  (approves/exits, job retained, native /goal stays in control); emergency-stop and duration
+  expiry still clear state + exit in native mode.
+- **Integration:** `autonomous-sessions-api.test.ts` — `native-goal/set` injects `/goal
+  <condition>` into the topic's session (verified via the recorded `sendInput` call) and flips
+  `goal_mode: native`; `native-goal/clear` injects `/goal clear`; 404 on unknown topic.
+- tsc clean; 174 affected tests green.
+
+## Note on approach
+
+The original spec sketched Phase 2 via a `ThreadGoalSlot` provider primitive. The shipped
+approach instead drives native /goal by **injecting the slash command** through instar's
+existing session-input mechanism — simpler, and the correct use of a capability instar already
+has (rather than treating "no programmatic /goal API" as a blocker). Same intent (delegate to
+native /goal where present), better mechanism.

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-native-delegation.md

@@ -0,0 +1,76 @@
+# Side-Effects Review — native /goal delegation (Phase 2)
+
+**Version / slug:** `goal-native-delegation`
+**Date:** 2026-05-24
+**Author:** echo
+**Second-pass reviewer:** internal conformance pass
+
+## Summary of the change
+
+Where the framework has a native /goal loop (Claude Code >= 2.1.139), autonomous mode delegates
+completion to it: instar **injects `/goal <condition>`** into the session via
+`SessionManager.sendInput` (tmux send-keys — its existing session-input mechanism), marks the
+job `goal_mode: native`, and the stop-hook **defers** the continue/stop decision to native
+/goal (approves each turn). instar still enforces emergency-stop + duration by injecting
+`/goal clear` first. Phase 2 of `docs/specs/goal-completion-evaluator.md`. `src/`: two routes
+(`/autonomous/native-goal/set|clear`) + capability-index entry + migration marker bump. Non-src:
+hook native branch, setup auto-detection.
+
+## Decision-point inventory
+- Stop-hook `goal_mode: native` branch — **modify**: defer completion to native /goal (approve);
+  still enforce emergency-stop + duration (clear native first). This REMOVES instar's completion
+  authority for native topics by design (native /goal is the authority there).
+- `POST /autonomous/native-goal/set` / `clear` — **add**: inject the slash command + flip
+  goal_mode. Thin; the side-effect is the session injection.
+- `setup-autonomous.sh` native detection — **modify** (`.claude/`): activate native mode when
+  Claude Code >= 2.1.139 + a condition is set.
+
+## 1. Over-block
+- In native mode instar approves (never blocks) for completion, so instar cannot over-block.
+  Native /goal's own hook decides. No new over-block path.
+
+## 2. Under-block (false "done" / premature exit)
+- instar approving in native mode does NOT cause a false done: in Claude Code's hook composition
+  a `block` from native /goal wins over instar's `approve`, so native /goal keeps the session
+  working until ITS evaluator confirms the condition. If native /goal somehow isn't active, the
+  session would exit — mitigated because goal_mode:native is only set after a successful inject
+  (the set endpoint flips the flag only when sendInput returns true).
+
+## 3. Level-of-abstraction fit
+- Correct + the point of the change: drive the framework's native feature via instar's own
+  session-input mechanism, rather than reimplementing or treating "no /goal API" as a blocker.
+
+## 4. Blocking authority
+- [x] In native mode instar **yields** completion authority to native /goal (reduces instar's
+  authority — safe direction) while retaining its terminal STOP concerns (emergency/duration) by
+  clearing the native goal. No new brittle authority added.
+
+## 5. Interactions (the key one: two Stop hooks)
+- instar's hook + native /goal's hook both fire each turn. Resolved by composition: instar
+  approves (completion) so native /goal's block keeps control; instar only force-stops on
+  emergency/duration, and does so by clearing native /goal first (so they don't fight).
+- **Emergency-stop** already kills the session via the sentinel path (native /goal dies with it);
+  the hook also clears native /goal on the flag. **Duration** clears native /goal then exits.
+- Falls back cleanly to the instar evaluator (Phase 1) when native /goal is absent.
+
+## 6. External surfaces
+- **Session injection:** instar types `/goal <condition>` / `/goal clear` into the agent's own
+  tmux session (send-keys). This is instar's established mechanism (initial-message injection).
+  No new external/credential surface.
+- **HTTP:** two authed routes under the already-claimed `/autonomous` prefix.
+
+## 7. Rollback cost
+- Low. Reverting restores instar's own evaluator everywhere (Phase 1 still in main). A
+  `goal_mode: native` left in a state file is ignored by an older hook (falls to the evaluator/
+  promise path). Migration marker is content-sniffed (rollback re-deploys cleanly).
+
+## 8. Test evidence
+- Hook: native defers (approve/exit, retained) + emergency/duration clear+exit. Integration:
+  set injects `/goal <cond>` (verified sendInput) + flips goal_mode; clear injects `/goal clear`;
+  404 unknown topic. tsc clean; 174 affected tests green.
+
+## Deviation from the original spec
+Spec Phase 2 sketched a `ThreadGoalSlot` provider primitive. Shipped instead via direct slash-
+command injection through `SessionManager.sendInput` — simpler and the correct use of an existing
+instar capability (per maintainer direction: "we already input text into sessions; use that to
+call /goal"). Same intent, better mechanism; `ThreadGoalSlot` left unimplemented (not needed).