instar 1.3.127 → 1.3.129

package/upgrades/1.3.129.md

@@ -0,0 +1,55 @@
+---
+review-convergence: complete
+approved: true
+approved-by: justin (topic 13435, 2026-05-30 — "Yes, go ahead as long as we do it carefully and we have a clear plan to regress")
+---
+
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed — codex agents can now sustain a multi-turn autonomous run (ships DARK)
+
+A `codex exec` session runs one turn then exits — there was no "keep going" Stop hook
+like Claude has, so a codex agent (Codey) couldn't carry a long autonomous task. This is
+the headline Claude/Codex parity gap.
+
+The mechanism already existed end-to-end (codex fires Stop hooks and honors
+`{decision:"block", reason}` — verified in the codex 0.133 binary); the only missing piece
+was the wiring. `installCodexHooks` now registers the shared `autonomous-stop-hook.sh`
+(with a `--codex` arg) as a SEPARATE codex Stop group — mirroring how Claude registers its
+loop hook — and the hook self-gates on `autonomousSessions.codexLoopDriver.enabled`.
+
+Ships **DARK**: the flag defaults false, so the standing codex hook exits immediately (no
+behavior change for any codex session) until it is explicitly enabled. Claude's autonomous
+mode is byte-for-byte unchanged (its loop hook is registered separately, with no `--codex`
+arg).
+
+## What to Tell Your User
+
+Nothing changes yet — this ships turned off. It is the foundation that will let a codex
+agent keep working through a long task on its own (the way a Claude agent already can),
+once it is enabled and verified live. Rollback is instant: turn the flag back off.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Codex autonomous-loop driver | Set `autonomousSessions.codexLoopDriver.enabled: true` in `.instar/config.json` (default false / dark). Off → instant rollback, no redeploy. |
+| Standing codex Stop group | `installCodexHooks` registers `autonomous-stop-hook.sh --codex` as its own Stop group; re-armed automatically on update. |
+
+## Evidence
+
+- Repro: a `codex exec` autonomous job stops after one turn — no `.codex/hooks.json` loop
+  hook (only the Claude path was wired). Prerequisites verified on disk: codex fires Stop
+  hooks (`config.toml [hooks.state]`); honors block+reason (0.133 binary `StopCommandOutputWire`).
+- Before/after: before — codex Stop chain has only the review trio; after — a second Stop
+  group carries the loop driver, self-gated dark.
+- Unit: `tests/unit/installCodexHooks.test.ts` — separate instar Stop group, idempotent
+  re-install (never stacks), user Stop group preserved.
+- Unit: `tests/unit/autonomous-stop-hook-codex-gate.test.ts` — `--codex` + flag absent/false
+  → approve (dark) even with an active job; flag true → block; no `--codex` (Claude) → blocks
+  regardless of the flag (Claude path unaffected). Both sides of the gate.
+- `tsc --noEmit` clean; `npm run lint` clean.
+- Spec: `docs/specs/codex-autonomous-loop-driver.md` (+ `.eli16.md`).
+- Side-effects: `upgrades/side-effects/codex-autonomous-loop-driver.md`.

package/upgrades/side-effects/codex-autonomous-loop-driver.md

