@sabaiway/agent-workflow-kit 1.45.0 → 1.46.0

package/tools/recommendations.mjs

@@ -6,19 +6,23 @@
 // bridge allowlist, autonomy render drifted, sandbox not provisioned, gates undeclared) — every
 // `upgrade` run therefore ends with a mandatory, deterministic Recommendations section: what is
 // sub-optimal · the benefit in ONE plain line · the exact consent-gated apply one-liner. The agent
-// pastes the section VERBATIM (the composeStatusLine precedent) and then OFFERS to apply; the user
-// picks items in plain language; the agent runs EXACTLY the rendered one-liners — no improvisation,
-// each writer's own consent semantics intact.
+// PRESENTS the section in the user's conversational language — every fact, count and item from
+// the tool, nothing added or dropped; commands, paths, hosts and rule strings byte-exact; the raw
+// tool block shown on request (the AD-032 report-contract lane). The user picks items in plain
+// language; after the per-item consent moment the agent runs EXACTLY the rendered one-liners — no
+// improvisation, each writer's own consent semantics intact.
 //
 // Contract:
 //   node recommendations.mjs --cwd <project-root> [--json]
 // --cwd is REQUIRED (subdir-proof: the target project is explicit, never inferred from the shell's
 // current directory). The section renders PRESENT-EVEN-WHEN-EMPTY (the exact empty-state line
-// below). Benefit lines are frozen tool DATA, fact-true: the dual velocity+security wording rides
-// ONLY items with a real security delta (sandbox/autonomy render); the bridge-wrappers item claims
-// velocity only. A probe failure is a stated skipped-item line — never a crash, never a fabricated
-// item. The network-allowlist item is HAND-APPLY by design (bridge council 2026-07-11, both
-// backends concur): the kit never seeds sandbox.network.allowedDomains / filesystem.allowWrite.
+// 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).
 //
 // 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/
