instar 1.3.197 → 1.3.198

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.197",
+  "version": "1.3.198",
   "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-06-02T04:46:08.483Z",
-  "instarVersion": "1.3.197",
+  "generatedAt": "2026-06-02T05:25:38.499Z",
+  "instarVersion": "1.3.198",
   "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": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "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": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "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": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "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": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "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": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "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": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "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": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "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": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "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": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "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": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "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": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "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": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "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": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "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": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "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": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1489,7 +1489,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/upgrades/1.3.198.md

@@ -0,0 +1,24 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+An agent that loses its private code copy can now actually reinstall itself at boot.
+
+When the boot wrapper detects a missing "shadow install" it runs `npm install` to self-heal. Some packages run native setup scripts that shell out to `node`/`npm` by name — and under macOS launchd the boot process often has a stripped `PATH` without them, so the reinstall died with "command not found" and the agent stayed stuck (looping on "Shadow install missing"). The reinstall now puts the resolved node directory on PATH and sets npm's scripts-prepend-node-path, so those setup scripts resolve node/npm and the self-heal completes. Existing agents get the fixed wrapper regenerated automatically on update.
+
+## What to Tell Your User
+
+Nothing to do. This makes an agent's automatic self-repair actually work when its private code copy goes missing — the case where it most needs to recover on its own, unattended. A healthy agent is completely unaffected; this only changes the recovery path.
+
+## Summary of New Capabilities
+
+- The boot-wrapper reinstall (`instar-boot.cjs` and `instar-boot.sh`) prepends the resolved node directory to PATH and sets `npm_config_scripts_prepend_node_path` so native postinstall scripts (e.g. sharp) resolve node/npm under a launchd-spawned boot child instead of failing with "command not found".
+- The post-update migration regenerates older boot wrappers that predate this fix (it now requires the install-path marker to consider a wrapper current), so deployed agents receive the fix on their next update — not just new installs.
+
+## Evidence
+
+- Root cause of a real 2026-06-02 failure: a paired test agent could not start; `instar-boot` looped on "Shadow install missing" and a manual reinstall failed on sharp's postinstall with `sh: node: command not found`; re-running with node on PATH fixed it immediately.
+- `tsc --noEmit` clean. `PostUpdateMigrator-bootWrapperAbiCheck` extended to 8 green tests (3-marker idempotency, regen-when-install-path-marker-absent, generated `.cjs` passes `node --check` + carries the env, `.sh` carries the PATH export); 30 sibling boot-wrapper tests still green. Side-effects review: upgrades/side-effects/fix-bootwrapper-install-path.md.

package/upgrades/side-effects/fix-bootwrapper-install-path.md

