instar 1.3.149 → 1.3.151

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.149",
+  "version": "1.3.151",
   "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:33:04.801Z",
-  "instarVersion": "1.3.149",
+  "generatedAt": "2026-05-31T08:16:51.978Z",
+  "instarVersion": "1.3.151",
   "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
+      "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
+      "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
+      "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
+      "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
+      "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
+      "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
+      "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
+      "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
+      "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
+      "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
+      "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
+      "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
+      "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
+      "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": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
+      "contentHash": "3418f7109a38172a28a3a202c8a878c1064f55911a82155c53a0b1ccde44e804",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1489,7 +1489,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "09e2c3f8c4a1f7d579224923247e788bf1b90a79ecbc629c4598179cf534ffa2",
+      "contentHash": "3418f7109a38172a28a3a202c8a878c1064f55911a82155c53a0b1ccde44e804",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {
@@ -1545,7 +1545,7 @@
       "type": "subsystem",
       "domain": "coordination",
       "sourcePath": "src/core/MultiMachineCoordinator.ts",
-      "contentHash": "44aa63dff721e15ad680db4c1d552abfc9e97e610498b6752496c222f27f323b",
+      "contentHash": "1dc3fb11c8ddea5cfe5f02561636cd54c1661d0e9da04f54607ad7679f027ea6",
       "since": "2025-01-01"
     },
     "subsystem:backup-manager": {

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/1.3.151.md

@@ -0,0 +1,65 @@
+---
+review-convergence: complete
+approved: true
+approved-by: echo (standing 12h deploy mandate, topic 13481; multi-machine live-transfer cascade)
+---
+
+# Instar Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed — a silent standby machine now correctly recognizes the awake machine as in charge
+
+Two narrow fixes for the multi-machine live session-transfer path (the one that
+moves a conversation from one machine to another when you say "move this to the
+Mac mini"). Both were found by running the transfer live between a laptop and a
+Mac mini and tracing why the handoff was rejected.
+
+1. **Signing-key fallback.** Each machine signs its mesh messages with a private
+   key file. The loader looked only for the current filename; a machine whose key
+   was saved under the older filename threw an error at boot, which silently
+   aborted its lease-coordination setup — so it never learned which machine was in
+   charge. The loader now also checks the legacy filename before giving up,
+   matching the fallback the lifeline loader already had.
+
+2. **Silent standby stops crowning itself.** A machine configured as a silent
+   standby (it never answers messages on its own) was still trying to claim the
+   "I'm in charge" lease at startup. On a machine without the shared git-backed
+   coordination medium, that produced a split-brain where both machines thought
+   they were in charge and the handoff was refused. A silent standby now only
+   watches the lease and never claims one, so the awake machine always wins and the
+   handoff is accepted.
+
+## Summary of New Capabilities
+
+- `MachineIdentity.loadSigningKey()` falls back to the legacy `signing-private.pem`
+  when the canonical `signing-key.pem` is absent (rethrows if neither exists).
+- `MultiMachineCoordinator.isLeaseObserveOnly` (driven by
+  `multiMachine.telegramPolling === false`): a silent standby skips lease
+  acquire/renew in both `initializeLease` and `tickLease`, only reconciling its
+  role to the observed lease — removing the git-less split-brain epoch leapfrog.
+
+## What to Tell Your User
+
+If you run your agent on more than one machine, moving a live conversation from one
+machine to another is now more reliable. A quiet backup machine will correctly
+treat your main machine as the one in charge instead of fighting it for control,
+and a machine whose security key was saved under an older filename will no longer
+fail to join the handoff. Nothing to configure — it applies on the next update.
+
+## Evidence
+
+- Both bugs were found live on the two-machine setup (laptop plus Mac mini) by
+  instrumenting the lease broadcast or observe path: the mini threw ENOENT on the
+  canonical key at boot so its lease coordinator never attached, and once that was
+  fixed it rejected the laptop's lease as below its own self-issued epoch floor.
+- Unit, `tests/unit/machine-identity.test.ts`: loadSigningKey falls back to the
+  legacy name and still throws when neither file exists.
+- Unit, `tests/unit/multi-machine-coordinator.test.ts`: a silent standby never
+  acquires or renews (across initializeLease and tickLease); a normal machine does
+  acquire; the observe-only flag reflects telegramPolling false.
+- 109 related unit tests pass (machine-identity, multi-machine-coordinator,
+  LeaseCoordinator, mesh-signing-key-resolution, multimachine-syncstatus);
+  tsc --noEmit clean.
+- Spec, `docs/specs/silent-standby-lease.md` plus the .eli16.md sibling.
+- Side-effects, `upgrades/side-effects/silent-standby-lease.md`.

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.

package/upgrades/side-effects/silent-standby-lease.md

@@ -0,0 +1,115 @@
+# Side-Effects Review — Silent-standby git-less lease (observe-only + legacy-key fallback)
+
+**Version / slug:** `silent-standby-lease`
+**Date:** `2026-05-31`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+Two narrowly-scoped fixes for bugs #4 + #5 of the multi-machine live-transfer
+cascade:
+
+1. `MachineIdentity.loadSigningKey()` — on ENOENT for the canonical
+   `signing-key.pem`, fall back to the legacy `signing-private.pem` if present,
+   else rethrow. (The mini's key was under the legacy name; the lease setup threw
+   at boot, so the `LeaseCoordinator` never attached and the mini never resolved a
+   holder.)
+2. `MultiMachineCoordinator` — new `isLeaseObserveOnly` getter
+   (`multiMachine.telegramPolling === false`). A silent standby skips
+   `acquireIfEligible`/`renew` in both `initializeLease` and `tickLease`; it only
+   reconciles its role to whatever lease it observes. It never holds its own lease,
+   so with the git-less `LocalLeaseStore` (no shared CAS) it can't leapfrog the
+   primary's epoch and reject the primary as `below-git-floor`.
+
+## Decision-point inventory
+
+- **loadSigningKey fallback branch** — ENOENT on canonical → try legacy name →
+  exists? read it : rethrow original. Both sides covered by unit tests.
+- **isLeaseObserveOnly gate** — true (telegramPolling:false) → observe-only path
+  (no acquire/renew); false/undefined → unchanged acquire+renew path. Both sides
+  covered by unit tests (silent standby never acquires; normal machine does).
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject?** A silent standby
+(`telegramPolling:false`) no longer acquires a lease at all — so it can never
+become awake on its own. That is the INTENT: a muted standby that became "awake but
+not serving" is the incoherent state we are removing. A machine that should be able
+to take over sets `telegramPolling:true` (or unsets it), which is the unchanged
+acquire path. The key fallback rejects nothing — it only ADDS a second lookup
+location before the same rethrow.
+
+## 2. Under-block
+
+**What does this still miss?** It does not add auto-failover for a silent standby
+(out of scope — failover for it is a deliberate un-mute). It does not add a shared
+CAS to `LocalLeaseStore`; the split-brain is avoided by not acquiring rather than
+by making git-less acquisition safe (correct for the one-awake-machine model; the
+active-active pool, which needs real shared CAS, remains git-backed). The key
+fallback covers only the one known legacy name (`signing-private.pem`), matching
+the lifeline loader's existing fallback — not an open-ended search.
+
+## 3. Level-of-abstraction fit
+
+**Right layer?** Yes. The key fallback lives in the single `loadSigningKey()`
+loader that every lease/transport consumer already calls (one chokepoint). The
+observe-only gate lives in `MultiMachineCoordinator`'s two lease entry points
+(`initializeLease`, `tickLease`) — the only places acquisition is decided — derived
+from the same `telegramPolling` flag that already designates a silent standby
+elsewhere. No new config surface, no duplicated rule.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+No blocking authority added. The observe-only gate REMOVES an action (acquisition)
+for a configured-silent machine; it never blocks a message or an operation. The key
+fallback is a pure read-path widen with an unchanged terminal rethrow. Neither path
+gates any user-facing or outbound behavior.
+
+## 5. Interactions
+
+`loadSigningKey` feeds `HttpLeaseTransport` (lease broadcast/observe) and
+machineAuth signing; widening it only makes a previously-throwing legacy-keyed
+machine succeed — no consumer sees a different value, only a present-vs-throw
+difference. The observe-only gate interacts with `reconcileRoleToLease` (still
+called every tick, now inside each branch) and with `LeaseCoordinator.effectiveView`
+(a standby with an empty `LocalLeaseStore` folds the primary's observed broadcast
+cleanly). Idempotent: both paths produce the same result on repeated boots/ticks.
+
+## 6. External surfaces
+
+No HTTP routes, no config defaults, no notifications, no Telegram. `/health`'s
+`multiMachine.syncStatus.leaseHolder` will now correctly resolve to the primary on a
+silent standby (the visible, intended effect). Pure code.
+
+## 7. Rollback cost
+
+Low. Revert the PR: `loadSigningKey` returns to canonical-only (re-bricks a
+legacy-keyed machine's lease setup) and the coordinator returns to always-acquire
+(re-introduces the split-brain on git-less standbys). No schema, no migration, no
+persisted state created by this change. The one deploy-time action (clear the mini's
+stale self-issued `lease-local.json`) is a one-shot cleanup, not a rollback cost.
+
+## Conclusion
+
+Minimal, additive-or-removing-an-action change with both decision sides unit-tested,
+no new authority, no external surface beyond a corrected `/health` field, and a cheap
+revert. It closes the final two layers blocking the live two-machine transfer.
+
+## Second-pass review (if required)
+
+Not required — no new blocking authority, no destructive op, both decision branches
+covered by tests, reversible. (Live two-machine transfer proof is the Tier-3 gate
+that follows deploy.)
+
+## Evidence pointers
+
+- `tests/unit/machine-identity.test.ts` — loadSigningKey legacy fallback + still-throws.
+- `tests/unit/multi-machine-coordinator.test.ts` — observe-only never acquires/renews;
+  normal machine acquires; `isLeaseObserveOnly` reflects the flag.
+- 109 related unit tests green (machine-identity, coordinator, LeaseCoordinator,
+  mesh-signing-key-resolution, multimachine-syncstatus); `tsc --noEmit` clean.
+- Spec: `docs/specs/silent-standby-lease.md` (+ `.eli16.md`).
+- `upgrades/NEXT.md` — upgrade guide.