instar 1.3.148 → 1.3.150

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.148",
+  "version": "1.3.150",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-31T07:09:17.964Z",
-  "instarVersion": "1.3.148",
+  "generatedAt": "2026-05-31T08:02:41.896Z",
+  "instarVersion": "1.3.150",
   "entryCount": 193,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "5efb86088319998cc5bdb201ef7f49e293b911508941a1bbbeff866b8872eec8",
+      "contentHash": "3418f7109a38172a28a3a202c8a878c1064f55911a82155c53a0b1ccde44e804",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "5efb86088319998cc5bdb201ef7f49e293b911508941a1bbbeff866b8872eec8",
+      "contentHash": "3418f7109a38172a28a3a202c8a878c1064f55911a82155c53a0b1ccde44e804",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "5efb86088319998cc5bdb201ef7f49e293b911508941a1bbbeff866b8872eec8",
+      "contentHash": "3418f7109a38172a28a3a202c8a878c1064f55911a82155c53a0b1ccde44e804",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "5efb86088319998cc5bdb201ef7f49e293b911508941a1bbbeff866b8872eec8",
+      "contentHash": "3418f7109a38172a28a3a202c8a878c1064f55911a82155c53a0b1ccde44e804",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "5efb86088319998cc5bdb201ef7f49e293b911508941a1bbbeff866b8872eec8",
+      "contentHash": "3418f7109a38172a28a3a202c8a878c1064f55911a82155c53a0b1ccde44e804",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "5efb86088319998cc5bdb201ef7f49e293b911508941a1bbbeff866b8872eec8",
+      "contentHash": "3418f7109a38172a28a3a202c8a878c1064f55911a82155c53a0b1ccde44e804",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -65,7 +65,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "5efb86088319998cc5bdb201ef7f49e293b911508941a1bbbeff866b8872eec8",
+      "contentHash": "3418f7109a38172a28a3a202c8a878c1064f55911a82155c53a0b1ccde44e804",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -74,7 +74,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "5efb86088319998cc5bdb201ef7f49e293b911508941a1bbbeff866b8872eec8",
+      "contentHash": "3418f7109a38172a28a3a202c8a878c1064f55911a82155c53a0b1ccde44e804",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -83,7 +83,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "5efb86088319998cc5bdb201ef7f49e293b911508941a1bbbeff866b8872eec8",
+      "contentHash": "3418f7109a38172a28a3a202c8a878c1064f55911a82155c53a0b1ccde44e804",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "5efb86088319998cc5bdb201ef7f49e293b911508941a1bbbeff866b8872eec8",
+      "contentHash": "3418f7109a38172a28a3a202c8a878c1064f55911a82155c53a0b1ccde44e804",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -101,7 +101,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "5efb86088319998cc5bdb201ef7f49e293b911508941a1bbbeff866b8872eec8",
+      "contentHash": "3418f7109a38172a28a3a202c8a878c1064f55911a82155c53a0b1ccde44e804",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -110,7 +110,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "5efb86088319998cc5bdb201ef7f49e293b911508941a1bbbeff866b8872eec8",
+      "contentHash": "3418f7109a38172a28a3a202c8a878c1064f55911a82155c53a0b1ccde44e804",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "5efb86088319998cc5bdb201ef7f49e293b911508941a1bbbeff866b8872eec8",
+      "contentHash": "3418f7109a38172a28a3a202c8a878c1064f55911a82155c53a0b1ccde44e804",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -128,7 +128,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "5efb86088319998cc5bdb201ef7f49e293b911508941a1bbbeff866b8872eec8",
+      "contentHash": "3418f7109a38172a28a3a202c8a878c1064f55911a82155c53a0b1ccde44e804",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "5efb86088319998cc5bdb201ef7f49e293b911508941a1bbbeff866b8872eec8",
+      "contentHash": "3418f7109a38172a28a3a202c8a878c1064f55911a82155c53a0b1ccde44e804",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1489,7 +1489,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "5efb86088319998cc5bdb201ef7f49e293b911508941a1bbbeff866b8872eec8",
+      "contentHash": "3418f7109a38172a28a3a202c8a878c1064f55911a82155c53a0b1ccde44e804",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/upgrades/1.3.149.md

