instar 1.3.874 → 1.3.876

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.874",
+  "version": "1.3.876",
   "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-07-18T20:20:52.277Z",
-  "instarVersion": "1.3.874",
+  "generatedAt": "2026-07-18T20:43:31.622Z",
+  "instarVersion": "1.3.876",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "b8e7e8d2210384e18a9a676f344c306005757886bebdb97a5afb71678069a3f2",
+      "contentHash": "e63a480f47775520068fe640a60c1f95edac847024de9fdb61dcfd5fe5e3e745",
       "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": "b8e7e8d2210384e18a9a676f344c306005757886bebdb97a5afb71678069a3f2",
+      "contentHash": "e63a480f47775520068fe640a60c1f95edac847024de9fdb61dcfd5fe5e3e745",
       "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": "b8e7e8d2210384e18a9a676f344c306005757886bebdb97a5afb71678069a3f2",
+      "contentHash": "e63a480f47775520068fe640a60c1f95edac847024de9fdb61dcfd5fe5e3e745",
       "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": "b8e7e8d2210384e18a9a676f344c306005757886bebdb97a5afb71678069a3f2",
+      "contentHash": "e63a480f47775520068fe640a60c1f95edac847024de9fdb61dcfd5fe5e3e745",
       "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": "b8e7e8d2210384e18a9a676f344c306005757886bebdb97a5afb71678069a3f2",
+      "contentHash": "e63a480f47775520068fe640a60c1f95edac847024de9fdb61dcfd5fe5e3e745",
       "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": "b8e7e8d2210384e18a9a676f344c306005757886bebdb97a5afb71678069a3f2",