@@ -26,6 +30,8 @@
 // Dependency-free, Node >= 18. No side effects on import (the isDirectRun idiom).
 
 import { readFileSync, readdirSync, lstatSync } 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 {
@@ -60,24 +66,141 @@ export const RECOMMENDATIONS_EMPTY_LINE = 'no recommendations — flow optimal.'
 // The one dual-wording security clause — rides ONLY the items with a real security delta.
 export const DUAL_SECURITY_BENEFIT = 'safer — blast radius bounded by the OS sandbox, not human attention';
 
+// ── the verdict-first contract (D1, REC-UX-REWORK) ──────────────────────────────────────────────
+// The optimal state (no items, no skips) renders the frozen empty-state line ALONE — byte-identical
+// to the pre-verdict contract. Every other state opens the body with ONE verdict line composed from
+// these frozen templates ({X}-style placeholders; the "(s)" invariant form IS the pinned
+// pluralization rule — no singular/plural branching). The templates are English tool DATA
+// (doc-parity-bound in both mode docs); user-language rendering is the agent's presentation layer.
+export const VERDICT_ATTENTION_TEMPLATE = '{K} item(s) need attention';
+export const VERDICT_NOTHING_BROKEN = 'nothing is broken';
+export const VERDICT_OPTIONAL_TEMPLATE = '{N} optional recommendation(s), apply any you want';
+export const VERDICT_SKIPS_TEMPLATE = 'optimality NOT attested — {M} probe check(s) skipped';
+
+// ── the frozen severity registry (D1; pinned by tests) ─────────────────────────────────────────
+// `attention` — the item reports a CONFIGURED declaration that is broken, drifted, degrading or
+// invalid (the deployment needs review); `optional` — an offer to enable an unconfigured
+// capability. One class per key, frozen registry data; a `<key>.<variant>` entry classes a
+// per-site arm whose semantics differ from its base (the invalid-env arm reports an INVALID
+// configured value — attention — while the unset arm stays an offer).
+export const SEVERITY_ATTENTION = 'attention';
+export const SEVERITY_OPTIONAL = 'optional';
+export const SEVERITIES = Object.freeze({
+  'velocity-core': SEVERITY_OPTIONAL,
+  'kit-tools-tier': SEVERITY_OPTIONAL,
+  'bridge-tier': SEVERITY_OPTIONAL,
+  'autonomy-policy': SEVERITY_OPTIONAL,
+  'autonomy-render': SEVERITY_ATTENTION,
+  'sandbox-provision': SEVERITY_OPTIONAL,
+  'review-recipe': SEVERITY_ATTENTION,
+  'gates-declaration': SEVERITY_OPTIONAL,
+  'gate-hook': SEVERITY_OPTIONAL,
+  'family-freshness': SEVERITY_ATTENTION,
+  'sandbox-masks': SEVERITY_OPTIONAL,
+  'agy-adddir': SEVERITY_OPTIONAL,
+  'agy-adddir.invalid-env': SEVERITY_ATTENTION,
+  'sandbox-lane': SEVERITY_OPTIONAL,
+});
+// The per-item render tags (frozen presentation data, same language contract as the templates).
+export const SEVERITY_LABELS = Object.freeze({
+  [SEVERITY_ATTENTION]: 'needs attention',
+  [SEVERITY_OPTIONAL]: 'optional',
+});
+
+// {X}-style template fill (D1/D2): every placeholder must be supplied — a miss is a programming
+// error that surfaces through the probe's stated-skip lane, never a rendered "{K}".
+const fillTemplate = (template, values) => template.replace(/\{([A-Za-z]+)\}/g, (_, name) => {
+  if (!(name in values)) throw new Error(`unfilled template placeholder {${name}}`);
+  return String(values[name]);
+});
+
+// composeVerdict(counts) → the ONE verdict line, or null for the optimal state (D1 state matrix).
+// attention>0 leads; the "nothing is broken" wording renders ONLY when attention==0 AND skipped==0
+// (a skipped probe could hide an attention-class problem, so the claim would overreach; it renders
+// only as the lead-in to the optional offer, never in a skips-only state); the skips part is
+// appended last.
+export const composeVerdict = ({ attention, optional, skipped }) => {
+  if (attention === 0 && optional === 0 && skipped === 0) return null;
+  const parts = [];
+  if (attention > 0) parts.push(fillTemplate(VERDICT_ATTENTION_TEMPLATE, { K: attention }));
+  if (optional > 0) {
+    const offer = fillTemplate(VERDICT_OPTIONAL_TEMPLATE, { N: optional });
+    parts.push(attention === 0 && skipped === 0 ? `${VERDICT_NOTHING_BROKEN} — ${offer}` : offer);
+  }
+  if (skipped > 0) parts.push(fillTemplate(VERDICT_SKIPS_TEMPLATE, { M: skipped }));
+  return parts.join('; ');
+};
+
+// ── the frozen WHAT-template registry (D2; pinned by the static shape test) ─────────────────────
+// Every static WHAT template lives here — `<key>` is the item key, `<key>.<variant>` a per-site
+// variant of the same item — so ALL variants are assertable at build time (single line, char cap,
+// banned tokens), never a fixture-coverage gamble. A pure-placeholder template marks a WHAT whose
+// content is fully dynamic (capped at composition by truncation-with-count).
+export const WHATS = Object.freeze({
+  'velocity-core': 'routine read-only commands still prompt — {n} audited read-only allowlist entr(ies) not seeded',
+  'kit-tools-tier': "the kit's own read-only tools still prompt — {n} kit-tools tier entr(ies) not seeded",
+  'bridge-tier': 'council review runs prompt per bridge invocation — {n} bridge-wrappers tier entr(ies) not seeded (placed bridges only, code mode only)',
+  'autonomy-policy': 'no {path} — the computed defaults apply implicitly (red-lines ask/deny; every activity floors at prompt)',
+  'autonomy-render': 'the declared autonomy policy is not rendered into .claude/settings.json — drift: {drift}',
+  'sandbox-provision': 'the OS sandbox is unavailable: {reason}',
+  'sandbox-provision.installable': 'the OS sandbox is unavailable: {reason} — installable via the doctor (consent tuple {tuple})',
+  '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',
+  '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)',
+  'agy-adddir': 'agy-review is placed but AGY_REVIEW_ALLOW_ADDDIR is not set ({file}) — an oversized code review refuses instead of offloading',
+  'agy-adddir.invalid-env': 'AGY_REVIEW_ALLOW_ADDDIR is set to an INVALID value ({value}) — refuse-mode applies and the settings file is shadowed while it is set',
+  'sandbox-lane': 'the wired review wrappers declare a session-sandbox recipe (egress hosts + writable state dirs) not yet acknowledged for this project',
+});
+
+// ── the shape contract (D2): registry strings AND composed items stay one line under the cap ────
+export const ITEM_LINE_CAP = 140;
+export const SKIP_REASON_CAP = 200;
+
+const oneLineOf = (text) => String(text).replace(/\s*[\r\n]+\s*/g, ' ').trim();
+// Scalar truncation-with-count — a capped value states what it dropped, never a silent cut.
+// GUARANTEED result.length <= cap for every input/budget: when even the count note cannot fit
+// the budget, the tail arm hard-slices to a bare ellipsis instead of overflowing.
+const truncatedTo = (text, cap) => {
+  if (text.length <= cap) return text;
+  const note = (dropped) => `… (+${dropped} more chars)`;
+  let keep = cap;
+  while (keep > 0 && keep + note(text.length - keep).length > cap) keep -= 1;
+  if (keep === 0) return cap <= 0 ? '' : `${text.slice(0, cap - 1)}…`;
+  return text.slice(0, keep) + note(text.length - keep);
+};
+// List truncation-with-count: whole leading entries + " (+N more)" for the dropped tail; if even
+// the first entry overflows, it is scalar-truncated so the count survives.
+const capList = (entries, budget, sep = '; ') => {
+  for (let take = entries.length; take >= 1; take -= 1) {
+    const joined = entries.slice(0, take).join(sep);
+    const tail = take < entries.length ? ` (+${entries.length - take} more)` : '';
+    if (joined.length + tail.length <= budget) return joined + tail;
+  }
+  const tail = entries.length > 1 ? ` (+${entries.length - 1} more)` : '';
+  return truncatedTo(entries[0], Math.max(0, budget - tail.length)) + tail;
+};
+// The char budget a template leaves for its placeholder values.
+const templateBudget = (template) => ITEM_LINE_CAP - template.replace(/\{[A-Za-z]+\}/g, '').length;
+
 // ── the frozen benefit registry (fact-true; pinned by tests) ────────────────────────────────────
 export const BENEFITS = Object.freeze({
   'velocity-core': 'velocity — routine read-only commands stop prompting while the maintainer is away',
   'kit-tools-tier': "velocity — the kit's own read-only tools run promptless (audited, resolved-absolute tier)",
   'bridge-tier':
-    'velocity — unattended council review runs: the placed review wrappers’ code mode stops prompting (delegated execution and the plan/diff modes keep their prompt)',
+    'velocity — placed review wrappers run code-mode council reviews promptless (plan/diff modes and delegated execution keep their prompt)',
   'autonomy-policy': 'clarity — the per-activity autonomy policy becomes an explicit, versioned declaration instead of implicit computed defaults',
-  'autonomy-render': `velocity — the sandbox auto-allows confined commands per your declared policy; ${DUAL_SECURITY_BENEFIT}`,
-  'sandbox-provision': `velocity — confined ad-hoc commands stop prompting once the OS sandbox is available; ${DUAL_SECURITY_BENEFIT}`,
+  'autonomy-render': `velocity — confined commands auto-allow per your declared policy; ${DUAL_SECURITY_BENEFIT}`,
+  'sandbox-provision': `velocity — confined ad-hoc commands stop prompting; ${DUAL_SECURITY_BENEFIT}`,
   '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)',
   '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; CAVEAT: re-enables the Issue-001 stall risk (the hard timeout bounds it)',
-  'network-allowlist':
-    'unblocks the NETWORK half of in-sandbox bridge runs where the sandbox honors settings keys (settings-native harnesses; the network gate ONLY — no filesystem allowance is recommended); RISK stated plainly: pre-allows egress to these hosts for EVERY sandboxed command (informed hand-consent only). Live-observed 2026-07-12: an IDE-managed session sandbox ignores these settings keys too — there the durable lanes are the harness’s own per-host network consents / session sandbox config, or the per-run consented bypass; codex additionally needs a writable HOME (EROFS ~/.codex)',
+  'agy-adddir': 'large reviews — an oversized agy code review offloads to a staging dir instead of refusing',
+  'sandbox-lane': 'discoverability — the manifest-declared observed sandbox recipe for bridge runs surfaces itself instead of waiting to be asked',
 });
 
 // A typed usage failure (exit 2) — the codebase's typed-error idiom (no classes).
@@ -103,12 +226,12 @@ const probeVelocityItems = ({ root, deps, add, skip }) => {
   // above owns the real failure modes).
   const core = planVelocityProfile(preflight, {});
   if (core.toAdd.length > 0) {
-    add('velocity-core', `routine read-only commands still prompt — ${core.toAdd.length} audited read-only allowlist entr(ies) not seeded`, applyLine(''));
+    add('velocity-core', fillTemplate(WHATS['velocity-core'], { n: core.toAdd.length }), applyLine(''));
   }
   try {
     const kt = planVelocityProfile(preflight, { kitTools: true });
     if (kt.tierToAdd.length > 0) {
-      add('kit-tools-tier', `the kit's own read-only tools still prompt — ${kt.tierToAdd.length} kit-tools tier entr(ies) not seeded`, applyLine(' --kit-tools'));
+      add('kit-tools-tier', fillTemplate(WHATS['kit-tools-tier'], { n: kt.tierToAdd.length }), applyLine(' --kit-tools'));
     }
   } catch (err) {
     skip('kit-tools-tier', err);
@@ -117,7 +240,7 @@ const probeVelocityItems = ({ root, deps, add, skip }) => {
     const bt = planVelocityProfile(preflight, { bridgeTier: true, findWrapper: deps.findWrapper });
     const delta = bt.bridgeToAdd.length + bt.excludedToAdd.length;
     if (delta > 0) {
-      add('bridge-tier', `council review runs prompt per bridge invocation — ${delta} bridge-wrappers tier entr(ies) not seeded (placed bridges only, code mode only)`, applyLine(' --bridge-tier'));
+      add('bridge-tier', fillTemplate(WHATS['bridge-tier'], { n: delta }), applyLine(' --bridge-tier'));
     }
   } catch (err) {
     skip('bridge-tier', err);
@@ -134,7 +257,7 @@ const probeAutonomyItems = ({ root, deps, add, skip }) => {
     // declaration: its render check still runs below (codex, Segment B closing).
     if (source !== 'none' && isSparseSeedConfig(config)) return;
     if (source === 'none') {
-      add('autonomy-policy', `no ${AUTONOMY_REL} — the computed defaults apply implicitly (red-lines ask/deny; every activity floors at prompt)`, '/agent-workflow-kit set-autonomy (run IN the target project — the conversational writer previews, then writes its docs/ai/autonomy.json)');
+      add('autonomy-policy', fillTemplate(WHATS['autonomy-policy'], { path: AUTONOMY_REL }), '/agent-workflow-kit set-autonomy (run IN the target project — the conversational writer previews, then writes its docs/ai/autonomy.json)');
     }
   } catch (err) {
     skip('autonomy-policy', err);
@@ -144,7 +267,8 @@ const probeAutonomyItems = ({ root, deps, add, skip }) => {
   try {
     const check = checkAutonomyProfile({ cwd: root }, deps);
     if (!check.inSync) {
-      add('autonomy-render', `the declared autonomy policy is not rendered into .claude/settings.json — drift: ${check.drift[0]}${check.drift.length > 1 ? ` (+${check.drift.length - 1} more)` : ''}`, `node ${q(toolPath('velocity-profile.mjs'))} --autonomy --apply --cwd ${q(root)}`);
+      const drift = capList(check.drift, templateBudget(WHATS['autonomy-render']));
+      add('autonomy-render', fillTemplate(WHATS['autonomy-render'], { drift }), `node ${q(toolPath('velocity-profile.mjs'))} --autonomy --apply --cwd ${q(root)}`);
     }
   } catch (err) {
     skip('autonomy-render', err);
@@ -156,10 +280,11 @@ const probeSandboxProvision = ({ root, deps, add, skip }) => {
     const p = probeSandboxAvailability(deps);
     if (p.available) return;
     const plan = deriveDoctorPlan({ probeResult: p, env: deps.env ?? process.env, isExec: deps.isExecutable ?? isExecutableFile });
-    const installNote = plan.tuple ? ` — installable via the doctor (consent tuple ${plan.tuple})` : '';
+    const variant = plan.tuple ? 'sandbox-provision.installable' : 'sandbox-provision';
+    const reason = truncatedTo(oneLineOf(p.reason), templateBudget(WHATS[variant]) - (plan.tuple ? String(plan.tuple).length : 0));
     // The doctor reads process.cwd() (deployment-gated) and takes no --cwd flag — the one-liner
     // pins the target project via a cd prefix (codex R2, Segment B).
-    add('sandbox-provision', `the OS sandbox is unavailable: ${p.reason}${installNote}`, `cd ${q(root)} && node ${q(toolPath('autonomy-doctor.mjs'))}`);
+    add('sandbox-provision', fillTemplate(WHATS[variant], { reason, tuple: plan.tuple }), `cd ${q(root)} && node ${q(toolPath('autonomy-doctor.mjs'))}`);
   } catch (err) {
     skip('sandbox-provision', err);
   }
@@ -179,7 +304,7 @@ const probeReviewRecipe = ({ root, deps, add, skip }) => {
       }
     }
     if (degraded.length > 0) {
-      add('review-recipe', degraded.join('; '), '/agent-workflow-kit backends');
+      add('review-recipe', fillTemplate(WHATS['review-recipe'], { degraded: capList(degraded, templateBudget(WHATS['review-recipe'])) }), '/agent-workflow-kit backends');
     }
   } catch (err) {
     skip('review-recipe', err);
@@ -196,13 +321,13 @@ const probeGates = ({ root, deps, add, skip }) => {
     // scripts and writes only on an explicit yes) — never the runner.
     if (!sg.declarationPresent || sg.declaredGates === 0) {
       // The seeder writes ONLY with --apply and consent is per-entry (--only) — the apply field
-      // stays a PURE executable command (run-exactly-verbatim feeds it to the shell); the
+      // stays a PURE executable command (run-exactly-as-rendered feeds it to the shell); the
       // two-step preview semantics live in WHAT, never as prose appended to the command.
-      add('gates-declaration', 'no declared gate matrix (docs/ai/gates.json absent or empty) — gate commands run ad hoc and prompt one by one; the apply line is the PREVIEW (writes nothing) — it prints the exact consent-gated --apply [--only <id>] line to run next', `node ${q(toolPath('seed-gates.mjs'))} --cwd ${q(root)}`);
+      add('gates-declaration', fillTemplate(WHATS['gates-declaration'], {}), `node ${q(toolPath('seed-gates.mjs'))} --cwd ${q(root)}`);
       return;
     }
     if (sg.declaredGates > 0 && !sg.wired) {
-      add('gate-hook', `${sg.declaredGates} declared gate(s) prompt per run — the gate-approval hook is not wired`, `node ${q(toolPath('gate-hook.mjs'))} --apply --cwd ${q(root)}`);
+      add('gate-hook', fillTemplate(WHATS['gate-hook'], { n: sg.declaredGates }), `node ${q(toolPath('gate-hook.mjs'))} --apply --cwd ${q(root)}`);
     }
   } catch (err) {
     skip('gate-hook', err);
@@ -228,7 +353,7 @@ const probeFamilyFreshness = ({ deps, add, skip }) => {
       // ALL caveats per row — a memory missing BOTH templates must not drop the second (codex).
       ...caveated.map((r) => `${r.name}: ${r.caveats.join('; ')}`),
     ];
-    add('family-freshness', parts.join('; '), 'npx @sabaiway/agent-workflow-kit@latest init');
+    add('family-freshness', fillTemplate(WHATS['family-freshness'], { parts: capList(parts, templateBudget(WHATS['family-freshness'])) }), 'npx @sabaiway/agent-workflow-kit@latest init');
   } catch (err) {
     skip('family-freshness', err);
   }
@@ -239,11 +364,11 @@ const probeMasksItem = ({ root, deps, add, skip }) => {
     const p = probeSandboxMasks({ cwd: root, ...deps });
     if (p == null) return; // not a git work tree — the lane is N/A, not sub-optimal
     if (!needsMasksApply(p)) return;
-    const stale = p.staleReal.length ? `; ${p.staleReal.length} fenced entr(ies) became REAL paths (a fresh apply drops them by construction)` : '';
+    const variant = p.staleReal.length > 0 ? 'sandbox-masks.stale-real' : 'sandbox-masks';
     // A stale-real-only fence (EMPTY derivation over a non-empty block) makes the plain --apply
     // REFUSE — the exact one-liner must carry --clear there (codex R1, Segment B).
     const apply = p.masks.length === 0 && p.staleReal.length > 0 ? `${p.applyCmd} --clear` : p.applyCmd;
-    add('sandbox-masks', `${p.masks.length} sandbox device mask(s) clutter git status — the managed exclude block is absent or stale${stale}`, apply);
+    add('sandbox-masks', fillTemplate(WHATS[variant], { n: p.masks.length, m: p.staleReal.length }), apply);
   } catch (err) {
     skip('sandbox-masks', err);
   }
@@ -265,7 +390,8 @@ const probeAgyAdddir = ({ deps, add, skip }) => {
       if (env.AGY_REVIEW_ALLOW_ADDDIR === '') return;
       // env > file: while ANY env value is set the wrapper ignores the settings file, so the file
       // writer cannot fix an invalid env — the honest apply is to fix/unset the env var (codex).
-      add('agy-adddir', `AGY_REVIEW_ALLOW_ADDDIR is set to an INVALID value (${JSON.stringify(env.AGY_REVIEW_ALLOW_ADDDIR)}) — the wrapper falls back to refuse-mode and the settings file is shadowed while the env var is set`, 'HAND-APPLY: unset AGY_REVIEW_ALLOW_ADDDIR in the environment (or export it as 1), THEN configure it durably via the bridge-settings writer');
+      const value = truncatedTo(oneLineOf(JSON.stringify(env.AGY_REVIEW_ALLOW_ADDDIR)), templateBudget(WHATS['agy-adddir.invalid-env']));
+      add('agy-adddir', fillTemplate(WHATS['agy-adddir.invalid-env'], { value }), 'HAND-APPLY: unset AGY_REVIEW_ALLOW_ADDDIR in the environment (or export it as 1), THEN configure it durably via the bridge-settings writer', 'agy-adddir.invalid-env');
       return;
     }
     const confPath = settingsPath({ getenv: env, home: deps.home });
@@ -285,7 +411,7 @@ const probeAgyAdddir = ({ deps, add, skip }) => {
     // The settings writer REFUSES a duplicate-carrying file — rendering its command would hand
     // the user a guaranteed failure; the honest apply is fix-duplicates-first (codex terminal).
     const dups = duplicateKeys(parsed);
-    const what = `agy-review is placed but AGY_REVIEW_ALLOW_ADDDIR is not set (${SETTINGS_FILENAME}) — an oversized code review refuses instead of offloading`;
+    const what = fillTemplate(WHATS['agy-adddir'], { file: SETTINGS_FILENAME });
     if (dups.length > 0) {
       add('agy-adddir', what, `HAND-APPLY: ${SETTINGS_FILENAME} carries duplicate key(s) (${dups.join(', ')}) and the settings writer refuses to edit it — remove the duplicate lines by hand, THEN run: node ${q(toolPath('bridge-settings.mjs'))} --set AGY_REVIEW_ALLOW_ADDDIR=1 --apply`);
       return;
@@ -296,16 +422,18 @@ const probeAgyAdddir = ({ deps, add, skip }) => {
   }
 };
 
-// networkHosts of every BUNDLED bridge whose review wrapper is in the placed set — derived from the
-// manifests (the single documentation source), never a hardcoded host list here.
-const bundledNetworkHosts = (placedWrappers, deps) => {
+// The manifest-declared session-sandbox recipe surfaces of every BUNDLED bridge whose review
+// wrapper is in the wired set — networkHosts ∪ writableDirs, derived from the manifests (the
+// single documentation source), never hardcoded here.
+const bundledSandboxRecipe = (placedWrappers, deps) => {
   const readFile = deps.readFile ?? readFileSync;
   const readDir = deps.readdir ?? readdirSync;
   const bundleRoot = deps.bundleRoot ?? DEFAULT_BUNDLE_ROOT;
   const hosts = [];
+  const dirEntries = [];
   for (const dir of readDir(bundleRoot)) {
-    // An unreadable/unparsable bundled manifest must NOT thin the paste list silently — a partial
-    // allowlist pasted as complete is worse than no item. The throw reaches the probe's catch and
+    // An unreadable/unparsable bundled manifest must NOT thin the recipe silently — a partial
+    // recipe rendered as complete is worse than no item. The throw reaches the probe's catch and
     // becomes a stated skip.
     let manifest;
     try {
@@ -316,14 +444,58 @@ const bundledNetworkHosts = (placedWrappers, deps) => {
       throw new Error(`bundled manifest unreadable: ${join(dir, 'capability.json')} — ${err?.message ?? err}`);
     }
     const reviewCmd = manifest?.roles?.review?.cmd;
-    if (reviewCmd && placedWrappers.includes(reviewCmd) && Array.isArray(manifest.networkHosts)) {
+    if (!reviewCmd || !placedWrappers.includes(reviewCmd)) continue;
+    if (Array.isArray(manifest.networkHosts)) {
       for (const h of manifest.networkHosts) if (!hosts.includes(h)) hosts.push(h);
     }
+    if (Array.isArray(manifest.writableDirs)) dirEntries.push(...manifest.writableDirs);
   }
-  return hosts;
+  return { hosts, dirEntries };
+};
+
+// D6 resolution, mirroring the wrappers' byte-semantics (`${VAR:-default}` + the exact case-arms:
+// `~` / `~/…` / `/…` ride as-given; EVERY other form — including `~user/…`, which the wrappers
+// never resolve as a home path — anchors like a relative path). The advisor anchors to the TARGET
+// PROJECT ROOT (the pinned --cwd), matching what a wrapper invoked from the project root resolves
+// (the documented dispatch form; the wrapper itself anchors to its invocation $PWD).
+const resolveWritableDir = (entry, { env, root }) => {
+  const value = entry.env == null ? '' : (env[entry.env] ?? '');
+  if (value === '') return entry.default;
+  if (value === '~' || value.startsWith('~/') || value.startsWith('/')) return value;
+  return resolve(root, value);
 };
 
-const probeNetworkAllowlist = ({ root, deps, add, skip }) => {
+// The NEUTRAL recipe fingerprint (D4): a hash over the resolved hosts ∪ dirs data — an
+// acknowledgement token, never a security key. Canonical form is HOME-SYMBOLIC: an
+// absolute dir under the resolved home canonicalizes BACK to its `~/…` form and tilde forms stay
+// symbolic — so `~/.codex` and its absolute expansion acknowledge the SAME recipe AND the default
+// recipe's fingerprint is identical across machines/users (a committed project-scope ack never
+// churns between them); only a genuinely-outside-home absolute override stays absolute
+// (machine-specific by nature). Any change to the recipe re-fires the item.
+export const recipeFingerprint = ({ hosts, dirs, home }) => {
+  const homeAbs = resolve(home);
+  const norm = (d) => {
+    if (d === '~') return '~';
+    if (d.startsWith('~/')) return `~/${d.slice(2)}`;
+    const abs = resolve(d);
+    if (abs === homeAbs) return '~';
+    return abs.startsWith(`${homeAbs}/`) ? `~/${abs.slice(homeAbs.length + 1)}` : abs;
+  };
+  const canonical = JSON.stringify({ hosts: [...hosts].sort(), dirs: [...new Set(dirs.map(norm))].sort() });
+  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.
+export const SANDBOX_LANE_ACK_PARENT = 'agentWorkflow';
+export const SANDBOX_LANE_ACK_KEY = 'sandboxLaneAck';
+
+// 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']);
+
+const probeSandboxLane = ({ root, deps, add, skip }) => {
   try {
     const settings = readSettingsFile(join(root, SETTINGS_FILE), { ...deps, cwd: root });
     const localSettings = readSettingsFile(join(root, SETTINGS_LOCAL_FILE), { ...deps, cwd: root });
@@ -331,8 +503,8 @@ const probeNetworkAllowlist = ({ root, deps, add, skip }) => {
     const excluded = Array.isArray(sandbox?.excludedCommands) ? sandbox.excludedCommands : [];
     const probePlaced = deps.findWrapper ?? ((cmd) => findOnPath(cmd, deps).state === 'present');
     // Wired = the FULL two-surface tier proof (excludedCommands + the code-mode allow rule, either
-    // scope) — surfacing the risky egress hand-apply while the tier is half-configured would
-    // front-run the bridge-tier item (codex terminal). Byte-form from the tier's own constants.
+    // scope) — surfacing the recipe while the tier is half-configured would front-run the
+    // bridge-tier item (codex terminal). Byte-form from the tier's own constants.
     const allowRules = [
       ...(Array.isArray(settings.data?.permissions?.allow) ? settings.data.permissions.allow : []),
       ...(Array.isArray(localSettings.data?.permissions?.allow) ? localSettings.data.permissions.allow : []),
@@ -341,27 +513,26 @@ const probeNetworkAllowlist = ({ root, deps, add, skip }) => {
       (w) => excluded.includes(w) && probePlaced(w) && allowRules.includes(`Bash(${w} ${BRIDGE_REVIEW_MODE}:*)`),
     );
     if (wired.length === 0) return; // the tier is not (fully) wired — the bridge-tier item covers first
-    // Convergence (codex R3): a hand-applied list must silence the item — compare the LIVE
-    // allowedDomains (project + local scope) against the manifests and render only what is missing.
-    const projectApplied = Array.isArray(sandbox?.network?.allowedDomains) ? sandbox.network.allowedDomains : [];
-    const localApplied = Array.isArray(localSettings.data?.sandbox?.network?.allowedDomains) ? localSettings.data.sandbox.network.allowedDomains : [];
-    // Local scope counts toward COVERAGE only — the paste targets the COMMITTED project file, so a
-    // local-only allowance must never be widened to the whole project (codex terminal).
-    const applied = [...projectApplied, ...localApplied];
-    const manifestHosts = bundledNetworkHosts(wired, deps);
-    const missing = manifestHosts.filter((h) => !applied.includes(h));
-    if (missing.length === 0 && applied.length > 0) return; // every manifest host is already hand-applied
-    // The pasted value is the FULL desired final list for the PROJECT scope (project ∪ missing) —
-    // a missing-only snippet pasted verbatim would DROP the already-applied domains and oscillate.
-    const finalList = [...projectApplied, ...missing];
-    const hostsJson = finalList.map((h) => JSON.stringify(h)).join(', ');
+    const { hosts, dirEntries } = bundledSandboxRecipe(wired, deps);
+    const env = deps.getenv ?? process.env;
+    const home = deps.home ?? homedir();
+    const dirs = [];
+    for (const entry of dirEntries) {
+      const resolved = resolveWritableDir(entry, { env, root });
+      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]];
+    if (acks.includes(fingerprint)) return; // the acknowledged recipe — the item converged
     add(
-      'network-allowlist',
-      'IF plain wrapper runs still hit sandbox network prompts, this session’s sandbox is HARNESS-MANAGED — settings-level exclusions are inert there (live-observed 2026-07-11)',
-      `HAND-APPLY (the kit never writes this): in .claude/settings.json set the key sandbox.network.allowedDomains to [${hostsJson}] — a MERGE into the existing sandbox object (keep excludedCommands and every other sandbox key); hosts from the bridges' capability.json networkHosts (observed-minimal; a blocked host names itself at run time)`,
+      '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)`,
     );
   } catch (err) {
-    skip('network-allowlist', err);
+    skip('sandbox-lane', err);
   }
 };
 
@@ -375,31 +546,58 @@ const PROBES = Object.freeze([
   probeFamilyFreshness,
   probeMasksItem,
   probeAgyAdddir,
-  probeNetworkAllowlist,
+  probeSandboxLane,
 ]);
 
 export const buildRecommendations = ({ cwd, deps = {} } = {}) => {
   const root = resolve(cwd);
   const items = [];
   const skips = [];
-  const add = (key, what, apply) => items.push({ key, what, benefit: BENEFITS[key], apply });
-  const skip = (key, err) => skips.push({ key, reason: err?.message ?? String(err) });
-  for (const probe of PROBES) probe({ root, deps, add, skip });
+  // Skip reasons ride arbitrary Error.messages — normalized to ONE line and length-capped so a
+  // multiline or oversized message can never rebuild a prose wall (D2).
+  const skip = (key, err) => skips.push({ key, reason: truncatedTo(oneLineOf(err?.message ?? String(err)), SKIP_REASON_CAP) });
+  // The runtime shape backstop (D2): every COMPOSED item is validated at construction — a
+  // 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) => {
+    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 (problems.length > 0) {
+      skip(key, new Error(`item shape violation — ${problems.join('; ')}`));
+      return;
+    }
+    items.push({ key, severity: SEVERITIES[severityKey], what, benefit: BENEFITS[key], apply });
+  };
+  for (const probe of deps.probes ?? PROBES) probe({ root, deps, add, skip });
   return { root, items, skips };
 };
 
-// ── rendering (the agent pastes this section VERBATIM) ──────────────────────────────────────────
+// ── rendering (English tool DATA — the agent presents it in the user's conversational language,
+// facts/counts complete, commands byte-exact; the raw block on request) ─────────────────────────
 export const formatRecommendations = ({ items, skips }) => {
   const lines = [RECOMMENDATIONS_SECTION_HEADER, ''];
-  if (items.length === 0 && skips.length === 0) {
+  const attention = items.filter((i) => i.severity === SEVERITY_ATTENTION).length;
+  const verdict = composeVerdict({ attention, optional: items.length - attention, skipped: skips.length });
+  if (verdict == null) {
     // The flow-optimal claim renders ONLY when every probe ran and none fired — an empty item
     // list beside skipped checks would falsely attest optimality (codex R1, Segment B).
     lines.push(RECOMMENDATIONS_EMPTY_LINE);
-  } else if (items.length === 0) {
-    lines.push(`no applicable items, but ${skips.length} probe check(s) were skipped — the flow is NOT attested optimal:`);
-  } else {
-    items.forEach((item, i) => {
-      lines.push(`${i + 1}. ${item.what}`);
+    return lines.join('\n');
+  }
+  lines.push(verdict);
+  if (items.length > 0) {
+    lines.push('');
+    // Attention items lead (stable within each class — the frozen probe order).
+    const ordered = [...items].sort(
+      (a, b) => (a.severity === SEVERITY_ATTENTION ? 0 : 1) - (b.severity === SEVERITY_ATTENTION ? 0 : 1),
+    );
+    ordered.forEach((item, i) => {
+      lines.push(`${i + 1}. ${SEVERITY_LABELS[item.severity] ?? SEVERITY_LABELS[SEVERITY_OPTIONAL]}: ${item.what}`);
       lines.push(`   benefit: ${item.benefit}`);
       lines.push(`   apply: ${item.apply}`);
     });
@@ -415,15 +613,17 @@ const HELP = `recommendations — the read-only upgrade Recommendations advisor
 Usage:
   node recommendations.mjs --cwd <project-root> [--json]
 
-Computes the deterministic Recommendations section every kit upgrade ends with: what is
-sub-optimal in THIS deployment · the benefit in one plain line · 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 network-allowlist item is HAND-APPLY by design — this tool and
-the kit writers never seed sandbox network/filesystem allowances.
+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
+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.
 
 Read-only: never writes, never commits, never runs a subscription CLI. Exit codes: 0 report
 rendered (items or empty); 1 error; 2 usage.`;