@@ -0,0 +1,64 @@
+---
+review-convergence: complete
+approved: true
+approved-by: echo (standing 12h deploy mandate, topic 13435; instar-codey node-ABI outage — deeper root)
+---
+
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed — the boot wrapper can now heal back to an asdf/nvm node
+
+This is the deeper root of the node-ABI outage that the previous release addressed
+at the heal layer. When an agent's Node pointer drifts to a newer Node (e.g. after
+a Homebrew upgrade installs Node 25) but its compiled database driver was built for
+the older Node it had been using via a version manager (asdf / nvm), the boot
+wrapper tries to "heal" by switching to a Node whose ABI matches the driver. But
+its candidate list only looked at the standard system Node locations
+(`/opt/homebrew/bin`, `/usr/local/bin`, `/usr/bin`) — it never looked at
+asdf/nvm-managed Nodes. So the one Node that could load the driver was invisible to
+it, and it self-healed FORWARD to the wrong ABI and got stuck. This took
+instar-codey offline for hours.
+
+The fix adds the system-resolved Node (`which node`, which resolves through
+asdf/nvm shims) to the heal candidate list. It is purely additive — it only expands
+a candidate pool that is already filtered to ABI-compatible nodes before selection,
+so it cannot make a heal worse. A migration-parity marker bump regenerates the boot
+wrapper on existing agents (including ones already stuck with the old script).
+
+## Summary of New Capabilities
+
+- The generated `instar-boot.cjs` node-heal now adds the PATH-resolved node
+  (`which node`) to its candidate list before the ABI-compatibility selection,
+  mirroring the already-correct `resolveNodeCandidates()` symlink-creation path.
+- `PostUpdateMigrator.migrateBootWrapperAbiCheck` now requires both the ABI-check
+  marker AND the new version-managed-node marker; agents missing the new marker are
+  regenerated on update.
+
+## What to Tell Your User
+
+If you ever upgrade Node on the machine running your agent, the agent can now
+recover its database engine on its own even when the Node it needs is one managed
+by a version manager like asdf or nvm. Previously it only knew to look in the
+standard system spots, so an agent could get stuck pointing at the wrong Node after
+an upgrade. Nothing to configure — it applies on the next update, and agents that
+were already stuck get the repair automatically.
+
+## Evidence
+
+- Root cause traced live in instar-codey logs: the boot wrapper self-healed the
+  node link forward to Homebrew Node 25 (ABI 141) while the better-sqlite3 binary
+  was ABI 127, with the matching asdf Node 22 absent from the candidate list.
+- The already-correct `resolveNodeCandidates()` in the same file (setup.ts) was
+  confirmed to include `which node`; only the generated boot-wrapper template
+  lacked it.
+- Unit: `tests/unit/PostUpdateMigrator-bootWrapperAbiCheck.test.ts` — new cases:
+  generated wrapper contains the `which node` discovery before the ABI loop
+  (cross-platform), regenerates when the new marker is absent (the codey case),
+  idempotent when both markers present.
+- Regression: boot-wrapper cjs/plist + durable-node-selection + shadow-install
+  self-heal + launchd-handoff suites — 46 tests pass.
+- `tsc --noEmit` clean; `npm run lint` clean.
+- Spec: `docs/specs/boot-wrapper-version-managed-node-candidates.md` (+ `.eli16.md`).
+- Side-effects: `upgrades/side-effects/boot-wrapper-version-managed-node-candidates.md`.

package/upgrades/1.3.150.md

