instar 1.3.1153 → 1.3.1154

package/dist/data/standards-guard-index.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1153",
+  "packageVersion": "1.3.1154",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

package/dist/data/standards-guard-index.meta.json

@@ -1,5 +1,5 @@
 {
-  "sha256": "c9fe9271930f52c79239f9b43e4d3c873717dc1dd98744525290c8ccba4f07bf",
+  "sha256": "49844097b7495749a584409f6b28788b61127591a3f707a03ef9622e69bf1dd1",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1153"
+  "packageVersion": "1.3.1154"
 }

package/dist/data/standards-registry.meta.json

@@ -2,5 +2,5 @@
   "sha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
   "articleCount": 88,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1153"
+  "packageVersion": "1.3.1154"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1153",
+  "version": "1.3.1154",
   "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/scripts/lint-sync-subprocess-chokepoint.js

@@ -78,6 +78,61 @@ const ALLOW = /lint-allow-sync-spawn:/;
 const FUNNELED = /\bwithSyncOp\s*\(/;
 
 const inScanDir = (p) => SCAN_DIRS.some((d) => p === d || p.startsWith(d + '/'));
+
+/**
+ * Names this file has bound to a raw sync spawn, so `ex(...)` is seen the same
+ * as `execFileSync(...)`. Two forms, both ordinary code rather than evasions:
+ *
+ *   import { execFileSync as run } from 'node:child_process';   // renamed import
+ *   const ex = execFileSync;                                    // local alias
+ *
+ * Measured before this was added: BOTH walked past the check while the plain
+ * form was caught, and NEITHER appears anywhere in the scanned directories
+ * today — so this is a pure forward ratchet with no baseline to grow.
+ *
+ * DELIBERATELY NOT COLLECTED: `const ex = <something>.execFileSync`. The
+ * VIOLATION regex excludes a dot-prefixed name on purpose, and that exclusion
+ * was measured to be RIGHT: all 14 namespace-form occurrences in the scanned
+ * dirs are either calls through `SafeGitExecutor` (the audited git funnel, 13
+ * of them) or sit inside a generated hook script's template literal, which runs
+ * in its own process and cannot block this event loop. Widening to dot-prefixed
+ * names would flag the funnel itself. Recorded here so it is not re-litigated.
+ */
+function collectSyncSpawnAliases(content) {
+  const names = new Set();
+  const SPAWNS = '(?:spawnSync|execSync|execFileSync)';
+
+  // import { execFileSync as run } from 'node:child_process'
+  const importRe = new RegExp(
+    String.raw`import\s*\{([^}]*)\}\s*from\s*['"\`](?:node:)?child_process['"\`]`,
+    'g'
+  );
+  let m;
+  while ((m = importRe.exec(content)) !== null) {
+    for (const part of m[1].split(',')) {
+      const bit = part.trim().match(new RegExp(String.raw`^${SPAWNS}\s+as\s+([A-Za-z_$][\w$]*)$`));
+      if (bit) names.add(bit[1]);
+    }
+  }
+
+  // const ex = execFileSync;   (bare RHS only — see the dot note above)
+  const aliasRe = new RegExp(
+    String.raw`\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*${SPAWNS}\s*(?=[;,\n)])`,
+    'g'
+  );
+  while ((m = aliasRe.exec(content)) !== null) names.add(m[1]);
+
+  return names;
+}
+
+/** A call-shape matcher for the collected names, or null when there are none. */
+function aliasCallRegex(names) {
+  if (!names.size) return null;
+  const alt = [...names].map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
+  // Same dot-exclusion as VIOLATION: `obj.ex(...)` is a method on something
+  // else, not the bound spawn.
+  return new RegExp(String.raw`(?<![.\w])(?:${alt})\s*\(`);
+}
 const normalize = (p) => p.split(path.sep).join('/');
 
 function listFiles() {
@@ -133,12 +188,15 @@ function collectHits() {
       continue;
     }
     const lines = content.split('\n');
+    // Names this file has bound to a raw sync spawn. Collected up-front so a
+    // binding that appears BELOW the function using it is still resolved.
+    const aliasRe = aliasCallRegex(collectSyncSpawnAliases(content));
     const seenLineText = new Map(); // trimmed-line-text → occurrence count so far
     for (let i = 0; i < lines.length; i++) {
       const raw = lines[i];
       const trimmed = raw.trimStart();
       if (/^(\/\/|\*|\/\*)/.test(trimmed)) continue; // comment-only mention
-      if (!VIOLATION.test(raw)) continue;
+      if (!VIOLATION.test(raw) && !(aliasRe && aliasRe.test(raw))) continue;
       // FUNNELED: a sync spawn wrapped by withSyncOp(...) on the same line is the required
       // pattern (the marker sees it) — allowed unconditionally, never grandfathered/baselined.
       if (FUNNELED.test(raw)) continue;

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-08-15T01:31:14.741Z",
-  "instarVersion": "1.3.1153",
+  "generatedAt": "2026-08-15T02:06:17.465Z",
+  "instarVersion": "1.3.1154",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/src/data/standards-guard-index.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1153",
+  "packageVersion": "1.3.1154",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

package/src/data/standards-guard-index.meta.json

@@ -1,5 +1,5 @@
 {
-  "sha256": "c9fe9271930f52c79239f9b43e4d3c873717dc1dd98744525290c8ccba4f07bf",
+  "sha256": "49844097b7495749a584409f6b28788b61127591a3f707a03ef9622e69bf1dd1",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1153"
+  "packageVersion": "1.3.1154"
 }

package/src/data/standards-registry.meta.json

@@ -2,5 +2,5 @@
   "sha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
   "articleCount": 88,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1153"
+  "packageVersion": "1.3.1154"
 }

package/upgrades/1.3.1154.md

@@ -0,0 +1,65 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`scripts/lint-sync-subprocess-chokepoint.js` — the forward ratchet that keeps raw
+synchronous subprocess spawns out of the runtime hot path, so a blocked-but-alive
+server is never mistaken for a dead one — now resolves bound names.
+
+It matched the spawn NAME on the call line, so two ordinary forms walked past
+while the plain call was caught. Measured with a positive control firing in the
+same run:
+
+```ts
+import { execFileSync as run } from 'node:child_process';  run(...);   // exit 0 — EVADED
+const ex = execFileSync;                                   ex(...);    // exit 0 — EVADED
+```
+
+A renamed import is not an evasion; it is how a name collision gets resolved.
+
+**Neither form appears anywhere in the scanned directories today** (0 local
+aliases, 0 renamed imports, against a control of 53 files carrying plain named
+imports), so this is a pure forward ratchet: the frozen baseline does not grow
+and nothing existing can break.
+
+**Scope reversed by measurement.** `VIOLATION` also excludes a DOT-prefixed name,
+and there are 14 namespace-form occurrences in the scanned dirs — "14 invisible
+blocking spawns" would have been the headline. Counting what they *are*:
+**13 are `SafeGitExecutor.execSync(`**, i.e. calls THROUGH the audited git funnel
+(flagging them would report correct use of the funnel as a bypass of it), and the
+**1 remaining sits inside a generated hook script's template literal**, which runs
+in its own process and cannot block this event loop. All 14 exclusions are
+correct; the dot-exclusion is left alone and pinned by two tests so it is not
+"fixed" later.
+
+Added `collectSyncSpawnAliases()` (renamed imports from `(node:)child_process`,
+and bare local aliases) and `aliasCallRegex()` (carrying the same dot-exclusion as
+the original rule). `VIOLATION`, `FUNNELED`, `ALLOW`, the baseline format and the
+exit codes are unchanged.
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+- `tests/unit/sync-spawn-alias-resolution.test.ts` — 12/12 green.
+- **Negative control: 4 of 12 fail** against the shipped lint (exactly the four
+  defect cases). The other 8 pass both ways and are the controls. Script restored
+  byte-exact after the control.
+- Six anti-over-block controls, because this lint fails builds — the two that
+  matter most: an aliased spawn wrapped by `withSyncOp` is still NOT flagged (the
+  funnel is the required pattern; overriding it would punish the code the rule
+  exists to produce), and an aliased spawn carrying an allow-comment is still NOT
+  flagged.
+- Real tree: `exit 0` before AND after. `tsc --noEmit` exit 0. Full `npm run lint`
+  chain exit 0.
+- Declared open in the source: dot-prefixed names (measured correct), cross-module
+  aliases, and `const ex = <ns>.execFileSync`.

package/upgrades/side-effects/sync-spawn-alias-resolution.md

@@ -0,0 +1,166 @@
+# Side-Effects Review — sync-spawn ratchet resolves bound names
+
+**Version / slug:** `sync-spawn-alias-resolution`
+**Date:** `2026-08-15`
+**Author:** `echo`
+**Second-pass reviewer:** `not required — Tier 1 (CI-only lint script, no runtime path). The rule, the funnel, the allow-comment escape and the frozen baseline are all unchanged; the check now resolves two more ways of naming the same banned call.`
+
+## Summary of the change
+
+`scripts/lint-sync-subprocess-chokepoint.js` is the forward ratchet for tmux
+event-loop resilience: a synchronous subprocess spawn blocks the single-threaded
+event loop for the child's whole lifetime, so outside the `withSyncOp` marker
+funnel a raw sync spawn is banned. The incident behind it — a blocked-but-alive
+server that looked dead to its supervisor and was restarted for being busy.
+
+It matched the spawn NAME on the call line. Measured against the shipped lint
+with a positive control (plain `execFileSync(...)`) firing in the same run:
+
+| form | shipped |
+|---|---|
+| `execFileSync('tmux', …)` — POSITIVE CONTROL | exit 1 (caught) |
+| **`import { execFileSync as run } …; run(…)`** | **exit 0 — EVADES** |
+| **`const ex = execFileSync; ex(…)`** | **exit 0 — EVADES** |
+
+A renamed import is not an evasion; it is how a name collision gets resolved.
+
+**Neither form appears anywhere in the scanned directories today** (measured: 0
+local aliases, 0 renamed imports, against a control of 53 files carrying plain
+named imports). So this is a pure forward ratchet — nothing is added to the
+frozen baseline and nothing existing can break.
+
+## The scope decision, which measurement reversed
+
+`VIOLATION` also excludes a DOT-prefixed name, and my first read was that this
+was the same class of hole. There are **14** namespace-form occurrences in the
+scanned directories, and "14 invisible blocking spawns" would have been the
+headline.
+
+Counting what they *are* rather than how many:
+
+- **13 are `SafeGitExecutor.execSync(`** — calls THROUGH the audited git funnel.
+  Flagging them would invert the rule, reporting correct use of the funnel as a
+  bypass of it.
+- **1 is `childProcess.execFileSync(` inside `getStopGateRouterHook()`** — which
+  returns a template literal for a generated hook script. That text runs in its
+  own short-lived process and cannot block this event loop.
+
+**All 14 exclusions are correct. The dot-exclusion is left alone**, and two tests
+pin it so a future reader does not "fix" it and break the funnel. The header
+records the measurement for the same reason.
+
+**A probe of mine returned the flattering answer and was wrong.** To test whether
+the 14th sat inside a template literal I counted unescaped backticks before its
+line — in a 16,000-line file, where backticks inside strings and comments corrupt
+the count. It reported "not inside a template", which supported the bigger
+finding. Reading the enclosing function signature settled it in one line.
+
+## Decision-point inventory
+
+- `collectSyncSpawnAliases(content)` — ADD. Per-file: renamed imports from
+  `(node:)child_process`, and `const|let|var X = <bare spawn name>`.
+- `aliasCallRegex(names)` — ADD. Call-shape matcher carrying the SAME
+  dot-exclusion as `VIOLATION`; returns null when there are no names.
+- The per-file loop — CHANGED: `if (!VIOLATION.test(raw) && !(aliasRe && aliasRe.test(raw))) continue;`
+- `VIOLATION`, `FUNNELED`, `ALLOW`, `SCAN_DIRS`, `EXTENSIONS`, the baseline
+  format, the baseline file and the exit codes — UNCHANGED.
+- No runtime block/allow decision added or modified. CI-time only.
+
+## 1. Over-block
+
+The dominant risk — this lint fails builds. Six controls, each with a test, all
+passing under BOTH old and new behaviour:
+
+- **an aliased spawn wrapped by `withSyncOp` is not flagged.** The most important
+  one: the funnel is the REQUIRED pattern, and if resolution overrode it the fix
+  would punish exactly the code the rule exists to produce.
+- **an aliased spawn carrying `lint-allow-sync-spawn:` is not flagged** — the
+  existing escape for genuinely pre-runtime calls still works.
+- an unrelated identifier that merely shares the name is not flagged — only a
+  name actually bound to a spawn is collected.
+- a method call on another object (`helper.ex(...)`) is not flagged — the alias
+  matcher carries the same dot-exclusion as the original rule.
+- a file with no sync spawn is not flagged.
+- the two dot-exclusion pins above (`SafeGitExecutor.execSync`, `cp.execFileSync`).
+
+**Real tree: exit 0 before AND after.** Full `npm run lint` chain exit 0.
+
+Residual over-block risk, stated: a very short alias (`run`, `ex`) shadowed later
+in the same file by an unrelated binding of the same name would be flagged. Not
+observed anywhere today, and the failure is loud and one line to fix, unlike the
+silent miss it replaces.
+
+## 2. Under-block
+
+Stated in the source:
+
+- **Dot-prefixed names** — deliberately excluded, measured correct (above).
+- **Cross-module aliases** — a wrapper exported from another file.
+- **`const ex = <ns>.execFileSync`** — not collected, because collecting it would
+  require resolving the namespace, which is the dot case.
+- The header's pre-existing honesty stands: this is a static line regex and
+  cannot prove a flagged line is actually wrapped at runtime — that is the
+  marker unit tests' job.
+
+## 3. Level-of-abstraction fit
+
+Same layer as the existing check — line regex over file text, no AST, no new
+dependency. Alias collection is the smallest addition that answers the question
+the rule already asks ("is this line a raw sync spawn?") for names the file
+creates itself.
+
+## 4. Signal vs authority compliance
+
+A CI ratchet, not a runtime authority. It gained reach over two more spellings of
+a violation it already forbade, and no new decision-making power. The funnel, the
+escape and the baseline are untouched.
+
+## 5. Interactions
+
+- Already in the `lint` chain CI runs; chain exit 0 with this change.
+- The frozen baseline is untouched and does not grow — the newly-reachable forms
+  have zero existing instances.
+- Alias collection is one extra regex pass per file; no perceptible change in
+  chain duration.
+- No source module, route, config key, or state file touched.
+
+## 6. External surfaces
+
+None. Developer tooling. The Agent Awareness Standard does not apply.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Machine-local by design, and correct.** A CI-time source scan: reads files in
+one checkout, returns an exit code. No durable state, no user-facing notice, no
+generated URL, no runtime decision — nothing to replicate, merge on read, or
+strand on a topic transfer. Every machine runs it over its own checkout of the
+same tracked source and reaches the same verdict; alias collection is explicitly
+per-file, so it cannot depend on the rest of the checkout, let alone another
+machine.
+
+## 8. Rollback cost
+
+`git revert` of one script plus the added test file. No migration, no state, no
+deployed artifact, no runtime impact, no baseline change to undo.
+
+## Conclusion
+
+Ship. Two ordinary ways of naming a banned blocking call are now seen, the
+existing funnel and escape still win over the new reach, the deliberate
+dot-exclusion is measured-correct and pinned rather than widened, and the real
+tree is verified clean in both directions.
+
+## Evidence pointers
+
+- `tests/unit/sync-spawn-alias-resolution.test.ts` — **12/12 green**.
+- **Negative control: 4 of 12 fail** against the shipped lint (exactly the four
+  defect cases). The other 8 pass **both ways** — one positive control, two
+  escape-still-wins, three over-block, two dot-exclusion pins. Script restored
+  **byte-exact** after the control (sha match).
+- Reproduced by hand FIRST with a positive control in the same run.
+- Zero existing instances of either newly-reached form (control: 53 files with
+  plain named imports), so the frozen baseline does not grow.
+- Real-tree verdict: exit 0 before and after. `tsc --noEmit` exit 0. Full chain
+  exit 0.
+- Tier **1** declared: CI-only script, no runtime path, no authority, no
+  capability.