instar 1.3.1627 → 1.3.1628

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

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

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

@@ -1,5 +1,5 @@
 {
-  "sha256": "24434c017122276e23e09b821e5f9e7f900d878c9a7cdaa143f3c6b0debdf62a",
+  "sha256": "b7bdec77909966bae0c48ed812dc177a28d214980fa5e6f5d415831cca3395b2",
   "registrySha256": "db01d9f92c6aa26ca903702896b41be53722982ed07d27633237bb254c214290",
-  "packageVersion": "1.3.1627"
+  "packageVersion": "1.3.1628"
 }

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

@@ -2,5 +2,5 @@
   "sha256": "db01d9f92c6aa26ca903702896b41be53722982ed07d27633237bb254c214290",
   "articleCount": 93,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1627"
+  "packageVersion": "1.3.1628"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1627",
+  "version": "1.3.1628",
   "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

@@ -21,11 +21,14 @@
  * for direct destructive `git <verb>` invocations (closed verb list).
  *
  * Exit codes:
- *   0 — no violations.
+ *   0 — every enumerated target file was inspected and none has a violation.
  *   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".
+ *   2 — could not inspect: NONE of the scanned files parsed (an environment
+ *       problem, e.g. a missing `typescript`), or SOME target file could not be
+ *       read or parsed (or a directory could not be listed) and no violation was
+ *       found elsewhere. Each uninspected path is printed with its reason.
+ *       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
@@ -237,6 +240,54 @@ function hasAllowComment(text) {
 
 const violations = [];
 
+/**
+ * Files (or directories) this run was meant to inspect but could not: unreadable,
+ * unparseable, or an unlistable directory. Each one is a hole in the scan, and a
+ * hole must not look like a clean file (#2190 / #2189) — any entry here refuses
+ * the run with the path and the reason.
+ */
+const uninspected = [];
+
+function recordUninspected(file, reason) {
+  uninspected.push({ file, reason });
+}
+
+/** Errors worth one more attempt: the file may be mid-write or the fd table momentarily full. */
+const TRANSIENT_READ_CODES = new Set(['EAGAIN', 'EBUSY', 'EINTR', 'EMFILE', 'ENFILE']);
+const READ_RETRY_DELAYS_MS = [50, 200];
+
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/** Read a file, briefly retrying transient errors. Throws the last error if every attempt fails. */
+function readFileWithRetry(file) {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      // Test hook, fail-closed only (same contract as INSTAR_LINT_FORCE_PARSE_FAILURE):
+      // it can only make a read fail, never make a file pass. `<basename>` fails
+      // every attempt; `<basename>:<n>` fails only the first n (exercises the retry).
+      const forced = process.env.INSTAR_LINT_FORCE_READ_FAILURE;
+      const [forcedName, forcedTimes] = (forced || '').split(':');
+      if (forcedName && path.basename(file) === forcedName
+        && (forcedTimes === undefined || attempt < Number(forcedTimes))) {
+        const err = new Error(`forced read failure (INSTAR_LINT_FORCE_READ_FAILURE=${forced})`);
+        err.code = 'EBUSY';
+        throw err;
+      }
+      return fs.readFileSync(file, 'utf8');
+    } catch (err) {
+      if (attempt >= READ_RETRY_DELAYS_MS.length || !TRANSIENT_READ_CODES.has(err.code)) throw err;
+      sleepSync(READ_RETRY_DELAYS_MS[attempt]);
+    }
+  }
+}
+
+function describeError(err) {
+  const message = String(err && err.message ? err.message : err);
+  return err && err.code && !message.startsWith(err.code) ? `${err.code}: ${message}` : message;
+}
+
 /**
  * Per-callsite marker: `// safe-git-allow: incremental-migration` placed on
  * the line immediately above (or at end of) a flagged callsite suppresses
@@ -336,6 +387,12 @@ const FS_MODULE_NAMES = new Set([
  *   7. Dynamic property access used to evade the rule (`fs['rm' + 'Sync']`) — flag.
  */
 function lintTsFile(file, text) {
+  // Per-file variant of the INSTAR_LINT_FORCE_PARSE_FAILURE hook (a basename
+  // instead of '1'), for the partial-failure refusal. Fail-closed only.
+  const forcedParse = process.env.INSTAR_LINT_FORCE_PARSE_FAILURE;
+  if (forcedParse && forcedParse !== '1' && path.basename(file) === forcedParse) {
+    throw new Error(`forced parse failure (INSTAR_LINT_FORCE_PARSE_FAILURE=${forcedParse})`);
+  }
   const T = ts();
   const sf = T.createSourceFile(file, text, T.ScriptTarget.Latest, true);
   const ctx = { text };
@@ -728,7 +785,9 @@ function lintPackageJsonScripts(file, text) {
   let pkg;
   try {
     pkg = JSON.parse(text);
-  } catch {
+  } catch (err) {
+    // An unparseable package.json hides every npm script from the git-verb check.
+    recordUninspected(file, `could not parse as JSON: ${describeError(err)}`);
     return;
   }
   const scripts = pkg.scripts || {};
@@ -751,7 +810,10 @@ function walkDir(dir, out) {
   let entries;
   try {
     entries = fs.readdirSync(dir, { withFileTypes: true });
-  } catch {
+  } catch (err) {
+    // A target dir that does not exist has nothing to inspect; one that exists
+    // but cannot be listed hides every file beneath it.
+    if (err.code !== 'ENOENT') recordUninspected(dir, `could not list directory: ${describeError(err)}`);
     return;
   }
   for (const e of entries) {
@@ -809,6 +871,18 @@ function gatherAll() {
   return out;
 }
 
+function writeUninspected() {
+  if (uninspected.length === 0) return;
+  process.stderr.write('\n');
+  process.stderr.write(
+    `[lint-no-direct-destructive] COULD NOT INSPECT ${uninspected.length} path(s) — `
+    + 'these were NOT checked, so this run cannot report them clean:\n'
+  );
+  for (const u of uninspected) {
+    process.stderr.write(`  ${path.relative(ROOT, u.file) || u.file}\n    ${u.reason}\n`);
+  }
+}
+
 // ── Main ───────────────────────────────────────────────────────────
 
 function main() {
@@ -828,8 +902,9 @@ function main() {
   for (const file of files) {
     let text;
     try {
-      text = fs.readFileSync(file, 'utf8');
-    } catch {
+      text = readFileWithRetry(file);
+    } catch (err) {
+      recordUninspected(file, `could not read: ${describeError(err)}`);
       continue;
     }
 
@@ -854,10 +929,12 @@ function main() {
       lintTsFile(file, text);
       astParsed += 1;
     } catch (err) {
-      // 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 thrown parse is a file this run did not inspect (#2190). It used to be a
+      // stderr warning with exit 0, so an unchecked file looked exactly like a
+      // clean one. Syntax the parser dislikes does NOT land here —
+      // createSourceFile recovers and returns a tree — so this cannot fail a
+      // build over one odd-but-valid file; it fires when inspection itself broke.
+      recordUninspected(file, `failed to parse: ${describeError(err)}`);
     }
   }
 
@@ -870,6 +947,7 @@ function main() {
   // 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) {
+    writeUninspected();
     process.stderr.write('\n');
     process.stderr.write(
       `[lint-no-direct-destructive] COULD NOT INSPECT — ${astAttempted} file(s) were scanned `
@@ -886,6 +964,17 @@ function main() {
     return 2;
   }
 
+  // Partial holes (#2190): some files could not be inspected. Name each one and
+  // its reason. Exit 2 ("could not inspect") unless violations were also found,
+  // which stay exit 1 — a definite finding outranks an incomplete scan.
+  if (uninspected.length > 0) {
+    writeUninspected();
+    if (violations.length === 0) {
+      process.stderr.write('Fix the cause (permissions, encoding, a broken install) and re-run.\n');
+      return 2;
+    }
+  }
+
   if (violations.length === 0) {
     return 0;
   }

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-11-03T14:15:29.861Z",
-  "instarVersion": "1.3.1627",
+  "generatedAt": "2026-11-03T18:02:09.861Z",
+  "instarVersion": "1.3.1628",
   "entryCount": 206,
   "entries": {
     "hook:session-start": {

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

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

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

@@ -1,5 +1,5 @@
 {
-  "sha256": "24434c017122276e23e09b821e5f9e7f900d878c9a7cdaa143f3c6b0debdf62a",
+  "sha256": "b7bdec77909966bae0c48ed812dc177a28d214980fa5e6f5d415831cca3395b2",
   "registrySha256": "db01d9f92c6aa26ca903702896b41be53722982ed07d27633237bb254c214290",
-  "packageVersion": "1.3.1627"
+  "packageVersion": "1.3.1628"
 }

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

@@ -2,5 +2,5 @@
   "sha256": "db01d9f92c6aa26ca903702896b41be53722982ed07d27633237bb254c214290",
   "articleCount": 93,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1627"
+  "packageVersion": "1.3.1628"
 }

package/upgrades/1.3.1628.md

@@ -0,0 +1,21 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The direct destructive-operation lint now reports files and directories it could not inspect. Temporary read errors are retried briefly; an unreadable or unparseable path produces a nonzero result instead of being silently skipped.
+
+## What to Tell Your User
+
+The source safety check now tells you when it could not inspect an enumerated source file. A clean result means it read the paths it selected to inspect.
+
+## Summary of New Capabilities
+
+- Names unreadable or unparseable selected files and unlistable existing directories, with the reason inspection failed.
+- Retries short-lived file read errors before reporting that the scan was incomplete.
+
+## Evidence
+
+The focused lint tests cover read and parse failures, transient retries, unreadable directories, and a clean tree. The exact PR head also passed the local unit, integration, and end-to-end verification before this release-note-only follow-up; the new head still requires its own verification.

package/upgrades/side-effects/lint-destructive-fail-closed.md

@@ -0,0 +1,72 @@
+# Side-Effects Review — destructive-operation lint scan completeness
+
+**Version / slug:** `lint-destructive-fail-closed`  
+**Date:** 2026-11-03  
+**Author:** Echo desk, integrating Justin's 2.0 agent PR #2641  
+**Second-pass reviewer:** independent reviewer subagent, 2026-11-03
+
+## Summary of the change
+
+`scripts/lint-no-direct-destructive.js` now records source paths it could not read, parse, or list, and returns exit 2 when inspection was incomplete and no definite violation was found. It retries transient read failures twice. Definite violations retain exit 1 and the incomplete paths are still reported. `tests/unit/lint-no-direct-destructive.test.ts` covers these boundaries. The release fragment and ELI16 overview explain the change. The decision point is whether a lint scan may certify a target set as clean; the existing policy still decides which destructive operations violate the rule.
+
+## Decision-point inventory
+
+- Lint scan completion and exit code — **modified**: an uninspected requested path makes a clean verdict unavailable.
+- Destructive-operation detection — **passed through**: existing patterns and allow comments are unchanged.
+- Release and pre-commit callers — **passed through**: they consume the command's result; this patch does not change those callers.
+
+## 1. Over-block
+
+A legitimate source tree can now fail lint when a file is temporarily unreadable or the parser throws. Two short retries cover transient read errors, but a longer file replacement may still require a rerun. A directory that exists but cannot be listed also fails, even if it ultimately contains no relevant source file, because the scanner cannot establish that fact. A missing optional directory remains acceptable. The cost is a failed development gate with a named path, which is repairable without changing product state.
+
+## 2. Under-block
+
+The scanner still only inspects paths selected by its existing traversal and file-extension rules. A destructive call outside those targets or hidden behind dynamic code can evade the preexisting detector. Explicit paths that do not exist, and staged paths whose files cannot be stat'ed, are filtered before the read loop; those remain a separate missing-target gap. A target file that is modified after it was read can change before a later build step. The normal `npm run lint` chain stops on exit 2, but `scripts/pre-push-gate.js` currently turns exit 2 into a warning. That caller can still let an incomplete pre-push scan through. This patch changes the scanner's verdict for selected paths; it does not make every caller reject that verdict or claim a transactionally frozen repository snapshot.
+
+## 3. Level-of-abstraction fit
+
+Scan completeness belongs inside the scanner, where read, parse, and directory-list errors are visible. The existing development and release gates consume its exit code; a separate downstream checker could not recover which path was skipped. This is a structural validator for an attempted inspection, while the existing destructive-operation detector retains its policy.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] This is a hard-invariant validation: a scan cannot certify a selected path it did not inspect.
+- [ ] This adds a semantic judgment based on a brittle signal.
+
+The principle explicitly permits structural validation and safety guards for destructive actions. The rule here is enumerable: an attempted target path was inspected or it was not. Exit 2 says “could not inspect” and prints evidence; it does not claim a destructive operation was found or infer author intent. The existing gate owns whether to block the commit on that result. A failure may need a retry, but a clean verdict must not be fabricated.
+
+## 4b. Judgment-point check
+
+No new static heuristic at a competing-signals decision point. The only new choice is whether every selected path was inspected. That is an invariant of the scan, not a ranking among liveness, urgency, ownership, or conversational signals.
+
+## 5. Interactions
+
+- **Shadowing:** The existing total-parser-failure branch still runs first; the new partial-hole branch follows it. A definite destructive violation still exits 1. The package-script JSON parser records malformed input rather than silently skipping it.
+- **Double-fire:** A read failure records one path once; no separate worker is started. The diagnostic lists incomplete paths when a definite violation is present, avoiding a silent second failure.
+- **Races:** A concurrent write may produce a transient read error. Two short retries precede exit 2; rerunning remains available. There is no shared mutable state across lint processes.
+- **Feedback loops:** The lint is invoked by development gates and may stop a commit or push, but it does not mutate the source being inspected or schedule a new run.
+
+## 6. External surfaces
+
+Other contributors and agents see path-specific stderr and exit 2 for an incomplete scan that previously looked clean. Existing scripts that distinguish exit 1 from exit 2 retain that distinction, including the pre-push gate's warning behavior. No Telegram, GitHub API, database, or user message is emitted by the lint. No operator-facing action is added; resolving a named unreadable file remains a developer task. Runtime product behavior is unchanged until a developer invokes the lint gate.
+
+## 6b. Operator-surface quality
+
+No operator surface — not applicable. No dashboard, approval, or grant form is changed.
+
+## 7. Multi-machine posture
+
+**Machine-local BY DESIGN.** Each checkout's files, permissions, and parser installation are machine-specific facts; each machine runs its own lint against its own source tree. The result has no agent conversation, durable user state, notice, or URL to replicate. A PR merges only after its relevant gate evidence is evaluated for the code being shipped.
+
+## 8. Rollback cost
+
+Revert the source and test commit, then rerun lint. No state migration or user repair is needed. A revert restores the old incomplete-scan behavior, so it should be used only if the new diagnostic itself is faulty; the named path gives a narrower repair route.
+
+## Conclusion and class closure
+
+The change handles unreadable files, thrown parses, malformed package scripts, and unlistable existing directories with one incomplete-scan record path. A selected file that reaches the read loop is no longer silently skipped. Remaining limits include missing paths filtered before that loop, the pre-push caller's warning treatment of exit 2, and the existing pattern policy. The focused tests and exact-head local gate are the verification surfaces; the new commit needs its own exact-head gate before merge.
+
+## Independent second pass
+
+Confirmed the pre-push warning and pre-enumeration missing-path gaps are disclosed under Under-block; the selected-path scan-completeness change is reversible and consistent with the structural safety-guard exception in `docs/signal-vs-authority.md`. **Concur with the review.**