@sabaiway/agent-workflow-kit 5.11.0 → 5.11.2

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-vocabulary.mjs

@@ -0,0 +1,96 @@
+// flow-vocabulary.mjs — the CLOSED flow-record vocabulary (kinds, purposes, terminal lanes, the
+// design seed assignment, the allowed-transition table) plus the five shared form bindings every
+// validator states its refusals in: HEX64_RE, isPlainObject, isNonEmptyString, isHex64 and refuse.
+// Split out of flow-record.mjs unchanged (baseline-practices tranche 3), which now re-exports the
+// ten public names here; the five shared bindings stay OFF that surface (plan D3) — the leaves that
+// need them import this module, so the record family's named grammars have exactly one home and no
+// copy can drift.
+//
+// The LOWEST leaf of the family and pure form: no filesystem, no git, no CLI, no side effects on
+// import, and orchestration-config.mjs (the schema version) is its only tools sibling. Imports run
+// ONE way — the shape, identity, legality and manifest leaves compose this module; nothing here
+// reaches back up to the facade.
+
+import { FLOW_SCHEMA_VERSION } from './orchestration-config.mjs';
+
+export { FLOW_SCHEMA_VERSION };
+
+const deepFreeze = (value) => {
+  if (value !== null && typeof value === 'object') {
+    Object.values(value).forEach(deepFreeze);
+    Object.freeze(value);
+  }
+  return value;
+};
+
+// ── the closed vocabulary ─────────────────────────────────────────────────────────────────────────
+
+export const CHAIN_KIND = 'chain';
+export const CHAIN_PURPOSES = deepFreeze(['adoption', 'round', 'refresh', 're-baseline', 'freeze', 'unfreeze', 'park', 'resume', 'converged', 'complete']);
+export const STEP_SCOPED_PURPOSES = deepFreeze(['round', 'refresh', 're-baseline', 'freeze', 'unfreeze', 'converged']);
+export const PLAN_LANE_PURPOSES = deepFreeze(['adoption', 'park', 'resume', 'complete']);
+export const GLOBAL_KINDS = deepFreeze(['internal-attestation', 'down-mark', 'down-mark-up', 'down-mark-clear', 'degrade-justification', 'rerun-cause', 'bookkeeping-delta', 'maintainer-override', 'consult-attestation', 'subset-attempt']);
+export const FLOW_KINDS = deepFreeze([CHAIN_KIND, ...GLOBAL_KINDS]);
+
+// Reserved lane-typed terminals (#16): converged terminates a CYCLE (its step's sequence), complete
+// terminates the PLAN. Park is a resumable suspension, never a terminal (#59).
+export const TERMINAL_LANES = deepFreeze({ converged: 'cycle', complete: 'plan' });
+
+// Design §5 seed member → family assignment; the drift-guard test binds this map to the verbatim
+// seed list on one side and to the shipped CHAIN_PURPOSES/GLOBAL_KINDS on the other.
+export const DESIGN_SEED_ASSIGNMENT = deepFreeze({
+  adoption: { family: 'chain', purpose: 'adoption' },
+  'round-chain': { family: 'chain', purpose: 'round' },
+  refresh: { family: 'chain', purpose: 'refresh' },
+  're-baseline': { family: 'chain', purpose: 're-baseline' },
+  unfreeze: { family: 'chain', purpose: 'unfreeze' },
+  freeze: { family: 'chain', purpose: 'freeze' },
+  converged: { family: 'chain', purpose: 'converged' },
+  park: { family: 'chain', purpose: 'park' },
+  resume: { family: 'chain', purpose: 'resume' },
+  complete: { family: 'chain', purpose: 'complete' },
+  'internal-attestation': { family: 'global', kind: 'internal-attestation' },
+  'down-mark': { family: 'global', kind: 'down-mark' },
+  'down-mark up': { family: 'global', kind: 'down-mark-up' },
+  'down-mark clear': { family: 'global', kind: 'down-mark-clear' },
+  'degrade-justification': { family: 'global', kind: 'degrade-justification' },
+  'rerun-cause': { family: 'global', kind: 'rerun-cause' },
+  'bookkeeping-delta': { family: 'global', kind: 'bookkeeping-delta' },
+  'maintainer-override': { family: 'global', kind: 'maintainer-override' },
+  'consult-attestation': { family: 'global', kind: 'consult-attestation' },
+});
+
+// The allowed-transition table — an exported frozen structure, never prose. Within a step:
+// converged ends the sequence (only the unfreeze lane reopens it, and only in its own cycle);
+// freeze admits only unfreeze/converged. Plan lane: park admits only resume (and both preserve the
+// pre-park cycle/round); complete admits nothing; adoption is only ever the chain's first record.
+// The boundary lane (between steps): the opener round, the unfreeze reopen, and a re-baseline for
+// disjoint base motion that reopens nothing. The cross-step edge (the opener's prior-terminal
+// reference) is enforced by validateChainSequence, distinct from the within-step successor rule.
+export const ALLOWED_TRANSITIONS = deepFreeze({
+  stepOpening: 'round',
+  withinStep: {
+    round: ['round', 'refresh', 're-baseline', 'freeze', 'converged'],
+    refresh: ['round', 'refresh', 're-baseline', 'freeze', 'converged'],
+    're-baseline': ['round', 'refresh', 're-baseline', 'freeze', 'converged'],
+    freeze: ['unfreeze', 'converged'],
+    unfreeze: ['round', 'refresh', 're-baseline', 'freeze', 'converged'],
+    converged: ['unfreeze'],
+  },
+  planLane: {
+    adoption: ['round', 'park', 'complete'],
+    park: ['resume'],
+    resume: ['round', 'park', 'complete'],
+    complete: [],
+  },
+  boundary: ['round', 'unfreeze', 're-baseline'],
+});
+
+// ── the shared form bindings (D3) — the record family's named grammars, off the public surface ────
+
+export const HEX64_RE = /^[0-9a-f]{64}$/;
+export const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+export const isNonEmptyString = (v) => typeof v === 'string' && v.length > 0;
+export const isHex64 = (v) => typeof v === 'string' && HEX64_RE.test(v);
+
+export const refuse = (reason) => ({ ok: false, reason });

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/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)));

package/tools/set-autonomy.mjs

@@ -22,7 +22,6 @@
 // Dependency-free, Node >= 22. No side effects on import (the isDirectRun idiom).
 
 import { readFileSync, lstatSync } from 'node:fs';
-import { pathToFileURL } from 'node:url';
 import {
   AUTONOMY_REL,
   fail,
@@ -35,6 +34,7 @@ import {
   AUTONOMY_README,
 } from './autonomy-config.mjs';
 import { writeAutonomy as writeAutonomyFs } from './autonomy-write.mjs';
+import { isDirectRun } from './direct-run.mjs';
 
 // ── argument parsing (usage errors → exit 2) ────────────────────────────────────────
 
@@ -186,8 +186,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/set-flow.mjs

@@ -30,7 +30,7 @@
 
 import { readFileSync, lstatSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
-import { pathToFileURL, fileURLToPath } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import {
   CONFIG_REL,
@@ -44,6 +44,7 @@ import {
   FLOW_CANDIDATE_CLASSES,
   FLOW_SCHEMA_1_FIXTURE,
 } from './orchestration-config.mjs';
+import { isDirectRun } from './direct-run.mjs';
 import { writeConfig as writeConfigFs } from './orchestration-write.mjs';
 import { loadDeclaration } from './run-gates.mjs';
 import { compareSemver } from './semver-lite.mjs';
@@ -456,8 +457,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);