@@ -0,0 +1,83 @@
+# Side-Effects Review — Boot-wrapper reinstall: put node on PATH for native postinstalls
+
+**Version / slug:** `fix-bootwrapper-install-path`
+**Date:** `2026-06-02`
+**Author:** `echo`
+**Tier:** 1 (small, well-understood bugfix; ELI16 + side-effects, no converged spec) — but HIGH blast radius (boot shim), reviewed accordingly
+**Parent principle:** Cross-Machine Coherence / Bootstrap Robustness — an agent must be able to self-heal its own install
+
+## Summary of the change
+
+The boot wrapper (`instar-boot.cjs` / `instar-boot.sh`, generated by `installBootWrapper`
+in `src/commands/setup.ts`) self-heals a missing shadow install by running `npm install`.
+That `npm install` was spawned with **no `env` / no PATH augmentation**, so native
+postinstall scripts (e.g. `sharp`: `sh -c "node install/check.js || npm run build"`) ran in
+a subshell whose PATH — under a launchd-spawned boot child — has no `node`/`npm`, dying with
+`command not found`. The reinstall then aborts and the shadow install never heals.
+
+**Observed live (2026-06-02):** a throwaway mini agent could not start — `instar-boot`
+looped on "Shadow install missing", and a manual reinstall reproduced it: it failed on
+`sharp`'s postinstall (`sh: node: command not found`). Re-running with `node` on PATH
+succeeded immediately.
+
+### What changed
+- `src/commands/setup.ts` — `installBootWrapper`:
+  - **`.cjs` (jsWrapper):** the reinstall `execFileSync(nodeBin, [npmCli, 'install', …])` now
+    passes `env: installEnv` where `installEnv` prepends `path.dirname(nodeBin)` to `PATH` and
+    sets `npm_config_scripts_prepend_node_path: 'true'`.
+  - **`.sh` (bashWrapper):** the reinstall now runs with
+    `PATH="$(dirname "$NODE_BIN"):$PATH" npm_config_scripts_prepend_node_path=true` prefixed.
+- `src/core/PostUpdateMigrator.ts` — `migrateBootWrapperAbiCheck`: the "already current" guard
+  now ALSO requires the `npm_config_scripts_prepend_node_path` marker, so existing agents whose
+  wrapper predates this fix are regenerated on update (Migration Parity).
+
+## Decision-point inventory
+- reinstall env: augment vs inherit → augment (prepend node dir + npm flag). Inheriting the
+  launchd PATH is the bug.
+- migration: add a 3rd required marker vs leave 2 → add the marker (otherwise deployed agents
+  with the 2 prior markers never regenerate and never get the fix).
+- auto-re-port / auto-anything else: none — purely the reinstall env.
+
+## 1. Over-correction risk
+The env only AUGMENTS PATH (prepends node dir; keeps the rest) and sets one npm flag. A healthy
+agent never enters the reinstall branch at all (`if (!fs.existsSync(SHADOW))`), so the change is
+inert unless the shadow install is actually missing. `npm_config_scripts_prepend_node_path` is
+npm's own documented option for exactly this case.
+
+## 2. Under-correction risk
+The migration regenerates only wrappers missing the new marker; agents already regenerated stay
+put (idempotent). The `.sh` variant is for manual/Linux use; the launchd-critical path is `.cjs`.
+
+## 3. Level-of-abstraction fit
+The fix lives in the single boot-wrapper generator (`installBootWrapper`) that both `init` and the
+migration call — one source, both consumers. No scattering.
+
+## 4. Signal vs Authority
+Pure deterministic env construction (no LLM/heuristic). Appropriate.
+
+## 5. External surfaces
+None. No route/config-schema change. The generated wrapper gains an env on one spawn.
+
+## 6. Interactions with existing primitives
+The reinstall's debounce marker, the ABI-aware node self-heal, and the version-managed-node
+candidate discovery are all unchanged; this only adds an env to the npm spawn and a 3rd marker
+to the migration's idempotency sniff (composes with the existing two).
+
+## 7. Rollback cost
+Trivial: drop the `env`/PATH additions and the 3rd marker clause. No persistent state.
+
+## Migration parity
+- New agents: `installBootWrapper` (via `init`) writes the fixed wrapper.
+- Existing agents: `migrateBootWrapperAbiCheck` regenerates `instar-boot.cjs` because the new
+  `npm_config_scripts_prepend_node_path` marker is absent. Idempotent — re-running skips once the
+  marker is present.
+
+## Tests
+`tsc --noEmit` clean. `PostUpdateMigrator-bootWrapperAbiCheck` extended to 8 tests (all green):
+the "skip" idempotency case now requires all THREE markers; a new regen case for a wrapper with
+the two prior markers but missing the install-path marker; a generated-content test asserting the
+`.cjs` reinstall passes `env: installEnv` with `npm_config_scripts_prepend_node_path` + the PATH
+prepend AND that the generated `.cjs` passes `node --check` (guards against template-escaping
+bricking the boot shim); a `.sh` generated-content test. 30 sibling boot-wrapper tests
+(`bootWrapperCjs`, `plist-coherence`, `lifeline-shadow-install-self-heal`, `init-join-launchd-handoff`)
+all still green — no regressions.