@sabaiway/agent-workflow-kit 5.10.0 → 5.11.1

package/tools/flow-subset-budget.mjs

@@ -0,0 +1,81 @@
+// flow-subset-budget.mjs — the Decision-7/8 counting-context budget (Plan 4): the two caps, the ONE
+// budget walk both consumers share (subsetAttemptState), the exhaustion remedy prose, and the
+// under-lock gate the append lane runs. Split out of flow-store.mjs unchanged (baseline-practices
+// tranche 2); the facade re-exports everything here except subsetAttemptGate, which crosses to
+// flow-append.mjs alone and stays off the store's public surface.
+//
+// PURE over read results, beside flow-chain-state.mjs at the bottom of the store's five leaves: no
+// store IO, no git, no fs, and the record vocabulary is its only tools sibling.
+
+import { flowRecordKey, subsetFoldBatchDigest } from './flow-record.mjs';
+
+// The waste bound is the CAP, not the prose (Decision 8): a counting context allows at most
+// THREE red attempts (two blind + one diagnosed) on its own; past that, no diagnosis reopens it —
+// only a recorded FRESH-EYES consult verdict does, one further attempt per consult.
+export const SUBSET_ATTEMPT_MAX_REDS = 3;
+
+// Past the SECOND red every further attempt at the key rides a recorded diagnosis — the
+// obligation keys on REDS, never on the attempt index (a green history stays blind-legal).
+export const SUBSET_ATTEMPT_DIAGNOSIS_REDS = 2;
+
+// subsetAttemptState(records, probe) → { attempts, nextIndex, reds, credits, exhausted } — the
+// ONE Decision-7/8 budget walk both consumers share (the locked gate below re-runs it under the
+// lock; run-gates' pre-gate check reads it lock-free). The exhaustion ladder is PERMIT-based
+// and foldBatch-GLOBAL (round-3 disposition): red counts stay per key, but permits and their
+// consumption span EVERY subsetDigest of the round context — one consult verdict is exactly
+// ONE further attempt across the whole foldBatch, whichever subset spends it. Consult identity
+// {backend, nonce} is tracked STORE-WIDE before any relevance filtering, so a replay from
+// another round (or any seen identity — pre-exhaustion or spent) never credits; a credit is
+// granted only for a NEW identity whose {planId, cycle, stepId, round} digests to this
+// foldBatch while SOME key of the foldBatch is base-exhausted at that point in raw order.
+// EVERY attempt recorded past its own key's base budget consumes one credit, whatever its
+// status; a tampered store that drove credits negative stays exhausted (fail closed).
+export const subsetAttemptState = (records, probe) => {
+  const key = flowRecordKey({ kind: 'subset-attempt', ...probe });
+  const attempts = [];
+  const seenConsults = new Set();
+  const redsByKey = new Map();
+  let credits = 0;
+  const someKeyExhausted = () => [...redsByKey.values()].some((n) => n >= SUBSET_ATTEMPT_MAX_REDS);
+  for (const r of records) {
+    if (r.kind === 'subset-attempt' && r.foldBatch === probe.foldBatch) {
+      const rKey = flowRecordKey(r);
+      const priorReds = redsByKey.get(rKey) ?? 0;
+      if (priorReds >= SUBSET_ATTEMPT_MAX_REDS) credits -= 1;
+      if (r.status === 'red') redsByKey.set(rKey, priorReds + 1);
+      if (rKey === key) attempts.push(r);
+    } else if (r.kind === 'consult-attestation') {
+      const identity = JSON.stringify([r.backend, r.nonce]);
+      const relevant = subsetFoldBatchDigest({ planId: r.planId, cycle: r.cycle, stepId: r.stepId, round: r.round }) === probe.foldBatch;
+      if (relevant && !seenConsults.has(identity) && someKeyExhausted()) credits += 1;
+      seenConsults.add(identity);
+    }
+  }
+  const reds = redsByKey.get(key) ?? 0;
+  return {
+    attempts,
+    nextIndex: attempts.reduce((m, r) => Math.max(m, r.attemptIndex), 0) + 1,
+    reds,
+    credits,
+    exhausted: reds >= SUBSET_ATTEMPT_MAX_REDS && credits <= 0,
+  };
+};
+
+export const subsetExhaustionRemedy = 'the fresh-eyes lane reopens it (Decision 8 — never a human wait-state): dispatch a MANDATORY grounded bridge consult (a different model) carrying the full attempt/diagnosis trail; its recorded consult-attestation at this round context reopens exactly ONE further diagnosed attempt. Otherwise park the stuck work with its trail and switch to independent work; a fresh context opens with the next round (new foldBatch) or a declared pregateExclude change (new subsetDigest)';
+
+// The under-lock rules the factory does NOT already enforce itself: the exhaustion ladder and
+// the byte-distinct diagnosis (blind thrashing refuses; a NEW hypothesis proceeds). The
+// monotonic index and the reds-based diagnosis REQUIREMENT live in the factory alone — it is
+// the ONLY entry for this kind (the generic lane refuses it by name, round-9 fold), computes
+// the index from the SAME locked snapshot this gate sees, and throws its own named stops first.
+export const subsetAttemptGate = (records, snapshot) => {
+  const { attempts, reds, exhausted } = subsetAttemptState(records, snapshot);
+  if (exhausted) {
+    return { ok: false, reason: `this counting context already holds ${reds} red attempts — EXHAUSTED (two blind + one diagnosed, Decision 8) and no diagnosis reopens it; ${subsetExhaustionRemedy}` };
+  }
+  const prior = attempts.find((r) => r.attemptIndex === snapshot.attemptIndex - 1);
+  if (typeof snapshot.diagnosis === 'string' && prior != null && prior.diagnosis === snapshot.diagnosis) {
+    return { ok: false, reason: "the diagnosis is byte-identical to the prior attempt's — a diagnosed continuation states a NEW hypothesis (Decision 8); blind thrashing refuses" };
+  }
+  return { ok: true };
+};

