instar 1.3.148 → 1.3.149

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.148",
+  "version": "1.3.149",
   "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-31T07:33:04.801Z",
+  "instarVersion": "1.3.149",
   "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
       "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
       "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
       "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
       "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
       "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
       "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
       "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
       "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
       "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
       "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
       "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
       "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
       "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
       "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1489,7 +1489,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "5efb86088319998cc5bdb201ef7f49e293b911508941a1bbbeff866b8872eec8",
+      "contentHash": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
       "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/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.