@sabaiway/agent-workflow-kit 1.47.0 → 1.48.0

package/tools/recommendations.mjs

@@ -19,10 +19,11 @@
 // below) and VERDICT-FIRST (D1): every non-optimal state opens with ONE composed verdict line.
 // Registry strings are frozen tool DATA, fact-true, one line under the shape cap (D2); posture/
 // risk prose lives in the mode doc at the consent moment (D3). A probe failure is a stated
-// skipped-item line — never a crash, never a fabricated item. The sandbox-lane item is HAND-APPLY
-// by design (bridge council 2026-07-11, both backends concur): the kit never seeds
-// sandbox.network.allowedDomains / filesystem.allowWrite; its convergence is a NEUTRAL
-// fingerprint-bound acknowledgement, never a security key (D4).
+// skipped-item line — never a crash, never a fabricated item. The kit never seeds
+// sandbox.network.allowedDomains / filesystem.allowWrite (HAND-APPLY territory; bridge council
+// 2026-07-11, both backends concur); the sandbox-lane item's convergence is a NEUTRAL
+// fingerprint-bound acknowledgement recorded by the consent-gated ack writer into the family-owned
+// docs/ai/acks.json (AD-055 relocated it off the host settings schema), never a security key (D4).
 //
 // Read-only: never writes, never commits, never runs a subscription CLI. The reused probes are all
 // exported read-only surfaces of their owning tools (velocity/autonomy/doctor/backends/recipes/
@@ -55,6 +56,7 @@ import { probeSandboxMasks, needsMasksApply } from './sandbox-masks.mjs';
 import { shellQuoteArg } from './review-state.mjs';
 import { loadConfig } from './orchestration-config.mjs';
 import { DEFAULT_BUNDLE_ROOT, SETTINGS_FILENAME, settingsPath, parseSettings, duplicateKeys } from './bridge-settings-read.mjs';