@@ -0,0 +1,54 @@
+---
+review-convergence: complete
+approved: true
+approved-by: echo (standing 12h deploy mandate, topic 13435; live-found driving Codey)
+---
+
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed — the scope-check Stop hook no longer confuses Codex
+
+When an agent finishes a turn, a "scope-coherence checkpoint" Stop hook runs and, on
+the normal allow path, used to print a tiny `{decision:approve}` message. Claude
+treats that as allow, but Codex's Stop-hook contract is stricter: print
+`{decision:block,...}` to interrupt, print **nothing** to allow — an explicit
+approve message is rejected as "invalid stop hook JSON output". So on every Codex
+session completion that hook reported an error (the reply was already sent, so
+nothing actually broke, but the error was noisy and wrong). Found live while
+test-driving the Codex agent.
+
+The fix changes every allow path to emit nothing (empty stdout = allow), which is
+byte-equivalent for Claude and removes the error for Codex. The interrupt (block)
+path is unchanged. The hook is regenerated from source on every update, so all
+agents get the fix automatically.
+
+## Summary of New Capabilities
+
+- `scope-coherence-checkpoint` Stop hook is now Codex-stdout-safe: allow paths emit
+  empty stdout (instead of `{decision:approve}`); the block/checkpoint path is
+  unchanged. Sibling of the earlier autonomous-stop-hook Codex fix.
+
+## What to Tell Your User
+
+If you run a Codex-based agent, it will stop logging a spurious "invalid stop hook"
+error every time it finishes a turn. Nothing actually broke before (replies still
+went out), and Claude agents are unaffected — this just makes the scope-check hook
+speak Codex's dialect correctly. It applies automatically on the next update.
+
+## Evidence
+
+- Live: driving the Codex agent over Telegram, it completed a task + sent its reply,
+  then its session reported "Stop hook (failed) — invalid stop hook JSON output".
+- Audited the 5-hook Stop chain: only scope-coherence-checkpoint writes on the allow
+  path; the others write only on block (codex-safe), and the autonomous hook was
+  fixed earlier.
+- Unit: `tests/unit/scope-coherence-reentry.test.ts` — allow paths now exit 0 with
+  empty stdout; the generated hook contains no `{decision:approve}` and keeps
+  `{decision:block}`.
+- Regression: PostUpdateMigrator-buildStopHook + migration-parity-hooks +
+  installCodexHooks — 28 tests pass.
+- `tsc --noEmit` + `npm run lint` clean.
+- Spec: `docs/specs/codex-scope-coherence-stdout-safe.md` (+ `.eli16.md`).
+- Side-effects: `upgrades/side-effects/codex-scope-coherence-stdout-safe.md`.

package/upgrades/side-effects/boot-wrapper-version-managed-node-candidates.md

