instar 1.3.1153 → 1.3.1155

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.1155",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

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

@@ -1,5 +1,5 @@
 {
-  "sha256": "c9fe9271930f52c79239f9b43e4d3c873717dc1dd98744525290c8ccba4f07bf",
+  "sha256": "4768f67585d114ee7064f8a97895cdf66f96074719ad149a661bcee76e79625b",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1153"
+  "packageVersion": "1.3.1155"
 }

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.1155"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1153",
+  "version": "1.3.1155",
   "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-no-direct-destructive.js

@@ -23,6 +23,9 @@
  * Exit codes:
  *   0 — no violations.
  *   1 — at least one violation.
+ *   2 — could not inspect: files were scanned and NONE parsed (an environment
+ *       problem, e.g. a missing `typescript`). Distinct from 1 on purpose —
+ *       "I could not look" is not "I looked and found nothing".
  *
  * Usage:
  *   node scripts/lint-no-direct-destructive.js                # full repo
@@ -39,6 +42,14 @@ import { fileURLToPath } from 'node:url';
 // only when a TS file actually needs parsing.
 let _ts = null;
 function ts() {
+  // Test hook for the parsed-nothing refusal below. It can ONLY force the
+  // fail-closed path (every file fails to parse → the run refuses to report
+  // clean); there is no flag here that can make this lint pass something it
+  // would otherwise flag. Without it the refusal would be untested, which is
+  // the failure mode this whole guard exists to prevent.
+  if (process.env.INSTAR_LINT_FORCE_PARSE_FAILURE === '1') {
+    throw new Error('forced parse failure (INSTAR_LINT_FORCE_PARSE_FAILURE=1)');
+  }
   if (_ts) return _ts;
   _ts = require('typescript');
   return _ts;
@@ -304,7 +315,15 @@ function lintTsFile(file, text) {
   const T = ts();
   const sf = T.createSourceFile(file, text, T.ScriptTarget.Latest, true);
   const ctx = { text };
-  const r = (f, l, c, m) => report(f, l, c, m, ctx);
+  // Declaration collection runs BEFORE reporting (see the collect/report loop at
+  // the foot of this function), so a binding declared after the function that
+  // uses it is still resolved. While collecting, findings are suppressed —
+  // otherwise every violation would be reported once per collection pass.
+  let collecting = true;
+  const r = (f, l, c, m) => {
+    if (collecting) return;
+    report(f, l, c, m, ctx);
+  };
 
   /** module name → local identifier (default + namespace + named) */
   const childProcessIdentifiers = new Set();
@@ -319,6 +338,34 @@ function lintTsFile(file, text) {
     return { line: lc.line + 1, col: lc.character + 1 };
   }
 
+  /**
+   * Strip syntax that changes nothing at runtime but hides an identifier from a
+   * structural check — parentheses, `as` assertions, `<T>` assertions and `!`.
+   * `(fs as any)['rmSync'](p)` performs exactly the same delete as `fs.rmSync(p)`;
+   * without this it reached the computed-access branch as a ParenthesizedExpression
+   * and the `isIdentifier` test failed, so the call was invisible.
+   */
+  /**
+   * Idempotent: collection now runs more than once (see the collect/report loop
+   * below), and an array push is the one collector here that is not naturally
+   * idempotent — repeated passes would duplicate entries and keep the binding
+   * count growing, so the fixpoint would never be reached.
+   */
+  function addSimpleGitImport(localName) {
+    if (!simpleGitImports.some((s2) => s2.localName === localName)) {
+      simpleGitImports.push({ localName });
+    }
+  }
+
+  function unwrap(node) {
+    let n = node;
+    while (n && (T.isParenthesizedExpression(n) || T.isAsExpression(n)
+                 || T.isTypeAssertionExpression?.(n) || T.isNonNullExpression(n))) {
+      n = n.expression;
+    }
+    return n;
+  }
+
   function visit(node) {
     // ── Imports ────────────────────────────────────────────────
     if (T.isImportDeclaration(node) && node.moduleSpecifier && T.isStringLiteral(node.moduleSpecifier)) {
@@ -342,7 +389,7 @@ function lintTsFile(file, text) {
             } else if (FS_MODULE_NAMES.has(mod) && DESTRUCTIVE_FS_NAMES.has(importedName)) {
               fsNamedDestructiveImports.set(localName, importedName);
             } else if (mod === 'simple-git' && importedName === 'simpleGit') {
-              simpleGitImports.push({ localName });
+              addSimpleGitImport(localName);
             }
           }
         }
@@ -355,7 +402,7 @@ function lintTsFile(file, text) {
         } else if (FS_MODULE_NAMES.has(mod)) {
           fsNamespaceIdentifiers.add(localName);
         } else if (mod === 'simple-git') {
-          simpleGitImports.push({ localName });
+          addSimpleGitImport(localName);
         }
       }
     }
