@sabaiway/agent-workflow-kit 1.29.0 → 1.30.0

package/tools/grounding.mjs

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+// grounding.mjs — the grounded-review facts assembler behind `/agent-workflow-kit grounding`
+// (AD-038). An ungrounded agy review GUESSES (AD-028); the grounding CONTRACT is mechanized
+// (`agy-review --facts @f`, AD-033) but population was a manual chore — this tool emits the two
+// mechanical halves of a facts payload so assembly is a command, not hand-copying:
+//
+//   --constraints        slice the root AGENTS.md `## 🚫 Hard Constraints` section, verbatim
+//                        (exactly-one-match — 0 or >1 headings is a loud STOP, never a guess);
+//   --plan <path>        extract the plan's decision-bearing canonical sections, verbatim + whole:
+//                        `## Approach` (REQUIRED — its "What we are NOT doing" text rides inside;
+//                        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.
+//
+// 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
+// rejected, mirroring agy-review.sh), MINUS --reserve-bytes <n> — the artifact share the caller
+// expects `agy-review` to add around these facts. Overflow is TRIMMED tail-first with a loud
+// in-band marker + stderr report (never a silent cut).
+//
+// Catalog honesty: this is a WRITER — `--out <path>` writes a file. Invariant: `--out` accepts
+// only gitignored / out-of-repo scratch destinations and REFUSES a tracked path AND an in-repo
+// not-ignored path (a new untracked file would itself move the review fingerprint the facts are
+// about to ground). stdout is the default. It never commits and never runs a subscription CLI.
+//
+// Dependency-free, Node >= 18. No side effects on import (the isDirectRun idiom).
+
+import { readFileSync, writeFileSync, lstatSync, realpathSync } from 'node:fs';
+import { resolve, join, relative, isAbsolute, dirname, basename } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { fail } from './orchestration-config.mjs';
+
+// The agy single-argv byte contract (mirrors agy-review.sh — the wrapper is the enforcement home).
+export const DEFAULT_MAX_PROMPT_BYTES = 120000;
+export const ARGV_HARD_MAX = 131000;
+
+export const CONSTRAINTS_HEADING = /^## .*Hard Constraints$/;
+export const PLAN_SECTIONS = [
+  { heading: '## Approach', optional: false },
+  { heading: '## Verification', optional: false },
+  { heading: '## Decisions (locked)', optional: true },
+];
+
+// ── pure section slicing (exactly-one-match; the inject-methodology discipline) ────────
+
+// Slice ONE `## `-level section (its heading line through the line before the next `## ` heading),
+// verbatim. `heading` is a string (trimmed-line equality) or a RegExp over the trimmed line.
+// 0 matches → null when optional, else STOP; >1 matches → always STOP (never guess which).
+export const sliceSection = (text, heading, { optional = false, label = 'document' } = {}) => {
+  const lines = text.split('\n');
+  const matchesAt = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const trimmed = lines[i].trim();
+    if (typeof heading === 'string' ? trimmed === heading : heading.test(trimmed)) matchesAt.push(i);
+  }
+  const shown = typeof heading === 'string' ? heading : String(heading);
+  if (matchesAt.length === 0) {
+    if (optional) return null;
+    throw fail(1, `${label}: required section "${shown}" not found — STOP (nothing sliced)`);
+  }
+  if (matchesAt.length > 1) {
+    throw fail(1, `${label}: section "${shown}" appears ${matchesAt.length} times — must be exactly one; STOP (never guess which)`);
+  }
+  const start = matchesAt[0];
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (/^## /.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end).join('\n').replace(/\n+$/, '\n');
+};
+
+// ── assembly ───────────────────────────────────────────────────────────────────────
+
+export const assembleGrounding = ({ constraintsText = null, planText = null, planLabel = 'plan' } = {}) => {
+  const parts = [];
+  if (constraintsText != null) {
+    parts.push(sliceSection(constraintsText, CONSTRAINTS_HEADING, { label: 'AGENTS.md' }));
+  }
+  if (planText != null) {
+    for (const { heading, optional } of PLAN_SECTIONS) {
+      const section = sliceSection(planText, heading, { optional, label: planLabel });
+      if (section != null) parts.push(section);
+    }
+  }
+  return parts.join('\n');
+};
+
+// Trim `payload` to `budget` bytes, tail-first, with a loud in-band marker. The budget is a HARD
+// ceiling: when it is smaller than the marker itself, the marker is truncated too (the output may
+// never exceed `budget` — a facts file over the reserved share would push the final wrapper prompt
+// past the argv ceiling; codex R1 finding). Returns { text, trimmedBytes }. Never a silent cut.
+export const trimToBudget = (payload, budget) => {
+  const bytes = Buffer.byteLength(payload, 'utf8');
+  if (bytes <= budget) return { text: payload, trimmedBytes: 0 };
+  const marker = `\n[grounding] TRIMMED: the assembled facts exceeded the byte budget — tail dropped; tighten the sources or raise --reserve-bytes accounting.\n`;
+  const keep = Math.max(0, budget - Buffer.byteLength(marker, 'utf8'));
+  const joined = Buffer.from(payload, 'utf8').subarray(0, keep).toString('utf8').replace(/�+$/, '') + marker;
+  // Hard-cap the final text (covers budget < marker size): byte-slice, then drop any split rune.
+  const text = Buffer.from(joined, 'utf8').subarray(0, budget).toString('utf8').replace(/�+$/, '');
+  return { text, trimmedBytes: bytes - keep };
+};
+
+// ── the --out destination guard (gitignored / out-of-repo scratch ONLY) ────────────────
+
+const gitLine = (args, cwd) => {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8', windowsHide: true });
+  return r.error || r.status == null ? null : { status: r.status, stdout: r.stdout ?? '' };
+};
+
+// STOP unless `outPath` is a safe scratch destination: outside any git work tree, or gitignored
+// inside one. A TRACKED path and an in-repo NOT-ignored path are both refused (a facts file must
+// never enter the tree it grounds — it would move the fingerprint and could be committed). The
+// check runs on the REAL destination, never the lexical path (codex R1 finding): a symlink leaf is
+// refused outright, and the parent directory is realpath-resolved first, so a gitignored or
+// out-of-repo symlink can never route the write onto a tracked/in-repo file. Returns the resolved
+// real path the caller must write to.
+export const assertScratchDestination = (outPath, cwd) => {
+  const lexical = isAbsolute(outPath) ? outPath : resolve(cwd, outPath);
+  let leaf = null;
+  try {
+    leaf = lstatSync(lexical);
+  } catch {
+    leaf = null; // absent → a fresh file; the parent still gets realpath-checked below
+  }
+  if (leaf?.isSymbolicLink()) {
+    throw fail(1, `--out refuses a symlink destination (${outPath}) — the write would follow it onto another file; name the real scratch path`);
+  }
+  let realParent;
+  try {
+    realParent = realpathSync(dirname(lexical));
+  } catch {
+    throw fail(1, `--out parent directory does not exist (${dirname(lexical)}) — create the scratch dir first`);
+  }
+  const full = join(realParent, basename(lexical));
+  const top = gitLine(['rev-parse', '--show-toplevel'], cwd);
+  if (top == null || top.status !== 0) return full; // no git tree → plain scratch, fine
+  const root = top.stdout.replace(/\r?\n$/, '');
+  const rel = relative(root, full);
+  if (rel.startsWith('..') || isAbsolute(rel)) return full; // really outside the work tree → scratch
+  const tracked = gitLine(['ls-files', '--error-unmatch', '--', rel], root);
+  if (tracked != null && tracked.status === 0) {
+    throw fail(1, `--out refuses a TRACKED path (${rel}) — grounding output is scratch; write it to a gitignored path or outside the repo`);
+  }
+  const ignored = gitLine(['check-ignore', '-q', '--', rel], root);
+  if (ignored == null || ignored.status !== 0) {
+    throw fail(1, `--out refuses an in-repo path that is not gitignored (${rel}) — a new untracked file would move the review fingerprint; use a gitignored path or a location outside the repo`);
+  }
+  return full;
+};
+
+// ── CLI ────────────────────────────────────────────────────────────────────────────
+
+const HELP = `grounding — grounded-review facts assembler for the agent-workflow family (AD-038).
+
+Usage:
+  node grounding.mjs [--constraints] [--plan <path>] [--reserve-bytes <n>] [--out <path>]
+
+  --constraints        slice the root AGENTS.md "Hard Constraints" section verbatim
+                       (exactly one matching heading, else a loud STOP)
+  --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
+  --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 — gitignored / out-of-repo scratch ONLY
+                       (a tracked or in-repo not-ignored path is refused)
+
+Feed the output to the review wrapper: agy-review code --facts @<out>. AGY_MAX_PROMPT_BYTES
+honors the wrapper's contract (default ${DEFAULT_MAX_PROMPT_BYTES}; may only tighten — above the
+OS argv ceiling it is rejected). Writer honesty: --out writes ONE scratch file; nothing else is
+ever written; never commits, never runs a subscription CLI.
+
+Exit codes: 0 success; 2 usage; 1 STOP (missing/duplicate section, unreadable file, refused --out).`;
+
+const parseArgs = (argv) => {
+  let constraints = false;
+  let plan = null;
+  let out = null;
+  let reserve = 0;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--constraints') constraints = true;
+    else if (a === '--plan') {
+      plan = argv[i + 1];
+      if (!plan || plan.startsWith('--')) throw fail(2, '--plan requires a <path>');
+      i += 1;
+    } else if (a === '--out') {
+      out = argv[i + 1];
+      if (!out || out.startsWith('--')) throw fail(2, '--out requires a <path>');
+      i += 1;
+    } else if (a === '--reserve-bytes') {
+      const raw = argv[i + 1];
+      if (!raw || !/^\d+$/.test(raw)) throw fail(2, '--reserve-bytes requires a non-negative integer');
+      reserve = Number(raw);
+      i += 1;
+    } else throw fail(2, `unknown argument: ${a}`);
+  }
+  if (!constraints && plan == null) throw fail(2, 'nothing to assemble — pass --constraints and/or --plan <path>');
+  return { constraints, plan, out, reserve };
+};
+
+const resolveBudget = (env, reserve) => {
+  const raw = env.AGY_MAX_PROMPT_BYTES ?? String(DEFAULT_MAX_PROMPT_BYTES);
+  if (!/^\d+$/.test(raw)) throw fail(2, `AGY_MAX_PROMPT_BYTES='${raw}' is not a non-negative integer`);
+  const max = Number(raw);
+  if (max > ARGV_HARD_MAX) {
+    throw fail(2, `AGY_MAX_PROMPT_BYTES=${max} exceeds the OS single-argv ceiling (~${ARGV_HARD_MAX}) — the override may only tighten (mirrors agy-review)`);
+  }
+  const budget = max - reserve;
+  if (budget <= 0) throw fail(2, `--reserve-bytes ${reserve} leaves no budget under AGY_MAX_PROMPT_BYTES=${max}`);
+  return budget;
+};
+
+export const main = (argv, ctx = {}) => {
+  const cwd = ctx.cwd ?? process.cwd();
+  const env = ctx.env ?? process.env;
+  try {
+    if (argv.includes('--help') || argv.includes('-h')) return { code: 0, stdout: HELP, stderr: '' };
+    const { constraints, plan, out, reserve } = parseArgs(argv);
+    const budget = resolveBudget(env, reserve);
+
+    const readOrStop = (path, label) => {
+      try {
+        return readFileSync(resolve(cwd, path), 'utf8');
+      } catch (err) {
+        throw fail(1, `${label} '${path}' is unreadable (${(err && err.code) || err}) — STOP`);
+      }
+    };
+    const constraintsText = constraints ? readOrStop('AGENTS.md', 'root AGENTS.md') : null;
+    const planText = plan != null ? readOrStop(plan, 'plan file') : null;
+
+    const payload = assembleGrounding({ constraintsText, planText, planLabel: plan ?? 'plan' });
+    const { text, trimmedBytes } = trimToBudget(payload, budget);
+    const stderr = trimmedBytes > 0
+      ? `[grounding] TRIM: assembled ${Buffer.byteLength(payload, 'utf8')} bytes > budget ${budget} (AGY_MAX_PROMPT_BYTES minus --reserve-bytes ${reserve}) — dropped ${trimmedBytes} tail bytes; the cut is marked in-band.`
+      : '';
+
+    if (out != null) {
+      const realOut = assertScratchDestination(out, cwd);
+      writeFileSync(realOut, text);
+      return { code: 0, stdout: `[grounding] wrote ${Buffer.byteLength(text, 'utf8')} bytes to ${out} — pass it as: agy-review code --facts @${out}`, stderr };
+    }
+    return { code: 0, stdout: text, stderr };
+  } catch (err) {
+    return { code: err.exitCode ?? 1, stdout: '', stderr: `grounding: ${err.message}` };
+  }
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) {
+  const r = main(process.argv.slice(2));
+  // Exact writes + a natural exit (codex R2): console.log would append a stray newline to the
+  // byte-exact facts payload, and process.exit() can truncate large piped stdout before Node
+  // flushes. The payload already ends with '\n' (sliceSection normalizes); only a non-payload
+  // message (help / the --out report) gains the terminating newline it lacks.
+  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`);
+  process.exitCode = r.code;
+}

package/tools/procedures.mjs

@@ -18,10 +18,15 @@
 
 import { readFileSync, lstatSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { pathToFileURL } from 'node:url';
+import { join, dirname } from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
 import { detectBackends, wrapperCmdFor, wrapperContractFor } from './detect-backends.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 READ-ONLY checker (review-state.mjs
+// performs no fs writes, so the "procedures never reaches a writer" import-split invariant holds;
+// the WRITER-capable grounding.mjs is only NAMED in rendered text, never imported).
+import { plansInFlight, PLANS_REL } from './review-state.mjs';
 // The config schema/read core lives in orchestration-config.mjs (the single config contract). procedures
 // is READ-ONLY: it imports the reader + the SHARED slot/recipe validity, never the fs-writer
 // (orchestration-write.mjs) — so "the read-only advisor can never reach a writer" is STRUCTURALLY true
@@ -188,6 +193,41 @@ const reviewLoopAdvice = (slots) =>
       ]
     : [];
 
+// The grounding pre-step (AD-038, extending the AD-033 verbatim-contract rendering): whenever the
+// resolved dispatch includes agy-review, print the CONCRETE facts-assembly invocation + the
+// --facts form as a copy-paste pre-step — population, not placeholders. Plan-path population rule
+// (the review-state plan-in-flight detector): exactly ONE plan in flight → render it populated;
+// zero or several → the explicit `--plan <path>` placeholder + a one-line discovery caveat. The
+// suggested --out lives OUTSIDE the repo (/tmp) — grounding.mjs refuses a non-scratch destination.
+const GROUNDING_TOOL = join(dirname(fileURLToPath(import.meta.url)), 'grounding.mjs');
+const GROUNDING_FACTS_OUT = '/tmp/review-facts.md';
+const groundingPreStepAdvice = (activity, slots, plans) => {
+  if (!slots.some((s) => (s.backends ?? []).includes('agy-review'))) return [];
+  const planArg = plans.length === 1 ? `--plan "${PLANS_REL}/${plans[0]}"` : '--plan <path>';
+  // plan-authoring reviews the plan FILE — when exactly one plan is in flight, the review command
+  // is populated with the same discovered path (codex R3: a known path never renders a placeholder).
+  const reviewForm =
+    activity === 'plan-authoring'
+      ? plans.length === 1
+        ? `agy-review plan "${PLANS_REL}/${plans[0]}"`
+        : 'agy-review plan <plan-file>'
+      : 'agy-review code';
+  // `run:`/`then:` prefixes keep these POPULATED command lines machine-distinguishable from the
+  // verbatim contract DESCRIPTORS above (the descriptor drift guard set-equals bare wrapper lines).
+  // Path arguments are double-quoted — a skill dir or plan name with a space must stay copy-pasteable.
+  const lines = [
+    'Grounding pre-step (agy is dispatched — assemble the verified facts BEFORE the review; grounding.mjs slices verbatim, judgment additions stay yours):',
+    `  run:  node "${GROUNDING_TOOL}" --constraints ${planArg} --out ${GROUNDING_FACTS_OUT}`,
+    `  then: ${reviewForm} --facts @${GROUNDING_FACTS_OUT}`,
+  ];
+  if (plans.length === 0) {
+    lines.push(`  ↳ plan discovery: no plan in flight under ${PLANS_REL} — substitute the plan file you are reviewing against, or drop --plan for constraints-only facts.`);
+  } else if (plans.length > 1) {
+    lines.push(`  ↳ plan discovery: ${plans.length} plans in flight under ${PLANS_REL} (${plans.join(', ')}) — populate --plan with the one under review.`);
+  }
+  return lines;
+};
+
 // The cost-lane advisory block (cost-tiered execution — orchestration.md §5 canon, paraphrased
 // at the point of use like reviewLoopAdvice paraphrases §9/§4). Rendered UNCONDITIONALLY for
 // every activity — the lanes route EVERY step, review-backed or not (unlike reviewLoopAdvice,
@@ -226,7 +266,7 @@ const contractLines = ({ cmd, contract }) => {
   return lines;
 };
 
-const formatHuman = ({ activity, section, slots, warnings }) => {
+const formatHuman = ({ activity, section, slots, warnings, plans }) => {
   const lines = [
     section,
     '',
@@ -238,6 +278,8 @@ const formatHuman = ({ activity, section, slots, warnings }) => {
     if (s.reason) lines.push(`      ↳ ${s.reason}`);
     for (const c of s.contracts ?? []) lines.push(...contractLines(c));
   }
+  const grounding = groundingPreStepAdvice(activity, slots, plans);
+  if (grounding.length) lines.push('', ...grounding);
   const advice = reviewLoopAdvice(slots);
   if (advice.length) lines.push('', ...advice);
   lines.push('', ...costLanesAdvice());
@@ -248,7 +290,7 @@ const formatHuman = ({ activity, section, slots, warnings }) => {
   return lines.join('\n');
 };
 
-const buildJson = ({ activity, section, slots, configSource, warnings }) => ({
+const buildJson = ({ activity, section, slots, configSource, warnings, plans }) => ({
   activity,
   section,
   slots: Object.fromEntries(
@@ -257,6 +299,8 @@ const buildJson = ({ activity, section, slots, configSource, warnings }) => ({
     slots.map((s) => [s.slot, { recipe: s.recipe, source: s.source, degradedFrom: s.degradedFrom, reason: s.reason, backends: s.backends, contracts: s.contracts }]),
   ),
   reviewLoop: reviewLoopAdvice(slots),
+  // ADDITIVE (AD-038): the populated grounding pre-step, structured (empty when agy is not dispatched).
+  groundingPreStep: groundingPreStepAdvice(activity, slots, plans),
   // ADDITIVE (cost-tiered execution): the unconditional cost-lane advisory, structured.
   costLanes: costLanesAdvice(),
   configSource,
@@ -311,9 +355,10 @@ export const main = (argv, ctx = {}) => {
     }
     const slots = resolveAllSlots({ activity, config, detection, overrides });
     const warnings = [...detectWarnings, ...collectWarnings(slots)];
+    const plans = plansInFlight(cwd);
     const stdout = json
-      ? JSON.stringify(buildJson({ activity, section, slots, configSource, warnings }), null, 2)
-      : formatHuman({ activity, section, slots, warnings });
+      ? JSON.stringify(buildJson({ activity, section, slots, configSource, warnings, plans }), null, 2)
+      : formatHuman({ activity, section, slots, warnings, plans });
     return { code: 0, stdout, stderr: '' };
   } catch (err) {
     return { code: err.exitCode ?? 1, stdout: '', stderr: `procedures: ${err.message}` };

package/tools/recipes.mjs

@@ -17,6 +17,7 @@
 import { pathToFileURL } from 'node:url';
 import {
   detectBackends,
+  wrapperCmdFor,
   READY,
   NEEDS_SKILL,
   NEEDS_CLI,
@@ -300,6 +301,41 @@ export const composeStatusLine = (detection, recommendation) => {
   return `backends: ${backends} — run /agent-workflow-kit backends · recipes: ${recommendation.clause} — see /agent-workflow-kit recipes`;
 };
 
+// ── the one-line ACTIVE-recipe line (the discovery line — configured, never recommended) ───────────
+
+// composeActiveRecipeLine({ config, source }, detection) → ONE line rendering the CONFIGURED recipe of
+// every activity/slot (resolved via resolveActivityRecipe: config entry, else computed default), each
+// with its source label, its degradation stated, and its dispatched wrapper set — explicitly labeled
+// "configured" and contrasted with the readiness-RECOMMENDED recipe (which composeStatusLine shows and
+// which is NOT what runs). This is the machine-composed sibling of composeStatusLine (AD-034): the
+// session-start checklist + the handover "Active recipes:" slot paste it verbatim, so no agent composes
+// the configured-recipe facts by hand. `{ config, source }` is exactly what loadConfig returns (source
+// 'none' when no config file exists). Always exactly one line: no part may carry a newline (pinned).
+export const composeActiveRecipeLine = ({ config, source } = {}, detection) => {
+  const cells = [];
+  for (const [activity, def] of Object.entries(ACTIVITIES)) {
+    for (const slot of Object.keys(def.slots)) {
+      const r = resolveActivityRecipe({ config: config ?? {}, readiness: detection, activity, slot });
+      const { dispatch } = planRecipe(r.recipe, detection);
+      const wrappers = dispatch.map((d) => wrapperCmdFor(d.backend, d.role)).filter(Boolean);
+      const srcLabel = r.source === 'config' ? 'configured' : 'computed default';
+      const head = r.degradedFrom
+        ? `${activity}.${slot} = ${r.degradedFrom} (${srcLabel}; degrades here to ${r.recipe} — ${r.reason})`
+        : `${activity}.${slot} = ${r.recipe} (${srcLabel})`;
+      const suffix =
+        wrappers.length >= 2
+          ? ` → every backend every round: ${wrappers.join(' + ')}`
+          : wrappers.length === 1
+            ? ` → ${wrappers[0]}`
+            : '';
+      cells.push(`${head}${suffix}`);
+    }
+  }
+  const rec = recommendRecipe(detection);
+  const origin = source === 'none' || config == null ? 'no config file — computed defaults apply' : `from ${source}`;
+  return `active recipes (${origin}): ${cells.join(' · ')} — the configured recipes above are what runs; readiness-recommended here: ${rec.recipe} (informational)`;
+};
+
 // ── report + CLI ─────────────────────────────────────────────────────────────────
 
 // The structured report behind `--json` — the recipes, the recommendation, a plan per recipe, and
@@ -343,38 +379,68 @@ export const formatRecipes = (detection) => {
 };
 
 // The full argv vocabulary — anything else rejects LOUDLY. The old parse silently routed unknown
-// args into the multi-line human render; with `--status-line` (whose output is pasted as fact) a
-// mistyped flag masquerading as a mode would be a silent failure, so the parse is strict now.
-const KNOWN_ARGS = new Set(['--help', '-h', '--json', '--status-line']);
+// args into the multi-line human render; with `--status-line` / `--active-line` (whose output is
+// pasted as fact) a mistyped flag masquerading as a mode would be a silent failure, so the parse is
+// strict now.
+const KNOWN_ARGS = new Set(['--help', '-h', '--json', '--status-line', '--active-line']);
+const EXCLUSIVE_ARGS = ['--json', '--status-line', '--active-line']; // each owns stdout whole
 
-const main = (argv) => {
+const main = async (argv) => {
   if (argv.includes('--help') || argv.includes('-h')) {
     console.log(`recipes — read-only orchestration-recipe advisor for the agent-workflow family.
 
 Usage:
-  node recipes.mjs [--json | --status-line]
+  node recipes.mjs [--json | --status-line | --active-line]
 
 Lists the four recipes (Solo / Reviewed / Council / Delegated) and, from the read-only backend
 detector, plans + recommends one for the current environment. --status-line prints exactly ONE
 line — the machine-composed backend-status summary the bootstrap/upgrade reports paste verbatim.
---json emits the structured report (incl. the same line as \`statusLine\`); the two are mutually
+--active-line prints exactly ONE line — the CONFIGURED recipe per activity/slot, resolved from the
+per-project docs/ai/orchestration.json (read from the current directory) + live readiness, with
+degradation stated; paste it verbatim at session start / into the handover "Active recipes:" slot.
+--json emits the structured report (incl. the same line as \`statusLine\`); the three are mutually
 exclusive. Detection only — never writes, never commits, never runs a subscription CLI.`);
     return;
   }
   const unknown = argv.find((a) => !KNOWN_ARGS.has(a));
   if (unknown !== undefined) {
     console.error(`[agent-workflow-kit] unknown argument: ${unknown}`);
-    process.exit(1);
+    return 1;
   }