@@ -0,0 +1,51 @@
+# Side-effects — Boot-wrapper version-managed node candidates
+
+## 1. What files/state does this touch at runtime?
+The generated `<stateDir>/instar-boot.cjs` (regenerated by `installBootWrapper`
+when the PostUpdateMigrator detects the new marker is missing). At boot, the
+wrapper's self-heal may additionally run `which node` and, if it resolves an
+ABI-compatible node, repoint the `.instar/bin/node` symlink to it. No config,
+schema, or other files.
+
+## 2. Does it change any functional behavior?
+Yes, narrowly + additively: the node-heal candidate pool now also includes the
+PATH-resolved node (`which node` → asdf/nvm/volta). Selection is unchanged — the
+existing ABI-compatibility loop still picks the candidate that can load the
+existing better-sqlite3 binary. The only new outcome is: a heal that previously
+had NO compatible candidate (and stayed on the wrong-ABI node) can now find the
+version-managed node and heal correctly.
+
+## 3. What happens on failure / non-darwin / no `which`?
+- `which` missing or no node on PATH: the probe is wrapped in try/catch and
+  swallowed — the heal proceeds exactly as before with the well-known candidates.
+- Non-darwin: the boot wrapper + its migration are darwin/launchd-specific; the
+  migration short-circuits with a `non-darwin` skip.
+- A resolved node that can't load the module: skipped by the existing
+  ABI-compatibility loop, identical to any other incompatible candidate.
+
+## 4. Migration parity — do existing agents get it?
+Yes. `migrateBootWrapperAbiCheck` now requires BOTH the ABI-drift marker AND the
+`version-managed node candidates` marker to consider a wrapper current; an install
+missing the new marker (e.g. instar-codey) is regenerated via `installBootWrapper`
+on its next update. Idempotent (both markers → skip). New agents get it at setup.
+
+## 5. Could it spam / flood / burn resources?
+No. The heal path runs only at boot and only when the current node fails the
+better-sqlite3 load check (ABI drift) — the rare case. It adds at most one
+`which node` exec (5s timeout) to that already-rare path. No loop, no network.
+
+## 6. Rollback / off-switch?
+Revert the PR. The marker bump means a reverted version would (correctly) see the
+new marker as "extra" — the old sniff only required the ABI marker, so reverting
+leaves existing regenerated wrappers working (they still contain the ABI marker).
+No residual state, no flag.
+
+## 7. Concurrency / ordering?
+None new. The `which node` probe is a single synchronous exec inside the existing
+single-threaded `selfHealNodeSymlink()`, before the ABI-compatibility loop.
+
+## Blast radius
+Small + additive on a critical path. Two source edits (`setup.ts` template +
+`PostUpdateMigrator.ts` sniff) + test coverage. It only EXPANDS an already
+ABI-filtered candidate pool, mirrors the already-correct `resolveNodeCandidates()`
+in the same file, and cannot make a heal worse. Darwin/launchd-scoped.

package/upgrades/side-effects/codex-scope-coherence-stdout-safe.md

@@ -0,0 +1,42 @@
+# Side-effects — scope-coherence-checkpoint codex stdout-safe
+
+## 1. What files/state does this touch at runtime?
+Only the generated `.instar/hooks/instar/scope-coherence-checkpoint.js` (rewritten
+by the always-overwrite built-in-hook migration). At Stop time the hook reads its
+state file + (when deep) fetches active-job context — unchanged. The only change is
+what it writes to stdout on the allow paths (now nothing).
+
+## 2. Does it change any functional behavior?
+- **Claude:** none. Empty stdout == approve in Claude Code, identical to the prior
+  explicit `{decision:'approve'}`. The scope-checkpoint still blocks (prompts) when
+  deep-implementation + cooldown + min-age conditions are met.
+- **codex:** the allow paths no longer emit `{decision:'approve'}`, so codex stops
+  reporting "invalid stop hook JSON output" on session completion. The block path is
+  unchanged (codex accepts `{decision:'block',...}`).
+
+## 3. What happens on failure / weird input?
+The catch-all error path now allows (empty stdout) instead of emitting approve-JSON
+— same allow outcome, codex-safe. Malformed stdin still falls through to allow.
+
+## 4. Migration parity — do existing agents get it?
+Yes, automatically. The hook is in the always-overwrite built-in-hook set, so every
+agent regenerates it from the fixed `getScopeCoherenceCheckpointHook()` on its next
+update (incl. instar-codey). No marker/sniff needed.
+
+## 5. Could it spam / flood / burn resources?
+No — it REDUCES output (writes less). The hook runs only at Stop, same as before.
+
+## 6. Rollback / off-switch?
+Revert the PR; the next update regenerates the prior hook. No residual state, no
+flag. Reverting restores `{decision:'approve'}` (Claude unaffected; codex error
+returns).
+
+## 7. Concurrency / ordering?
+None new. Single short-lived hook process per Stop event, unchanged.
+
+## Blast radius
+Small + behavior-preserving on Claude, error-fixing on codex. One generator method
+in PostUpdateMigrator (six allow-path stdout writes removed; block path kept) + test
+updates. Mirrors the #604 codex-stdout convention. The broader approve-JSON class
+(other hooks + additionalContext signal hooks) is explicitly out of scope, tracked
+under #32 / ledger issue codex-stop-chain-multi-json-invalid.