@@ -376,7 +423,7 @@ function lintTsFile(file, text) {
               fsNamespaceIdentifiers.add(localName);
               requireBindings.set(localName, mod);
             } else if (mod === 'simple-git') {
-              simpleGitImports.push({ localName });
+              addSimpleGitImport(localName);
             }
           }
           // Destructured: const { execFileSync } = require('child_process')
@@ -392,7 +439,7 @@ function lintTsFile(file, text) {
               } else if (FS_MODULE_NAMES.has(mod) && DESTRUCTIVE_FS_NAMES.has(importedName)) {
                 fsNamedDestructiveImports.set(localName, importedName);
               } else if (mod === 'simple-git' && importedName === 'simpleGit') {
-                simpleGitImports.push({ localName });
+                addSimpleGitImport(localName);
               }
             }
           }
@@ -441,6 +488,83 @@ function lintTsFile(file, text) {
       }
     }
 
+    // ── Local re-bindings of a banned namespace or function ────
+    // The sets above were populated ONLY from imports/requires, so one line of
+    // ordinary tidying disabled the funnel for a whole file:
+    //
+    //   const fsp = fs.promises;   await fsp.rm(p, { recursive: true });
+    //
+    // Aliasing `fs.promises` to a short name is idiomatic JavaScript, not an
+    // evasion — and `fs.promises.rm` written out IS caught, so the difference
+    // between flagged and invisible was a variable. Resolving the binding feeds
+    // the EXISTING checks below rather than adding a parallel rule.
+    if (T.isVariableDeclaration(node) && node.initializer) {
+      const init = unwrap(node.initializer);
+
+      // `const X = <expr>` where X is a plain identifier.
+      if (T.isIdentifier(node.name)) {
+        const local = node.name.text;
+
+        // Whole-namespace alias: `const f = fs` / `const fsp = fs.promises`.
+        if (T.isIdentifier(init) && fsNamespaceIdentifiers.has(init.text)) {
+          fsNamespaceIdentifiers.add(local);
+        } else if (T.isIdentifier(init) && childProcessIdentifiers.has(init.text)) {
+          childProcessIdentifiers.add(local);
+        } else if (T.isPropertyAccessExpression(init)) {
+          const base = unwrap(init.expression);
+          const member = init.name.text;
+
+          // `const fsp = fs.promises` — still the fs namespace, so the member
+          // checks below apply to it unchanged.
+          if (T.isIdentifier(base) && fsNamespaceIdentifiers.has(base.text) && member === 'promises') {
+            fsNamespaceIdentifiers.add(local);
+          } else if (T.isIdentifier(base) && fsNamespaceIdentifiers.has(base.text)
+                     && DESTRUCTIVE_FS_NAMES.has(member)) {
+            // `const del = fs.rmSync`
+            fsNamedDestructiveImports.set(local, member);
+          } else if (T.isIdentifier(base) && childProcessIdentifiers.has(base.text)
+                     && CHILD_PROCESS_FNS.has(member)) {
+            // `const ex = cp.execFileSync`
+            childProcessNamedImports.set(local, member);
+          } else if (T.isPropertyAccessExpression(base) && T.isIdentifier(unwrap(base.expression))
+                     && fsNamespaceIdentifiers.has(unwrap(base.expression).text)
+                     && base.name.text === 'promises'
+                     && DESTRUCTIVE_FS_NAMES.has(member)) {
+            // `const del = fs.promises.rm`
+            fsNamedDestructiveImports.set(local, member);
+          }
+        }
+      }
+
+      // `const { rmSync, unlink: del } = fs` / `... = fs.promises`
+      if (T.isObjectBindingPattern(node.name)) {
+        const init2 = unwrap(node.initializer);
+        let isFsSource = false;
+        let isCpSource = false;
+        if (T.isIdentifier(init2)) {
+          isFsSource = fsNamespaceIdentifiers.has(init2.text);
+          isCpSource = childProcessIdentifiers.has(init2.text);
+        } else if (T.isPropertyAccessExpression(init2) && init2.name.text === 'promises') {
+          const base = unwrap(init2.expression);
+          isFsSource = T.isIdentifier(base) && fsNamespaceIdentifiers.has(base.text);
+        }
+        if (isFsSource || isCpSource) {
+          for (const el of node.name.elements) {
+            if (!T.isBindingElement(el) || !T.isIdentifier(el.name)) continue;
+            const original = el.propertyName && T.isIdentifier(el.propertyName)
+              ? el.propertyName.text
+              : el.name.text;
+            const local = el.name.text;
+            if (isFsSource && DESTRUCTIVE_FS_NAMES.has(original)) {
+              fsNamedDestructiveImports.set(local, original);
+            } else if (isCpSource && CHILD_PROCESS_FNS.has(original)) {
+              childProcessNamedImports.set(local, original);
+            }
+          }
+        }
+      }
+    }
+
     // ── Member call on namespace identifier ────────────────────
     if (T.isCallExpression(node) && T.isPropertyAccessExpression(node.expression)) {
       const obj = node.expression.expression;
@@ -479,7 +603,7 @@ function lintTsFile(file, text) {
 
     // ── Dynamic / computed access: fs['rm' + 'Sync'](...) ──────
     if (T.isCallExpression(node) && T.isElementAccessExpression(node.expression)) {
-      const obj = node.expression.expression;
+      const obj = unwrap(node.expression.expression);
       const arg = node.expression.argumentExpression;
       if (T.isIdentifier(obj) && fsNamespaceIdentifiers.has(obj.text)) {
         // Any computed member access on the fs namespace is suspicious;
@@ -513,6 +637,19 @@ function lintTsFile(file, text) {
     return false;
   }
 
+  // Collect, then report. Collection repeats until the binding sets stop
+  // growing, so a chain (`const a = fs; const b = a.promises`) resolves however
+  // it is ordered in the file, and a binding declared BELOW the function that
+  // uses it is still known. Bounded so a pathological file cannot spin.
+  const bindingCount = () =>
+    fsNamespaceIdentifiers.size + fsNamedDestructiveImports.size
+    + childProcessIdentifiers.size + childProcessNamedImports.size + simpleGitImports.length;
+  for (let pass = 0; pass < 5; pass += 1) {
+    const before = bindingCount();
+    visit(sf);
+    if (bindingCount() === before) break;
+  }
+  collecting = false;
   visit(sf);
 }
 
@@ -661,6 +798,9 @@ function main() {
     files = gatherAll();
   }
 
+  // Scan-coverage counters: a run that parsed nothing inspected nothing.
+  let astAttempted = 0;
+  let astParsed = 0;
   for (const file of files) {
     let text;
     try {
@@ -685,14 +825,43 @@ function main() {
     if (hasAllowComment(text)) continue;
 
     // AST lint for ts/js/mjs/cjs
+    astAttempted += 1;
     try {
       lintTsFile(file, text);
+      astParsed += 1;
     } catch (err) {
-      // Parse failure → emit a soft warning, not a violation.
+      // Parse failure → emit a soft warning, not a violation. Deliberate: one
+      // unparseable file should not fail a build over syntax this parser does
+      // not accept. The total-failure case below is a different situation.
       process.stderr.write(`[lint-no-direct-destructive] failed to parse ${rel}: ${err.message}\n`);
     }
   }
 
+  // A run in which NOTHING parsed did not inspect anything, and "no violations
+  // found" would be a statement about a scan that never happened. Measured live
+  // on 2026-08-15: in a checkout without node_modules the `typescript` require
+  // fails for every file, so this guard against unaudited deletes reported
+  // clean and exited 0, with only stderr lines a CI log buries.
+  //
+  // This is deliberately the TOTAL-failure case only, so it cannot fail a build
+  // over one file the parser dislikes: in any working checkout, files parse.
+  if (astAttempted > 0 && astParsed === 0) {
+    process.stderr.write('\n');
+    process.stderr.write(
+      `[lint-no-direct-destructive] COULD NOT INSPECT — ${astAttempted} file(s) were scanned `
+      + 'and NONE could be parsed, so nothing was actually inspected. This is an environment '
+      + "problem (most often a missing `typescript` dependency — run `npm install`), not a clean "
+      + 'tree. Reporting success here would silently disable the destructive-operation funnel.\n'
+    );
+    // Exit 2, NOT 1. "I could not inspect" and "I found violations" are
+    // different facts and callers act on them differently: pre-push-gate.js
+    // already treats a lint that FAILED TO RUN as a warning and a lint that
+    // found VIOLATIONS as a push-blocking error. Returning 1 here reported an
+    // uninstalled scratch tree as violations — which is how this was caught,
+    // by three pre-push-gate tests going red in CI.
+    return 2;
+  }
+
   if (violations.length === 0) {
     return 0;
   }

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/scripts/pre-push-gate.js

@@ -420,7 +420,13 @@ try {
     [path.join(ROOT, 'scripts/lint-no-direct-destructive.js')],
     { cwd: ROOT, stdio: ['ignore', 'inherit', 'inherit'] },
   );
-  if (result.status !== 0) {
+  if (result.status === 2) {
+    // Exit 2 = the lint could not inspect anything (an environment problem such
+    // as a missing `typescript`), which is NOT a violation. The gate already
+    // treats a lint that failed to run as a warning; this is the same fact
+    // arriving through an exit code instead of a thrown error.
+    warnings.push('lint-no-direct-destructive could not inspect this tree (see output above)');
+  } else if (result.status !== 0) {
     errors.push('lint-no-direct-destructive: violations detected (see output above)');
   }
 } catch (err) {

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:10:19.346Z",
+  "instarVersion": "1.3.1155",
   "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.1155",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

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

@@ -1,5 +1,5 @@
 {
-  "sha256": "c9fe9271930f52c79239f9b43e4d3c873717dc1dd98744525290c8ccba4f07bf",
+  "sha256": "4768f67585d114ee7064f8a97895cdf66f96074719ad149a661bcee76e79625b",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1153"
+  "packageVersion": "1.3.1155"
 }

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.1155"
 }

package/upgrades/1.3.1155.md

@@ -0,0 +1,132 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`scripts/lint-no-direct-destructive.js` — the funnel guard that keeps every
+destructive git/fs operation inside `SafeGitExecutor` / `SafeFsExecutor`, so each
+delete carries an audit entry — now resolves local bindings before applying its
+rules.
+
+Its identifier sets were populated ONLY from imports and requires. Measured
+against the shipped lint with a positive control (`fs.rmSync`) firing in the same
+pass:
+
+```ts
+const fsp = fs.promises;
+await fsp.rm(p, { recursive: true, force: true });   // exit 0 — EVADED
+const del = fs.rmSync; del(p);                        // exit 0 — EVADED
+const { rmSync: del } = fs; del(p);                   // exit 0 — EVADED
+(fs as any)['rmSync'](p);                             // exit 0 — EVADED
+```
+
+`fs.promises.rm` written out IS caught, so the difference between flagged and
+invisible was a variable. Aliasing a namespace to a short name is idiomatic
+JavaScript — the gap needed a tidy afternoon, not an attacker.
+
+The lint AST-walks, so it already caught renamed imports (`import { rmSync as
+nuke }`) where a regex check could not. The gap was narrower than "it doesn't
+understand names": it understood names arriving from imports and nothing about
+names a file creates itself.
+
+Added: `unwrap()` (strips parens / `as` / `!` before identity tests),
+local-binding collection for namespace aliases, function aliases and object
+binding patterns, and a collect-then-report loop that repeats until the binding
+sets stop growing — so resolution is order-independent and alias chains resolve.
+
+**Second finding, hit live rather than reasoned about.** Running the lint in a
+worktree with no `node_modules`, the `typescript` require failed for EVERY file
+and the lint reported **clean, exit 0** — a guard against unaudited deletes
+silently became a no-op, with only stderr lines a CI log buries. The per-file
+soft-warning is deliberate and right; ONE file failing and EVERY file failing are
+different situations. A run that scanned files and parsed none of them now
+refuses to report clean and names the likely cause, exiting **2** rather than 1:
+"I could not look" and "I looked and found nothing" are different facts, and
+`pre-push-gate.js` already treats a lint that failed to run as a warning and one
+that found violations as a push-blocking error. (The first version returned 1 and
+turned three pre-push-gate tests red — the gate copies itself into a scratch
+fixture with no dependencies, so my "no working checkout can reach it" claim was
+wrong; a test fixture reaches it.)
+
+**Declared open in the source:** cross-module names, runtime-assembled access,
+and indirection through a container object (`const io = { del: fs.unlinkSync }`)
+— measured, and left open because that is not an ordinary way to write a delete
+and chasing it widens over-block risk on a build-failing lint.
+
+`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).
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+- `tests/unit/destructive-lint-local-bindings.test.ts` — 16/16 green.
+- **Negative control: 7 of 16 fail** against the shipped lint (all six defect
+  cases plus the parsed-nothing refusal). The other 9 pass both ways and are the
+  controls. Script restored byte-exact after the control.
+- Five anti-over-block controls, because this lint fails builds: a
+  non-destructive call; a non-destructive method on an aliased namespace;
+  `mkdir` through that alias (creating is not deleting); an unrelated object
+  exposing the same names; an alias that is never called.
+- Real tree: `exit 0` before AND after. Full `npm run lint` chain exit 0.
+  `tsc --noEmit` exit 0.
+- The new test routes its own teardown through `SafeFsExecutor` rather than
+  taking an allowlist entry — the test that argues for the rule follows it.
+
+- `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/destructive-lint-local-bindings.md

@@ -0,0 +1,193 @@
+# Side-Effects Review — destructive-op guard resolves local bindings
+
+**Version / slug:** `destructive-lint-local-bindings`
+**Date:** `2026-08-15`
+**Author:** `echo`
+**Second-pass reviewer:** `not required — Tier 1 (CI-only lint script, no runtime path). The rule and the funnel are unchanged; the check now resolves one more kind of name before applying the rules it already had, and refuses to report clean on a run that inspected nothing.`
+
+## Summary of the change
+
+`scripts/lint-no-direct-destructive.js` is the funnel guard for
+`COMPREHENSIVE-DESTRUCTIVE-TOOL-CONTAINMENT-SPEC` — only `SafeGitExecutor` /
+`SafeFsExecutor` may call destructive git/fs primitives directly, so that every
+delete carries an audit entry.
+
+It AST-walks, which already buys it real import resolution. But its identifier
+sets were populated ONLY from imports and requires, never from local bindings.
+Measured against the shipped lint with a positive control (a plain `fs.rmSync`)
+firing in the same pass:
+
+| form | shipped |
+|---|---|
+| `fs.rmSync(p)` — POSITIVE CONTROL | exit 1 (caught) |
+| `import { rmSync }` / `import { rmSync as nuke }` | exit 1 (caught — better than any regex lint here) |
+| `fs.promises.rm(p)` written out | exit 1 (caught) |
+| **`const fsp = fs.promises; await fsp.rm(p, …)`** | **exit 0 — EVADES** |
+| `const del = fs.rmSync; del(p)` | **exit 0 — EVADES** |
+| `const { rmSync: del } = fs; del(p)` | **exit 0 — EVADES** |
+| `(fs as any)['rmSync'](p)` | **exit 0 — EVADES** |
+
+The first evasion is the one that matters. `fs.promises.rm` IS caught, so the
+difference between flagged and invisible was a variable — and aliasing a
+namespace to a short name is idiomatic JavaScript, not an evasion. The gap needed
+a tidy afternoon, not an attacker.
+
+Resolution now feeds the EXISTING checks rather than adding rules beside them.
+
+## The second finding, hit live rather than reasoned about
+
+Running the lint in a fresh worktree with no `node_modules`, the `typescript`
+require failed for **every** file — and the lint reported **clean, exit 0**, with
+only stderr lines a CI log buries. A guard against unaudited deletes silently
+became a no-op.
+
+The per-file soft-warning is deliberate and stated in the source ("Parse failure
+→ emit a soft warning, not a violation"), and it is right: one file the parser
+dislikes should not fail a build. But ONE file failing and EVERY file failing are
+different situations — the second means nothing was inspected, and "no violations
+found" is then a statement about a scan that never happened.
+
+Added: a run that scanned files and parsed NONE of them refuses to report clean
+and names the likely cause. Deliberately the total-failure case only, so it
+cannot fail a build over one awkward file.
+
+**It exits 2, not 1, and CI taught me that distinction.** My first version
+returned 1 — the violation code — and three `pre-push-gate` tests went red,
+because the gate copies itself into a scratch fixture with no `node_modules`,
+runs this lint there, and (correctly) reads a non-zero exit as "violations
+detected". My claim that "no working checkout can reach it" was wrong: a test
+fixture reaches it. The gate ALREADY distinguishes a lint that failed to RUN
+(warning) from one that found VIOLATIONS (push-blocking error) — I was sending an
+environment problem down the violation channel. Now the lint exits **2** for
+could-not-inspect and `pre-push-gate.js` maps 2 onto its existing warning path.
+"I could not look" and "I looked and found nothing" are different facts.
+
+## Decision-point inventory
+
+- `unwrap(node)` — ADD. Strips parens / `as` / `<T>` / `!` before identity tests.
+- Local-binding collection in `visit` — ADD. Namespace aliases, destructive-function
+  aliases, object-binding patterns, for both fs and child_process.
+- `addSimpleGitImport(localName)` — ADD. Idempotent; collection now runs more than
+  once and an array push is the one collector that is not naturally idempotent.
+- Collect-then-report loop — CHANGED. Collection repeats until the binding sets
+  stop growing (bounded at 5), then one reporting pass. Makes resolution
+  order-independent and resolves alias chains.
+- Parsed-nothing refusal — ADD.
+- `INSTAR_LINT_FORCE_PARSE_FAILURE` — ADD, test hook. It can ONLY force the
+  fail-closed path; there is no flag here that can make this lint pass something
+  it would otherwise flag.
+- Exit code **2** — ADD, for could-not-inspect. 0 and 1 keep their meanings.
+- `scripts/pre-push-gate.js` — CHANGED: maps exit 2 onto its EXISTING
+  failed-to-run warning path instead of the violations error path.
+- `ALLOWLIST`, `DESTRUCTIVE_FS_NAMES`, `CHILD_PROCESS_FNS`, the violation
+  messages and the shell/package.json grep — UNCHANGED.
+
+## 1. Over-block
+
+**The dominant risk — this lint fails builds, and a noisy check gets switched
+off, after which it protects nothing.** Five controls, each with a test, all
+passing under BOTH the old and new behaviour:
+
+- a non-destructive fs call is not flagged;
+- a NON-destructive method on an aliased namespace is not flagged (the alias is
+  not the violation, the destructive method is);
+- `mkdir` through that same alias is not flagged — creating is not deleting;
+- an unrelated object exposing the same names is not flagged (resolution is
+  anchored to the fs/child_process namespace, never to a method name);
+- an alias that is never called is not flagged.
+
+**Real tree: exit 0 before AND after, zero violations.** Full `npm run lint`
+chain exit 0.
+
+The parsed-nothing refusal is scoped to `attempted > 0 && parsed === 0`.
+**I first wrote here that "no working checkout can reach it" — that was wrong and
+CI proved it.** The pre-push gate copies itself into a scratch fixture with no
+`node_modules` and runs this lint there, so three of its tests went red. The
+condition is reachable; what was wrong was reporting it through the VIOLATION
+exit code. Exit 2 fixes the signal rather than narrowing the condition, and the
+three tests pass with the refusal still firing.
+
+## 2. Under-block
+
+Stated in the source rather than implied:
+
+- **Cross-module names** — a destructive function re-exported from another file
+  is not followed. Needs a whole-program symbol graph, not one file at a time.
+- **Runtime-assembled access** — a name built from a variable, a call, or a
+  template.
+- **Indirection through a container** — `const io = { del: fs.unlinkSync }; io.del(p)`
+  remains invisible. Measured and left open: unlike the namespace alias, that is
+  not an ordinary way to write a delete, and chasing it widens over-block risk on
+  a build-failing lint for a contrived shape.
+
+## 3. Level-of-abstraction fit
+
+Same layer as the existing check — TypeScript AST over one file, no type checker,
+no new dependency. Local-binding resolution is the smallest addition that answers
+the question the existing rules already ask ("is this call a destructive fs/git
+primitive?") for names the file creates itself.
+
+## 4. Signal vs authority compliance
+
+A CI guard, not a runtime authority. It gained reach (more forms of the same
+violation) and one fail-closed condition, but no new decision-making power over
+agent behaviour. The funnel itself is untouched.
+
+## 5. Interactions
+
+- Already in the `lint` chain CI runs; membership verified explicitly rather than
+  inferred from a `package.json` reference. Chain exit 0 with this change.
+- Collection now runs up to 5 times per file plus one reporting pass. Measured on
+  the real tree: no perceptible change in chain duration.
+- **The new test routes its own teardown through `SafeFsExecutor` rather than
+  taking an allowlist entry** — the test that argues for the rule follows it. This
+  is the one behavioural cost: one audit entry per test run.
+- 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; determinism comes from the
+source tree, not from coordination.
+
+One honest note: the parsed-nothing refusal makes the verdict depend on the
+checkout being *installed*, not just present. That is the intended behaviour —
+an uninstalled checkout cannot inspect anything, and saying so is the point.
+
+## 8. Rollback cost
+
+`git revert` of one script plus the added test file. No migration, no state, no
+deployed artifact, no runtime impact.
+
+## Conclusion
+
+Ship. Four evasions closed on a safety funnel — one of them an ordinary tidying
+pattern rather than an evasion — a run that inspects nothing can no longer report
+clean, five anti-over-block controls added, and the real tree verified clean in
+both directions.
+
+## Evidence pointers
+
+- `tests/unit/destructive-lint-local-bindings.test.ts` — **16/16 green**.
+- **Negative control: 7 of 16 fail** against the shipped lint (all six defect
+  cases plus the parsed-nothing refusal). The other 9 pass **both ways** — which
+  is what makes them controls. Script restored **byte-exact** after the control
+  (sha match).
+- Reproduced by hand FIRST with a positive control firing in the same run; the
+  control is what makes the EVADES verdicts mean anything. A first probe batch in
+  an uninstalled worktree returned exit 0 for *everything including the controls*
+  — uniform results across independent subjects indicted the instrument, which is
+  how the parsed-nothing finding was discovered at all.
+- Real-tree verdict: exit 0 before and after. Full `npm run lint` chain exit 0.
+- `tsc --noEmit` exit 0.
+- Tier **1** declared: `classifyTier` reports riskFloor 1 with no safety-invariant
+  match (directional controls: `SessionReaper.ts` and `SecretStore.ts` both floor
+  2). The size heuristic suggests 2 on added LOC alone — stated openly, since the
+  tier I choose is the one that lets my own change through.

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.