instar 1.3.153 → 1.3.155

package/upgrades/{1.3.153.md → 1.3.154.md}

@@ -35,6 +35,11 @@ checks the publish gate enforces, and a malformed fragment fails the push loudly
 
 ## What to Tell Your User
 
+If you run a Codex-based agent, it can now run in autonomous mode and keep itself going across
+many turns until the goal is met — the same way a Claude agent does. Before, a Codex agent in
+autonomous mode would quietly stop after a single turn. Nothing to configure; it applies on the
+next update, and Claude agents are unaffected.
+
 Behind the scenes, the way I prepare release notes got a lot more robust. Each
 change now writes its own small note in its own file, instead of every change
 fighting over one shared notes file. That means when several updates are being
@@ -44,8 +49,43 @@ I talk to you — this is purely a smoother release pipeline on my side.
 
 ## Summary of New Capabilities
 
+- `setup-autonomous.sh` now enables native /goal delegation for Codex agents (detected via config
+  `enabledFrameworks` containing `codex-cli`), not just Claude Code >= 2.1.139. Codex autonomous
+  mode auto-delegates to native /goal; the stop-hook's existing `goal_mode:native` branch defers.
+- `PostUpdateMigrator` marker bump (`native-goal/set` → `IS_CODEX_AGENT`) re-deploys the fixed
+  setup script to existing agents.
+
 | Capability | How to Use |
 |-----------|-----------|
 | Per-PR release-note fragments | Write `upgrades/next/<slug>.md` (one file per change) |
 | Fragment assembler | `node scripts/assemble-next-md.mjs` (runs automatically in publish) |
 | Legacy NEXT.md | Still supported — folded in for backward compatibility |
+
+## Evidence
+
+- Root cause traced by reading setup-autonomous.sh: the native /goal hand-off existed but was
+  gated on `claude --version >= 2.1.139` (empty for a codex agent → codex fell to the dark
+  Phase-1 no-op). Proven live in round 2 that codex /goal sustains 1→2→3 across turns.
+- Unit: `tests/unit/autonomous-codex-native-goal-detection.test.ts` — both sides of the
+  decision boundary (codex enables, Claude/absent skips, multi-framework enables, missing config
+  best-effort skips).
+- Unit: `tests/unit/PostUpdateMigrator-autonomousStopHook.test.ts` — a prior native-/goal setup
+  is re-deployed by the marker bump; all existing cases stay green (8 tests).
+- `tsc --noEmit` + `npm run lint` clean.
+- Spec: `docs/specs/codex-autonomy-native-goal-autowire.md` (+ `.eli16.md`).
+- Side-effects: `upgrades/side-effects/codex-autonomy-native-goal-autowire.md`.
+- Final proof is the live drive: Codey running the real /autonomous skill and sustaining multi-turn.
+
+## What Changed — Codex agents now run autonomous mode on their own (Claude parity)
+
+When you put an agent in autonomous mode, it should keep working across many turns until the job
+is done. Claude agents already did this (via the stop hook). Codex agents did NOT — they would
+quietly stop after one turn. Codex actually has its own way to sustain a multi-turn run (its
+built-in /goal loop), and instar already handed the goal off to it automatically — but only
+behind a check for "Claude command-line version 2.1.139+", which is empty for a Codex agent. So
+Codex agents fell through that Claude-shaped gate and never got the hand-off.
+
+This adds a small framework-aware fallback: if the Claude check doesn't apply, instar detects a
+Codex agent (from its own config) and hands the goal to Codex's native /goal loop. Now a Codex
+agent in autonomous mode sustains multi-turn work automatically, the same as a Claude agent. The
+Claude path is unchanged, and the sensitive stop hook is untouched.

package/upgrades/1.3.155.md

