instar 1.3.1151 → 1.3.1152

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

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

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

@@ -1,5 +1,5 @@
 {
-  "sha256": "2781a4e62937b5faedcefb2635981134a4f27ba058786b5d16b5017f41b017e9",
+  "sha256": "cb5b39009ce485f47b3010b819bd2a9c0dc4e2294204deaef41bf69db200fd41",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1151"
+  "packageVersion": "1.3.1152"
 }

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1151",
+  "version": "1.3.1152",
   "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-unfunneled-tmux-literal-send.js

@@ -22,9 +22,33 @@
  * Structure > Willpower — a comment asking authors to remember is a wish; this
  * is the guarantee.
  *
- * Guardrail, not proof: a wrapper that builds the argv array dynamically could
- * still evade it. The declared duty stays "literal sends go through the
- * funnel"; this catches the direct pattern.
+ * SCOPE CORRECTED 2026-08-15. The previous header said only that "a wrapper that
+ * builds the argv array dynamically could still evade it". That understated the
+ * gap: the check was LINE-oriented and required `send-keys` and `'-l'` on the
+ * SAME line, so four PLAIN literal forms — none of them dynamic, none of them a
+ * wrapper — walked straight past it. Measured against the shipped check, with the
+ * one-line form as a positive control firing in the same run:
+ *
+ *   ["send-keys", "-l", p]                        CONTROL  exit 1 (caught)
+ *   [\n  "send-keys",\n  "-l",\n  p,\n]        exit 0 — EVADES
+ *   const F = "-l";      ["send-keys", F, p]      exit 0 — EVADES
+ *   const C = "send-keys"; [C, "-l", p]           exit 0 — EVADES
+ *   ["send-keys","-l",p]  // buildLiteralSendArgs exit 0 — EVADES
+ *
+ * The first is the one that matters: a multi-line argv array is simply how any
+ * formatter writes an array over the print width. The guard could be defeated by
+ * running prettier. The last is worse in kind — merely NAMING the funnel in a
+ * COMMENT on that line suppressed the check, so `// TODO: use buildLiteralSendArgs`
+ * beside a raw send silenced the guard that the TODO was admitting was needed.
+ *
+ * Now: comments are stripped quote-aware first, string constants are resolved
+ * per file, and the unit of matching is the ARRAY LITERAL (bracket-matched,
+ * bounded) rather than the line — which is what the original rule always meant.
+ *
+ * STILL not proof, and this is the honest remainder: an argv array assembled at
+ * RUNTIME (push(), concat(), spread of a computed list, a helper that returns the
+ * array) is invisible here. That is the gap the original header named, and it is
+ * the only one left. Closing it needs dataflow, not more patterns.
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -46,20 +70,142 @@ function walk(dir, out = []) {
   return out;
 }
 
