@sabaiway/agent-workflow-kit 5.6.0 → 5.8.0

package/tools/grounding.mjs

@@ -11,6 +11,9 @@
 //                        it is not a heading in canon) and `## Verification` (REQUIRED — STOP if
 //                        missing), plus `## Decisions (locked)` (optional-if-absent, the engine §7
 //                        heading this release adds); a DUPLICATE heading is always a STOP.
+//   --extra <text|@file> append orchestrator-supplied facts verbatim AFTER the mechanical halves
+//                        (repeatable; @file reads are confined to the work tree + the system temp
+//                        surface — the merge happens INSIDE the tool, corpus #88/#95).
 //
 // Byte budget: the output honors the same AGY_MAX_PROMPT_BYTES contract the agy wrapper enforces
 // (default 120000; the override may only TIGHTEN — above the OS single-argv ceiling ~131000 is
@@ -31,6 +34,7 @@ import { tmpdir } from 'node:os';
 import { pathToFileURL } from 'node:url';
 import { spawnSync } from 'node:child_process';
 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.
 // READ core only — never autonomy-write.mjs (the import-split invariant).
 import { AUTONOMY_REL, loadAutonomy, resolveAutonomy, isSparseSeedConfig } from './autonomy-config.mjs';
@@ -81,7 +85,7 @@ export const sliceSection = (text, heading, { optional = false, label = 'documen
 
 // ── assembly ───────────────────────────────────────────────────────────────────────
 
-export const assembleGrounding = ({ constraintsText = null, autonomyText = null, planText = null, planLabel = 'plan' } = {}) => {
+export const assembleGrounding = ({ constraintsText = null, autonomyText = null, planText = null, planLabel = 'plan', extraTexts = [] } = {}) => {
   const parts = [];
   if (constraintsText != null) {
     parts.push(sliceSection(constraintsText, CONSTRAINTS_HEADING, { label: 'AGENTS.md' }));
@@ -96,6 +100,10 @@ export const assembleGrounding = ({ constraintsText = null, autonomyText = null,
       if (section != null) parts.push(section);
     }
   }
+  // Orchestrator extras ride LAST, verbatim in argv order — live judgment facts read after the
+  // mechanical slices, and the merge happens INSIDE the tool (corpus #88/#95: a shell append onto
+  // the emitted facts file was the recurring un-covered lane).
+  for (const t of extraTexts) parts.push(t);
   return parts.join('\n');
 };
 
@@ -151,10 +159,23 @@ const resolveAutonomyFacts = ({ cwd }) => {
   return renderAutonomyFacts(config, source);
 };
 
+// The realpath'd system temp surface ($TMPDIR / os.tmpdir() / /tmp) — the shared scratch boundary
+// for the --out write guard and the --extra read guard.
+const systemTempRoots = () => [...new Set([tmpdir(), process.env.TMPDIR, '/tmp'].filter(Boolean).map((p) => {
+  try {
+    return realpathSync(p);
+  } catch {
+    return null;
+  }
+}).filter(Boolean))];
+
 // ── the --out destination guard (gitignored / out-of-repo scratch ONLY) ────────────────
 
 const gitLine = (args, cwd) => {
-  const r = spawnSync('git', args, { cwd, encoding: 'utf8', windowsHide: true });
+  // Ambient GIT_* location vars (GIT_DIR / GIT_WORK_TREE / …) would let rev-parse prove a FOREIGN
+  // tree — every location answer must come from cwd alone, for every gitLine consumer.
+  const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !/^GIT_/i.test(k)));
+  const r = spawnSync('git', args, { cwd, env, encoding: 'utf8', windowsHide: true });
   return r.error || r.status == null ? null : { status: r.status, stdout: r.stdout ?? '' };
 };
 
@@ -199,13 +220,7 @@ export const assertScratchDestination = (outPath, cwd) => {
   // the repo is scratch" would let an unattended run overwrite e.g. ~/.bashrc promptless.
   // $TMPDIR / os.tmpdir() / /tmp are the scratch surface; everything else refuses loudly.
   const assertTempScratch = () => {
-    const tempRoots = [...new Set([tmpdir(), process.env.TMPDIR, '/tmp'].filter(Boolean).map((p) => {
-      try {
-        return realpathSync(p);
-      } catch {
-        return null;
-      }
-    }).filter(Boolean))];
+    const tempRoots = systemTempRoots();
     if (!tempRoots.some((t) => full === t || full.startsWith(`${t}${sep}`))) {
       throw fail(1, `--out refuses an outside-repo destination that is not under a system temp root (${full}) — grounding output is scratch: use $TMPDIR//tmp, or a fresh gitignored in-repo path (temp roots checked: ${tempRoots.join(', ')})`);
     }
@@ -243,7 +258,8 @@ export const assertScratchDestination = (outPath, cwd) => {
 const HELP = `grounding — grounded-review facts assembler for the agent-workflow family (AD-038).
 
 Usage:
-  node grounding.mjs [--constraints] [--autonomy] [--plan <path>] [--reserve-bytes <n>] [--out <path>]
+  node grounding.mjs [--constraints] [--autonomy] [--plan <path>] [--extra <text|@file>]...
+                     [--reserve-bytes <n>] [--out <path>]
 
   --constraints        slice the root AGENTS.md "Hard Constraints" section verbatim
                        (exactly one matching heading, else a loud STOP)
@@ -255,6 +271,14 @@ Usage:
   --plan <path>        extract the plan's decision-bearing sections verbatim + whole:
                        "## Approach" + "## Verification" (REQUIRED — STOP if missing),
                        "## Decisions (locked)" when present; a duplicate heading is a STOP
+  --extra <text|@file> append orchestrator-supplied extra facts byte-verbatim AFTER the
+                       mechanical sections (repeatable, argv order; the agy-review --facts
+                       convention: literal text, or @path read whole through a race-free
+                       descriptor). An @file must resolve inside the PROVEN git work tree
+                       (rev-parse success; the git dir itself refused) or the system temp
+                       surface — anything else refuses loudly, as does a missing, empty, or
+                       non-regular file. The merge happens INSIDE the tool: no shell append
+                       onto the emitted facts file
   --reserve-bytes <n>  the artifact share agy-review will add around these facts — the output
                        budget becomes AGY_MAX_PROMPT_BYTES − n (loud tail-trim on overflow)
   --out <path>         write instead of stdout — system-temp scratch (rewritable), or a FRESH
@@ -274,11 +298,19 @@ const parseArgs = (argv) => {
   let plan = null;
   let out = null;
   let reserve = 0;
+  const extra = [];
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
     if (a === '--constraints') constraints = true;
     else if (a === '--autonomy') autonomy = true;
-    else if (a === '--plan') {
+    else if (a === '--extra') {
+      const val = argv[i + 1];
+      if (val == null || val === '' || val === '@' || val.startsWith('--')) {
+        throw fail(2, '--extra requires <text|@file> (repeatable)');
+      }
+      extra.push(val);
+      i += 1;
+    } else if (a === '--plan') {
       plan = argv[i + 1];
       if (!plan || plan.startsWith('--')) throw fail(2, '--plan requires a <path>');
       i += 1;
@@ -293,10 +325,10 @@ const parseArgs = (argv) => {
       i += 1;
     } else throw fail(2, `unknown argument: ${a}`);
   }
-  if (!constraints && !autonomy && plan == null) {
-    throw fail(2, 'nothing to assemble — pass --constraints, --autonomy, and/or --plan <path>');
+  if (!constraints && !autonomy && plan == null && extra.length === 0) {
+    throw fail(2, 'nothing to assemble — pass --constraints, --autonomy, --plan <path>, and/or --extra <text|@file>');
   }
-  return { constraints, autonomy, plan, out, reserve };
+  return { constraints, autonomy, plan, out, reserve, extra };
 };
 
 const resolveBudget = (env, reserve) => {
@@ -316,7 +348,7 @@ export const main = (argv, ctx = {}) => {
   const env = ctx.env ?? process.env;
   try {
     if (argv.includes('--help') || argv.includes('-h')) return { code: 0, stdout: HELP, stderr: '' };
-    const { constraints, autonomy, plan, out, reserve } = parseArgs(argv);
+    const { constraints, autonomy, plan, out, reserve, extra } = parseArgs(argv);
     const budget = resolveBudget(env, reserve);
 
     const readOrStop = (path, label) => {
@@ -348,8 +380,65 @@ export const main = (argv, ctx = {}) => {
     }
     const planText = plan != null ? readOrStop(plan, 'plan file') : null;
 
+    // --extra @file reads are CONFINED: the bridge tier auto-allows this tool with an args
+    // wildcard, so an unconfined @file would let an unattended run ship ANY readable file
+    // (~/.ssh, ~/.bashrc) into a prompt payload bound for a subscription CLI. The admitted read
+    // surface — computed ONCE per invocation — is the PROVEN git work tree (rev-parse success
+    // required; a cwd fallback would collapse the guard when cwd=$HOME) plus the system temp
+    // surface, MINUS the git dir(s) — repository internals never enter a facts payload. A non-@
+    // value is literal fact text (the agy-review --facts convention).
+    const extraReadSurface = () => {
+      const tempRoots = systemTempRoots();
+      const top = gitLine(['rev-parse', '--show-toplevel'], cwd);
+      if (top == null || top.status !== 0) return { tempRoots, topReal: null, gitDirsReal: [] };
+      const topReal = realpathSync(top.stdout.replace(/\r?\n$/, ''));
+      const gitDirsReal = ['--absolute-git-dir', '--git-common-dir'].map((flag) => {
+        const r = gitLine(['rev-parse', flag], cwd);
+        if (r == null || r.status !== 0) {
+          throw fail(1, `--extra cannot resolve the git dir (git rev-parse ${flag} failed) — refusing @file reads in an unmappable repo`);
+        }
+        return realpathSync(resolve(cwd, r.stdout.replace(/\r?\n$/, '')));
+      });
+      // The linked-worktree `.git` is a FILE inside the tree yet outside both answers above —
+      // repository metadata all the same.
+      gitDirsReal.push(join(topReal, '.git'));
+      return { tempRoots, topReal, gitDirsReal };
+    };
+    const surface = extra.some((v) => v.startsWith('@')) ? extraReadSurface() : null;
+    const resolveExtra = (value) => {
+      if (!value.startsWith('@')) return value;
+      const ref = value.slice(1);
+      const real = (() => {
+        try {
+          // Canonicalize the PARENT only — the leaf stays un-dereferenced so the no-follow open
+          // refuses a symlink leaf instead of silently reading its target.
+          const lexical = resolve(cwd, ref);
+          return join(realpathSync(dirname(lexical)), basename(lexical));
+        } catch (err) {
+          throw fail(1, `--extra file '${ref}' is unreadable (${(err && err.code) || err}) — STOP`);
+        }
+      })();
+      const within = (root) => real === root || real.startsWith(`${root}${sep}`);
+      const inTree = surface.topReal != null && within(surface.topReal);
+      if (!inTree && !surface.tempRoots.some(within)) {
+        throw fail(1, `--extra '@${ref}' resolves outside the work tree and the system temp surface (${real}) — refusing to read it into the facts payload`);
+      }
+      if (surface.gitDirsReal.some(within)) {
+        throw fail(1, `--extra '@${ref}' resolves inside the git dir (${real}) — repository internals never enter a facts payload`);
+      }
+      // Descriptor-bound read (the kit's ONE no-follow door): a FIFO cannot block the open, and a
+      // leaf swapped after the containment checks cannot change what the fd reads.
+      const r = readRegularFileNoFollow(real);
+      if (r.outcome === 'absent') throw fail(1, `--extra file '${ref}' is unreadable (ENOENT) — STOP`);
+      if (r.outcome === 'foreign') throw fail(1, `--extra file '${ref}' is not a regular file (${r.className}) — refusing; STOP`);
+      if (r.outcome !== 'ok') throw fail(1, `--extra file '${ref}' is unreadable (${r.code}) — STOP`);
+      if (r.content.trim() === '') throw fail(1, `--extra file '${ref}' is empty — nothing to append; STOP`);
+      return r.content; // byte-verbatim — no trailing-newline normalization
+    };
+    const extraTexts = extra.map(resolveExtra);
+
     const parts = [];
-    const assembled = assembleGrounding({ constraintsText, autonomyText, planText, planLabel: plan ?? 'plan' });
+    const assembled = assembleGrounding({ constraintsText, autonomyText, planText, planLabel: plan ?? 'plan', extraTexts });
     if (assembled) parts.push(assembled);
     const payload = parts.join('\n');
     const { text, trimmedBytes } = trimToBudget(payload, budget);

package/tools/hide-footprint.mjs

@@ -444,6 +444,15 @@ export const hideFootprint = (opts = {}, deps = {}) => {
   const writtenPatterns = buildBlock(writtenList.map((c) => c.pattern));
   const needsUntrack = includedAsks.filter((a) => a.verdict === 'ask-tracked');
 
+  // The +N/−N delta against the CURRENT managed block (L3). The current set is the RAW fence body
+  // (canonicalized where recognized): a stale pattern the wholesale re-derive would silently drop
+  // is exactly what the removed list must surface.
+  const currentBlockPatterns = [...new Set(fenceBodyLines.map((l) => lineToPattern(l)).filter(Boolean).map((p) => recognizeHideRule(p) ?? p))];
+  const writtenSet = new Set(writtenPatterns);
+  const currentSet = new Set(currentBlockPatterns);
+  const added = writtenPatterns.filter((p) => !currentSet.has(p));
+  const removed = currentBlockPatterns.filter((p) => !writtenSet.has(p)).sort();
+
   // ── build the new file (splice the fence; preserve outside lines) ──────────────
   const fenceLines = writtenPatterns.length ? [START_MARKER, ...writtenPatterns, END_MARKER] : [];
   const newLines = writtenPatterns.length
@@ -471,6 +480,8 @@ export const hideFootprint = (opts = {}, deps = {}) => {
     action,
     visibility: 'hidden',
     wrote: writtenPatterns,
+    added,
+    removed,
     asks: asks.filter((a) => !includedAsks.some((i) => i.pattern === a.pattern)).map((a) => ({ path: a.pattern, reason: a.reason, owner: a.owner })),
     needsUntrack: needsUntrack.map((a) => {
       const target = patternToProbe(a.pattern).replace(/\/$/, '');
@@ -530,16 +541,23 @@ const fmtGlobal = (g) => {
   return [];
 };
 
-const formatReport = (r, dryRun) => {
+export const formatReport = (r, dryRun) => {
   const lines = [dryRun ? 'hide-footprint — DRY RUN (no changes)' : 'hide-footprint'];
-  if (r.visibility === 'visible') return [...lines, `  • deployment is VISIBLE (anchor ${r.anchor} is tracked) — nothing to hide; wrote zero bytes`].join('\n');
-  if (r.ambiguous) return [...lines, `  • AMBIGUOUS visibility (anchor ${r.anchor} is untracked AND not ignored) — cannot tell fresh-uncommitted from broken-hidden; ASK the user before writing`].join('\n');
+  if (r.visibility === 'visible') return [...lines, `  • deployment is VISIBLE (${r.anchor} is tracked) — nothing to hide; wrote zero bytes`].join('\n');
+  if (r.ambiguous) return [...lines, `  • AMBIGUOUS visibility (${r.anchor} is untracked AND not ignored) — cannot tell fresh-uncommitted from broken-hidden; ASK the user before writing`].join('\n');
   lines.push(`  • ${r.action} ${r.excludeFile}`);
   // The block contains every written pattern, but a TRACKED --include path is NOT hidden by it (it is
   // reported separately, below) — so the "hidden" line lists only the genuinely-hidden untracked paths.
   const untrackedOnly = new Set(r.needsUntrack.map((n) => n.path));
   const hiddenNow = r.wrote.filter((p) => !untrackedOnly.has(p));
   if (hiddenNow.length) lines.push(`  • hidden (${hiddenNow.length}): ${hiddenNow.join(', ')}`);
+  // The block delta (L3) — rendered in dry-run and apply alike; sets listed, never counted alone.
+  // --unhide and the reconcile no-op paths carry no delta fields: their reports stay unchanged.
+  if (Array.isArray(r.added) && Array.isArray(r.removed)) {
+    if (r.added.length) lines.push(`  • +${r.added.length} added: ${r.added.join(', ')}`);
+    if (r.removed.length) lines.push(`  • −${r.removed.length} removed: ${r.removed.join(', ')}`);
+    if (!r.added.length && !r.removed.length) lines.push('  • +0/−0 — the hidden set is unchanged');
+  }
   for (const a of r.asks) lines.push(`  • ASK ${a.path} — ${a.reason}`);
   for (const n of r.needsUntrack) lines.push(`  • tracked, NOT hidden: ${n.path} — run \`${n.command}\` to un-track (kept on disk)`);
   if (r.dropped.length) lines.push(`  • skipped ${r.dropped.length} already-ignored (tracked .gitignore)`);

package/tools/lens-region.mjs

@@ -172,6 +172,58 @@ export const frontmatterMaxLines = (text) => {
   return null;
 };
 
+// ── the outcome lines (pure composers — the CLI's one voice) ──────────────────────
+// Every user-facing outcome line the CLI prints, one pure composer per outcome, so the
+// composed-lines guard (test/composed-lines-ux.test.mjs) can render each against the L2
+// user-grade invariants. runCli only ever prints through this table. Raw diagnostics never ride
+// the human sentence: they land on the ONE machine-formatted detail line (`[lens-region]
+// error=<JSON-encoded>` — one line, reversible, control bytes escaped), the `[tool] key=value`
+// channel the L2 rule exempts by grammar. JSON.stringify leaves DEL/C1 and the U+2028/U+2029
+// separators raw, and a dynamic path can carry any byte — both dynamic parts are therefore made
+// line-safe explicitly: the machine value gains extra JSON escapes (still reversible), and the
+// human line collapses every control/separator byte to one space.
+const LINE_UNSAFE = new RegExp('[\\u007f-\\u009f\\u2028\\u2029]', 'g');
+const HUMAN_UNSAFE = new RegExp('[\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+', 'g');
+const escUnsafe = (c) => `\\u${c.codePointAt(0).toString(16).padStart(4, '0')}`;
+const ERROR_DETAIL = (raw) => `[lens-region] error=${JSON.stringify(String(raw)).replace(LINE_UNSAFE, escUnsafe)}`;
+const oneLine = (s) => String(s).replace(HUMAN_UNSAFE, ' ');
+
+export const OUTCOME_LINES = Object.freeze({
+  errorDetail: ERROR_DETAIL,
+  targetAbsent: (target) => `[lens-region] ${target} is absent — skipped (nothing to update; the file is seeded at bootstrap).`,
+  commsNoRegion: (target) => [
+    `[lens-region] no "${COMMS_LABEL}" section in ${target} — left untouched.`,
+    '[lens-region] note: the Communication section is absent or renamed — deployments seeded before it existed simply lack it; add it from the current template to enable refresh. Your file is never rewritten.',
+  ],
+  commsCurrent: () => '[lens-region] Communication section already current — nothing to do (zero-diff).',
+  commsCustom: () => [
+    '[lens-region] Communication section carries a custom edit — preserved verbatim.',
+    '[lens-region] note: the canonical Communication section has changed since this section was edited — compare it with the current template when convenient; your wording is never overwritten.',
+  ],
+  capSkipNote: () => '[lens-region] note: no `maxLines` frontmatter on the target — the line-cap guard is skipped.',
+  commsCapRefused: (target, count, cap) => `[lens-region] refused — refreshing the Communication section would push ${target} to ${count} lines (cap ${cap}); trim the file and re-run. The Communication section was not changed.`,
+  commsRefreshed: () => '[lens-region] refreshed the Communication section to the current canon.',
+  templateCanonStop: () => `[lens-region] STOP — the kit's bundled agent_rules.md template canon is unreadable; reinstall the kit: npx @sabaiway/agent-workflow-kit@latest init`,
+  lensNoRegion: (target) => [
+    `[lens-region] no "${HEADING_LABEL}" section in ${target} — left untouched.`,
+    '[lens-region] note: the planning/review lens section is missing or renamed — it cannot be auto-refreshed; restore the canonical heading to re-enable refresh.',
+  ],
+  engineTooOld: () => '[lens-region] skipped — the installed engine is too old (or incomplete) to supply the lens canon; refresh it with `npx @sabaiway/agent-workflow-engine@latest init`, then re-run.',
+  // The human line keeps the classified "methodology engine not found/invalid" contract; a typed
+  // error (engine-source attaches {stable, reason}) splits its raw reason onto the machine line.
+  engineStop: (err) => {
+    const human = `[lens-region] STOP — ${oneLine(err?.stable ?? err?.message ?? String(err))}`;
+    return err?.reason ? [human, ERROR_DETAIL(err.reason)] : [human];
+  },
+  lensCurrent: () => '[lens-region] lens section already current — nothing to do (zero-diff).',
+  lensCustom: () => [
+    '[lens-region] lens section carries a custom edit — preserved verbatim.',
+    '[lens-region] note: the canonical planning/review lens has changed since this section was edited — compare it with the project methodology canon when convenient; your wording is never overwritten.',
+  ],
+  lensCapRefused: (target, count, cap) => `[lens-region] refused — refreshing would push ${target} to ${count} lines (cap ${cap}); trim the file and re-run. The planning/review lens section was not changed.`,
+  lensRefreshed: () => '[lens-region] refreshed the planning/review lens section to the current canon.',
+});
+
 // ── CLI: `lens-region.mjs reconcile <path/to/agent_rules.md>` ─────────────────────
 // Outcome lines are the contract the upgrade/bootstrap prose relays in plain language; exit 0 on
 // every classified outcome (including the soft skips and the cap refusals), exit 1 ONLY on a
@@ -203,7 +255,7 @@ export const runCli = async (argv, deps = {}) => {
     }
   })();
   if (text === null) {
-    log(`[lens-region] ${argv[1]} is absent — skipped (nothing to reconcile; the substrate seeds it at bootstrap).`);
+    log(OUTCOME_LINES.targetAbsent(argv[1]));
     return 0;
   }
 
@@ -229,43 +281,41 @@ export const runCli = async (argv, deps = {}) => {
     }
   })();
   if (!templateRegion.found) {
-    logError(`[lens-region] reconcile STOP — the kit's bundled agent_rules.md template canon is unreadable${templateRegion.error ? ` (${templateRegion.error})` : ''}; reinstall the kit: npx @sabaiway/agent-workflow-kit@latest init`);
+    logError(OUTCOME_LINES.templateCanonStop());
+    if (templateRegion.error) logError(OUTCOME_LINES.errorDetail(templateRegion.error));
     return 1;
   }
   const commsResult = reconcileCommsText(text, normalizeCommsBody(templateRegion.body), COMMS_PRIORS);
   const currentText = await (async () => {
     if (commsResult.status === 'no-region') {
-      log(`[lens-region] no "${COMMS_LABEL}" section in ${argv[1]} — left untouched.`);
-      log('[lens-region] note: the Communication section is absent or renamed — deployments seeded before it existed simply lack it; add it from the current template to enable refresh. Your file is never rewritten.');
+      for (const line of OUTCOME_LINES.commsNoRegion(argv[1])) log(line);
       return text;
     }
     if (commsResult.status === 'current') {
-      log('[lens-region] Communication section already current — nothing to do (zero-diff).');
+      log(OUTCOME_LINES.commsCurrent());
       return text;
     }
     if (commsResult.status === 'custom') {
-      log('[lens-region] Communication section carries a custom edit — preserved verbatim.');
-      log('[lens-region] note: the canonical Communication section has changed since this section was edited — compare it with the current template when convenient; your wording is never overwritten.');
+      for (const line of OUTCOME_LINES.commsCustom()) log(line);
       return text;
     }
     const commsMax = frontmatterMaxLines(text);
     if (commsMax === null) {
-      log('[lens-region] note: no `maxLines` frontmatter on the target — the line-cap guard is skipped.');
+      log(OUTCOME_LINES.capSkipNote());
     }
     if (commsMax !== null && lineCount(commsResult.text) > commsMax) {
-      log(`[lens-region] refused — refreshing the Communication section would push ${argv[1]} to ${lineCount(commsResult.text)} lines (cap ${commsMax}); trim the file and re-run. The Communication section was not changed.`);
+      log(OUTCOME_LINES.commsCapRefused(argv[1], lineCount(commsResult.text), commsMax));
       return text;
     }
     await atomicWrite(commsResult.text);
-    log('[lens-region] refreshed the Communication section to the current canon.');
+    log(OUTCOME_LINES.commsRefreshed());
     return commsResult.text;
   })();
 
   // 3. No matching lens heading → preserve + advise, engine never consulted (the outcome is
   //    preserve regardless, so the lazy contract holds).
   if (!extractLensRegion(currentText).found) {
-    log(`[lens-region] no "${HEADING_LABEL}" section in ${argv[1]} — left untouched.`);
-    log('[lens-region] note: the planning/review lens section is missing or renamed — it cannot be auto-refreshed; restore the canonical heading to re-enable refresh.');
+    for (const line of OUTCOME_LINES.lensNoRegion(argv[1])) log(line);
     return 0;
   }
 
