@khoavu882/doflow 2.0.0-beta.5 → 2.0.0

package/src/runtime/advice/shadow-dispatcher.js

@@ -0,0 +1,276 @@
+'use strict';
+
+const { resolveShadowConfig } = require('./shadow-config.js');
+const { applyElevationInvariant } = require('./elevation.js');
+const { evaluateBenchBar } = require('./bench-gate.js');
+const { appendPick, appendMiss, newPickId } = require('./record.js');
+const { createAdviceClient } = require('./client.js');
+const { loadAdviceRegistry } = require('./registry.js');
+const { loadStorageRegistry } = require('../storage/registry.js');
+const { resolveRoots } = require('../storage/roots.js');
+const { profileAdvisorCap, capMode } = require('./mode.js');
+const { REPO_ROOT } = require('../../helper/repo-root.js');
+
+/** The advice registry's kinds (core/registry/advice.json). */
+                                                                                                          
+                                           
+                                              
+                                                
+
+                       
+                
+                                                                             
+ 
+
+                        
+                
+                
+                 
+                           
+ 
+
+/** The advice client's reply (client.ts ask). */
+                        
+                  
+                         
+                           
+                        
+                           
+ 
+
+                      
+                            
+                   
+                              
+                 
+                        
+                
+                 
+                                                                   
+                                         
+ 
+
+                        
+                                                  
+ 
+
+                            
+               
+                   
+                       
+ 
+
+                          
+                  
+                  
+ 
+
+                                                                                               
+
+                              
+                              
+                                                                                     
+                                  
+               
+                        
+                     
+ 
+
+                                
+                   
+                 
+                
+                     
+                         
+                       
+            
+                                                                                                                              
+                            
+                                                                    
+                               
+                                                                          
+                   
+ 
+
+                                   
+                   
+                            
+                   
+                     
+                             
+                                                                   
+                        
+                    
+                         
+                   
+ 
+
+/** One advisor call: the pick, or the reason there is none. `off` means the advice setting is off: nothing is recorded. */
+                       
+                                      
+                      
+                                                           
+                        
+                          
+                       
+                     
+ 
+
+/** The budget of one advisor call: the registry's timeoutMs (core/registry/advice.json), 0 (no call) when unknown. */
+function budgetMs(context                      )         {
+  const own = context.adviceRegistry?.timeoutMs;
+  if (typeof own === 'number' && Number.isFinite(own) && own > 0) return own;
+  try {
+    const loaded = loadAdviceRegistry({ repoRoot: REPO_ROOT });
+    const shipped = loaded.ok ? loaded.registry.timeoutMs : null;
+    return typeof shipped === 'number' && Number.isFinite(shipped) && shipped > 0 ? shipped : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Asks the advisor with `model` (the one effective model; the client's own setting when null), bounded by `budget`.
+ * When the budget ends the call's signal is aborted, so the client drops its request, socket and timer; the bound's own
+ * timer is unref'd, so neither it nor a client that ignores the signal holds the process open. The client is asked
+ * not to record: the dispatcher records the call itself.
+ */
+async function askAdvisor(context                      , services                    , model               , budget        )                       {
+  const startedAt = Date.now();
+  const call = (status                       , reason               , res                      )              => ({
+    status, pick: null, answer: null, reason, provider: res?.provider ?? null, model: res?.model ?? model, durationMs: Date.now() - startedAt,
+  });
+  let timer                                           ;
+  const controller = new AbortController();
+  try {
+    const client               = services.adviceClient || createAdviceClient({
+      adviceRegistry: context.adviceRegistry,
+      roots: services.roots,
+      fsImpl: services.fsImpl,
+    });
+    const options             = {
+      questionSet: context.questionSet,
+      kind: context.kind,
+      staticAnswer: context.staticAnswer ?? context.staticPick,
+      caller: context.caller,
+      taskId: context.taskId ?? null,
+      record: false,
+      signal: controller.signal,
+    };
+    if (model) options.model = model;
+    const timeout = new Promise           ((resolve) => {
+      timer = setTimeout(() => { controller.abort(); resolve('timeout'); }, budget);
+      timer.unref?.();
+    });
+    const res = await Promise.race([client.ask(options), timeout]);
+    if (res === 'timeout') return call('miss', 'timeout');
+    if (res?.status === 'off') return call('off', res.reason ?? null, res);
+    if (res?.status !== 'answered') return call('miss', typeof res?.reason === 'string' && res.reason ? res.reason : 'unavailable', res);
+    const first = res.answers?.[0];
+    if (typeof first?.pick !== 'string' || !first.pick) return call('miss', 'malformed-reply', res);
+    const asked = call('answered', null, res);
+    // The answer carries the model that was asked, so a caller can report it.
+    return { ...asked, pick: first.pick, answer: { ...first, model: asked.model } };
+  } catch {
+    return call('miss', 'config-invalid');
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function storeRoots(context                      , services                    )                    {
+  if (services.roots) return services.roots;
+  try {
+    return resolveRoots({ registry: loadStorageRegistry({ repoRoot: REPO_ROOT }), projectRoot: context.projectRoot, env: context.env });
+  } catch {
+    return null;
+  }
+}
+
+/** Records one advisor call through record.ts: a pick line when there is a pick, a miss line with its reason otherwise. */
+function recordCall(context                      , services                    , mode                  , asked             , pickId        , elevated         )       {
+  if (context.record === false || asked.status === 'off') return;
+  const roots = storeRoots(context, services);
+  if (!roots) return;
+  const common = { roots, fsImpl: services.fsImpl, kind: context.kind, caller: context.caller, model: asked.model, durationMs: asked.durationMs, mode };
+  if (asked.status === 'answered') {
+    appendPick({
+      ...common,
+      pickId,
+      elevated,
+      answer: asked.answer,
+      question: context.questionSet?.questions?.[0],
+      staticAnswer: context.staticAnswer ?? context.staticPick,
+      provider: asked.provider,
+      state: context.questionSet?.state ?? context.state,
+      taskId: context.taskId ?? null,
+    });
+  } else {
+    appendMiss({ ...common, reason: asked.reason });
+  }
+}
+
+async function interceptDecisionPoint(context                      , services                     = {})                                   {
+  const config                   = services.shadowConfig || resolveShadowConfig(context.kind, {
+    projectRoot: context.projectRoot,
+    env: context.env,
+    fsImpl: services.fsImpl,
+    roots: services.roots,
+  });
+
+  // A chosen rollout profile caps the configured mode (mode.ts; `staged` caps act to shadow, D2).
+  const mode             = capMode(profileAdvisorCap({ projectRoot: context.projectRoot, env: context.env, fsImpl: services.fsImpl }), config.mode);
+  const staticPick = context.staticPick;
+  const unchanged = { kind: context.kind, effectiveDecision: staticPick, staticPick, advisorPick: null, elevated: false, agreed: null };
+
+  // Off: no model call, no record.
+  if (mode !== 'act' && mode !== 'shadow') return { ...unchanged, mode: 'off', pickId: null };
+
+  // The one effective model: the bar is checked for it, the client is asked with it, and the record names it.
+  const model = config.model;
+  const budget = budgetMs(context);
+  const pickId = newPickId();
+
+  // Shadow: return the static pick now; the detached call records its pick or miss. With record:false nothing could be
+  // kept, so no call is made.
+  const shadow = (warning         )                          => {
+    if (context.record !== false) {
+      askAdvisor(context, services, model, budget)
+        .then((asked) => recordCall(context, services, 'shadow', asked, pickId, false))
+        .catch(() => {});
+    }
+    return { ...unchanged, mode: 'shadow', pickId, ...(warning ? { warning } : {}) };
+  };
+  if (mode === 'shadow') return shadow();
+
+  // Act: only past the bench bar for the model that will be asked; otherwise it degrades to shadow.
+  let bar                 = { passed: false, reason: `no model is named for kind '${context.kind}'` };
+  if (model) {
+    try {
+      bar = await (services.benchGate || evaluateBenchBar)(context.kind, model);
+    } catch (error     ) {
+      bar = { passed: false, reason: `bench gate failed: ${error?.message || 'unknown error'}` };
+    }
+  }
+  if (bar?.passed !== true) return shadow(`BENCH_BAR_UNMET: ${bar?.reason || 'Accuracy failed static baseline'}`);
+
+  const asked = await askAdvisor(context, services, model, budget);
+  const { effectiveDecision, elevated } = applyElevationInvariant(context.kind, staticPick, asked.pick);
+  recordCall(context, services, 'act', asked, pickId, elevated);
+
+  return {
+    kind: context.kind,
+    effectiveDecision,
+    mode: 'act',
+    staticPick,
+    advisorPick: asked.pick,
+    advisorAnswer: asked.answer,
+    pickId,
+    elevated,
+    agreed: asked.pick !== null ? asked.pick === staticPick : null,
+  };
+}
+
+module.exports = {
+  interceptDecisionPoint,
+};

package/src/runtime/brief-rules.js

@@ -0,0 +1,81 @@
+'use strict';
+
+// The must-carry rules of a worker brief (135 item 3). Run directly by Node native type-stripping:
+//
+//   node src/runtime/brief-rules.js --write   rewrite the mustCarry key of core/registry/rules.json
+//   node src/runtime/brief-rules.js --check   exit 0 equal, 1 differs, 2 usage
+//
+// RULES.md lines ending in the must-carry marker are copied into the `mustCarry` key of the rule
+// ledger, because an installed runtime ships `core/registry/` but not `core/shared/`. The key is
+// generated, never edited by hand; only it is rewritten, the rest of the file stays byte-identical.
+// G78 fails when it differs from RULES.md.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { REPO_ROOT } = require('../helper/repo-root.js');
+
+const SOURCE_REL = 'core/shared/guidance/rules/RULES.md';
+const TARGET_REL = 'core/registry/rules.json';
+const MARKER = ' <!-- must-carry -->';
+const MIN_LINES = 3;
+const MAX_LINES = 5;
+
+/** The marked lines of `text`, marker and leading `- ` removed, in file order. */
+function mustCarryLines(text        )           {
+  return text.split('\n')
+    .filter((line) => line.endsWith(MARKER))
+    .map((line) => line.slice(0, -MARKER.length).replace(/^- /, ''));
+}
+
+/** The ledger text with its `mustCarry` key set from `text`; throws when the marker count is out of range. */
+function compileBriefRules(text        , ledgerText        )         {
+  const lines = mustCarryLines(text);
+  if (lines.length < MIN_LINES || lines.length > MAX_LINES) {
+    throw new Error(`${SOURCE_REL} has ${lines.length} must-carry lines; expected ${MIN_LINES} to ${MAX_LINES}`);
+  }
+  const ledger = JSON.parse(ledgerText);
+  delete ledger.mustCarry;
+  delete ledger.mustCarryNote;
+  ledger.mustCarry = lines;
+  ledger.mustCarryNote = `Generated from the ${MARKER.trim()} lines of ${SOURCE_REL} by src/runtime/brief-rules.js --write; never edit by hand`;
+  return `${JSON.stringify(ledger, null, 2)}\n`;
+}
+
+/** The committed lines under `root`, or the reason they cannot be read; never throws. */
+function loadBriefRules(root        )                                           {
+  try {
+    const data = JSON.parse(fs.readFileSync(path.join(root, TARGET_REL), 'utf8'));
+    if (!Array.isArray(data.mustCarry) || data.mustCarry.some((line         ) => typeof line !== 'string')) return { reason: `${TARGET_REL} has no mustCarry array` };
+    return { lines: data.mustCarry };
+  } catch (err     ) {
+    return { reason: err.code === 'ENOENT' ? `${TARGET_REL} is missing` : `${TARGET_REL} is unreadable` };
+  }
+}
+
+const USAGE = 'usage: node src/runtime/brief-rules.js --write|--check\n';
+
+/** The CLI: 0 written or equal, 1 the committed file differs, 2 usage. */
+function main(argv          , root         = REPO_ROOT)         {
+  if (argv.length !== 1 || (argv[0] !== '--write' && argv[0] !== '--check')) {
+    process.stderr.write(USAGE);
+    return 2;
+  }
+  const target = path.join(root, TARGET_REL);
+  const expected = compileBriefRules(fs.readFileSync(path.join(root, SOURCE_REL), 'utf8'), fs.readFileSync(target, 'utf8'));
+  if (argv[0] === '--write') {
+    fs.writeFileSync(target, expected);
+    return 0;
+  }
+  if (fs.readFileSync(target, 'utf8') === expected) return 0;
+  process.stderr.write(`brief-rules: ${TARGET_REL} mustCarry is stale; run node src/runtime/brief-rules.js --write\n`);
+  return 1;
+}
+
+module.exports = { SOURCE_REL, TARGET_REL, MARKER, mustCarryLines, compileBriefRules, loadBriefRules, main };
+
+if (require.main === module) {
+  try { process.exitCode = main(process.argv.slice(2)); } catch (err     ) {
+    process.stderr.write(`brief-rules: ${err.message}\n`);
+    process.exitCode = 1;
+  }
+}

package/src/runtime/brief-tools.js

@@ -17,6 +17,8 @@ const { loadRegistry } = require('../registry/index.js');
 const { CapabilityRouter } = require('./capability-router.js');
 const { probeProviders, HEALTHY, UNVERIFIED } = require('./health.js');
 const { mcpReach } = require('./mcp-reach.js');
+const { touchesManifest } = require('./mcp-consultations.js');
+const { loadBriefRules } = require('./brief-rules.js');
 const { WorkflowOrchestrator } = require('./workflow-orchestrator.js');
 const { resolveActiveFeature } = require('./feature-resolve.js');
 const { finishRuntime, usageError, captureCaught } = require('./cli-result.js');
@@ -28,7 +30,9 @@ const { resolveRoots } = require('./storage/roots.js');
 const { resolveSetting } = require('./advice/config.js');
 const { materializeKind } = require('./advice/kinds.js');
 const { createAdviceClient } = require('./advice/client.js');
+const { resolveShadowConfig } = require('./advice/shadow-config.js');
 const { strengthWords } = require('./advice/strength.js');
+const { resolveTier } = require('./worker/models.js');
 
 const SCHEMA = 1;
 const REACHABLE = new Set(['selected', 'configured']);
@@ -49,13 +53,20 @@ function hasServer(reach     , harnessId     , server     ) {
   return harnessId ? REACHABLE.has(stateOn(reach, harnessId, server)) : reach.harnesses.some((row     ) => REACHABLE.has(row.servers[server]));
 }
 
-/** The target harness: a registry id named by the caller, else the one harness installed at the
- * project scope (the global scope when the project has none), else none. */
-function chooseTarget({ registry, reach, harness, missing }     ) {
+/** IC-017: the resolved primary harness when it is a registry id and its state permits targeting. */
+function primaryHarnessOf(primary     , registry     ) {
+  if (!primary || ['unknown', 'refused', 'not-primary'].includes(primary.state)) return null;
+  return registry.harnesses.some((item     ) => item.id === primary.harness) ? primary.harness : null;
+}
+
+/** The target harness: a registry id named by the caller, else the resolved primary, else the one
+ * harness installed at the project scope (the global scope when the project has none), else none. */
+function chooseTarget({ registry, reach, harness, primaryHarness, missing }     ) {
   if (harness) {
     if (registry.harnesses.some((item     ) => item.id === harness)) return harness;
     missing.push(`harness '${harness}' is not a registry harness; ignored`);
   }
+  if (primaryHarness) return primaryHarness;
   const rows = reach?.harnesses || [];
   for (const scope of ['project', 'global']) {
     const ids = [...new Set(rows.filter((row     ) => row.scope === scope).map((row     ) => row.id))];
@@ -64,22 +75,6 @@ function chooseTarget({ registry, reach, harness, missing }     ) {
   return null;
 }
 
-/** Tier for a dispatch: the task line's tier when valid, else the owner's, else the default (IC-004).
- * A registry without `dispatchTiers` (the key is optional) gives `standard` with a note. */
-function resolveTier({ dispatchTiers, owner, tier, missing }     ) {
-  if (!dispatchTiers) {
-    missing.push('models.json has no dispatchTiers; tier standard assumed');
-    return { tier: 'standard', source: 'default', note: 'models.json has no dispatchTiers' };
-  }
-  if (tier !== undefined && tier !== null && tier !== '') {
-    if (dispatchTiers.tiers.includes(tier)) return { tier, source: 'task' };
-    missing.push(`tier '${tier}' is not in dispatchTiers.tiers; ignored`);
-  }
-  if (Object.hasOwn(dispatchTiers.byOwner, owner)) return { tier: dispatchTiers.byOwner[owner], source: 'owner' };
-  missing.push(`owner '${owner}' has no tier in models.json dispatchTiers`);
-  return { tier: dispatchTiers.default, source: 'default' };
-}
-
 /** The first provider of a capability whose probe status is `status`, in registry order, or null. */
 function firstWith(router     , capabilityId     , probes     , status     ) {
   return (router.capabilities[capabilityId]?.providers || []).find((provider     ) => probes[provider.id]?.status === status) || null;
@@ -102,6 +97,9 @@ function resolveRoute(router     , route     , probes     ) {
 }
 
 const cell = (text     ) => String(text).replace(/\|/g, '\\|').replace(/\s+/g, ' ');
+// The hand-back status ids, in the order of core/registry/workflows.json agents.handback.statuses;
+// G76 holds this text, the fallback in do-task-brief.sh and every spec/TOML status line to that list.
+const HANDBACK_IDS = ['done', 'done-with-concerns', 'needs-context', 'blocked'];
 const trigger = (server     ) => server.trigger.replace(/\.$/, '');
 
 /**
@@ -113,16 +111,34 @@ const trigger = (server     ) => server.trigger.replace(/\.$/, '');
  * @param {string} input.owner
  * @param {string} [input.tier] the task line's tier
  * @param {string} [input.harness] target harness id
+ * @param {Object} [input.primary] resolved primary result (IC-017)
+ * @param {Object} [input.bindings] workers.models bindings result (IC-017)
  * @param {2|3} [input.headingLevel]
+ * @param {string} [input.repoRoot] where `core/registry/rules.json` is read from
  * @param {{feature:?string, runTaskId:?string, stageId:?string, skill:?string}|null} [input.stage]
- * @returns {{markdown: string, record: Object}} the record is IC-018 without `tasks`
+ * @returns {{markdown: string, record: Object}} the IC-018 record, including model (IC-017), without `tasks`
  */
-function renderBriefTools({ registry, router, probes, reach, owner, tier, harness, headingLevel = 2, stage = null }     ) {
+function renderBriefTools({ registry, router, probes, reach, owner, tier, harness, primary = null, bindings = null, headingLevel = 2, stage = null, repoRoot = REPO_ROOT }     ) {
   const missing      = [];
   const hashes = '#'.repeat(Number(headingLevel) === 3 ? 3 : 2);
-  const target = chooseTarget({ registry, reach, harness, missing });
+  const primaryHarness = primaryHarnessOf(primary, registry);
+  const target = chooseTarget({ registry, reach, harness, primaryHarness, missing });
   const targetHarness = target ? registry.harnesses.find((item     ) => item.id === target) : null;
   const resolved = resolveTier({ dispatchTiers: registry.dispatchTiers, owner, tier, missing });
+  const lineHarness = registry.harnesses.some((item     ) => item.id === harness) ? harness : primaryHarness;
+  const lineHarnessEntry = lineHarness ? registry.harnesses.find((item     ) => item.id === lineHarness) : null;
+  let model = null;
+  if (lineHarness) {
+    const { resolveBinding } = require('./worker/models.js');
+    const binding = resolveBinding({ worker: lineHarness, tier: resolved.tier, bindings, descriptor: lineHarnessEntry?.worker });
+    if (binding.source === 'invalid') {
+      model = { harness: lineHarness, id: null, source: 'invalid' };
+    } else if (binding.source === 'binding') {
+      model = { harness: lineHarness, id: binding.model, source: 'binding' };
+    } else {
+      model = { harness: lineHarness, id: null, source: 'harness-default' };
+    }
+  }
   const sourceText = resolved.source === 'owner' ? `owner ${owner}`
     : resolved.source === 'task' ? 'task line' : `default; ${resolved.note || `owner ${owner} has no tier`}`;
 
@@ -162,8 +178,18 @@ function renderBriefTools({ registry, router, probes, reach, owner, tier, harnes
   }
 
   const skill = stage?.skill || null;
+  const taskClass = stage?.taskClass || null;
+  const diffFiles = stage?.diffFiles || [];
+
   const expectedServers = skill
-    ? registry.mcp.filter((server     ) => (server.steps || []).some((step     ) => step.skill === skill && !step.expectedWhen)) : [];
+    ? registry.mcp.filter((server     ) => (server.steps || []).some((step     ) => {
+        if (step.skill !== skill) return false;
+        if (!step.expectedWhen) return true;
+        if (step.expectedWhen === 'dependency-change') return taskClass === 'dependency-change';
+        if (step.expectedWhen === 'manifest-review') return touchesManifest(diffFiles);
+        return false;
+      }))
+    : [];
   const expectedIds = new Set(expectedServers.map((server     ) => server.id));
   const expected = expectedServers.map((server     ) => {
     let state;
@@ -177,11 +203,20 @@ function renderBriefTools({ registry, router, probes, reach, owner, tier, harnes
   const list = (servers     ) => (servers.length ? servers.map((server     ) => `\`${server.id}\` (${trigger(server)})`).join('; ') : 'none');
   const targetName = targetHarness ? targetHarness.displayName || targetHarness.id : 'any installed harness';
 
+  const carried = loadBriefRules(repoRoot);
+  if ('reason' in carried) missing.push(`brief-rules: ${carried.reason}`);
+
   const lines = [
+    ...('lines' in carried ? [`${hashes} Rules that apply to you`, '', ...carried.lines.map((line        ) => `- ${line}`), ''] : []),
     `${hashes} Tier and tools`,
     '',
     `Tier: \`${resolved.tier}\` (${sourceText}), per`,
     '`references/MODEL_SELECTION.md`.',
+    ...(model ? [model.source === 'invalid'
+      ? `Model: binding unreadable on \`${model.harness}\`; harness default.`
+      : model.source === 'binding'
+        ? `Model: \`${model.id}\` on \`${model.harness}\` (binding, user layer).`
+        : `Model: harness default on \`${model.harness}\`.`] : []),
     '',
     'Tools this machine answers with, per information need. Searching with them before reading whole',
     'files is recommended where it saves reading; it is not required.',
@@ -199,12 +234,18 @@ function renderBriefTools({ registry, router, probes, reach, owner, tier, harnes
     if (item.reach === 'unreachable') lines.push(`\`${item.server}\` is not reachable on ${targetName}; report it as \`${item.server}=unavailable\`.`);
     else if (item.reach === 'unknown') lines.push(`\`${item.server}\` may not be reachable on ${targetName}; if no tool answers, report \`${item.server}=unavailable\`.`);
   }
+  for (const s of expectedServers) {
+    if (typeof s.trigger === 'string' && s.trigger.toLowerCase().includes('library')) {
+      lines.push(`Vendor/library facts: \`${s.id}\` first, else a URL, else UNVERIFIED.`);
+    }
+  }
   lines.push(
     '',
     `${hashes} Report format`,
     '',
-    `End ${Number(headingLevel) === 3 ? "each task's report" : 'your report'} with one line naming every tool and MCP server you used:`,
+    'Put one line naming every tool and MCP server you used just before the final status line:',
     '`Tools used: <name>[=used|nothing-usable|unavailable|skipped:<reason>], ...`',
+    `End ${Number(headingLevel) === 3 ? "each task's report" : 'your report'} with one line \`Status: <status>\`, where the status is one of ${HANDBACK_IDS.map((id) => `\`${id}\``).join(', ')}.`,
   );
 
   const record = {
@@ -217,6 +258,7 @@ function renderBriefTools({ registry, router, probes, reach, owner, tier, harnes
     tier: resolved.tier,
     tierSource: resolved.source,
     harness: target,
+    model: model ?? null,
     expected,
     optional: also.map((server     ) => server.id),
     tools,
@@ -230,7 +272,7 @@ function currentStageOf({ repoRoot = REPO_ROOT, projectRoot, taskId }     ) {
   try {
     const run = new WorkflowOrchestrator({ repoRoot, projectRoot }).readRun(taskId);
     const node = run && run.cursor < run.program.length ? run.program[run.cursor] : null;
-    return node && node.type === 'stage' ? { stageId: node.id, skill: node.skill } : null;
+    return node && node.type === 'stage' ? { stageId: node.id, skill: node.skill, taskClass: run.taskClass ?? null } : null;
   } catch { return null; }
 }
 
@@ -279,13 +321,14 @@ function adviceRecord(result     ) {
     };
   }
   if (result?.status === 'unavailable') return { kind: 'tier', status: 'unavailable', reason: result.reason || 'config-invalid' };
+  if (result?.status === 'shadow') return { kind: 'tier', status: 'shadow', reason: result.reason ?? null };
   return null;
 }
 
 /**
  * The tier renderer remains synchronous/pure; optional local advice is requested afterward.
  */
-async function handleBriefToolsCommand({ owner, tier, harness, slug, headingLevel, tasks, json = false, repoRoot = REPO_ROOT, projectRoot = process.cwd(), buildAdapters = null, probe = probeProviders, adviceClient = null }      = {}) {
+async function handleBriefToolsCommand({ owner, tier, harness, slug, headingLevel, tasks, json = false, repoRoot = REPO_ROOT, projectRoot = process.cwd(), env = process.env, buildAdapters = null, probe = probeProviders, adviceClient = null }      = {}) {
   if (!owner) return usageError('brief-tools', '--owner is required (the agent type the brief is for)', json);
   const level = headingLevel === undefined ? 2 : Number(headingLevel);
   if (level !== 2 && level !== 3) return usageError('brief-tools', `--heading-level must be 2 or 3, got '${headingLevel}'`, json);
@@ -297,7 +340,12 @@ async function handleBriefToolsCommand({ owner, tier, harness, slug, headingLeve
     let reach = null;
     try { reach = mcpReach({ registry, projectRoot, adapters: buildAdapters ? buildAdapters() : undefined }); } catch { notes.push('install facts unavailable; MCP reach unknown'); }
     const stage = stageFor({ repoRoot, projectRoot, slug, missing: notes });
-    const rendered = renderBriefTools({ registry, router, probes, reach, owner, tier, harness, headingLevel: level, stage });
+    let primary = null;
+    const { readBindings } = require('./worker/models.js');
+    const { resolvePrimary } = require('./context/primary.js');
+    try { primary = resolvePrimary({ env, projectRoot, registry }); } catch { notes.push('primary unresolved; default target unchanged'); }
+    const bindings = readBindings({ env, projectRoot });
+    const rendered = renderBriefTools({ registry, router, probes, reach, owner, tier, harness, primary, bindings, headingLevel: level, stage, repoRoot });
     let markdown = rendered.markdown;
     const record      = rendered.record;
     record.missing.push(...notes);
@@ -307,21 +355,50 @@ async function handleBriefToolsCommand({ owner, tier, harness, slug, headingLeve
       try {
         const adviceRegistry = loadAdviceRegistry({ repoRoot });
         const storageRegistry = loadStorageRegistry({ repoRoot });
-        const roots = resolveRoots({ registry: storageRegistry, projectRoot: path.resolve(projectRoot) });
-        if (adviceRegistry.ok && (adviceClient || resolveSetting({ adviceRegistry: adviceRegistry.registry, roots }).state === 'on')) {
+        const roots = resolveRoots({ registry: storageRegistry, projectRoot: path.resolve(projectRoot), env });
+        if (adviceRegistry.ok && (adviceClient || resolveSetting({ adviceRegistry: adviceRegistry.registry, roots, env }).state === 'on')) {
           const lines = taskLinesForAdvice({ projectRoot, feature: stage?.feature || slug, tasks: taskIds });
           const built = materializeKind('tier', { adviceRegistry: adviceRegistry.registry });
           const client = adviceClient || createAdviceClient({ adviceRegistry: adviceRegistry.registry, roots });
-          const result = built.ok ? await client.ask({
-            questionSet: { state: `${owner}\n${lines.join('\n')}`, questions: [built.question] },
-            kind: 'tier', staticAnswer: record.tier, caller: 'brief-tools', taskId: stage?.feature || slug,
-          }) : { status: 'unavailable', reason: built.reason || 'config-invalid' };
+          const state = `${owner}\n${lines.join('\n')}`;
+          const shadow = resolveShadowConfig('tier', { projectRoot: path.resolve(projectRoot), env, roots });
+          let result      = { status: 'unavailable', reason: built.reason || 'config-invalid' };
+          if (built.ok && !shadow.kindSet) {
+            // advice.kinds.tier unset: the client asks and records, as before the dispatcher. A chosen rollout
+            // profile caps it: off asks nothing; shadow records the pick and shows none.
+            const { profileAdvisorCap, unsetKindPath } = require('./advice/mode.js');
+            const route = unsetKindPath(profileAdvisorCap({ projectRoot: path.resolve(projectRoot), env }));
+            if (route === 'off') result = { status: 'off', reason: null };
+            else {
+              result = await client.ask({
+                questionSet: { state, questions: [built.question] },
+                kind: 'tier', staticAnswer: record.tier, caller: 'brief-tools', taskId: stage?.feature || slug,
+              });
+              if (route === 'shadow' && result?.status === 'answered') result = { status: 'shadow', reason: null };
+            }
+          } else if (built.ok) {
+            const { interceptDecisionPoint } = require('./advice/shadow-dispatcher.js');
+            const intercepted = await interceptDecisionPoint({
+              kind: 'tier', caller: 'brief-tools', state, staticPick: record.tier,
+              questionSet: { state, questions: [built.question] }, adviceRegistry: adviceRegistry.registry,
+              taskId: stage?.feature || slug, projectRoot: path.resolve(projectRoot), env,
+            }, { adviceClient: client, roots, shadowConfig: shadow });
+            // Only act shows a pick, and it is the decision after the raise-only rule.
+            if (intercepted.mode === 'act' && intercepted.advisorPick) {
+              result = { status: 'answered', answers: [{
+                ...intercepted.advisorAnswer, pick: intercepted.effectiveDecision, pickId: intercepted.pickId,
+                agrees: intercepted.effectiveDecision === record.tier,
+              }] };
+            } else if (intercepted.mode === 'shadow') result = { status: 'shadow', reason: intercepted.warning || null };
+            else if (intercepted.mode === 'off') result = { status: 'off', reason: null };
+            else result = { status: 'unavailable', reason: intercepted.warning || null };
+          }
           const added = adviceRecord(result);
           if (added) {
             record.advice = added;
             if (added.status === 'answered') {
               const line = `Decision model: \`${added.pick}\` (${strengthWords({ word: added.strength, between: added.between })}), advisory. The tier above stands unless you change it.`;
-              markdown = markdown.replace(/(Tier: `[^`]+`[^\n]*\n`references\/MODEL_SELECTION\.md`\.)\n\n/, `$1\n${line}\n\n`);
+              markdown = markdown.replace(/(Tier: `[^`]+`[^\n]*\n`references\/MODEL_SELECTION\.md`\.(?:\nModel: [^\n]*)?)\n\n/, `$1\n${line}\n\n`);
             }
           }
         }