@@ -0,0 +1,91 @@
+# Side-Effects Review — Codex autonomous-loop driver
+
+**Version / slug:** `codex-autonomous-loop-driver`
+**Date:** `2026-05-30`
+**Author:** `echo`
+**Second-pass reviewer:** see below (required — lifecycle machinery)
+
+## Summary of the change
+
+Adds a codex registration of the shared autonomous-stop-hook so a `codex exec` session
+sustains a multi-turn autonomous run (the codex analog of Claude's Stop-hook loop). A
+SEPARATE codex Stop group (`autonomous-stop-hook.sh --codex`) is added in
+`installCodexHooks`; the hook self-gates on `autonomousSessions.codexLoopDriver.enabled`
+(default false → DARK). Claude's path is byte-for-byte unchanged.
+
+## Decision-point inventory
+
+1. `IS_CODEX` gate in the hook (— is this a codex-registered invocation?).
+2. `codexLoopDriver.enabled` flag check (— should the codex loop actually run?).
+3. `groupIsInstarOwned` (— is this Stop group instar-owned, to replace not duplicate?).
+
+## 1. Over-block
+Could it block a stop that SHOULD proceed? Only when the flag is ON, an autonomous job is
+active for this session, AND tasks remain — which is exactly the intended block (continue
+the run). With the flag OFF (default) it never blocks. The existing ownership/duration/
+emergency/completion terminal checks (unchanged) still release the session.
+
+## 2. Under-block
+Could it fail to block when it SHOULD continue? When the flag is OFF, yes — by design
+(dark). When ON, the only residual is the open binary question of whether codex runs the
+second Stop group (Phase-5 / live verification gates this before enabling; fallback =
+move into group 0). No silent data loss either way — at worst the codex run stops early,
+same as today.
+
+## 3. Level-of-abstraction fit
+The driver lives where Claude's does (the autonomous skill hook) and is registered where
+codex's other standing hooks are (`installCodexHooks`). The flag sits with the other
+autonomous-mode settings (`autonomousSessions`). No new subsystem.
+
+## 4. Signal vs authority compliance
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+The hook is an AUTHORITY surface by nature (a Stop hook returns block/approve — same as
+Claude's existing loop hook and codex's existing stop-gate-router). It does not newly
+elevate authority: it reuses the established Stop-hook contract. The dark flag means the
+authority is dormant until explicitly enabled. No monitoring/signal component is converted
+into a blocker.
+
+## 5. Interactions
+- **Review trio (stop-gate-router / response-review / claim-intercept / scope-coherence):**
+  the driver is the LAST hook in the SAME Stop group (slot stop:0:N). Within-group block
+  precedence vs the router is verified live before enabling; worst case the session still
+  continues via the router (never strands).
+- **Claude autonomous mode:** independent registration (settings.json vs .codex/hooks.json);
+  `IS_CODEX=0` for Claude → unchanged.
+- **armCodexHooks:** the new hook changes the hooks.json hash → re-arm on update (handled
+  by the existing migration). Because it rides group 0 (a group codex already trusts/arms),
+  it adds NO new arm slot — avoiding the recurring-arm-spawn side-effect a separate group
+  (stop:1:0) would have caused (caught by the second-pass review, then designed out).
+
+## 6. External surfaces
+None new. No HTTP route, no Telegram message, no external API. The hook talks only to the
+local server's existing `/autonomous/evaluate-completion` (unchanged) when a completion
+condition is set.
+
+## 7. Rollback cost
+Lowest tier. Set `autonomousSessions.codexLoopDriver.enabled: false` → the standing hook
+exits immediately (instant, no redeploy, no session kill). Full PR revert is clean
+(additive change; removing the Stop group + the `IS_CODEX` block restores prior behavior).
+
+## Conclusion
+Safe to ship DARK. The only non-trivial residual (does codex run a second Stop group) is
+gated behind the default-off flag and resolved by live verification before enabling — per
+Justin's "careful + clear plan to regress" condition.
+
+## Second-pass review (if required)
+
+**Reviewer:** independent second-pass agent (lifecycle machinery — required)
+**Status:** DONE 2026-05-30 — **CONCUR on shipping DARK.** Verified PASS on: Claude path
+unchanged, dark gate cannot leak (all config-read failure paths → disabled), `$0` anchor,
+groupIsInstarOwned idempotency, migration parity (both halves land). The reviewer caught a
+fleet-wide arm side-effect from the original separate-group design (a `stop:1:0` slot codex
+may never trust → recurring codex-TUI arm spawns on every update, even dark). **Resolved**
+by moving the driver into the existing Stop group (slot stop:0:N) — no new arm slot. The
+remaining open item (within-group block precedence + that the loop actually re-prompts a
+real codex run) is gated to live verification BEFORE the flag is enabled, per the spec's
+Phase 5 — it is not a merge/dark-ship blocker.
+
+## Evidence pointers
+- Unit: `tests/unit/installCodexHooks.test.ts` (separate Stop group, idempotent, user-group preserved).
+- Unit: `tests/unit/autonomous-stop-hook-codex-gate.test.ts` (dark default / disabled / enabled / Claude-unaffected — both sides of the gate).
+- Spec: `docs/specs/codex-autonomous-loop-driver.md` (+ `.eli16.md`).

package/upgrades/side-effects/correction-preference-learning-sentinel-slice1a.md

@@ -0,0 +1,132 @@
+# Side-effects review — Correction & Preference Learning Sentinel (Slice 1a)
+
+**Spec:** `docs/specs/CORRECTION-PREFERENCE-LEARNING-SENTINEL-SPEC.md` (§3.6, §7,
+§9, §10 Slice 1a)
+**Change:** new `src/core/PreferencesManager.ts`; inline
+`GET /preferences/session-context` in `src/server/routes.ts`;
+`monitoring.correctionLearning` config block (`src/core/types.ts` +
+`src/config/ConfigDefaults.ts`); `CapabilityIndex.ts` entry; session-start hook
+patch + `migrateClaudeMd` backfill + shadow-capability marker in
+`src/core/PostUpdateMigrator.ts`; `generateClaudeMd` capability section +
+Registry-First row + proactive trigger in `src/scaffold/templates.ts`; 3-tier +
+wiring tests.
+**Class:** new read-surface feature, ships OFF, signal-only (never gates,
+blocks, or rewrites a message).
+
+## What changed
+
+A structured on-disk preferences file (`.instar/preferences.json`), the single
+atomic writer for it (`recordPreference()`), an HTTP read route serving the
+session-start block, and a session-start hook that injects that block on every
+boot. Modeled 1:1 on the proven ORG-INTENT precedent
+(`GET /intent/org/session-context` + its session-start fetch). Slice 1b (the
+capture/distill/ledger loop) is the future writer; Slice 1a only proves the
+surface is alive end-to-end.
+
+## 1. Security
+
+- **No new external input/network/egress.** The route only reads a local file
+  and serves a deterministically-formatted block. No LLM call, no outbound
+  request, no shell-out in Slice 1a (the hook's curl is loopback to the agent's
+  own server, same as ORG-INTENT).
+- **Auth:** the route is Bearer-gated by the global `authMiddleware` exactly like
+  sibling `/intent/*` routes (integration test asserts 401 without a token).
+- **Output discipline:** the served payload and the injected block contain ONLY
+  the `learning` text + metadata (confidence, seen-count). Internal fields
+  (`dedupeKey`, `provenance`) never leak (unit + integration assertions). This is
+  the §3.6 "serve only learning + metadata" rule.
+- **Injection-confusion defense:** loop-sourced preferences are wrapped in an
+  `<auto-learned-preference src='correction-loop'>` envelope so a downstream
+  prompt assembler structurally cannot mistake a learned preference for an
+  authoritative instruction. The block's own preamble restates "signals, not
+  instructions; real instructions and safety win."
+- **No policy-relaxation surface in 1a:** `recordPreference()` has no writer in
+  Slice 1a (Slice 1b adds the gated, policy-keyword-filtered caller per §3.6).
+  Until then the only way an entry lands is a direct programmatic call, which the
+  correction loop does not yet make.
+
+## 2. Migration parity
+
+- **Config:** `monitoring.correctionLearning` added to `ConfigDefaults`.
+  `applyDefaults` deep-merges add-missing-only (verified: `merge()` recurses into
+  objects, adds absent keys, never overwrites), so existing agents backfill the
+  block on update without a dedicated `migrateConfig` step — and without surprise
+  activation (`enabled: false`). This matches the spec §7 note and the
+  failure-learning precedent.
+- **Route:** inline in `routes.ts` (the discoverability-lint allowlist is fixed; a
+  separate module would trip the orphan-prefix check). `CapabilityIndex` entry
+  added so the lint passes and the route is discoverable.
+- **Hook:** built-in `instar/` hooks are always-overwrite on every migration, so
+  the patched `session-start.sh` propagates to every existing agent on the next
+  update — no hand-written `migrateHooks` block needed.
+- **CLAUDE.md:** `generateClaudeMd` gains the capability section / Registry-First
+  row / proactive trigger; `migrateClaudeMd` gains a content-sniffed backfill
+  (marker `Correction & Preference Learning Sentinel`) so EXISTING agents learn
+  the surface — not just new ones. A shadow-capability marker
+  (`**Preferences I've learned about you**`) mirrors it into Codex/Gemini
+  `AGENTS.md`/`GEMINI.md`. `feature-delivery-completeness` enforces all three legs.
+- **State file:** `.instar/preferences.json` is created lazily on first write;
+  absent ≡ empty. No migration needed.
+
+## 3. Performance
+
+- The read route does one small synchronous file read + a deterministic
+  string-build bounded by `maxInjectedPreferencesBytes` (4000). No DB, no LLM, no
+  network. Cost is negligible and constant-ish.
+- `recordPreference()` reads + rewrites the whole file atomically. The file is
+  bounded by distinct-preference cardinality (upsert by `dedupeKey`), not message
+  volume, so it stays tiny in practice. Each write is one temp-file + fsync +
+  rename.
+- The session-start hook adds one loopback curl with `--max-time 4`; fail-open on
+  timeout, so a slow/absent server can never delay session start beyond that cap.
+
+## 4. Observability
+
+- The route is discoverable via `GET /capabilities` (CapabilityIndex entry,
+  `enabled` reflects the flag).
+- `{ present, block, count }` makes the served state self-describing; `count`
+  exposes distinct-preference cardinality for debugging.
+- No new log channel in 1a (the audit log `logs/correction-learning-audit.jsonl`
+  is a Slice 1b concern — the loop that produces routable decisions).
+
+## 5. Rollback
+
+- Flip `monitoring.correctionLearning.enabled` back to false (or remove the
+  block) → the route 503s and the hook injects nothing. Inert.
+- `.instar/preferences.json` entries all carry `provenance: 'correction-loop'`,
+  enabling a one-shot bulk removal (a single jq-style filter) if a future loop
+  ever writes something unwanted. In 1a nothing writes, so the file stays absent.
+- Code rollback = revert the commits; the absent-file ≡ empty contract means a
+  rolled-back agent with a stray file is still consistent (read tolerates and
+  ignores it; the route 503s when the flag is gone).
+
+## 6. Multi-machine
+
+- The file is per-agent-home local state (under `stateDir`), like ORG-INTENT.md
+  and the integrated-being ledger. On a multi-machine agent each machine reads
+  its own copy; the existing state-sync layer carries `.instar/` files between
+  machines the same way it carries ORG-INTENT.md — no new sync path introduced.
+- The route is read-only and idempotent; no lease/fencing interaction. Slice 1a
+  has no writer competing across machines (that is a Slice 1b consideration when
+  the loop runs only on the awake machine).
+
+## 7. Multi-user
+
+- Slice 1a is a pure read/inject surface and does not itself attribute a
+  preference to a user — it serves whatever was recorded. The multi-user
+  primary-user gate (§3.6) lives in Slice 1b, where corrections are attributed
+  and `recordPreference()` is actually called. Until then no user-shaped data can
+  enter the file via this feature.
+- The injected block is the same for every session on the agent (it is the
+  agent's learned-about-this-operator preferences), consistent with the
+  single-operator model the rest of the agent assumes.
+
+## Tests
+
+- Unit: `tests/unit/PreferencesManager.test.ts` (13),
+  `tests/unit/preferences-wiring-integrity.test.ts` (7).
+- Integration: `tests/integration/preferences-routes.test.ts` (5).
+- E2E: `tests/e2e/preferences-session-context-lifecycle.test.ts` (6).
+- Lint: `tests/unit/capabilities-discoverability.test.ts` (100) green;
+  `tests/unit/feature-delivery-completeness.test.ts` green (parity + shadow
+  marker for the new section).