+/**
+ * Strip // and block comments WITHOUT touching string contents, replacing each
+ * removed character with a space so every byte offset — and therefore every
+ * reported line number — is preserved exactly.
+ */
+export function stripComments(src) {
+  let out = '';
+  let i = 0;
+  let quote = null;
+  while (i < src.length) {
+    const c = src[i];
+    const n = src[i + 1];
+    if (quote) {
+      out += c;
+      if (c === '\\') { out += n ?? ''; i += 2; continue; }
+      if (c === quote) quote = null;
+      i += 1;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === '`') { quote = c; out += c; i += 1; continue; }
+    if (c === '/' && n === '/') {
+      while (i < src.length && src[i] !== '\n') { out += ' '; i += 1; }
+      continue;
+    }
+    if (c === '/' && n === '*') {
+      out += '  '; i += 2;
+      while (i < src.length && !(src[i] === '*' && src[i + 1] === '/')) {
+        out += src[i] === '\n' ? '\n' : ' ';
+        i += 1;
+      }
+      out += '  '; i += 2;
+      continue;
+    }
+    out += c;
+    i += 1;
+  }
+  return out;
+}
+
+/**
+ * Identifiers bound to a plain string literal in THIS file. An identifier bound
+ * more than once to DIFFERENT values is UNRESOLVABLE and dropped, so an ambiguous
+ * name can never be substituted into a match — ambiguity fails toward NOT flagging,
+ * because a guess that fails someone's build is the expensive direction.
+ */
+export function collectStringConsts(code) {
+  const seen = new Map();
+  const conflicting = new Set();
+  const DECL = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(['"`])([^'"`\n]*)\2/g;
+  let m;
+  while ((m = DECL.exec(code)) !== null) {
+    const [, name, , value] = m;
+    if (seen.has(name) && seen.get(name) !== value) conflicting.add(name);
+    else seen.set(name, value);
+  }
+  for (const name of conflicting) seen.delete(name);
+  return seen;
+}
+
+/**
+ * Every bracket-matched array literal in the source, as {text, line}. Bounded:
+ * an array longer than MAX_ARRAY_CHARS is truncated rather than scanned whole, so
+ * a pathological file cannot make this quadratic. Unbalanced brackets simply
+ * yield no region — the check fails toward NOT flagging.
+ */
+const MAX_ARRAY_CHARS = 4000;
+export function arrayRegions(code) {
+  const regions = [];
+  for (let i = 0; i < code.length; i++) {
+    if (code[i] !== '[') continue;
+    let depth = 0;
+    let quote = null;
+    let j = i;
+    for (; j < code.length && j - i < MAX_ARRAY_CHARS; j++) {
+      const c = code[j];
+      if (quote) {
+        if (c === '\\') { j += 1; continue; }
+        if (c === quote) quote = null;
+        continue;
+      }
+      if (c === '"' || c === "'" || c === '`') { quote = c; continue; }
+      if (c === '[') depth += 1;
+      else if (c === ']') { depth -= 1; if (depth === 0) break; }
+    }
+    if (depth !== 0) continue;
+    const text = code.slice(i, j + 1);
+    const line = code.slice(0, i).split('\n').length;
+    regions.push({ text, line });
+  }
+  return regions;
+}
+
+/** True when the resolved region is a raw literal `send-keys -l` argv. */
+export function regionViolates(regionText, consts) {
+  let t = regionText;
+  for (const [name, value] of consts) {
+    t = t.replace(new RegExp(`\\b${name}\\b`, 'g'), `'${value}'`);
+  }
+  if (!/['"`]send-keys['"`]/.test(t)) return false;
+  if (!/['"`]-l['"`]/.test(t)) return false;
+  // Already funnelled — checked on COMMENT-STRIPPED code, so merely naming the
+  // funnel in a comment can no longer silence the guard.
+  if (t.includes('buildLiteralSendArgs')) return false;
+  return true;
+}
+
+export function scanSource(code) {
+  const stripped = stripComments(code);
+  const consts = collectStringConsts(stripped);
+  const hits = [];
+  for (const region of arrayRegions(stripped)) {
+    if (regionViolates(region.text, consts)) {
+      hits.push({ line: region.line, text: region.text.replace(/\s+/g, ' ').trim() });
+    }
+  }
+  return hits;
+}
+
+// DIRECT-INVOCATION GUARD. Without it, importing this module to unit-test the
+// helpers above runs the whole src/ scan and calls process.exit(1) the moment the
+// repo has a real violation — killing the importing process. Four other lints hit
+// exactly that this week; the guard is the same fix.
+const invokedDirectly =
+  process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
+
+if (invokedDirectly) runLint();
+
+function runLint() {
 const violations = [];
 
 for (const file of walk(SRC)) {
   const rel = path.relative(REPO, file);
   if (EXEMPT.has(rel)) continue;
-  const lines = fs.readFileSync(file, 'utf-8').split('\n');
-  lines.forEach((line, i) => {
-    // Match an argv array literal carrying both 'send-keys' and a '-l' flag.
-    if (!line.includes('send-keys')) return;
-    if (!/['"]-l['"]/.test(line)) return;
-    // Already funnelled.
-    if (line.includes('buildLiteralSendArgs')) return;
-    violations.push({ rel, line: i + 1, text: line.trim() });
-  });
+  for (const hit of scanSource(fs.readFileSync(file, 'utf-8'))) {
+    violations.push({ rel, line: hit.line, text: hit.text });
+  }
 }
 
 if (violations.length > 0) {
@@ -76,3 +222,4 @@ if (violations.length > 0) {
 }
 
 console.log(`✓ tmux literal sends funnelled (scanned ${walk(SRC).length} files, 0 unfunneled)`);
+}

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-08-15T00:48:31.405Z",
-  "instarVersion": "1.3.1151",
+  "generatedAt": "2026-08-15T01:02:42.043Z",
+  "instarVersion": "1.3.1152",
   "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.1151",
+  "packageVersion": "1.3.1152",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

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

@@ -1,5 +1,5 @@
 {
-  "sha256": "2781a4e62937b5faedcefb2635981134a4f27ba058786b5d16b5017f41b017e9",
+  "sha256": "cb5b39009ce485f47b3010b819bd2a9c0dc4e2294204deaef41bf69db200fd41",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1151"
+  "packageVersion": "1.3.1152"
 }

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

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

package/upgrades/1.3.1152.md

@@ -0,0 +1,54 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`scripts/lint-no-unfunneled-tmux-literal-send.js` now matches the bracket-matched ARGV ARRAY rather
+than a single line.
+
+That lint guards the `send-keys -l` argv ceiling (~16.2 KB) — the class behind the 2026-08-04 incident
+where a ~40 KB prompt blew the ceiling, the circuit breaker misread the opaque send error as a provider
+rate-limit and tripped 14 consecutive times, and ten LLM-backed components sat at 76-100% error rate.
+
+It required `send-keys` and `'-l'` on the SAME line, so four PLAIN literal forms evaded it — measured
+against the shipped check with the one-line form as a positive control firing in the same run: a
+multi-line array (what any formatter produces), the flag lifted into a const, the verb lifted into a
+const, and — worst in kind — merely NAMING the funnel in a comment on that line, so
+`// TODO: use buildLiteralSendArgs` beside a raw send silenced the guard the TODO was admitting was
+needed.
+
+The first is the one that matters: **the guard could be defeated by running prettier.**
+
+Added: `stripComments` (quote-aware, line-number preserving), `collectStringConsts` (per-file;
+conflicting bindings dropped as unresolvable), `arrayRegions` (bracket-matched, string-aware, bounded),
+`regionViolates` and `scanSource`. The rule, the exemption and the message are unchanged. Also added a
+direct-invocation guard — importing the module previously ran the whole `src/` scan and could
+`process.exit(1)`, which is why its internals had never been unit-tested.
+
+## What to Tell Your User
+
+Nothing changes for you. A build-time check that stops a known way of breaking terminal sends could be
+walked past just by letting a code formatter split a list across lines — no intent required. It now
+reads the whole list instead of one line. Nothing you use behaves differently; a failure mode that once
+took down ten components for hours got harder to reintroduce by accident.
+
+## Summary of New Capabilities
+
+None. No new command, endpoint, setting, or runtime behaviour. A CI guard that a code formatter could
+defeat no longer can be.
+
+## Evidence
+
+- `tests/unit/tmux-send-lint-array-scope.test.ts` — 18/18 green.
+- **Negative control: 6 of 18 fail** against the shipped line-oriented behaviour; the other 12 pass both
+  ways and are the controls. Source restored byte-exact afterwards (sha match, zero markers left).
+- Six anti-over-block controls, because this lint blocks commits: send-keys without the flag; a genuinely
+  funnelled call; two SEPARATE arrays never joined; a const bound to a different flag; an example living
+  entirely inside a comment; and an identifier with conflicting bindings left unresolvable.
+- Real tree: `exit 0` before AND after, 1,631 files scanned.
+- Full `npm run lint` chain green; chain membership verified explicitly rather than inferred.
+- **Scope CORRECTED, not restated:** the old header claimed only that a dynamically-built argv could
+  evade it. None of the four measured evasions is dynamic. The header now names what was actually
+  missing, and the genuine remainder (a runtime-assembled array — push/concat/spread/helper).

package/upgrades/side-effects/tmux-send-lint-array-scope.md

@@ -0,0 +1,122 @@
+# Side-Effects Review — tmux send-keys guard matches the array, not the line
+
+**Version / slug:** `tmux-send-lint-array-scope`
+**Date:** `2026-08-15`
+**Author:** `echo`
+**Second-pass reviewer:** `not required — Tier 1 (CI-only lint script; no runtime path). The rule is unchanged; the check now reads the unit it always meant (the argv array) instead of a single line.`
+
+## Summary of the change
+
+`scripts/lint-no-unfunneled-tmux-literal-send.js` guards the `send-keys -l` argv ceiling (~16.2 KB).
+The 2026-08-04 incident it exists to prevent: a ~40 KB prompt blew the ceiling, `LlmCircuitBreaker`
+misclassified the opaque send error as a provider rate-limit and tripped 14 consecutive times while ten
+LLM-backed components sat at 76-100% error rate.
+
+The check required `send-keys` AND `'-l'` on the SAME LINE. Measured against the shipped check, with the
+one-line form as a positive control firing in the same run:
+
+| form | shipped |
+|---|---|
+| `["send-keys", "-l", p]` — POSITIVE CONTROL | exit 1 (caught) |
+| the same array across 5 lines | **exit 0 — EVADES** |
+| `const F = "-l"; ["send-keys", F, p]` | **exit 0 — EVADES** |
+| `const C = "send-keys"; [C, "-l", p]` | **exit 0 — EVADES** |
+| `["send-keys","-l",p] // buildLiteralSendArgs` | **exit 0 — EVADES** |
+
+The unit of matching is now the bracket-matched ARRAY LITERAL, over comment-stripped, const-resolved
+source. The rule, the exemption and the message are unchanged.
+
+## Decision-point inventory
+
+- `stripComments(src)` — ADD — quote-aware; replaces removed bytes with spaces so line numbers are exact.
+- `collectStringConsts(code)` — ADD — per-file identifier → literal; conflicting bindings dropped.
+- `arrayRegions(code)` — ADD — bracket-matched, string-aware, bounded at 4000 chars per region.
+- `regionViolates(text, consts)` — ADD — resolves then applies the EXISTING two patterns.
+- `scanSource(code)` — ADD — the composed scan, extracted so matching is testable.
+- Direct-invocation guard — ADD — the scan runs only when invoked directly.
+- The `EXEMPT` set, the two patterns, the violation message and exit codes — UNCHANGED.
+- No runtime block/allow decision added or modified. CI-time only.
+
+## 1. Over-block
+
+The failure that matters: this lint blocks commits, and a check that flags correct code gets switched
+off. Six controls, each with a test, all passing under BOTH old and new behaviour:
+
+- `send-keys` WITHOUT `-l` is not flagged (only the literal form has the ceiling).
+- A genuinely funnelled `buildLiteralSendArgs(...)` call is not flagged.
+- **Two separate arrays are never joined** — an unrelated `["ls", "-l"]` cannot complete a send-keys
+  array. This is the whole reason the unit is a bracket-matched region rather than a line window.
+- A const bound to a different flag is not flagged.
+- An example living entirely inside a comment is not flagged — which is what makes it safe to document
+  the bad pattern, including in this file and the ELI16.
+- An identifier bound twice to DIFFERENT values is unresolvable and never substituted.
+
+Unbalanced brackets yield no region, so a syntax error elsewhere cannot become a false accusation.
+
+**Verified against the real tree: exit 0 before AND after**, scanning 1,631 files. No new flags.
+
+## 2. Under-block
+
+Stated in the source, and it is a CORRECTION rather than a restatement. The old header claimed only
+that "a wrapper that builds the argv array dynamically could still evade it" — true, but it understated
+the gap, since none of the four measured evasions is dynamic or a wrapper. The header now names what was
+actually missing and what genuinely remains:
+
+- An argv array assembled at RUNTIME — `push()`, `concat()`, spread of a computed list, or a helper that
+  returns the array. That is the original declared gap and it is the only one left.
+- Closing it needs dataflow, not more patterns.
+
+## 3. Level-of-abstraction fit
+
+Same layer as the existing check — regex over source text, no AST, no type information, no new
+dependency. Bracket matching is the minimum needed to read an array literal as one unit; going further
+(a parser) would be a different check at a different layer.
+
+## 4. Signal vs authority compliance
+
+Unchanged. A CI guard, not a runtime authority. It pushes callers toward `buildLiteralSendArgs()`; the
+funnel itself stays exempt.
+
+## 5. Interactions
+
+- `npm run lint` chain — membership verified explicitly (in the `lint` chain CI runs, not merely
+  referenced by a standalone entry); full chain green.
+- The direct-invocation guard changes import behaviour from "runs the src/ scan and may exit(1)" to
+  "exports only". Nothing imported this module before, so no caller changes.
+- No source module, route, config key, or state file touched.
+
+## 6. External surfaces
+
+None. Developer tooling, not an agent capability; the Agent Awareness Standard does not apply.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Machine-local BY DESIGN, and correctly so — not an unexamined assumption.** A CI-time source scan with
+no runtime surface: it reads files in one checkout and exits. No durable state, no user-facing notice, no
+generated URL, no runtime decision — so nothing to replicate, nothing to merge on read, nothing that can
+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. Resolution 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.
+
+## Conclusion
+
+Ship. Four evasions closed on a guard with a real production incident behind it, six anti-over-block
+controls added, the stated scope corrected rather than restated, and the import hazard removed.
+
+## Evidence pointers
+
+- `tests/unit/tmux-send-lint-array-scope.test.ts` — **18/18 green**.
+- **Negative control: 6 of 18 fail** against the shipped line-oriented behaviour. The other 12 pass both
+  ways — which is what makes them controls. Source restored byte-exact after the mutation (sha match,
+  zero markers left).
+- Reproduced by hand FIRST with a positive control firing in the same run; the control is what makes the
+  four EVADES verdicts mean anything.
+- Real-tree verdict: exit 0, 1,631 files scanned, before and after.
+- Full `npm run lint` chain green.
+- Tier **1** declared: risk floor 1, verified with a directional control (`SessionReaper.ts` → floor 2
+  with its reason named). 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.