+import { assertContainedRealPath } from './fs-safe.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const toolPath = (rel) => join(HERE, rel);
@@ -95,6 +97,9 @@ export const SEVERITIES = Object.freeze({
   'review-recipe': SEVERITY_ATTENTION,
   'gates-declaration': SEVERITY_OPTIONAL,
   'gate-hook': SEVERITY_OPTIONAL,
+  'read-lane': SEVERITY_OPTIONAL,
+  'read-lane.stale': SEVERITY_ATTENTION,
+  'read-lane.missing': SEVERITY_ATTENTION,
   'family-freshness': SEVERITY_ATTENTION,
   'sandbox-masks': SEVERITY_OPTIONAL,
   'agy-adddir': SEVERITY_OPTIONAL,
@@ -147,6 +152,9 @@ export const WHATS = Object.freeze({
   'review-recipe': '{degraded}',
   'gates-declaration': 'no declared gate matrix (docs/ai/gates.json absent or empty) — gates prompt one by one; the apply PREVIEWS its --apply line, writes nothing',
   'gate-hook': '{n} declared gate(s) prompt per run — the gate-approval hook is not wired',
+  'read-lane': 'the gate hook is wired but the read-only compound lane is off — pipes/chains of seeded reads still prompt one by one',
+  'read-lane.stale': 'the read-lane is ON but the placed gate hook is stale — an old hook never reads lanes.json, so the lane is silently dark; reseed it',
+  'read-lane.missing': 'the gate hook is wired but its placed file is missing — every Bash call errors and the read-lane is dark; re-place it',
   'family-freshness': '{parts}',
   'sandbox-masks': '{n} sandbox device mask(s) clutter git status — the managed exclude block is absent or stale',
   'sandbox-masks.stale-real': '{n} sandbox device mask(s) clutter git status — the exclude block is stale; {m} fenced entr(ies) are REAL paths (a fresh apply drops them)',
@@ -197,6 +205,7 @@ export const BENEFITS = Object.freeze({
   'review-recipe': 'review coverage — the review recipe you configured actually runs instead of silently degrading',
   'gates-declaration': 'velocity — your project’s gates run as ONE declared batch with a PASS/FAIL table',
   'gate-hook': 'velocity — your own declared gate commands auto-approve byte-exactly (opt-in PreToolUse hook)',
+  'read-lane': 'velocity — pipes/chains of your seeded read-only commands auto-approve instead of prompting (opt-in, conservatively classified)',
   'family-freshness': 'currency — placed family members carry the latest shipped fixes and features',
   'sandbox-masks': 'zero clutter — git status shows only your changes (the review domain already ignores the masks by construction)',
   'agy-adddir': 'large reviews — an oversized agy code review offloads to a staging dir instead of refusing',
@@ -334,6 +343,43 @@ const probeGates = ({ root, deps, add, skip }) => {
   }
 };
 
+// The read-lane offer (AD-055 Part II, Help-through-Recommendations): once the gate hook is PLACED
+// and WIRED, offer to enable the opt-in read-only compound lane. Mutually exclusive with the
+// gate-hook item BY CONSTRUCTION — that item keys on `!wired`, this one on `wired` — so an unplaced
+// or un-wired hook is covered there, never double-offered here. The apply is the gate-hook
+// --read-lane PREVIEW one-liner (its own currency check + posture note fire at the writer; it may
+// prompt once — it IS a consent flow). Converges once lanes.json enables the lane.
+const probeReadLane = ({ root, deps, add, skip }) => {
+  try {
+    const sg = surveyGateHook(root, deps);
+    if (sg.error) throw new Error(sg.error);
+    if (!sg.wired) return; // not wired → the gate-hook item covers (no double-fire)
+    if (!sg.filePlaced) {
+      // Wired but the placed hook FILE is missing — the hook errors on every Bash call and the lane
+      // is silently dark; surface it as attention with a place-first recovery (council R2-M2).
+      add('read-lane', fillTemplate(WHATS['read-lane.missing'], {}), `node ${q(toolPath('gate-hook.mjs'))} --apply --cwd ${q(root)}`, 'read-lane.missing');
+      return;
+    }
+    if (readReadLaneToggle(root, deps)) {
+      // The lane is ON: converged IFF the placed hook is byte-current — a stale (pre-1.48) hook never
+      // reads lanes.json, so the enabled lane is a silent no-op the user must reseed (council B7). The
+      // rm target is ABSOLUTE (council R2-M3) so running the recovery from any cwd can only delete this
+      // repo's hook.
+      if (isPlacedHookCurrent(root, deps)) return; // converged
+      add(
+        'read-lane',
+        fillTemplate(WHATS['read-lane.stale'], {}),
+        `HAND-APPLY: rm ${q(join(root, GATE_HOOK_REL))}, then node ${q(toolPath('gate-hook.mjs'))} --apply --cwd ${q(root)}`,
+        'read-lane.stale',
+      );
+      return;
+    }
+    add('read-lane', fillTemplate(WHATS['read-lane'], {}), `node ${q(toolPath('gate-hook.mjs'))} --read-lane --cwd ${q(root)}`);
+  } catch (err) {
+    skip('read-lane', err);
+  }
+};
+
 const probeFamilyFreshness = ({ deps, add, skip }) => {
   try {
     const survey = deps.surveyFamily ?? surveyFamily;
@@ -485,15 +531,102 @@ export const recipeFingerprint = ({ hosts, dirs, home }) => {
   return createHash('sha256').update(canonical).digest('hex').slice(0, 16);
 };
 
-// The kit-owned neutral ack namespace (D4): project-scoped, hand-applicable as one line, read from
-// BOTH settings scopes; the sandbox/permissions security keys are NEVER consulted as an ack.
+// The kit-owned neutral ack store (D4; AD-055 Part I): a FAMILY-OWNED strict-JSON file no host
+// validator guards — top-level key `sandboxLaneAck` (+ optional `_README`), unknown keys tolerated
+// on read (future acks are siblings). This is the PRIMARY ack channel; the legacy settings-scope
+// keys below are read for one deprecation window. The sandbox/permissions security keys are NEVER
+// consulted as an ack.
+export const ACKS_FILE = 'docs/ai/acks.json';
+export const ACKS_LANE_KEY = 'sandboxLaneAck';
+
+// The opt-in read-lane toggle file (AD-055 Part II) — the SAME kit-owned docs/ai/lanes.json the
+// placed hook reads live. The read-lane item offers to enable it once the hook is placed+wired.
+export const LANES_FILE = 'docs/ai/lanes.json';
+export const READ_LANE_KEY = 'readLane';
+
+// The placed gate hook + the bundled runtime the read-lane item byte-compares for currency (AD-055
+// Part II, council B7): an enabled lane over a STALE hook is a silent no-op — the pre-1.48 hook never
+// reads lanes.json — so it must surface as an ATTENTION reseed, not a silent convergence.
+const GATE_HOOK_REL = '.claude/hooks/agent-workflow-gates.mjs';
+const BUNDLED_HOOK_ABS = join(HERE, '..', 'references', 'hooks', 'gate-approve.mjs');
+
+// Byte-compare the placed gate hook against the bundled runtime. A read error (an unreadable placed
+// hook, a broken kit bundle) propagates → the probe states a skip, never a wrong currency verdict.
+const isPlacedHookCurrent = (root, deps) => {
+  const readFile = deps.readFile ?? readFileSync;
+  const placed = readFile(join(root, GATE_HOOK_REL), 'utf8');
+  const bundle = readFile(deps.bundledHookPath ?? BUNDLED_HOOK_ABS, 'utf8');
+  return placed === bundle;
+};
+
+// The LEGACY neutral ack namespace (pre-AD-055): read from BOTH settings scopes until the next kit
+// MAJOR (2.0.0) so a never-migrated host stays converged across the deprecation window (Decisions 3).
 export const SANDBOX_LANE_ACK_PARENT = 'agentWorkflow';
 export const SANDBOX_LANE_ACK_KEY = 'sandboxLaneAck';
 
+// Read the family-owned ack store. An ABSENT file (or absent docs/ai) is the NORMAL not-yet-acked
+// state → null (plain fall-through, never a skip). A parse/IO error on an EXISTING file THROWS — the
+// probe's catch turns it into a stated skip line (Decisions 2). A non-object root is a malformed
+// store (fail-closed skip); a non-string value at the key is tolerated → null (the item re-fires).
+// The WHOLE path chain (root / docs / ai / acks.json) is guarded WITHOUT following symlinks
+// BEFORE any read: a symlinked ANCESTOR could otherwise read an ack from OUTSIDE the project (the
+// writer refuses such a deployment — the reader must too), a symlinked/dangling LEAF must not read as
+// not-yet-acked, and a non-regular target (FIFO/dir/device) is a fail-closed SKIP — never read it (a
+// FIFO would BLOCK the advisor). ENOENT-safe: an absent file/dir is the NORMAL not-yet-acked null.
+const readAcksLane = (root, deps) => {
+  const readFile = deps.readFile ?? readFileSync;
+  const lstat = deps.lstat ?? lstatSync;
+  const absPath = join(root, ACKS_FILE);
+  let st;
+  try {
+    assertContainedRealPath(root, absPath, { lstat }); // symlinked root/ancestor/leaf or escape → throws
+    st = lstat(absPath);
+  } catch (err) {
+    if (err?.code === 'ENOENT') return null; // genuinely absent (file or docs/ai) — normal not-yet-acked
+    throw err; // a symlinked ancestor/leaf, an escape, or a real IO error — stated skip
+  }
+  if (!st.isFile()) {
+    throw new Error(`${ACKS_FILE} is not a regular file — refusing to read it`);
+  }
+  const parsed = JSON.parse(readFile(absPath, 'utf8'));
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${ACKS_FILE}: expected a JSON object`);
+  }
+  const value = parsed[ACKS_LANE_KEY];
+  return typeof value === 'string' ? value : null;
+};
+
+// Read the opt-in read-lane toggle for the read-lane item. An ABSENT file (or absent docs/ai) →
+// false (the lane is off — offer it). `readLane === true` → enabled (converged). A parse/IO error on
+// an EXISTING file, a symlinked ancestor/leaf, an escape, or a non-object root THROWS — the probe
+// turns it into a stated skip (a BROKEN toggle the writer would refuse to overwrite is not "off").
+// A present-but-non-boolean `readLane` is a valid store the writer merges → false (offer), never a skip.
+const readReadLaneToggle = (root, deps) => {
+  const readFile = deps.readFile ?? readFileSync;
+  const lstat = deps.lstat ?? lstatSync;
+  const absPath = join(root, LANES_FILE);
+  let st;
+  try {
+    assertContainedRealPath(root, absPath, { lstat }); // symlinked root/ancestor/leaf or escape → throws
+    st = lstat(absPath);
+  } catch (err) {
+    if (err?.code === 'ENOENT') return false; // genuinely absent — the lane is off, offer it
+    throw err; // a symlinked ancestor/leaf, an escape, or a real IO error — stated skip
+  }
+  if (!st.isFile()) {
+    throw new Error(`${LANES_FILE} is not a regular file — refusing to read it`);
+  }
+  const parsed = JSON.parse(readFile(absPath, 'utf8'));
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${LANES_FILE}: expected a JSON object`);
+  }
+  return parsed[READ_LANE_KEY] === true;
+};
+
 // D3: the risk-marked keys — every key here has a per-item posture note in the mode doc, surfaced
 // at the consent moment; the static contract test asserts EXACT bidirectional coverage
 // (risk-marked keys == mode-doc note keys — a dropped note goes red, not silent).
-export const RISK_NOTED_KEYS = Object.freeze(['agy-adddir', 'sandbox-lane']);
+export const RISK_NOTED_KEYS = Object.freeze(['agy-adddir', 'sandbox-lane', 'read-lane']);
 
 const probeSandboxLane = ({ root, deps, add, skip }) => {
   try {
@@ -522,14 +655,28 @@ const probeSandboxLane = ({ root, deps, add, skip }) => {
       if (!dirs.includes(resolved)) dirs.push(resolved);
     }
     const fingerprint = recipeFingerprint({ hosts, dirs, home });
-    // Convergence is the NEUTRAL fingerprint-bound acknowledgement, read from BOTH scopes — a
-    // changed recipe (hosts, dirs, or an env override) re-fires the item (D4).
-    const acks = [settings.data?.[SANDBOX_LANE_ACK_PARENT]?.[SANDBOX_LANE_ACK_KEY], localSettings.data?.[SANDBOX_LANE_ACK_PARENT]?.[SANDBOX_LANE_ACK_KEY]];
+    // Convergence is the NEUTRAL fingerprint-bound acknowledgement: the item converges iff the
+    // CURRENT fingerprint equals the ack in ANY consulted store — the family-owned acks.json FIRST,
+    // then the legacy settings scopes; a stale value in one store is ignored when another matches
+    // (Decisions 2). A changed recipe (hosts, dirs, or an env override) re-fires the item (D4).
+    const acks = [
+      readAcksLane(root, deps),
+      settings.data?.[SANDBOX_LANE_ACK_PARENT]?.[SANDBOX_LANE_ACK_KEY],
+      localSettings.data?.[SANDBOX_LANE_ACK_PARENT]?.[SANDBOX_LANE_ACK_KEY],
+    ];
     if (acks.includes(fingerprint)) return; // the acknowledged recipe — the item converged
+    // The item joins the CONSENT-GATED WRITER class (Decisions 4): the apply is the ack writer's
+    // PREVIEW one-liner (pure executable, cwd-independent), carrying the neutral fingerprint — never
+    // a security key. The LIVE recipe (egress hosts + resolved writable dirs) rides a separate
+    // rendered `recipe:` line (the fill source for the mode doc's lane-(2) hand-apply block); the
+    // fingerprint encodes it, so a changed recipe re-fires with a fresh command.
+    const recipe = `egress hosts [${hosts.join(', ')}]; writable state dirs [${dirs.join(', ')}] (observed-minimal; a blocked host names itself at run time)`;
     add(
       'sandbox-lane',
       fillTemplate(WHATS['sandbox-lane'], {}),
-      `HAND-APPLY (a neutral acknowledgement, never a security key): recipe — egress hosts [${hosts.join(', ')}]; writable state dirs [${dirs.join(', ')}] (observed-minimal; a blocked host names itself at run time); what to DO with it per host class: the mode doc's sandbox-lanes section; once handled, record the ack: set "${SANDBOX_LANE_ACK_PARENT}"."${SANDBOX_LANE_ACK_KEY}" to "${fingerprint}" in .claude/settings.json or settings.local.json — a MERGE into the existing ${SANDBOX_LANE_ACK_PARENT} object (keep its other keys; create it only if absent)`,
+      `node ${q(toolPath('ack-write.mjs'))} --fingerprint ${fingerprint} --cwd ${q(root)}`,
+      'sandbox-lane',
+      recipe,
     );
   } catch (err) {
     skip('sandbox-lane', err);
@@ -543,6 +690,7 @@ const PROBES = Object.freeze([
   probeSandboxProvision,
   probeReviewRecipe,
   probeGates,
+  probeReadLane,
   probeFamilyFreshness,
   probeMasksItem,
   probeAgyAdddir,
@@ -560,18 +708,22 @@ export const buildRecommendations = ({ cwd, deps = {} } = {}) => {
   // violation surfaces through the stated-skip lane, never a crash, never a rendered violation.
   // severityKey defaults to the item key; a per-site arm passes its `<key>.<variant>` entry when
   // its class differs from the base (the invalid-env attention arm).
-  const add = (key, what, apply, severityKey = key) => {
+  // `detail` (optional) is an extra rendered `recipe:` line — factual context that is TOO LONG for
+  // the capped WHAT and does NOT belong in the pure-command apply (the sandbox-lane live recipe:
+  // egress hosts + resolved writable dirs). Single-line like apply; absent for every other item.
+  const add = (key, what, apply, severityKey = key, detail = null) => {
     const problems = [];
     if (!(key in BENEFITS)) problems.push(`unregistered item key ${JSON.stringify(key)}`);
     if (!(severityKey in SEVERITIES)) problems.push(`unregistered severity key ${JSON.stringify(severityKey)}`);
     if (/[\r\n]/.test(what)) problems.push('WHAT is not a single line');
     else if (what.length > ITEM_LINE_CAP) problems.push(`WHAT exceeds the ${ITEM_LINE_CAP}-char cap (${what.length})`);
     if (/[\r\n]/.test(apply)) problems.push('apply is not a single line');
+    if (detail != null && /[\r\n]/.test(detail)) problems.push('recipe detail is not a single line');
     if (problems.length > 0) {
       skip(key, new Error(`item shape violation — ${problems.join('; ')}`));
       return;
     }
-    items.push({ key, severity: SEVERITIES[severityKey], what, benefit: BENEFITS[key], apply });
+    items.push({ key, severity: SEVERITIES[severityKey], what, benefit: BENEFITS[key], apply, detail });
   };
   for (const probe of deps.probes ?? PROBES) probe({ root, deps, add, skip });
   return { root, items, skips };
@@ -599,6 +751,7 @@ export const formatRecommendations = ({ items, skips }) => {
     ordered.forEach((item, i) => {
       lines.push(`${i + 1}. ${SEVERITY_LABELS[item.severity] ?? SEVERITY_LABELS[SEVERITY_OPTIONAL]}: ${item.what}`);
       lines.push(`   benefit: ${item.benefit}`);
+      if (item.detail) lines.push(`   recipe: ${item.detail}`);
       lines.push(`   apply: ${item.apply}`);
     });
   }
@@ -615,15 +768,16 @@ Usage:
 
 Computes the deterministic Recommendations section every kit upgrade ends with — VERDICT-FIRST:
 one composed verdict line opens every non-optimal render, then per item {severity · what is
-sub-optimal · the benefit in one plain line · the exact consent-gated apply one-liner}. --cwd is
+sub-optimal · the benefit in one plain line · an optional \`recipe:\` line (the sandbox-lane live
+recipe only) · the exact consent-gated apply one-liner}. --cwd is
 REQUIRED (the target project is explicit, never inferred from the shell's current directory). The
 section renders present-even-when-empty ("${RECOMMENDATIONS_EMPTY_LINE}"); a probe failure is a
 stated skipped-item line. Apply lines are cwd-independent (absolute tool paths, a pinned --cwd;
 the doctor item pins via a cd prefix; the ONE exception is the set-autonomy item — a
 conversational skill invocation labeled "run IN the target project") and preserve each writer's
-own consent semantics; the sandbox-lane item is HAND-APPLY by design — this tool and the kit
-writers never seed sandbox network/filesystem allowances, and its convergence is a neutral
-fingerprint acknowledgement, never a security key.
+own consent semantics; the kit never seeds sandbox network/filesystem allowances (HAND-APPLY
+territory), and the sandbox-lane convergence is a neutral fingerprint acknowledgement recorded by
+the consent-gated ack writer into docs/ai/acks.json (never a security key).
 
 Read-only: never writes, never commits, never runs a subscription CLI. Exit codes: 0 report
 rendered (items or empty); 1 error; 2 usage.`;

package/tools/velocity-profile.mjs

@@ -255,8 +255,19 @@ export const RUNTIME_RESIDUAL_FORMS = Object.freeze({
   writeRedirections: Object.freeze(['>', '>>', '1>', '2>', '&>', '>|']),
   // `$(…)` + backtick + process substitution `<(…)` all RUN a nested command (`>(…)` is caught by
   // the `>` redirection scan). Bare `<` is input redirection (reads a file — read-only commands may
-  // already do that), so it is deliberately NOT here.
-  commandSubstitutions: Object.freeze(['$(', '`', '<(']),
+  // already do that), so it is deliberately NOT here. The bash-5.3 function substitutions `${ cmd; }`
+  // (a blank — space/tab/newline/CR — right after `${`) and `${| cmd; }` (runs a command, assigns
+  // REPLY) also execute a nested command — matched as the literal openers `${ ` / `${\t` / `${\n` /
+  // `${\r` / `${|` (AD-055 Part II; the `\r` opener guards CRLF payloads — council agy nit). An
+  // ordinary `${VAR}` parameter expansion has NO blank after `${`, so it trips none of these — kept
+  // rung-(b)-silent on a settings-allowed single (rung (c) excludes all `$`).
+  commandSubstitutions: Object.freeze(['$(', '`', '<(', '${ ', '${\t', '${\n', '${\r', '${|']),
+  // A backslash immediately before a newline/CR is a bash LINE CONTINUATION: bash removes it and
+  // splices the two lines into ONE word, which can reconstruct a residual token (`--output`, `$(`,
+  // `${ …; }`) that a raw substring scan on the pre-splice string misses (`--outp\<newline>ut=f` →
+  // `--output=f`). Guards a settings-allowed SINGLE (rung c already forbids backslash in every
+  // segment). AD-055 Part II council fold (codex B3).
+  lineContinuations: Object.freeze(['\\\n', '\\\r']),
   // The `--output` write-flag family, matched as a raw SUBSTRING of the whole command (never a
   // whitespace-token check): the hook sees the pre-shell command string, so `--output=f`,
   // `"--output=f"`, `'--output' f`, and `\--output` must all trip it — over-asking on a benign