@sabaiway/agent-workflow-kit 5.11.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/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);

package/tools/set-recipe.mjs

@@ -23,8 +23,8 @@
 
 import { readFileSync, lstatSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { pathToFileURL } from 'node:url';
 import { detectBackends } from './detect-backends.mjs';
+import { isDirectRun } from './direct-run.mjs';
 import { resolveActivityRecipe, composeActiveRecipeLine } from './recipes.mjs';
 import { loadAutonomy, resolveAutonomy } from './autonomy-config.mjs';
 import {
@@ -230,8 +230,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/setup-backends.mjs

@@ -28,9 +28,10 @@ import {
   chmodSync, readFileSync, realpathSync,
 } from 'node:fs';
 import { join, resolve, relative, dirname, isAbsolute } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import os from 'node:os';
 import { KNOWN_BACKENDS, detectBackend, detectBackends, resolveDir, guideFor, READY } from './detect-backends.mjs';
+import { isDirectRun } from './direct-run.mjs';
 import { copyTreeRefresh, linkManaged, isReadonlyWriteBoundary } from './fs-safe.mjs';
 import {
   READONLY_RERUN_HINT, WRAPPER_MODE, scanBundleOwnedDrift, scanWrapperParity, parityVerdict,
@@ -821,5 +822,4 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
   return worst;
 };
 
-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/store-append.mjs

@@ -1,6 +1,6 @@
 // store-append.mjs — the PARAMETERIZED lock/CAS serialized-append leaf (delegation Plan 1, Phase 2,
-// D12). Extracted VERBATIM from flow-store.mjs, which is now its first caller; the delegation store
-// (dispatch-store.mjs) is the second. No CLI, no side effects on import.
+// D12). Extracted VERBATIM from the flow store, whose write door flow-append.mjs is now its first
+// caller; the delegation store (dispatch-store.mjs) is the second. No CLI, no side effects on import.
 //
 // Why a leaf rather than an import of the flow appender: `appendFlowRecordWithPreflight` hardwires
 // the AW_FLOW_STORE seam and validateFlowRecord, so a second store could only reuse it by pretending

package/tools/uninstall.mjs

@@ -24,8 +24,8 @@
 
 import { existsSync, statSync, lstatSync, readlinkSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
 import { join, resolve, dirname, basename, isAbsolute } from 'node:path';
-import { pathToFileURL } from 'node:url';
 import os from 'node:os';
+import { isDirectRun } from './direct-run.mjs';
 import { surveyFamily, surveyProject, FAMILY_MEMBERS, classifyMember, OK } from './family-registry.mjs';
 import { removeTreeManaged, unlinkManaged, MANAGED_LINK_CONFLICT } from './fs-safe.mjs';
 import { deriveLinks } from './setup-backends.mjs';
@@ -606,8 +606,7 @@ const main = (argv) => {
   }
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) {
+if (isDirectRun(import.meta.url)) {
   try {
     main(process.argv.slice(2));
   } catch (err) {

package/tools/velocity-profile.mjs

@@ -1,7 +1,7 @@
 import { existsSync, lstatSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { homedir, tmpdir } from 'node:os';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 // The --autonomy render reads the per-project autonomy policy through the read-only autonomy core
 // (AD-044). This file is the family's one .claude/settings.json writer, so the policy render lives here;
 // it never imports the policy fs-writer (autonomy-write.mjs) — the render owns the settings file, not
@@ -10,6 +10,7 @@ import { AUTONOMY_REL, loadAutonomy, resolveAutonomy, COMMAND_REDLINES } from '.
 // The bridge-wrappers tier's placement probe (AD-044 Plan 4, Decision 2): a tier entry derives ONLY
 // for a PLACED bridge wrapper — findOnPath is the same read-only PATH scan the backend detector uses.
 import { findOnPath } from './detect-backends.mjs';
+import { isDirectRun } from './direct-run.mjs';
 import { compareSemver } from './semver-lite.mjs';
 // The declared-path resolution + segment containment the allowWrite degrade shares with the
 // advisor's worktrees-dir convergence lane — ONE leaf, so the two readings cannot drift.
@@ -1820,5 +1821,4 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
   }
 };
 
-export 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)));