+      "contentHash": "e63a480f47775520068fe640a60c1f95edac847024de9fdb61dcfd5fe5e3e745",
       "since": "2025-01-01"
     },
     "hook:self-stop-guard": {
@@ -65,7 +65,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/self-stop-guard.js",
-      "contentHash": "b8e7e8d2210384e18a9a676f344c306005757886bebdb97a5afb71678069a3f2",
+      "contentHash": "e63a480f47775520068fe640a60c1f95edac847024de9fdb61dcfd5fe5e3e745",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -74,7 +74,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "b8e7e8d2210384e18a9a676f344c306005757886bebdb97a5afb71678069a3f2",
+      "contentHash": "e63a480f47775520068fe640a60c1f95edac847024de9fdb61dcfd5fe5e3e745",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -83,7 +83,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "b8e7e8d2210384e18a9a676f344c306005757886bebdb97a5afb71678069a3f2",
+      "contentHash": "e63a480f47775520068fe640a60c1f95edac847024de9fdb61dcfd5fe5e3e745",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "b8e7e8d2210384e18a9a676f344c306005757886bebdb97a5afb71678069a3f2",
+      "contentHash": "e63a480f47775520068fe640a60c1f95edac847024de9fdb61dcfd5fe5e3e745",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -101,7 +101,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "b8e7e8d2210384e18a9a676f344c306005757886bebdb97a5afb71678069a3f2",
+      "contentHash": "e63a480f47775520068fe640a60c1f95edac847024de9fdb61dcfd5fe5e3e745",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -110,7 +110,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "b8e7e8d2210384e18a9a676f344c306005757886bebdb97a5afb71678069a3f2",
+      "contentHash": "e63a480f47775520068fe640a60c1f95edac847024de9fdb61dcfd5fe5e3e745",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "b8e7e8d2210384e18a9a676f344c306005757886bebdb97a5afb71678069a3f2",
+      "contentHash": "e63a480f47775520068fe640a60c1f95edac847024de9fdb61dcfd5fe5e3e745",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -128,7 +128,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "b8e7e8d2210384e18a9a676f344c306005757886bebdb97a5afb71678069a3f2",
+      "contentHash": "e63a480f47775520068fe640a60c1f95edac847024de9fdb61dcfd5fe5e3e745",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "b8e7e8d2210384e18a9a676f344c306005757886bebdb97a5afb71678069a3f2",
+      "contentHash": "e63a480f47775520068fe640a60c1f95edac847024de9fdb61dcfd5fe5e3e745",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -146,7 +146,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "b8e7e8d2210384e18a9a676f344c306005757886bebdb97a5afb71678069a3f2",
+      "contentHash": "e63a480f47775520068fe640a60c1f95edac847024de9fdb61dcfd5fe5e3e745",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1562,7 +1562,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "b8e7e8d2210384e18a9a676f344c306005757886bebdb97a5afb71678069a3f2",
+      "contentHash": "e63a480f47775520068fe640a60c1f95edac847024de9fdb61dcfd5fe5e3e745",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/upgrades/{1.3.874.md → 1.3.875.md}

@@ -5,6 +5,31 @@
 
 ## What Changed
 
+The `mcp-health-autorefresh.sh` built-in hook (auto-restart-on-MCP-inaccessible: at
+session start it probes `claude mcp list` and, when an allowlisted MCP like playwright
+failed to connect, performs ONE loop-guarded `/sessions/refresh` so the tool re-registers)
+was **silently inert in production on coreutils-less Macs** — the platform instar agents
+actually run on. Its probe ran `timeout 45 claude mcp list`; bare `timeout` is a GNU
+coreutils binary absent on stock macOS, the command-not-found was swallowed by
+`2>/dev/null || true`, and the empty capture hit the script's quiet-exit guard. No error,
+no log — the recovery feature simply never ran. Linux CI never saw it because `timeout`
+always exists there.
+
+The generated script (authored in `src/core/PostUpdateMigrator.ts` →
+`getMcpHealthAutorefreshHook()`) now bounds the probe with the same portable timeout
+LADDER the autonomous stop hook's real-check runner uses: `timeout` → `gtimeout` →
+perl-alarm fallback (fork + setpgrp + group-KILL on a 45s alarm, exit 124 on timeout,
+and the correct 128+signal exit mapping for a signal-killed child — GNU-timeout
+semantics). With no bounded runner present at all, the script stays dark rather than run
+the probe unbounded. All safety properties are untouched: dark by default,
+explicit-false wins, allowlist-scoped, hard once-per-(session, failed-set) loop-guard.
+
+Migration parity: this hook is always-overwrite in `migrateHooks()`, so every deployed
+agent gets the fixed script automatically on this update — no manual step.
+
+This also fixes the deterministic macOS-only failure of
+`tests/unit/PostUpdateMigrator-mcpAutorefresh.test.ts`.
+
 The autonomous stop hook's real-check verification runner is now portable across the
 timeout-ladder rungs on the exit-status contract for signal-death. On macOS (no GNU
 `timeout`/`gtimeout`), the perl fallback rung mapped a check command killed by a signal to
@@ -37,6 +62,12 @@ This is PR-A of a two-PR staged landing. The runtime apprenticeship gate, accept
 
 ## What to Tell Your User
 
+If your agent runs on a Mac: a small self-healing feature that was accidentally asleep
+now works. When an important tool server (like the browser tool) fails to come up at the
+start of a session, the agent can restart that session once — automatically and at most
+once — so the tool comes back, instead of quietly running without it. Nothing to
+configure; the feature still respects its existing off-by-default/allowlist settings.
+
 Nothing visible changes in day-to-day use. On Macs, autonomous work sessions are now
 stricter about proving they're really done: a verification check that gets cut off
 mid-output can no longer be mistaken for a passing check, so a session can't slip out
@@ -47,6 +78,9 @@ No user-visible behavior changes in this release. This is infrastructure honesty
 
 ## Summary of New Capabilities
 
+- No new capabilities — a portability fix that makes the existing (config-gated)
+  MCP auto-refresh recovery actually run on macOS, identically to Linux.
+
 - No new capabilities — a safety/portability fix. The autonomous completion guarantee
   ("a failing real check always means keep working") now holds identically on macOS and
   Linux.
@@ -57,6 +91,16 @@ No user-visible behavior changes in this release. This is infrastructure honesty
 
 ## Evidence
 
+- Root cause reproduced on macOS 26 (no `timeout`/`gtimeout` installed): the probe line
+  produced an empty LIST and the script exited silently before any observable action.
+- Perl-rung contract proven live on this machine: hung command bounded (exit 124),
+  normal exit codes passed through (3 → 3), signal-death mapped to 128+signal
+  (SIGTERM → 143), stdout captured intact.
+- `tests/unit/PostUpdateMigrator-mcpAutorefresh.test.ts`: 9/9 pass (previously 1
+  deterministic failure on macOS), including `bash -n` syntax validity and the
+  always-overwrite migration-parity pin.
+- 14 targeted migrator + stop-hook sibling test files: 139/139 pass on this branch.
+
 - Instrumented reproduction on macOS 26 (Node 24): the shipped hook returned the
   allow-exit message for `printf "\xe4\xb8\xad%.0s" $(seq 1 100000); exit 1`
   (`PIPESTATUS[0]=0` from the perl rung) before the fix; after the fix it returns a valid

package/upgrades/1.3.876.md

@@ -0,0 +1,50 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Added `docs/AI-EMPLOYEE-ROADMAP.md` — the program-level roadmap that maps the
+apprenticeship program onto instar's top-level goal: an agent that works as a
+fully engaged AI employee. It defines the three capabilities that make up that
+posture — multi-machine coherence (3–4 machines, one identity), first-class
+chat-platform citizenship (Telegram today, Slack as the primary workplace
+surface next), and multi-principal service (every staff member served by the
+same agent with no identity bleed) — and lays each out as a stage ladder
+(A1→A4, B1→B3, C1→C3) with an explicit, evidence-gated exit bar. The method is
+prove-it-on-the-apprentice-first: every capability is developed and de-risked
+on a prototype agent under observation, through the same user channels a human
+would use, before any production agent inherits the configuration. Graduation
+is serial and evidence-gated — recorded, artifact-backed acceptances, never a
+vibe.
+
+This is documentation only. No code, config, hook, job, template, or test
+changes; no runtime surface; no behavior change for any deployed agent.
+
+## What to Tell Your User
+
+Nothing changes in how your agent behaves. The project now carries a public
+roadmap document describing where the platform is headed — an agent that works
+like a real employee: present on several machines as one coherent identity, a
+well-mannered citizen of workplace chat (Slack next), and able to serve a whole
+team without mixing people up — and how each step gets proven on a supervised
+prototype before it ever reaches a production agent.
+
+## Summary of New Capabilities
+
+- None (documentation only). New artifact: `docs/AI-EMPLOYEE-ROADMAP.md`, the
+  program-level map from the apprenticeship program to the full AI-employee
+  posture, with evidence-gated graduation criteria per capability.
+
+## Evidence
+
+- `docs/AI-EMPLOYEE-ROADMAP.md` — the roadmap itself (deliberately
+  organization-agnostic for this public repo).
+- `docs/specs/ai-employee-roadmap.eli16.md` — plain-English explainer.
+- `upgrades/side-effects/ai-employee-roadmap.md` — side-effects review; every
+  question resolves to "documentation-only, no runtime surface";
+  multi-machine posture unified-via-git; rollback = revert the doc.
+- Sanity: the whole-tree stall-coverage CI ratchet
+  (`tests/unit/stall-coverage-ratchet.test.ts`) runs green on this tree —
+  the change coexists with the freshly-landed PR-A ratchet.

package/upgrades/side-effects/ai-employee-roadmap.md

@@ -0,0 +1,86 @@
+# Side-Effects Review — ai-employee-roadmap (docs-only)
+
+**Change:** adds `docs/AI-EMPLOYEE-ROADMAP.md` — the program-level roadmap from
+the apprenticeship program to a full AI-employee posture (multi-machine
+coherence, first-class Slack citizenship, multi-principal service), with
+per-capability stage ladders and evidence-gated exit bars. Plus the standard
+artifacts (this review, the ELI16, the release fragment). **No source, config,
+template, hook, job, or test files are touched.** Documentation-only, no
+runtime surface.
+
+## Phase 1 principle check (recorded)
+
+Does this change involve a decision point? **No.** The document describes a
+program and its graduation criteria; it ships no validator, gate, sentinel, or
+any code that evaluates anything. The graduation decisions it describes are
+explicitly human/overseer acceptances recorded as artifacts — and none of that
+machinery ships here. Signal-vs-authority is not implicated: nothing here can
+block, allow, or judge.
+
+## 1. Over-block
+
+Nothing can be over-blocked: documentation-only, no runtime surface. The change
+introduces no blocking surface of any kind — no CI check, no gate, no hook. The
+only "block" it could ever exert is social (a reader citing the roadmap), which
+is outside the runtime.
+
+## 2. Under-block
+
+Nothing can be under-blocked: documentation-only, no runtime surface. No
+enforcement is promised by this change, so there is no enforcement to be
+incomplete. The exit bars the document names are enforced (or not) by the
+machinery of their own workstreams, each with its own specs and reviews.
+
+## 3. Level-of-abstraction fit
+
+Right layer. A program-level roadmap belongs in `docs/` at the repo root
+(`docs/AI-EMPLOYEE-ROADMAP.md`), above the individual capability specs it
+references and below nothing — it is the map that points at the specs, not a
+duplicate of any of them. It deliberately contains no schedule and no
+organization-specific content (agent names, staffing, rollout order stay with
+the operator, outside this public repo).
+
+## 4. Signal vs authority compliance
+
+Compliant vacuously: documentation-only, no runtime surface. The change creates
+no authority (nothing blocks) and no signal (nothing observes). The document
+itself *describes* the signal→authority discipline of the apprenticeship
+(observe-only guards graduating to enforcing on evidence), which is consistent
+with `docs/signal-vs-authority.md`, but describing it is not implementing it.
+
+## 5. Interactions
+
+None at runtime: documentation-only, no runtime surface. No job, sentinel,
+route, or hook reads this file. Repo-level interactions are benign: it cites
+existing specs (e.g. the apprenticeship scaffold spec, framework stall-coverage
+work) by path; if those move, the references go stale — a docs-freshness
+concern (the cartographer sweep's domain), not a behavior risk.
+
+## 6. External surfaces
+
+None: documentation-only, no runtime surface. No API route, no config key, no
+message to any user, no notification, no npm-shipped runtime change (the file
+rides the package inertly as documentation). The document was deliberately
+written organization-agnostic for this public repo — it names no organization,
+person, or deployed agent.
+
+## 7. Multi-machine posture
+
+**Unified-via-git.** The document is a repo-tracked file; every machine sees
+the same content at the same SHA. No per-machine runtime state is created, so
+there is nothing to strand, sync, or reconcile.
+
+## 8. Rollback cost
+
+Revert the doc (one revert of this commit). No data migration, no agent state,
+no config, no deployed-behavior change to unwind. Cheapest possible rollback
+class.
+
+## Second-pass review
+
+**Not required.** The second-pass trigger is for changes that wire
+block/allow decisions, session-lifecycle, messaging, or dispatch behavior —
+this change wires nothing: documentation-only, no runtime surface, no decision
+point, no enforcement. There is no code for a second reviewer to contradict
+against the artifact; the only reviewable claim ("the doc says what the ELI16
+and fragment say it says") is verified by reading the three files side by side.

package/upgrades/side-effects/mcp-autorefresh-timeout-macos.md

@@ -0,0 +1,126 @@
+# Side-Effects Review — MCP Auto-Refresh Hook macOS Timeout Portability
+
+**Version / slug:** `mcp-autorefresh-timeout-macos`
+**Date:** `2026-07-18`
+**Author:** Echo (autonomous, Tier-1 fix cycle, tracked ref CMT-896)
+**Second-pass reviewer:** self-reviewed-final-diff (session-lifecycle adjacent — the hook can trigger a /sessions/refresh — second pass required; performed as a genuinely fresh re-read of this artifact against the final diff; see "Second-pass review" below)
+
+## Summary of the change
+
+`tests/unit/PostUpdateMigrator-mcpAutorefresh.test.ts` ("DEV agent auto-enables…") failed
+deterministically on macOS while Linux CI was green. Root cause: the generated
+`mcp-health-autorefresh.sh` (authored in
+`src/core/PostUpdateMigrator.ts` → `getMcpHealthAutorefreshHook()`) ran its health probe
+as `LIST=$(timeout 45 "$CLAUDE_BIN" mcp list 2>/dev/null || true)`. Bare `timeout` is GNU
+coreutils — absent on coreutils-less Macs (this machine has neither `timeout` nor
+`gtimeout` nor Homebrew). The command-not-found error was swallowed by `2>/dev/null || true`,
+LIST stayed empty, and the script's `[ -n "$LIST" ] || exit 0` guard exited silently —
+so the auto-restart-on-MCP-inaccessible feature was **silently inert in production on
+macOS**, the platform instar agents actually run on. Same platform-gap family as the
+autonomous stop hook's real-check runner fix (previous cycle).
+
+Files modified (single source file):
+- `src/core/PostUpdateMigrator.ts` — the generated hook's probe line becomes a portable
+  bounded-runner LADDER mirroring the stop hook: `timeout` → `gtimeout` → perl-alarm
+  fallback. The perl rung forks, `setpgrp` + group-KILL on a 45s alarm (exit 124), and
+  maps child status with `exit(($?&127) ? 128+($?&127) : ($?>>8))` — GNU-timeout
+  semantics, so a signal-killed probe is never mistaken for a clean exit. If NO bounded
+  runner exists, the script stays dark (exit 0) — it never runs the probe unbounded.
+
+## The eight questions
+
+1. **Over-block** — None identified. On Linux (and Macs with coreutils) the first rung is
+   byte-identical to the old behavior. On coreutils-less Macs the change strictly
+   *enables* previously-dead functionality; it rejects nothing new. The no-runner-at-all
+   case (no timeout, no gtimeout, no perl) exits 0 exactly as the script effectively did
+   before — but now by explicit design with a comment, not by accident.
+2. **Under-block** — The fix closes the silent-inert hole. Remaining, pre-existing and
+   unchanged: a `claude mcp list` that exits 0 but prints garbage is still trusted as a
+   listing (grep simply won't match); the 45s bound is unchanged. The perl rung's
+   KILL-on-alarm is stricter than GNU `timeout`'s default TERM-then-KILL — acceptable
+   here because the probe is read-only (`mcp list` mutates nothing worth a graceful
+   shutdown). No issue identified.
+3. **Level-of-abstraction fit** — Correct layer: the bounded-runner contract lives inside
+   the generated script at the single probe callsite, exactly parallel to the stop hook's
+   ladder (the established in-repo pattern for "bound a command portably"). A shared
+   sourced library for the two ladders would be a bigger refactor of generated-script
+   plumbing than this fix warrants and would couple two independently-shipped hooks;
+   deliberately not done.
+4. **Signal-vs-authority compliance** — Not a message-flow decision point; deterministic
+   exit-status plumbing in an existing dark-by-default hook. The hook's authority shape
+   is unchanged: dark default, explicit-false wins, allowlist scope, hard loop-guard
+   (at most ONE refresh per (session, failed-set)). No brittle blocking heuristic added
+   (`docs/signal-vs-authority.md` reviewed — this adds no gate). No issue identified.
+5. **Interactions** — The ladder only changes HOW the probe is bounded, not what
+   downstream sees: LIST parsing, allowlist matching, marker loop-guard, and the
+   /sessions/refresh call are untouched. On machines with `timeout` (all of CI, most
+   Linux) the executed bytes are the same as before, so zero interaction delta there.
+   The perl rung's process-group KILL cannot touch the parent script (child is
+   `setpgrp`'d into its own group). No double-fire: rungs are exclusive `elif`s.
+6. **External surfaces** — None new. No network, config, API, or route changes. The
+   generated file's content changes (comment + ladder), which the existing unit suite
+   re-pins (`bash -n` syntax validity, safety-invariant greps, migration parity). Agents'
+   observable behavior change: on coreutils-less Macs an allowlisted failed MCP can now
+   actually trigger the (config-gated, loop-guarded) single session refresh — i.e. the
+   feature works as its spec and config already documented.
+7. **Multi-machine posture (Cross-Machine Coherence)** — Machine-local BY DESIGN: the
+   hook runs at session start on the machine hosting the session, probing THAT machine's
+   MCP registrations; its marker state (`.instar/state/mcp-autorefresh-marker.json`) is
+   per-machine and must not replicate (another machine's MCP health is meaningless here).
+   The fix makes behavior machine-uniform across the pool (a Mac and a Linux box now run
+   the same probe contract). No user-facing notice, no durable cross-machine state, no
+   URLs.
+8. **Rollback cost** — Low. Single-file revert of one commit restores the prior generated
+   script; the next migration pass always-overwrites the deployed copy back (same
+   delivery path as the fix). No data migration, no state repair — the marker file format
+   is unchanged. Reverting re-opens the silent-inert-on-macOS hole, so the back-out plan
+   is revert-and-re-fix.
+
+## Migration Parity (explicit)
+
+`migrateHooks()` writes this hook with an unconditional `fs.writeFileSync` into
+`.instar/hooks/instar/mcp-health-autorefresh.sh` on every migration run (always-overwrite,
+never install-if-missing) — verified in code (src/core/PostUpdateMigrator.ts, the
+migrateHooks try-block) and pinned by the passing test "migration parity: migrateHooks
+always-overwrites the hook into hooks/instar/". Deployed Macs therefore receive the fixed
+script automatically on their next instar update; no config or manual step.
+
+## Class-Closure Declaration
+
+- **defectClass:** `unbounded-self-action` — **closure: n/a** (negative declaration).
+  No new self-action is introduced: the diff's added `kill()` is the perl timeout rung
+  reaping its OWN bounded child probe (process hygiene inside a one-shot session-start
+  probe), not a controller emit. The hook's pre-existing self-triggered action (the
+  single `/sessions/refresh`) is unchanged and remains hard-bounded by the
+  once-per-(session, failed-set) marker loop-guard — it structurally cannot loop.
+  Mirrors the machine-readable declaration in the instar-dev trace.
+
+## Second-pass review (self-reviewed-final-diff)
+
+Fresh re-read of the final `git diff` against this artifact:
+
+- **Template-literal escaping audited character-by-character**: every shell `$` in the
+  added block is escaped `\$` (TS template literal), including all perl variables
+  (`\$t`, `\$p`, `\$SIG`, `\$?`); no bare `${` remains that TS would interpolate; the
+  perl program contains no single quotes so the bash single-quoted `-e '…'` wrapping is
+  sound. The generated output was syntax-checked via the suite's `bash -n` test (passes).
+- **Live contract proof re-run** (this machine, no timeout/gtimeout): perl rung returns
+  124 on a hung `sleep 30` with a 2s bound; passes through exit 3; maps SIGTERM death to
+  143; captures stdout correctly. The dev-gate unit test exercises the full script path
+  through the perl rung end-to-end (mock `claude` → probe → dead-port session resolution).
+- **First-pass omission caught and fixed in this artifact**: the initial draft of Q2 did
+  not name the KILL-vs-TERM strictness difference between the perl rung and GNU timeout's
+  default; added with the read-only-probe justification.
+- **Honest scope note**: this branch (off origin/main) does not contain the previous
+  cycle's stop-hook fix — `tests/unit/autonomous-stop-hook-realcheck.test.ts` still shows
+  that one known failure HERE (1 failed | 23 passed), which is the other PR's subject and
+  resolves when both merge. All 14 targeted sibling/migrator files (139 tests) pass on
+  this branch, including the previously-failing mcpAutorefresh suite (9/9).
+- **Checked for other bare-`timeout` callsites in generated scripts** (grep for
+  `timeout N` across `src/core/PostUpdateMigrator.ts`, `src/data/http-hook-templates.ts`,
+  `src/scaffold/`, `src/templates/`, `templates/`, excluding curl's `--connect-timeout`/
+  `--max-time` flags): the line fixed here was the ONLY bare coreutils-`timeout`
+  invocation; no other generated script carries this defect class. Sweep converged clean
+  in one re-pass. <!-- tracked: CMT-896 -->
+- Conclusion: artifact accurate against the final diff; no unlisted side effects found.
+  Reviewer concurs with shipping.