package/tools/flow-writer.mjs

@@ -48,7 +48,7 @@
 
 import { readFileSync, lstatSync } from 'node:fs';
 import { join, dirname } from 'node:path';
-import { pathToFileURL, fileURLToPath } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import { createHash, randomBytes } from 'node:crypto';
 import {
   FLOW_SCHEMA_VERSION, CHAIN_KIND, canonicalFlowDigest, flowTreeIdentity,
@@ -59,6 +59,7 @@ import {
   appendFlowRecord, appendFlowRecordWithPreflight, mintAdoption, readPlanFrontmatterId,
   resolveRecordReference, priorChainTerminal,
 } from './flow-store.mjs';
+import { isDirectRun } from './direct-run.mjs';
 import { readFileBytesNoFollow, gitLine } from './flow-store-read.mjs';
 import {
   resolveBase, computeTreeFingerprint, lexicalRepoRelative,
@@ -1256,8 +1257,7 @@ export const main = (argv, ctx = {}) => {
   }
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) {
+if (isDirectRun(import.meta.url)) {
   const r = main(process.argv.slice(2));
   if (r.stdout) console.log(r.stdout);
   if (r.stderr) console.error(r.stderr);

package/tools/gate-hook.mjs

@@ -41,7 +41,7 @@
 
 import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import {
   CLAUDE_DIR,
   EXPECTED_WORKFLOW_VERSION,
@@ -54,6 +54,7 @@ import {
   resolveEffectiveMode,
 } from './velocity-profile.mjs';
 import { assertDocsAiDeployment, writeDocsAiFileAtomic } from './atomic-write.mjs';
+import { isDirectRun } from './direct-run.mjs';
 import { shellQuoteArg } from './review-state.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -572,5 +573,4 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
   }
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) process.exit(main(process.argv.slice(2)));
+if (isDirectRun(import.meta.url)) process.exit(main(process.argv.slice(2)));

package/tools/gates-init.mjs

@@ -58,7 +58,8 @@
 
 import { existsSync, lstatSync, readFileSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
+import { isDirectRun } from './direct-run.mjs';
 import { discoverGateCandidates, EXPECTED_WORKFLOW_VERSION } from './velocity-profile.mjs';
 import { GATES_REL, validateDeclaration } from './run-gates.mjs';
 import { canonicalCheckerGates, coverageDeclarationDefects, isKitOwnedCheckerGate } from './gates-declaration.mjs';
@@ -795,5 +796,4 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
   }
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) process.exit(main(process.argv.slice(2)));
+if (isDirectRun(import.meta.url)) process.exit(main(process.argv.slice(2)));

package/tools/grounding.mjs

@@ -31,8 +31,8 @@
 import { readFileSync, writeFileSync, lstatSync, realpathSync } from 'node:fs';
 import { resolve, join, relative, isAbsolute, dirname, basename, sep } from 'node:path';
 import { tmpdir } from 'node:os';
-import { pathToFileURL } from 'node:url';
 import { spawnSync } from 'node:child_process';
+import { isDirectRun } from './direct-run.mjs';
 import { fail } from './orchestration-config.mjs';
 import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
 // (f) --autonomy (AD-044 Plan 3): the effective per-project autonomy policy for the facts payload.
@@ -466,8 +466,7 @@ export const main = (argv, ctx = {}) => {
   }
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) {
+if (isDirectRun(import.meta.url)) {
   const r = main(process.argv.slice(2));
   // Exact writes + a natural exit: console.log would append a stray newline to the
   // byte-exact facts payload, and process.exit() can truncate large piped stdout before Node

package/tools/hide-footprint.mjs

@@ -24,8 +24,8 @@ import {
 } from 'node:fs';
 import { join, resolve, relative, isAbsolute, basename } from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { pathToFileURL } from 'node:url';
 import os from 'node:os';
+import { isDirectRun } from './direct-run.mjs';
 import {
   KIT_OWN_PATHS, KNOWN_FOOTPRINT, FOOTPRINT_STOP, stop,
   normalizeSlashes, isDirPattern, patternToProbe, expandGlob, matchesKnownGlob,
@@ -584,5 +584,4 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
   }
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) process.exit(main(process.argv.slice(2)));
+if (isDirectRun(import.meta.url)) process.exit(main(process.argv.slice(2)));

package/tools/inject-methodology.mjs

@@ -26,6 +26,7 @@
 // ONLY when its content normalize-matches a KNOWN PRIOR canonical fragment (drift-guarded, append-only
 // per descriptor). A customized slot never matches → preserved verbatim + a read-only upgrade advisory.
 
+import { isDirectRun } from './direct-run.mjs';
 import { normalizeCanonical } from './orchestration-config.mjs';
 
 export const START_MARKER = '<!-- workflow:methodology:start -->';
@@ -599,9 +600,7 @@ export const runCli = async (argv, deps = {}) => {
   }
 };
 