@@ -0,0 +1,26 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+**A stored preference that gets violated now becomes a learning signal (dark).** This extends the Correction & Preference Learning Sentinel. A learned preference — for example, "don't defer work to a fresh session" or "never ask the user to edit files" — can now carry an optional self-violation pattern. When the agent emits an outbound message that contradicts such a preference, that is recorded as a self-violation in the correction ledger, which reinforces the preference's recurrence so it surfaces more prominently the next session.
+
+It is signal-only: the detector observes the finalized outbound message and records — it can never block, delay, or rewrite a message. It is fail-open (any detector error silently no-ops and delivery is unaffected) and dark (gated behind both the master correction-learning flag and a new self-violation sub-flag). A preference without a self-violation pattern is never checked, so existing preference files are fully backward compatible.
+
+## What to Tell Your User
+
+The correction-learning system can now notice when the agent's own outgoing message contradicts a preference it has already learned about how you like to work, and quietly use that as a signal to remember the preference more strongly next time. It only ever observes and records — it never blocks, delays, or changes a message — and it stays off until explicitly turned on.
+
+## Summary of New Capabilities
+
+- New `src/monitoring/SelfViolationDetector.ts` — pure, deterministic `detectSelfViolation`; precision-biased (a lone weak keyword never fires), never throws.
+- `PreferencesManager` preference records gain an optional `violationPattern` (regex or keyword grammar); fully backward compatible.
+- Observe-only outbound hook in `checkOutboundMessage` records self-violations to the `CorrectionLedger`; structurally independent of the tone-gate verdict and of the message itself.
+- New `monitoring.correctionLearning.selfViolationSignal` config flag (default false).
+
+## Evidence
+
+- `SelfViolationDetector` unit (17), self-violation wiring-integrity (5, asserts the outbound message passes through byte-for-byte unchanged and the detector fail-opens), integration (5), and E2E lifecycle (3) — all passed.
+- `npm run build` / `npm run lint` / `docs-coverage` clean.

package/upgrades/side-effects/codex-autonomy-native-goal-autowire.md

