instar 1.3.873 → 1.3.875

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.873",
+  "version": "1.3.875",
   "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:16:47.485Z",
-  "instarVersion": "1.3.873",
+  "generatedAt": "2026-07-18T20:25:13.928Z",
+  "instarVersion": "1.3.875",
   "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.875.md

@@ -0,0 +1,117 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## 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
+exit 0 via `exit($?>>8)` — the signal lives in the LOW byte of the status word, so the
+high byte is 0. The routine trigger is SIGPIPE: the capture pipeline byte-caps combined
+output at the source (`head -c`), and a verbose check still writing when the cap closes
+the pipe dies from signal 13. The failing check was then scored PASS and the hook
+**allowed the autonomous session to exit early** — a cardinal-invariant violation
+(any verification failure must route to keep-working). Linux was unaffected because GNU
+`timeout` maps signal-death to 128+signal (141, non-zero → FAIL). The perl rung now uses
+the same mapping: `exit(($?&127) ? 128+($?&127) : ($?>>8))`. Timeout (124), spawn-fail
+(127), and normal exits are unchanged.
+
+Same chain, second portability fix: macOS iconv `-c` emits the correctly-scrubbed UTF-8
+prefix but exits non-zero when the byte cap truncated a trailing multibyte character; the
+old exit-code `||` fallback then ALSO ran the C-locale printable filter and appended its
+output (a text-duplication hazard). The fallback now triggers only when iconv produced no
+output from non-empty input. The pinned sanitize → UTF-8 scrub → leak-scrub → clamp order
+is unchanged.
+
+This also fixes the deterministic macOS-only failure of
+`tests/unit/autonomous-stop-hook-realcheck.test.ts` ("invalid-UTF-8 capture … → next
+payload still builds") — the shipped hook was fixed; the test was not weakened.
+
+Instar now carries a canonical registry of every known way a framework session can stop (`src/data/stall-classes.ts`: eight classes, from mid-turn interrupts to context-window walls), and every supported framework must answer for each class in a stall-coverage matrix at `docs/frameworks/<framework>-stall-coverage.md`. A new validator (`src/core/stallCoverageValidator.ts`) enforces the standard structurally: exact status tokens (`covered | covered-dark | declared-gap | not-applicable`), resolvable detector/recovery symbols, positive-control evidence containing the framework's raw stall signature in a test the push suite actually collects, tracked refs on every declared gap, and a calendar aging ratchet on auto-seeded debt. A CI ratchet test in the whole-tree push suite validates all four seed matrices on every push, and an offline-first codemod (`scripts/stall-class-codemod.mjs`) seeds `declared-gap (new-class, unreviewed)` rows into every matrix whenever a class is added — so matrices cannot rot between onboardings.
+
+The four seed matrices ship honest: claude-code writes its existing stall family down for the first time (six classes covered or covered-dark, one declared gap — the drive-5 defect #9 interrupted-resume class, one structural N/A); codex-cli is honest zeros (every class a declared gap, each filed to the framework-issues ledger with a commitment anchor); gemini-cli is all not-applicable (framework dead upstream, `revalidateOn: framework-revival`); pi-cli is honest declared gaps for a ships-dark framework.
+
+This is PR-A of a two-PR staged landing. The runtime apprenticeship gate, acceptance machinery, and the recurring `stall-matrix-live-check` job are PR-B — nothing in PR-A gates any runtime behavior.
+
+## 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
+early on a technicality. Sessions that genuinely finish and pass their checks behave
+exactly as before.
+
+No user-visible behavior changes in this release. This is infrastructure honesty: your agent's platform now keeps a complete, continuously-validated map of how sessions can get stuck for every supported framework, so stall detection and recovery stop being learned one silent production stall at a time.
+
+## 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.
+
+- Canonical stall-class registry + per-framework stall-coverage matrices, CI-validated on every push.
+- Class-registry codemod that keeps every matrix complete as the class list grows.
+- Honest coverage baselines for claude-code, codex-cli, gemini-cli, and pi-cli (the claude-code stall family is now written down; every other framework's debt is tracked, not invisible).
+
+## 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
+  JSON `block` decision carrying the DATA-labeled, scrubbed, clamped output.
+- `tests/unit/autonomous-stop-hook-realcheck.test.ts`: 24/24 pass on macOS (previously
+  1 deterministic failure); all sibling stop-hook suites (9 files, 95 tests) and the
+  `PostUpdateMigrator` autonomous-hook suites (24 tests) pass.
+- Full push suite (`vitest.push.config.ts`) run from the worktree: zero failures.
+
+- The CI ratchet (`tests/unit/stall-coverage-ratchet.test.ts`) validates all four seed matrices, REQUIRED_MATRIX_FRAMEWORKS file presence, and spec-table/registry agreement — green on this tree.
+- Validator boundary tests (`tests/unit/stall-coverage-validator.test.ts`) cover both sides of every hermetic decision boundary from the spec's §5 list.
+- Evidence tests (`tests/unit/stall-evidence-claude-code.test.ts`) prove each claude-code covered-row detector genuinely fires on a realistic raw stall signature.
+- Codemod fleet-regression tests (`tests/unit/stall-class-codemod.test.ts`) prove: class-addition-without-codemod reds stale matrices; the codemod seeds correctly, idempotently, and honors --dry-run.
+- Spec: `docs/specs/framework-stall-coverage-matrix.md` (5 review rounds to convergence incl. cross-model review; operator-approved 2026-07-18).

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.

package/upgrades/side-effects/realcheck-utf8-macos-portability.md

@@ -0,0 +1,130 @@
+# Side-Effects Review — Real-Check Runner macOS Signal-Death Portability Fix
+
+**Version / slug:** `realcheck-utf8-macos-portability`
+**Date:** `2026-07-18`
+**Author:** Echo (autonomous, Tier-1 fix cycle)
+**Second-pass reviewer:** self-reviewed-final-diff (session-lifecycle-adjacent → 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/autonomous-stop-hook-realcheck.test.ts` ("invalid-UTF-8 capture … → next
+payload still builds") failed deterministically on macOS (Node 24) while Linux CI was
+green. Instrumented reproduction showed the hook did not emit broken JSON — it emitted the
+**allow-exit** message: the failing verification command was scored as a PASS. Root cause:
+the perl timeout-ladder rung (used when GNU `timeout`/`gtimeout` are absent — i.e. on
+macOS, where instar agents actually run) ended with `exit($?>>8)`. When the child command
+is killed by a **signal** — routinely SIGPIPE, because the source byte-cap
+(`head -c $RC_CAPTURE_BYTES`) closes the pipe while the command still writes — `$?`'s low
+byte holds the signal and the high byte is 0, so `$?>>8` == 0 == PASS. GNU `timeout` maps
+the same death to 128+signal (141), which is why Linux CI never saw it. This was a
+cardinal-invariant violation (a verification failure mode allowed a premature exit), not
+just a test-portability nit.
+
+Files modified (single file):
+- `.claude/skills/autonomous/hooks/autonomous-stop-hook.sh`
+  1. Perl runner exit mapping: `exit($?>>8)` → `exit(($?&127) ? 128+($?&127) : ($?>>8))`
+     — signal-death now reports 128+signal, byte-identical to GNU `timeout` and shell
+     semantics. Timeout (124), spawn-fail (127), and normal exits are untouched.
+  2. UTF-8 scrub fallback (same §5.3 chain, step 1b): macOS iconv `-c` emits the
+     correctly-scrubbed prefix but exits non-zero on a truncated trailing multibyte char;
+     the old `iconv … || tr -cd …` therefore ran BOTH commands and concatenated their
+     outputs (text duplication hazard for mixed ASCII/multibyte captures). The fallback
+     now keys on "iconv produced no output from non-empty input", never on exit code.
+  3. Comments documenting both portability behaviors. The PINNED ORDER
+     (sanitize → UTF-8 scrub → leak-scrub → clamp) is semantically unchanged.
+
+No test was weakened; the shipped hook was fixed.
+
+## The eight questions
+
+1. **Over-block** — By design this change *adds* blocking: a check command killed by a
+   signal (SIGPIPE from the byte cap, OOM-kill, external kill) now scores FAIL →
+   keep-working instead of PASS → exit. That is the cardinal invariant's required
+   direction ("any failure mode routes to keep-working"), not an over-block. A
+   genuinely-passing check is unaffected: a command that completes successfully exits 0
+   on its own before the wrapper reads status, and `($?&127)==0` preserves the old
+   mapping exactly. Edge considered: a check whose *last* action prints past the 65,536-
+   byte capture cap and would then have exited 0 — its SIGPIPE death now blocks the exit.
+   That command never got to its exit-0, so its success was never observable; treating an
+   unobservable success as non-pass is the fail-safe reading the invariant mandates (and
+   is identical to today's Linux/GNU-timeout behavior, so it introduces no new stringency
+   anywhere CI runs). No issue identified.
+2. **Under-block** — The fix closes the known signal-death→PASS hole. Remaining misses
+   are pre-existing and unchanged: a check that *itself* swallows failures (e.g.
+   `cmd || true`) still reports 0; the destructive-pattern pre-block remains a
+   pattern-list, not a sandbox. Nothing in this change widens them. The `cut -c` clamp
+   can still re-split a multibyte char after the UTF-8 scrub on both platforms (GNU and
+   BSD `cut -c` are byte-oriented in the C locale); this is tolerated today because `jq
+   --arg` replaces invalid bytes with U+FFFD on both platforms (verified live on macOS in
+   this cycle; Linux CI green proves the same), so the JSON payload remains valid. Left
+   as-is deliberately to keep this fix minimal; the scrub step guarantees jq receives at
+   most one truncated tail, never arbitrary garbage.
+3. **Level-of-abstraction fit** — Correct layer. The exit-status contract belongs to the
+   timeout-ladder rung itself: each rung must present the same observable contract
+   (0=pass, 124=timeout, 127=spawn-fail, non-zero=fail, 128+n=signal). Fixing the perl
+   rung to match GNU timeout keeps the ladder's consumers (the outcome switch at
+   §"Outcome") rung-agnostic. The iconv fallback fix likewise stays inside step 1b of the
+   pinned chain. No higher-layer gate should own POSIX status-word decoding.
+4. **Signal-vs-authority compliance** — This is not a message-flow decision point; it is
+   deterministic exit-status plumbing inside an existing gate. The authority structure is
+   unchanged: the real-check outcome still only *holds* completion (keep-working block);
+   the only path to exit remains judge-MET + check-PASS. Per `docs/signal-vs-authority.md`
+   there is no brittle blocking heuristic added — POSIX status decoding is exact, not
+   heuristic. No issue identified.
+5. **Interactions** — The 124 (ALRM handler exits directly) and 127 (exec-fail) paths are
+   untouched and cannot collide with the new mapping (the handler exits before `waitpid`
+   status is consulted; exec-fail is a normal exit). The P19 breaker consumes
+   outcome=fail rows identically regardless of exit code value. The audit row
+   (`logs/autonomous-realcheck.jsonl`) now records e.g. exitCode 141 where macOS
+   previously recorded 0 — consumers treat exitCode as opaque display data. No
+   double-fire, no shadowing, no race with adjacent cleanup. No issue identified.
+6. **External surfaces** — None new. No network, no config keys, no API change, no
+   template/migration surface: the hook ships inside the `autonomous` skill and
+   `installBuiltinSkills()`/`PostUpdateMigrator` handling for it is unchanged (the file
+   is delivered by the existing skill-content migration path; this edit rides the next
+   release exactly like any prior hook edit — verified that
+   `PostUpdateMigrator-autonomousStopHook.test.ts` passes). Timing dependence is
+   *reduced*: the outcome no longer depends on whether the platform's runner happens to
+   be GNU timeout or perl.
+7. **Multi-machine posture (Cross-Machine Coherence)** — Machine-local BY DESIGN. The
+   stop hook runs inside the one session process on the machine hosting the autonomous
+   run; its verdict never replicates and needs no merged read. The fix makes the
+   *behavior contract* machine-uniform (a run that fails its check on a Mac now blocks
+   exactly as it would on Linux), which improves cross-machine coherence of the
+   autonomous-run guarantee without any replication path. No user-facing notice is
+   emitted by this change (the block guidance text is unchanged), so one-voice gating is
+   unaffected; no durable state or URLs are created.
+8. **Rollback cost** — Low. Single-file, two-expression revert (`git revert` of one
+   commit); no data migration, no agent state repair, no config. Reverting restores the
+   macOS signal-death→PASS hole, so the rollback itself would be a safety regression —
+   the back-out plan is revert-and-re-fix, not revert-and-stay.
+
+## Second-pass review (self-reviewed-final-diff)
+
+Fresh re-read of the final `git diff` against this artifact, hunting for anything the
+first pass papered over:
+
+- **Verified the arithmetic**: `($?&127)` extracts the termination signal; for SIGPIPE
+  (13) the new expression exits 141, matching `bash`'s `$?` and GNU timeout. For a normal
+  exit N, `$?&127`==0 and the expression reduces to the old `$?>>8` — byte-identical
+  legacy behavior. Perl's `exit()` takes the value mod 256; 128+127=255 is in range, no
+  wrap hazard.
+- **Checked the ALRM race honestly**: if the alarm fires during `waitpid`, the handler
+  `exit 124`s immediately — the new mapping is never reached; timeout classification is
+  preserved. If the child dies from the handler's KILL in a lost race, 128+9=137 → FAIL →
+  keep-working — safe direction.
+- **Flagged and resolved one first-pass omission**: the first draft of Q1 did not
+  consider the "command succeeds but is killed printing its final output" case; added it
+  explicitly — the conclusion (fail-safe, matches existing Linux behavior) holds.
+- **iconv fallback re-check**: the new `[[ -z "$rc_utf8" && -n "$rc_san" ]]` guard means
+  an all-invalid-bytes capture (iconv emits nothing) still gets the C-locale printable
+  filter (yielding empty — acceptable, valid), and a non-empty scrub is never
+  double-appended. `|| true` keeps `set -e`-adjacent safety (the hook runs without
+  `set -e`, but the guard costs nothing). Confirmed no OTHER `iconv … ||` callsites exist
+  in the hook (grep: this is the only one).
+- **Scope check**: diff touches exactly one shipped file plus the three ceremony
+  artifacts; no test files modified — the failing test was fixed by fixing the hook, as
+  required. The pinned-order comment block remains accurate (order unchanged; step 1b
+  made exit-code-portable, step semantics identical).
+- Conclusion: artifact is accurate against the final diff; no unlisted side effects
+  found. Reviewer concurs with shipping.

package/upgrades/1.3.873.md

@@ -1,30 +0,0 @@
-# Upgrade Guide — vNEXT
-
-<!-- assembled-by: assemble-next-md -->
-<!-- bump: patch -->
-
-## What Changed
-
-Instar now carries a canonical registry of every known way a framework session can stop (`src/data/stall-classes.ts`: eight classes, from mid-turn interrupts to context-window walls), and every supported framework must answer for each class in a stall-coverage matrix at `docs/frameworks/<framework>-stall-coverage.md`. A new validator (`src/core/stallCoverageValidator.ts`) enforces the standard structurally: exact status tokens (`covered | covered-dark | declared-gap | not-applicable`), resolvable detector/recovery symbols, positive-control evidence containing the framework's raw stall signature in a test the push suite actually collects, tracked refs on every declared gap, and a calendar aging ratchet on auto-seeded debt. A CI ratchet test in the whole-tree push suite validates all four seed matrices on every push, and an offline-first codemod (`scripts/stall-class-codemod.mjs`) seeds `declared-gap (new-class, unreviewed)` rows into every matrix whenever a class is added — so matrices cannot rot between onboardings.
-
-The four seed matrices ship honest: claude-code writes its existing stall family down for the first time (six classes covered or covered-dark, one declared gap — the drive-5 defect #9 interrupted-resume class, one structural N/A); codex-cli is honest zeros (every class a declared gap, each filed to the framework-issues ledger with a commitment anchor); gemini-cli is all not-applicable (framework dead upstream, `revalidateOn: framework-revival`); pi-cli is honest declared gaps for a ships-dark framework.
-
-This is PR-A of a two-PR staged landing. The runtime apprenticeship gate, acceptance machinery, and the recurring `stall-matrix-live-check` job are PR-B — nothing in PR-A gates any runtime behavior.
-
-## What to Tell Your User
-
-No user-visible behavior changes in this release. This is infrastructure honesty: your agent's platform now keeps a complete, continuously-validated map of how sessions can get stuck for every supported framework, so stall detection and recovery stop being learned one silent production stall at a time.
-
-## Summary of New Capabilities
-
-- Canonical stall-class registry + per-framework stall-coverage matrices, CI-validated on every push.
-- Class-registry codemod that keeps every matrix complete as the class list grows.
-- Honest coverage baselines for claude-code, codex-cli, gemini-cli, and pi-cli (the claude-code stall family is now written down; every other framework's debt is tracked, not invisible).
-
-## Evidence
-
-- The CI ratchet (`tests/unit/stall-coverage-ratchet.test.ts`) validates all four seed matrices, REQUIRED_MATRIX_FRAMEWORKS file presence, and spec-table/registry agreement — green on this tree.
-- Validator boundary tests (`tests/unit/stall-coverage-validator.test.ts`) cover both sides of every hermetic decision boundary from the spec's §5 list.
-- Evidence tests (`tests/unit/stall-evidence-claude-code.test.ts`) prove each claude-code covered-row detector genuinely fires on a realistic raw stall signature.
-- Codemod fleet-regression tests (`tests/unit/stall-class-codemod.test.ts`) prove: class-addition-without-codemod reds stale matrices; the codemod seeds correctly, idempotently, and honors --dry-run.
-- Spec: `docs/specs/framework-stall-coverage-matrix.md` (5 review rounds to convergence incl. cross-model review; operator-approved 2026-07-18).