-const { pathToFileURL } = await import('node:url');
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) {
+if (isDirectRun(import.meta.url)) {
   const { code, stdout, stderr } = await runCli(process.argv.slice(2));
   if (stdout) process.stdout.write(stdout);
   if (stderr) process.stderr.write(stderr);

package/tools/lens-region.mjs

@@ -27,6 +27,7 @@
 //
 // Pure string functions (fs only in the CLI); dependency-free, Node >= 22.
 
+import { isDirectRun } from './direct-run.mjs';
 import { normalizeCanonical } from './orchestration-config.mjs';
 
 // The deployed-heading matcher (prefix, like the historical extractLensBlock: robust to a future
@@ -386,6 +387,4 @@ export const runCli = async (argv, deps = {}) => {
   return 0;
 };
 
-const { pathToFileURL } = await import('node:url');
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) process.exitCode = await runCli(process.argv.slice(2));
+if (isDirectRun(import.meta.url)) process.exitCode = await runCli(process.argv.slice(2));

package/tools/manifest/validate.mjs

@@ -20,7 +20,7 @@
 
 import { readFileSync, existsSync } from 'node:fs';
 import { resolve, join, isAbsolute } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { isDirectRun } from '../direct-run.mjs';
 
 export const FAMILY = 'agent-workflow';
 export const SUPPORTED_SCHEMA = 1;
@@ -765,5 +765,4 @@ const main = (argv) => {
   if (strict && notValid > 0) process.exit(1);
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) main(process.argv.slice(2));
+if (isDirectRun(import.meta.url)) main(process.argv.slice(2));

package/tools/migrate-adr-store.mjs

@@ -33,7 +33,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync, mkdirSync, writeFileSync, chmodSync } from 'node:fs';
 import { join, resolve, dirname, relative, isAbsolute } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import { writeContainedFileAtomic, assertDocsAiDeployment } from './atomic-write.mjs';
