instar 1.3.873 → 1.3.874

package/.claude/skills/autonomous/hooks/autonomous-stop-hook.sh

@@ -1098,12 +1098,19 @@ run_verification() {
   # Run in a subshell so the resolved CWD + scrubbed env never disturb the hook itself.
   # Combined stdout+stderr is byte-capped AT THE SOURCE (head -c) so a runaway log can
   # never buffer whole. Exit code via ${PIPESTATUS[0]} (the command's, not head's).
+  # SIGNAL-DEATH MAPPING (cardinal invariant): when the child dies from a SIGNAL —
+  # e.g. SIGPIPE, the routine outcome once head -c hits the byte cap and closes the
+  # pipe while the command is still writing — the perl runner must report 128+signal
+  # (mirroring GNU timeout and shell $? semantics), NEVER `$?>>8` alone: the low byte
+  # holds the signal and the HIGH byte is 0, so a bare `$?>>8` would map a
+  # killed-by-signal FAILING check to exit 0 == PASS and allow a premature exit.
+  # (Observed on macOS, where no GNU timeout exists and the perl rung is the default.)
   if [[ "$rc_runner" == "perl" ]]; then
     rc_raw=$(
       env "${rc_env_args[@]}" PATH="$rc_path" \
         bash -c '
           cd "$1" 2>/dev/null || true
-          "$5" -e '\''my($t,@c)=@ARGV; my $p=fork; if($p==0){setpgrp(0,0); exec @c or exit 127} $SIG{ALRM}=sub{kill("-KILL",$p); exit 124}; alarm($t); waitpid($p,0); exit($?>>8)'\'' "$2" bash -c "$3" 2>&1 | head -c "$4"
+          "$5" -e '\''my($t,@c)=@ARGV; my $p=fork; if($p==0){setpgrp(0,0); exec @c or exit 127} $SIG{ALRM}=sub{kill("-KILL",$p); exit 124}; alarm($t); waitpid($p,0); exit(($?&127) ? 128+($?&127) : ($?>>8))'\'' "$2" bash -c "$3" 2>&1 | head -c "$4"
           exit "${PIPESTATUS[0]}"
         ' _ "$cwd" "$RC_TIMEOUT_S" "$cmd" "$RC_CAPTURE_BYTES" "$rc_runner_bin"
     )
@@ -1131,8 +1138,15 @@ run_verification() {
   # 1b. UTF-8 scrub: a source head -c byte-cap can split a multibyte char, leaving a lone
   #     continuation byte that would later break jq --arg. iconv -c drops invalid bytes;
   #     fall back to an LC_ALL=C printable-only filter when iconv is absent.
+  #     PORTABILITY: macOS (BSD/citrus) iconv -c EMITS the correctly-scrubbed prefix but
+  #     still EXITS NON-ZERO on a truncated trailing multibyte char — so the fallback must
+  #     key on "produced no output from non-empty input", never on iconv's exit code
+  #     (an exit-code `||` would APPEND the fallback's output to iconv's, duplicating text).
   if command -v iconv >/dev/null 2>&1; then
-    rc_utf8=$(printf '%s' "$rc_san" | iconv -c -f utf-8 -t utf-8 2>/dev/null || printf '%s' "$rc_san" | LC_ALL=C tr -cd '\11\12\15\40-\176')
+    rc_utf8=$(printf '%s' "$rc_san" | iconv -c -f utf-8 -t utf-8 2>/dev/null || true)
+    if [[ -z "$rc_utf8" && -n "$rc_san" ]]; then
+      rc_utf8=$(printf '%s' "$rc_san" | LC_ALL=C tr -cd '\11\12\15\40-\176')
+    fi
   else
     rc_utf8=$(printf '%s' "$rc_san" | LC_ALL=C tr -cd '\11\12\15\40-\176')
   fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.873",
+  "version": "1.3.874",
   "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:20:52.277Z",
+  "instarVersion": "1.3.874",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

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

@@ -5,6 +5,30 @@
 
 ## What Changed
 
+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.
@@ -13,16 +37,35 @@ This is PR-A of a two-PR staged landing. The runtime apprenticeship gate, accept
 
 ## What to Tell Your User
 
+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 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
 
+- 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.

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.