@@ -276,14 +326,14 @@ export const runCli = async (argv, deps = {}) => {
     detectEngine(dir, { source, rel: LENS_FRAGMENT_REL }).ok && detectEngine(dir, { source, rel: LENS_PRIORS_REL }).ok;
   if (!lensPairPresent) {
     if (detectEngine(dir, { source }).ok) {
-      log('[lens-region] skipped — the installed engine is too old (or incomplete) to supply the lens canon; refresh it with `npx @sabaiway/agent-workflow-engine@latest init`, then re-run.');
+      log(OUTCOME_LINES.engineTooOld());
       return 0;
     }
     try {
       readEngineFragment(dir, { source, rel: LENS_FRAGMENT_REL }); // throws the canonical install-me error
       return 1; // defensive: the pair is unusable — never proceed to a read
     } catch (err) {
-      logError(`[lens-region] reconcile STOP — ${err.message}`);
+      for (const line of OUTCOME_LINES.engineStop(err)) logError(line);
       return 1;
     }
   }
@@ -292,34 +342,35 @@ export const runCli = async (argv, deps = {}) => {
   let fragment;
   let priors;
   try {
-    fragment = readEngineFragment(dir, { source, rel: LENS_FRAGMENT_REL });
-    priors = parseLensPriors(readEngineFragment(dir, { source, rel: LENS_PRIORS_REL }));
+    // deps.engineRead is the injectable read primitive (tests drive the vanished/unreadable arm
+    // deterministically — a chmod-based fixture is root- and platform-dependent).
+    fragment = readEngineFragment(dir, { source, rel: LENS_FRAGMENT_REL, readFileSync: deps.engineRead });
+    priors = parseLensPriors(readEngineFragment(dir, { source, rel: LENS_PRIORS_REL, readFileSync: deps.engineRead }));
   } catch (err) {
-    logError(`[lens-region] reconcile STOP — ${err.message}`);
+    for (const line of OUTCOME_LINES.engineStop(err)) logError(line);
     return 1;
   }
 
   // 5. The pure decision + the cap-guard + one atomic write.
   const result = reconcileLensText(currentText, fragment, priors);
   if (result.status === 'current') {
-    log('[lens-region] lens section already current — nothing to do (zero-diff).');
+    log(OUTCOME_LINES.lensCurrent());
     return 0;
   }
   if (result.status === 'custom') {
-    log('[lens-region] lens section carries a custom edit — preserved verbatim.');
-    log('[lens-region] note: the canonical planning/review lens has changed since this section was edited — compare it with the project methodology canon when convenient; your wording is never overwritten.');
+    for (const line of OUTCOME_LINES.lensCustom()) log(line);
     return 0;
   }
   // refreshed → cap-guard from the TARGET's own frontmatter, then atomic write.
   const maxLines = frontmatterMaxLines(currentText);
   if (maxLines === null) {
-    log('[lens-region] note: no `maxLines` frontmatter on the target — the line-cap guard is skipped.');
+    log(OUTCOME_LINES.capSkipNote());
   } else if (lineCount(result.text) > maxLines) {
-    log(`[lens-region] refused — refreshing would push ${argv[1]} to ${lineCount(result.text)} lines (cap ${maxLines}); trim the file and re-run. The planning/review lens section was not changed.`);
+    log(OUTCOME_LINES.lensCapRefused(argv[1], lineCount(result.text), maxLines));
     return 0;
   }
   await atomicWrite(result.text);
-  log('[lens-region] refreshed the planning/review lens section to the current canon.');
+  log(OUTCOME_LINES.lensRefreshed());
   return 0;
 };
 

package/tools/orchestration-config.mjs

@@ -1,4 +1,3 @@
-#!/usr/bin/env node
 // orchestration-config.mjs — the schema / read / pure-transform core for the per-project
 // orchestration config (docs/ai/orchestration.json). It is the SINGLE source of the config contract:
 //
@@ -16,12 +15,13 @@
 //
 // This module performs NO filesystem WRITES — only reads (loadConfig). The single fs-writer lives in
 // orchestration-write.mjs, which procedures.mjs never imports DIRECTLY (the pinned import-split
-// rule). Pure-where-possible (fs injectable), dependency-free, Node >= 22. No side
-// effects on import.
+// rule). It has NO CLI while upgrade.md names it — hence the registered refusal at the foot of the
+// file (direct-run.mjs), and no shebang. Fs-injectable, dependency-free, Node >= 22; nothing on import.
 
 import { readFileSync, lstatSync } from 'node:fs';
 import { join } from 'node:path';
 import { ACTIVITIES, SLOT_RECIPES } from './recipes.mjs';
+import { refuseDirectRun } from './direct-run.mjs';
 
 // The hand-editable / agent-writable, per-project config (strict JSON). cwd-relative — the error prefix
 // uses this rel path so a user sees a path they can open, never an absolute temp/host path.
@@ -396,3 +396,5 @@ export const refreshReadme = (config) => {
 
 // The canonical seed file body (what `init` deploys + what serializeConfig round-trips byte-identically).
 export const SEED_CONFIG = { _README: CANON_README, 'plan-authoring': { review: 'solo' }, 'plan-execution': { execute: 'solo', review: 'solo' } };
+
+refuseDirectRun(import.meta.url);

package/tools/orchestration-write.mjs

@@ -25,3 +25,10 @@ const stop = (message) => Object.assign(new Error(`[agent-workflow-kit] ${messag
 // creation. config is serialized canonically (serializeConfig: 2-space, _README-first, trailing NL).
 export const writeConfig = (cwd, config, deps = {}) =>
   writeDocsAiFileAtomic(cwd, CONFIG_REL, serializeConfig(config), deps, { stop, noun: 'a config' });
+
+// seedConfig(cwd, config, deps) → { writtenPath, created }. Same writer, CREATE-ONLY: it is the
+// seed-if-missing arm the ensure CLI runs, where a config that appeared between the probe and the
+// write must survive untouched (`created: false` says it did). writeConfig stays the arm for a
+// content update of a file the caller has just read.
+export const seedConfig = (cwd, config, deps = {}) =>
+  writeDocsAiFileAtomic(cwd, CONFIG_REL, serializeConfig(config), deps, { stop, noun: 'a config', createOnly: true });