@@ -0,0 +1,43 @@
+# Side-effects — Codex autonomous native /goal auto-wire
+
+## 1. What files/state does this touch at runtime?
+`.claude/skills/autonomous/scripts/setup-autonomous.sh` (skill content). At autonomous-mode
+activation on a CODEX agent, it now additionally POSTs `/autonomous/native-goal/set` (which the
+script already did for Claude>=2.1.139) — injecting `/goal <completion_condition>` into the
+session and marking the job `goal_mode:native` in `<topic>.local.md`. No new files, no config
+keys, no schema. The PostUpdateMigrator re-deploys the script to existing agents (marker bump).
+
+## 2. Does it change any functional behavior?
+- **Claude agents:** none. The Claude version gate is untouched; the codex check only runs when
+  the Claude gate already failed.
+- **Codex agents:** a codex autonomous job now auto-delegates to native `/goal` (previously it
+  fell through to the dark Phase-1 codexLoopDriver no-op and silently never sustained multi-turn).
+  The stop-hook's existing `goal_mode:native` branch then defers to native `/goal`.
+
+## 3. What happens on failure / weird config?
+Best-effort: the detection one-liner is `... 2>/dev/null || echo "0"`, so a missing/malformed
+config.json or absent python → `0` → not-codex → exactly the prior behavior (no regression). A
+codex agent whose native `/goal` POST fails → the script prints "Native /goal: unavailable" and
+instar's own completion evaluator drives (the existing fallback).
+
+## 4. Migration parity — do existing agents get it?
+Yes. `migrateAutonomousStopHookTopicKeyed` marker bumped `native-goal/set` → `IS_CODEX_AGENT`,
+so prior native-/goal installs are re-deployed; customized scripts (no stock fingerprint) are
+left untouched; already-updated agents skip (idempotent). New agents get it via installAutonomousSkill.
+
+## 5. Could it spam / flood / burn resources?
+No. It adds at most one extra `python3` config read + (for codex) one `native-goal/set` POST,
+once, at autonomous-mode activation — the same POST the script already made for Claude.
+
+## 6. Rollback / off-switch?
+Revert the PR. The marker would revert too; a reverted-version agent retains `native-goal/set`
+(still functional for Claude). No residual state, no flag.
+
+## 7. Concurrency / ordering?
+None new. Runs inline in the single setup-autonomous.sh activation flow, after the Claude gate.
+
+## Blast radius
+Small + additive, codex-only. One ~5-line fallback in setup-autonomous.sh + one migration marker
+bump in PostUpdateMigrator. No change to the sensitive stop-hook (the goal_mode:native defer
+already existed), no change to the Claude path. Mirrors the #604/#609 codex framework-additive
+pattern. The codexLoopDriver:true config footgun is a separate low-pri follow-up (#40 notes).

package/upgrades/side-effects/correction-self-violation-signal.md

@@ -0,0 +1,133 @@
+# Side-Effects Review — Correction & Preference Learning: Self-Violation Signal
+
+**Version / slug:** `correction-self-violation-signal`
+**Date:** `2026-05-31`
+**Author:** `echo`
+**Second-pass reviewer:** `not required — observe-only + dark by default; the detector holds no blocking authority and cannot alter/delay/block any outbound message`
+
+## Summary of the change
+
+Extends the shipped Correction & Preference Learning Sentinel so a stored-but-violated
+preference becomes a learning signal instead of evaporating. A learned preference can
+carry an OPTIONAL `violationPattern` (regex or keyword set). When the agent sends an
+outbound message that contradicts that pattern, the contradiction is recorded as a
+self-violation in the `CorrectionLedger` (a recurrence-reinforcing `user-preference`
+occurrence keyed on the violated lesson), so the preference's salience grows for the
+next session-start injection.
+
+Files: new `src/monitoring/SelfViolationDetector.ts` (pure `detectSelfViolation`);
+`src/core/PreferencesManager.ts` (+optional `violationPattern` on `PreferenceEntry`
+and `RecordPreferencePayload`, persisted/round-tripped, upsert-preserving); the
+outbound seam in `src/server/routes.ts` (a new OBSERVE-ONLY `observeSelfViolation`
+fire-and-forget branch inside `checkOutboundMessage`, structurally independent of the
+tone-gate verdict); config `monitoring.correctionLearning.selfViolationSignal`
+(types.ts + ConfigDefaults.ts); Agent-Awareness (templates.ts) + Migration-Parity
+backfill (PostUpdateMigrator migrateClaudeMd).
+
+## Decision-point inventory
+
+- `detectSelfViolation(text, prefs)` (new) — add — pure, deterministic, returns the
+  list of violated preferences. No authority; precision-biased (lone weak match never
+  fires); never throws.
+- `observeSelfViolation` seam branch (new) — add — records a matched violation to the
+  ledger + an audit line. Fire-and-forget VOID; cannot influence delivery.
+- `PreferenceEntry.violationPattern` (new optional field) — add — absent ≡ never
+  checked (back-compat).
+- Tone-gate / `checkOutboundMessage` block-decision — UNCHANGED — the observe branch
+  runs before the gate-availability early-return and never feeds the gate or the
+  return value.
+
+---
+
+## 1. Over-block
+
+Not applicable. The feature has NO block/allow surface. The observe branch runs as a
+fire-and-forget `void observeSelfViolation(...).catch(...)` that is structurally
+incapable of returning a block verdict, throwing into the delivery frame, or mutating
+the message. The wiring-integrity + E2E tests assert the message is delivered
+byte-for-byte unchanged whether or not a violation is detected.
+
+## 2. Under-block
+
+There is nothing to under-block — the feature never blocks. The "miss" direction
+(a real self-violation going unrecorded) is the deliberately-chosen safe direction:
+precision over recall. A lone/weak keyword never fires, an unparseable pattern is a
+no-check, and a preference without a `violationPattern` is skipped. A false
+self-violation that nags is the bad direction, so the matcher is conservative. A
+missed recording costs only a slightly weaker recurrence signal next session.
+
+## 3. Level-of-abstraction fit
+
+Correct. The detector is a pure, exhaustively-tested function (mirrors the
+deterministic `scrubSecrets` / Layer-0 classifier discipline of the same sentinel).
+The recording reuses the shipped `CorrectionLedger.record()` dedupe-upsert and its
+`toApiView()` raw-text-stripping discipline; the occurrence is a `user-preference`
+record at the code-determined `LEARNING_DETERMINISTIC_THRESHOLD` so it feeds the
+existing 3-pronged recurrence gate exactly like any other distilled correction. No
+new persistence layer, no new gate, no new authority.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] Yes — this change produces a SIGNAL (a ledger occurrence + an audit line) and
+  holds ZERO authority over any message. The user's explicit hard rule ("we've been
+  bitten by guards that block messages having too much power") is honored structurally:
+  the observe call is a separate VOID branch that runs regardless of the
+  `MessagingToneGate`'s verdict and never influences it. The single authority for
+  outbound delivery remains the `MessagingToneGate` (rules B1–B17), entirely unchanged.
+
+## 5. Interactions
+
+- **Shadowing:** none. The observe branch is additive at the top of
+  `checkOutboundMessage`; it does not read or alter the signals, the gate result, or
+  the 422 path. With the tone gate null, the observe branch still runs (it precedes
+  the gate-availability early-return) and the message still passes through.
+- **Double-fire:** the ledger dedupe-upserts on `kind:normalizedLearningHash`, so
+  repeated self-violations of the same preference collapse to ONE record with an
+  incrementing `occurrenceCount` (asserted by the integration test) — never a pile.
+- **Races:** the observe call is fire-and-forget and lazy-imports its modules; the
+  ledger is the shipped WAL SQLite store (single-writer-safe, fail-open on any error).
+  Two concurrent sends recording the same preference are both safely upserted.
+- **Feedback loops:** none. The detector reads `.instar/preferences.json` (written by
+  `recordPreference`) and writes the ledger; it never writes preferences, so it cannot
+  amplify its own pattern. The CorrectionAnalyzer that consumes the ledger is
+  off-hot-path (weekly cron) and only ROUTES via the existing by-construction
+  authority-bounded driver.
+
+## 6. External surfaces
+
+- **Other agents / install base:** pure additive source + a default-OFF config
+  sub-flag (auto-applied via ConfigDefaults; code reads `cl?.selfViolationSignal !==
+  true` so an agent whose config lacks the field behaves identically — OFF). The
+  optional `violationPattern` is fully back-compatible: shipped `.instar/preferences.json`
+  files have no such field and are simply never self-violation-checked (unit-tested
+  with a legacy-shaped file). Agent-Awareness + Migration-Parity are handled
+  (templates.ts bullet for new agents; idempotent content-sniffed migrateClaudeMd
+  backfill for existing agents).
+- **External systems:** none. The detector is local + deterministic; no LLM call, no
+  network. (Distinct from the capture/distill loop, which is a separate, already-shipped
+  surface.)
+- **Persistent state:** existing `correction-ledger.db` only (one extra occurrence
+  row per matched violation, bounded by the shipped per-key occurrence cap). Plus a
+  best-effort `[self-violation]` stderr audit line. No new files.
+- **Timing:** none. No timers; the observe call is one bounded synchronous detect plus
+  one ledger write, off the delivery path.
+
+## 7. Rollback cost
+
+Pure additive code + a default-off config sub-flag. Revert the commits → the detector,
+the seam branch, the schema field, the config flag, and the awareness text disappear;
+nothing else changes. Any ledger occurrences already recorded are inert and indexed
+exactly like every other correction record (no schema change to the ledger). No
+migration, no state repair, no user-visible behavior change (it never acted on a
+message).
+
+## Conclusion
+
+This review confirmed the change is observe-only: a tested, precision-biased,
+never-throwing decision function plus a fire-and-forget recording branch that is
+structurally incapable of blocking, delaying, or altering any outbound message. It
+ships dark behind both `correctionLearning.enabled` and the new `selfViolationSignal`
+sub-flag, is fully back-compatible with existing preference files, and reuses the
+shipped ledger's privacy + dedupe discipline. Clear to ship.