-  if (argv.includes('--json') && argv.includes('--status-line')) {
-    console.error('[agent-workflow-kit] --json and --status-line are mutually exclusive — pick one output');
-    process.exit(1);
+  const exclusive = EXCLUSIVE_ARGS.filter((a) => argv.includes(a));
+  if (exclusive.length > 1) {
+    console.error(`[agent-workflow-kit] ${exclusive.join(' and ')} are mutually exclusive — pick one output`);
+    return 1;
   }
   const detection = detectBackends();
-  if (argv.includes('--status-line')) console.log(composeStatusLine(detection, recommendRecipe(detection)));
+  if (argv.includes('--active-line')) {
+    // Lazy import: orchestration-config.mjs statically imports this module (ACTIVITIES/SLOT_RECIPES),
+    // so the config reader is pulled in at run time only — no static import cycle.
+    const { loadConfig } = await import('./orchestration-config.mjs');
+    try {
+      console.log(composeActiveRecipeLine(loadConfig(process.cwd()), detection));
+    } catch (err) {
+      console.error(`[agent-workflow-kit] ${err.message}`);
+      return err.exitCode ?? 1;
+    }
+  } else if (argv.includes('--status-line')) console.log(composeStatusLine(detection, recommendRecipe(detection)));
   else if (argv.includes('--json')) console.log(JSON.stringify(buildReport(detection), null, 2));
   else console.log(formatRecipes(detection));
+  return 0;
 };
 
 const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) main(process.argv.slice(2));
+// 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) {
+  main(process.argv.slice(2)).then(
+    (code) => {
+      process.exitCode = code ?? 0;
+    },
+    (err) => {
+      console.error(`[agent-workflow-kit] ${(err && err.message) || err}`);
+      process.exitCode = 1;
+    },
+  );
+}