@@ -47,6 +47,7 @@ import {
   defaultRegenerateIndex,
   runCli as runArchiveDecisions,
 } from '../references/scripts/archive-decisions.mjs';
+import { isDirectRun } from './direct-run.mjs';
 import { surveyAdrLayoutStrict, ADR_LAYOUT_PATHS } from './family-registry.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -463,5 +464,4 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
   }
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) process.exitCode = main();
+if (isDirectRun(import.meta.url)) process.exitCode = main();

package/tools/observation-builder.mjs

@@ -0,0 +1,123 @@
+// observation-builder.mjs — measure a scope and construct the OBSERVATION record (delegation
+// Plan 3, Phase 3). Extracted from dispatch.mjs so `dispatch observe` and the handoff-return rung
+// build the IDENTICAL record through ONE path: the rung is imported by dispatch.mjs for its verb,
+// so a rung importing dispatch.mjs back would be exactly the cycle test/read-graph-purity.test.mjs
+// pins the tools graph against. Every function here moved byte-for-byte; the only new export is
+// the record construction the observe verb previously inlined.
+//
+// Spawns nothing but git READS (through the shared gitLine). No CLI, no writes, no side effects on
+// import. Dependency-free, Node >= 22.
+
+import { readFileSync, openSync, closeSync, realpathSync, constants as fsConstants } from 'node:fs';
+import { resolve, sep } from 'node:path';
+import {
+  DELEGATION_SCHEMA_VERSION, computeNumerator, evaluateObservationEligibility,
+} from './dispatch-record.mjs';
+import { lstatNoFollowRead, describeNonRegular } from './fs-read-nofollow.mjs';
+import { gitLine } from './flow-store-read.mjs';
+import { lexicalRepoRelative } from './repo-lex.mjs';
+
+// The solo baseline counts each scope object's POST-IMAGE — the bytes on disk after the
+// construction — which is exactly the `new` numerator rule (D6). No exec diff kind enumerates
+// ranges, so a measured observation can never claim a partial object.
+const SOLO_COMPONENT_KIND = 'new';
+
+// The scope's anchor is the git TOP-LEVEL, never the caller's cwd: a recorded scope must name the
+// same objects whoever runs the tool from wherever. `null` outside a work tree — a repo-relative
+// domain with no repository has nothing to be relative TO, and falling back to cwd would be a
+// second, incompatible semantics for the same field.
+export const resolveRepoRoot = (cwd) => {
+  if (gitLine(['rev-parse', '--is-inside-work-tree'], cwd) !== 'true') return null;
+  const top = gitLine(['rev-parse', '--show-toplevel'], cwd);
+  return top === null ? null : realpathSync(top);
+};
+
+// The read is no-follow on the LEAF (a symlinked leaf is already refused by name above; O_NOFOLLOW
+// makes a swap between the classification and the read fail loudly rather than counting another
+// object's bytes). Honest limit: classify-then-read is not race-free, and it is not meant to be —
+// the scope is the orchestrator's OWN work tree and the result is a MAGNITUDE, never a store
+// identity, so a pathname race costs a wrong byte count, not a forged record.
+const readObjectBytes = (path) => {
+  const fd = openSync(path, (fsConstants.O_RDONLY ?? 0) | (fsConstants.O_NOFOLLOW ?? 0) | (fsConstants.O_NONBLOCK ?? 0));
+  try {
+    return readFileSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+};
+
+// One scope object → one numerator entry. Refuses by NAME on anything it cannot count honestly: a
+// path escaping the repo LEXICALLY, an absent path, a non-regular path (a symlinked leaf included —
+// following one would count another object's bytes under this name), and a path whose REAL location
+// is outside the repository. The last one is the case the lexical rule alone cannot see: it rejects
+// `../x` while accepting `link/x`, where `link` is an ancestor symlink pointing out of the tree.
+// The identity is the CANONICAL repo-relative path taken from the verified real path — not a content
+// hash. The solo domain has no rename lineage for a content id to protect, and a content id would
+// let one object read between two measurements look like TWO objects instead of refusing as the
+// producer contradiction it is ("one identity, one size"). Two equal-byte files at different paths
+// are two objects and count twice; one path reached twice (a second listing, an in-repo ancestor
+// symlink) is one object and counts once.
+export const measureObject = (root, rel) => {
+  const lexical = lexicalRepoRelative(rel);
+  if (!lexical.ok) return { ok: false, reason: `scope path "${rel}": ${lexical.reason}` };
+  const path = resolve(root, rel);
+  const stat = lstatNoFollowRead(path);
+  if (stat === null) return { ok: false, reason: `scope path "${rel}" does not exist — an observation counts objects that are actually there (fail closed)` };
+  if (!stat.isFile()) return { ok: false, reason: `scope path "${rel}" is a ${describeNonRegular(stat)}, not a regular file — the scope names repository objects (fail closed)` };
+  const real = realpathSync(path);
+  if (!real.startsWith(`${root}${sep}`)) {
+    return { ok: false, reason: `scope path "${rel}" resolves to ${real}, which leaves the repository at ${root} — an ancestor symlink is not a way out of the scope domain (fail closed)` };
+  }
+  const canonical = real.slice(root.length + 1);
+  const bytes = readObjectBytes(path);
+  return { ok: true, entry: { kind: SOLO_COMPONENT_KIND, path: canonical, objectId: canonical, postImageBytes: bytes.length } };
+};
+
+// One repo-relative path per scope entry, in the order given. The measured CANONICAL paths become
+// the record's `scope` as a canonical JSON array, so what was measured and what is written down are
+// the same statement — and a path carrying a space says so unambiguously.
+export const measureScope = (root, paths) => {
+  const entries = [];
+  for (const rel of paths) {
+    const measured = measureObject(root, rel);
+    if (!measured.ok) return measured;
+    entries.push(measured.entry);
+  }
+  const numerator = computeNumerator(entries);
+  return numerator.ok
+    ? { ...numerator, scope: JSON.stringify(entries.map((e) => e.path)) }
+    : { ok: false, reason: numerator.reason };
+};
+
+export const ratio = (value) => value.toFixed(3);
+
+// L is printed ONLY where the metric is eligible: an ineligible metric has a NAMED reason and no
+// ratio at all, and printing a number beside the name is how a silent zero gets read as a
+// measurement.
+export const formatRatio = (metric) => (metric.eligible
+  ? `L = ${ratio(metric.numeratorBytes / metric.denominatorBytes)} (${metric.numeratorBytes} B / ${metric.denominatorBytes} B)`
+  : `L = n/a — INELIGIBLE (${metric.ineligibleReason})`);
+
+// The ONE observation-record construction: the eligibility is evaluated here, over the same two
+// numbers the record carries, so a record and its own eligibility can never disagree at the door.
+export const buildObservationRecord = ({ waveId, stepClass, measured, provenance, denominatorBytes, planId, phase, timestamp }) => {
+  const eligibility = evaluateObservationEligibility({ numeratorBytes: measured.numeratorBytes, denominatorBytes });
+  return {
+    schema: DELEGATION_SCHEMA_VERSION,
+    kind: 'observation',
+    waveId,
+    stepClass,
+    scope: measured.scope,
+    metric: {
+      numeratorBytes: measured.numeratorBytes,
+      denominatorBytes,
+      components: measured.components,
+      provenance,
+      eligible: eligibility.eligible,
+      ineligibleReason: eligibility.ineligibleReason,
+    },
+    planId,
+    phase,
+    timestamp,
+  };
+};

package/tools/path-inventory.mjs

@@ -46,7 +46,7 @@
 
 import { openSync, fstatSync, readSync, closeSync, opendirSync, realpathSync, lstatSync, constants } from 'node:fs';
 import { resolve, relative, isAbsolute, sep, dirname } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { isDirectRun } from './direct-run.mjs';
 
 import {
   UsageError,
@@ -512,5 +512,4 @@ const emitResult = (r) => {
   process.exitCode = r.code;
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) emitResult(main(process.argv.slice(2)));
+if (isDirectRun(import.meta.url)) emitResult(main(process.argv.slice(2)));

package/tools/procedures.mjs

@@ -20,11 +20,12 @@
 import { readFileSync, lstatSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
-import { pathToFileURL, fileURLToPath } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import { detectBackends, wrapperCmdFor, wrapperContractFor } from './detect-backends.mjs';
 // The host-level bridge-settings registry (manifest-as-source) + its allowed-value labels. READ-ONLY
 // core only — never the writer — so this read-only advisor never imports the atomic-write core.
 import { loadRegistry, allowedLabel } from './bridge-settings-read.mjs';
+import { isDirectRun } from './direct-run.mjs';
 import { ACTIVITIES, resolveActivityRecipe, planRecipe } from './recipes.mjs';
 import { resolveEngineDir, readEngineFragment, PROCEDURES_FRAGMENT_REL } from './engine-source.mjs';
 // The plan-in-flight detector (AD-038) — imported from the plan-files.mjs LEAF (read-only fs by
@@ -586,8 +587,7 @@ export const main = (argv, ctx = {}) => {
   }
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) {
+if (isDirectRun(import.meta.url)) {
   const r = main(process.argv.slice(2));
   if (r.stdout) console.log(r.stdout);
   if (r.stderr) console.error(r.stderr);

package/tools/receipt-deadline.mjs

@@ -21,9 +21,9 @@
 // Node >= 22. No side effects on import (the isDirectRun idiom).
 
 import { join, dirname } from 'node:path';
-import { pathToFileURL } from 'node:url';
 import { createHash } from 'node:crypto';
 import { resolveReceiptsPath } from './core-evidence.mjs';
+import { isDirectRun } from './direct-run.mjs';
 import { SAFE_NONCE_RE, findingManifestBasename, decodeFindingManifest } from './flow-record.mjs';
 import { readFileBytesNoFollow } from './flow-store-read.mjs';
 
@@ -254,8 +254,7 @@ export const main = async (argv, ctx = {}) => {
   }
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) {
+if (isDirectRun(import.meta.url)) {
   main(process.argv.slice(2)).then((r) => {
     if (r.stdout) process.stdout.write(r.stdout.endsWith('\n') ? r.stdout : `${r.stdout}\n`);
     if (r.stderr) process.stderr.write(r.stderr.endsWith('\n') ? r.stderr : `${r.stderr}\n`);

package/tools/recipes.mjs

@@ -16,10 +16,10 @@
 
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
 // The host-level bridge-settings snapshot (fact-only, best-effort). READ-ONLY core only — never the
 // writer — so this read-only advisor never pulls in the atomic-write core.
 import { settingsSnapshot, DEFAULT_BUNDLE_ROOT } from './bridge-settings-read.mjs';
+import { isDirectRun } from './direct-run.mjs';
 import {
   detectBackends,
   wrapperCmdFor,
@@ -596,11 +596,10 @@ exclusive. Detection only — never writes, never commits, never runs a subscrip
   return 0;
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
 // Natural exit via process.exitCode — never process.exit inside the async main (it would drop buffered
 // stdio writes on piped stderr), and never a TOP-LEVEL await here: orchestration-config.mjs statically
 // imports this module, so awaiting the dynamic import during our own evaluation would deadlock the cycle.
-if (isDirectRun) {
+if (isDirectRun(import.meta.url)) {
   main(process.argv.slice(2)).then(
     (code) => {
       process.exitCode = code ?? 0;

package/tools/recommendations.mjs

@@ -35,7 +35,7 @@ import { readFileSync, readdirSync, lstatSync, existsSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import {
   preflightVelocityProfile,
   planVelocityProfile,
@@ -51,6 +51,7 @@ import {
 import { loadAutonomy, isSparseSeedConfig, AUTONOMY_REL } from './autonomy-config.mjs';
 import { deriveDoctorPlan } from './autonomy-doctor.mjs';
 import { detectBackends, findOnPath } from './detect-backends.mjs';
+import { isDirectRun } from './direct-run.mjs';
 import { ACTIVITIES, resolveActivityRecipe } from './recipes.mjs';
 import { surveyFamily, surveyGateHook, surveyAdrLayoutStrict } from './family-registry.mjs';
 import { probeSandboxMasks, needsMasksApply } from './sandbox-masks.mjs';
@@ -1534,8 +1535,7 @@ export const main = (argv, ctx = {}) => {
   }
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) {
+if (isDirectRun(import.meta.url)) {
   const r = main(process.argv.slice(2));
   if (r.stdout) process.stdout.write(r.stdout.endsWith('\n') ? r.stdout : `${r.stdout}\n`);
   if (r.stderr) process.stderr.write(r.stderr.endsWith('\n') ? r.stderr : `${r.stderr}\n`);

package/tools/release-scan.mjs

@@ -12,7 +12,7 @@
 
 import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
 import { join, extname, basename, resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { isDirectRun } from './direct-run.mjs';
 
 export const ALLOWLIST = [
   'codex-cli-bridge',
@@ -274,5 +274,4 @@ export const main = (argv) => {
   return reportOnly ? 0 : 1;
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) process.exitCode = main(process.argv.slice(2));
+if (isDirectRun(import.meta.url)) process.exitCode = main(process.argv.slice(2));

package/tools/repo-search.mjs

@@ -50,7 +50,7 @@
 import { openSync, fstatSync, readSync, closeSync, opendirSync, realpathSync, lstatSync, constants } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { join, resolve, relative, isAbsolute, sep } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { isDirectRun } from './direct-run.mjs';
 
 export const EXIT_OK = 0;
 export const EXIT_ERROR = 1;
@@ -590,5 +590,4 @@ const emitResult = (r) => {
   process.exitCode = r.code;
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) emitResult(main(process.argv.slice(2)));
+if (isDirectRun(import.meta.url)) emitResult(main(process.argv.slice(2)));

package/tools/review-state.mjs

@@ -90,10 +90,11 @@
 
 import { lstatSync, readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
-import { pathToFileURL, fileURLToPath } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { detectBackends, READY } from './detect-backends.mjs';
+import { isDirectRun } from './direct-run.mjs';
 import { resolveActivityRecipe, DISPLAY_ALIASES, requiredBackendsForConfiguredRecipe } from './recipes.mjs';
 import { CONFIG_REL, fail, loadConfig } from './orchestration-config.mjs';
 import { resolveFlowStorePath, readFlowStore, deriveFlowOwner, readPlanFrontmatterId } from './flow-store.mjs';
@@ -819,8 +820,7 @@ const emitResult = (r) => {
   process.exitCode = r.code;
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) {
+if (isDirectRun(import.meta.url)) {
   const argv = process.argv.slice(2);
   if (argv.includes('--await')) mainAwait(argv).then(emitResult);
   else emitResult(main(argv));

package/tools/run-gates.mjs

@@ -32,8 +32,8 @@
 import { readFileSync, lstatSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { pathToFileURL } from 'node:url';
 import { createHash, randomUUID } from 'node:crypto';
+import { isDirectRun } from './direct-run.mjs';
 import { computeTreeFingerprint } from './review-state.mjs';
 import { CONFIG_REL, loadConfig } from './orchestration-config.mjs';
 // The D3(a) final receipt rides the core-evidence SOLE WRITER (the sole-writer boundary — this
@@ -942,5 +942,4 @@ export const runCli = (argv, deps = {}) => {
   }
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) process.exitCode = runCli(process.argv.slice(2));
+if (isDirectRun(import.meta.url)) process.exitCode = runCli(process.argv.slice(2));

package/tools/sandbox-masks.mjs

@@ -36,8 +36,9 @@
 
 import { lstatSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
+import { isDirectRun } from './direct-run.mjs';
 import { fail } from './orchestration-config.mjs';
 import { isNeverCommittableStat, shellQuoteArg } from './review-state.mjs';
 import { assertContainedRealPath } from './fs-safe.mjs';
@@ -366,5 +367,4 @@ const emitResult = (r) => {
   process.exitCode = r.code;
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) emitResult(main(process.argv.slice(2)));
+if (isDirectRun(import.meta.url)) emitResult(main(process.argv.slice(2)));