shakers-cli 0.14.2 → 0.16.0

package/src/usage-repo-scope.js

@@ -1,69 +1,12 @@
 'use strict';
 
-// Repo-scoping for the `ai-usage` command, extracted from bin/ai-usage.js (structure refactor, issue 020).
+// Repo-scoping for the `ai-usage` command, extracted from bin/ai-usage.js.
 
-const { isRefusedWalkRoot } = require('./scan-exclusions');
-const {
-  detectRepos,
-  repoIdentityForCwd,
-  matchReposByFlag,
-  scopeFromSelection,
-  indexOfCurrentRepo,
-} = require('./detect-repos');
+const core = require('./repo-scope');
 const { promptSelect } = require('./prompt-select');
 const { createStdinAsk } = require('./stdin-ask');
 
-const MAX_MACHINE_WIDE_REPOS = 5;
-const SCOPE_MACHINE = 'machine';
-const SCOPE_REPO = 'repo';
-
-function currentRepoToplevel(cwd, repoIdentityFn = repoIdentityForCwd) {
-  try {
-    return repoIdentityFn(cwd).toplevel || cwd;
-  } catch {
-    return cwd;
-  }
-}
-
-// The real git toplevel of `cwd`, or null when `cwd` is not a repo (or is a refused system root like `/`, the MCP `cwd=/` case).
-function cwdRepoToplevel(cwd, repoIdentityFn = repoIdentityForCwd) {
-  if (isRefusedWalkRoot(cwd)) return null;
-  try {
-    return repoIdentityFn(cwd).toplevel || null;
-  } catch {
-    return null;
-  }
-}
-
-// Pure: builds the machine-wide root set.
-function machineWideToplevels(cwdRepoTop, detectedRepos, cap = MAX_MACHINE_WIDE_REPOS) {
-  const ordered = [];
-  const seen = new Set();
-  const push = (t) => {
-    if (typeof t !== 'string' || !t) return;
-    if (isRefusedWalkRoot(t)) return;
-    if (seen.has(t)) return;
-    seen.add(t);
-    ordered.push(t);
-  };
-  push(cwdRepoTop);
-  for (const r of detectedRepos || []) push(r && r.toplevel);
-  const capped = ordered.slice(0, cap);
-  return { toplevels: capped, total: ordered.length, capped: ordered.length > capped.length };
-}
-
-function cwdOnlyScope(repos, cwdToplevel) {
-  const idx = indexOfCurrentRepo(repos, cwdToplevel);
-  if (idx === -1) {
-    return { selectedCwds: new Set(), toplevels: [cwdToplevel], mode: 'cwd' };
-  }
-  const { selectedCwds, selectedToplevels } = scopeFromSelection(repos, [idx]);
-  return {
-    selectedCwds,
-    toplevels: selectedToplevels.length ? selectedToplevels : [cwdToplevel],
-    mode: 'cwd',
-  };
-}
+const { SCOPE_MACHINE, SCOPE_REPO, machineWideToplevels } = core;
 
 async function promptScope({ catalog, stdinIsTTY = true, mkAsk = createStdinAsk } = {}) {
   const c = (catalog && catalog.cli) || {};
@@ -88,75 +31,14 @@ async function promptScope({ catalog, stdinIsTTY = true, mkAsk = createStdinAsk
   }
 }
 
-// Resolve which repos feed the AI-usage evaluation.
-async function resolveRepoScope({
-  opts,
-  cwd,
-  injectedAsk,
-  catalog,
-  detectReposFn = detectRepos,
-  repoIdentityFn = repoIdentityForCwd,
-  chooseScope = promptScope,
-  isTTY = !!process.stdin.isTTY && !!process.stdout.isTTY,
-}) {
-  const cwdToplevel = currentRepoToplevel(cwd, repoIdentityFn);
-  const cwdRepoTop = cwdRepoToplevel(cwd, repoIdentityFn);
-  const note = (s) => {
-    if (!opts.json) process.stdout.write(`\n  ${s}\n`);
-  };
-
-  const detect = () => {
-    try {
-      return detectReposFn(process.env);
-    } catch {
-      return { repos: [], unassignedSessionCount: 0 };
-    }
-  };
-
-  // 1. Explicit repo list always wins.
-  if (opts.repos) {
-    const { repos, unassignedSessionCount } = detect();
-    note(catalog.cli.reposDetectedNote(repos.length, unassignedSessionCount));
-    const { indices, unmatched } = matchReposByFlag(repos, opts.repos);
-    if (unmatched.length > 0) {
-      process.stderr.write(`  ${catalog.cli.reposFlagUnmatched(unmatched.join(', '))}\n`);
-    }
-    if (indices.length > 0) {
-      const { selectedCwds, selectedToplevels } = scopeFromSelection(repos, indices);
-      return { selectedCwds, toplevels: [...new Set(selectedToplevels)], mode: 'flag' };
-    }
-    return cwdOnlyScope(repos, cwdToplevel);
-  }
-
-  const wantsMachine = opts.allRepos || opts.machine || opts.scope === SCOPE_MACHINE;
-  const wantsRepo = opts.repo || opts.scope === SCOPE_REPO;
-
-  let choice = null;
-  if (wantsMachine) choice = SCOPE_MACHINE;
-  else if (wantsRepo) choice = SCOPE_REPO;
-  else if (isTTY && !injectedAsk && !opts.json) {
-    choice = await chooseScope({ catalog, stdinIsTTY: true });
-  }
-  if (choice === null) choice = SCOPE_REPO;
-
-  if (choice === SCOPE_MACHINE) {
-    const { repos, unassignedSessionCount } = detect();
-    note(catalog.cli.reposDetectedNote(repos.length, unassignedSessionCount));
-    const mw = machineWideToplevels(cwdRepoTop, repos);
-    if (mw.capped) {
-      process.stderr.write(`\n  ${catalog.cli.reposScopeCapped(mw.toplevels.length, mw.total)}\n`);
-    }
-    note(catalog.cli.reposScopeAll);
-    return {
-      selectedCwds: null,
-      toplevels: mw.toplevels.length ? mw.toplevels : [cwdToplevel],
-      mode: 'all',
-    };
-  }
-
-  // Current repo.
-  const { repos } = detect();
-  return cwdOnlyScope(repos, cwdToplevel);
+function resolveRepoScope(args) {
+  return core.resolveRepoScope({
+    ...args,
+    chooseScope: args.chooseScope || promptScope,
+    note: (s) => {
+      if (!args.opts.json) process.stdout.write(`\n  ${s}\n`);
+    },
+  });
 }
 
 module.exports = { resolveRepoScope, machineWideToplevels, promptScope };

package/src/usage-run-steps.js

@@ -1,60 +1,29 @@
 'use strict';
 
-const { scan, scanForRoots } = require('./scanner');
-const { classify } = require('./maturity');
 const { renderTerminal } = require('./render-terminal');
-const { reportGateForIdentity } = require('./report-gating');
 const { revealText } = require('./typewriter');
 const { persistFootprint } = require('./report-store');
 const {
   loadConsentState,
   getConsentDecision,
-  recordConsent,
-  isValidEmail,
-  normalizeEmail,
   autoShare,
   consentPath,
 } = require('./share');
 const { runConsentPrompt } = require('./consent-flow');
 const { createStdinAsk } = require('./stdin-ask');
-const {
-  parseAgentDescriptions,
-  parseAgentOrgChartForRoots,
-  parseAgentDescriptionsForRoots,
-  parseAgentDefinitionsForRoots,
-} = require('./agent-org-chart');
-const { collectAgentUsage } = require('./agent-usage');
-const { collectSessionSignals } = require('./session-signals');
-const {
-  collectScopedGitActivity,
-  collectScopedWorkStreams,
-  collectScopedDetectionEvidence,
-} = require('./scope-signals');
-const { detectAuthorshipMismatch } = require('./authorship-mismatch');
-const { MODEL_CALL, REASON, skipped, attachModelCall } = require('./model-call-record');
-const {
-  getSynthesisEndpoint,
-  getRoadmapEndpoint,
-  getAgentEvaluationEndpoint,
-  getAiProfileEndpoint,
-} = require('./config');
+const { getAiProfileEndpoint } = require('./config');
 // "My work with AI" preview, read from the hub ai-profile (same as the front).
 const { resolveAiProfilePreview } = require('./ai-profile-preview');
 const { renderAiProfileTerminal } = require('./render-ai-fluency');
 const { ensureFreshSession } = require('./session-refresh');
 const { loadAuthSession, sessionStatus } = require('./auth-session-store');
 const { c: termColors } = require('./terminal-format');
-const { withStaticStatus, withSpinner } = require('./terminal-progress');
+const { withSpinner } = require('./terminal-progress');
 const { computeConsentSkip } = require('./consent-skip');
-const { getRoadmapEntry } = require('./roadmap-content');
-const {
-  maybeSynthesizeAgents,
-  maybeEvaluateAgents,
-  maybePersonalizeRoadmap,
-} = require('./usage-model-calls');
+const { collectIdentityAndUsage, storedAiConsent, reanchorReusedGrant } = require('./usage-scan');
 const { doBuildNextLevel } = require('./usage-oneshot-commands');
 
-// Automatic, silent PERSISTING once consent is `granted` (ADR-007, gating revised by ADR-011: consent controls persistence only, never what's shown).
+// Automatic, silent PERSISTING once consent is `granted` (consent controls persistence only, never what's shown).
 async function maybeAutoShare(report, maturity, root, catalog, { bypassThrottle = false } = {}) {
   try {
     const result = await autoShare(report, maturity, { root, bypassThrottle });
@@ -82,35 +51,17 @@ function sendStatusColor(reason) {
   return SEND_WARN_REASONS.has(reason) ? termColors.warning : termColors.danger;
 }
 
-function performScan({ opts, catalog }) {
-  const root = opts.root;
-  const report = withStaticStatus(catalog.cli.scanningLabel, () => scan({ root }));
-  // `let`, not `const`: this is the cwd tier.
-  const maturity = classify(report);
-
-  if (Array.isArray(report.agents) && report.agents.length > 0) {
-    report.agentDescriptions = parseAgentDescriptions(root || process.cwd());
-  }
-
-  return { report, maturity, root, rootDir: root || process.cwd() };
-}
-
 // The identity gate + local (no-network, no-LLM) agent-usage signal.
 function prepareIdentityAndUsage({ report, catalog, quiet = false }) {
-  const hasAgents = Array.isArray(report.agents) && report.agents.length > 0;
-  const gate = reportGateForIdentity();
-
+  const identity = collectIdentityAndUsage({ report });
   // --json owns stdout: one parseable document, and the MCP's JSON-RPC channel.
-  if (gate.showFrameworkIntro && !quiet) process.stdout.write(`\n  ${catalog.cli.frameworkIntroUsage}\n`);
-
-  // Local, no network, no LLM: how often each detected agent was invoked in the local Claude Code history.
-  if (hasAgents) report.agentUsage = collectAgentUsage(report.agents);
-
-  return { gate, hasAgents };
+  if (identity.gate.showFrameworkIntro && !quiet) process.stdout.write(`\n  ${catalog.cli.frameworkIntroUsage}\n`);
+  return identity;
 }
 
 async function resolveAiConsent({ opts, catalog, gate, injectedAsk }) {
-  // CONSENT GATE, MOVED TO BEFORE ANY AI/EGRESS CALL (talents-ai-score, ADR-051 — explicit product decision that AMENDS ADR-010/011/003 on purpose, not a bug fix).
+  // CONSENT GATE, MOVED TO BEFORE ANY AI/EGRESS CALL (explicit product decision, not a bug fix).
+  if (opts.json) return storedAiConsent({ gate });
   const state = loadConsentState();
   const decision = getConsentDecision(state);
   const consentSkip = computeConsentSkip({
@@ -122,143 +73,43 @@ async function resolveAiConsent({ opts, catalog, gate, injectedAsk }) {
   });
 
   let aiConsentGranted;
-  // A REUSED grant (skip/--json) carries a stale consent email; a fresh prompt re-anchors itself.
+  // A REUSED grant (skip) carries a stale consent email; a fresh prompt re-anchors itself.
   let reusedStoredConsent = false;
-  if (opts.json) {
-    // `--json` never had an interactive prompt — its whole point is a single parseable stdout document, and it does not gain one now.
-    aiConsentGranted = decision === 'granted' && (!state || state.emailVerified !== false);
+  if (consentSkip.message) {
+    process.stdout.write(`\n  ${consentSkip.message}\n`);
+  }
+  if (consentSkip.skip) {
+    // A TERMINAL decision already exists (a prior run's explicit grant or
+    // denial) — never re-asked.
+    aiConsentGranted = decision === 'granted';
     reusedStoredConsent = true;
   } else {
-    if (consentSkip.message) {
-      process.stdout.write(`\n  ${consentSkip.message}\n`);
-    }
-    if (consentSkip.skip) {
-      // A TERMINAL decision already exists (a prior run's explicit grant or
-      // denial) — never re-asked, per ADR-007/011.
-      aiConsentGranted = decision === 'granted';
-      reusedStoredConsent = true;
-    } else {
-      const ask = injectedAsk || createStdinAsk();
-      let result;
-      try {
-        result = await runConsentPrompt({
-          ask, catalog, loggedIn: gate.loggedIn, sessionEmail: gate.email, profile: gate.profile,
-        });
-      } finally {
-        if (!injectedAsk) ask.close();
-      }
-      aiConsentGranted = result === 'granted';
-    }
-    if (!aiConsentGranted) {
-      // No early return (reverted 8867450's wall): the local report still renders further down, same as ADR-011 always promised.
-      process.stdout.write(`\n  ${termColors.warning}${catalog.consent.noReportWithoutConsent}${termColors.reset}\n\n`);
+    const ask = injectedAsk || createStdinAsk();
+    let result;
+    try {
+      result = await runConsentPrompt({
+        ask, catalog, loggedIn: gate.loggedIn, sessionEmail: gate.email, profile: gate.profile,
+      });
+    } finally {
+      if (!injectedAsk) ask.close();
     }
+    aiConsentGranted = result === 'granted';
   }
-  // Re-anchor a reused grant to the session's login-proven email (ADR-006): else a stale consent email ingests the report under another account and this session's AI profile never populates.
-  if (reusedStoredConsent && aiConsentGranted && gate.loggedIn
-    && isValidEmail(gate.email) && state && state.email !== normalizeEmail(gate.email)) {
-    recordConsent('granted', gate.email, { verified: true });
+  if (!aiConsentGranted) {
+    // No early return: the local report still renders further down.
+    process.stdout.write(`\n  ${termColors.warning}${catalog.consent.noReportWithoutConsent}${termColors.reset}\n\n`);
   }
+  if (reusedStoredConsent && aiConsentGranted) reanchorReusedGrant({ gate, state });
   return aiConsentGranted;
 }
 
-function runAggregation({ report, scope, consentEmail, agentRoots, root, catalog }) {
-  withStaticStatus(catalog.cli.aggregatingLabel, () => {
-    report.gitActivity = collectScopedGitActivity(scope.toplevels, consentEmail);
-    // Display-only transparency warning (never feeds scoring, see authorship-mismatch.js).
-    report.authorshipMismatch = detectAuthorshipMismatch(scope.toplevels, consentEmail, report.gitActivity);
-    const sessionSignals = collectSessionSignals(process.env, scope.selectedCwds);
-    report.sessions = sessionSignals.sessions;
-    report.workStreams = collectScopedWorkStreams(scope.toplevels);
-    report.steering = sessionSignals.steering;
-    report.decisions = sessionSignals.decisions;
-    report.detectionEvidence = collectScopedDetectionEvidence(
-      scope.toplevels,
-      consentEmail,
-      report,
-    );
-
-    const scoped = scanForRoots(agentRoots, { root });
-    report.tools = scoped.tools;
-    report.summary = scoped.summary;
-    report.technologies = scoped.technologies;
-    report.mcp = scoped.mcp;
-    report.memory = scoped.memory;
-    report.automations = scoped.automations;
-    report.browserTools = scoped.browserTools;
-    report.agentCounts = scoped.agentCounts;
-    report.environment = scoped.environment;
-
-    report.agents = parseAgentOrgChartForRoots(agentRoots);
-    report.agentCounts.agents = report.agents.length;
-    if (report.agents.length > 0) {
-      report.agentDescriptions = parseAgentDescriptionsForRoots(agentRoots);
-      report.agentDefinitions = parseAgentDefinitionsForRoots(agentRoots);
-      report.agentUsage = collectAgentUsage(report.agents);
-    }
-  });
-}
-
-async function runModelCalls({
-  report, maturity, aiConsentGranted, opts, gate, hasAgents, agentRoots, rootDir, lang, catalog,
-}) {
-  // Which of the three will genuinely be ATTEMPTED.
-  const willAttemptSynthesis = aiConsentGranted && hasAgents && !!getSynthesisEndpoint();
-  const willAttemptEvaluation = aiConsentGranted && hasAgents && !!getAgentEvaluationEndpoint();
-  const roadmapEntryForTier = maturity.tierKey ? getRoadmapEntry(maturity.tierKey, lang) : null;
-  const willAttemptRoadmapPersonalization =
-    aiConsentGranted
-    && gate.showRoadmap
-    && !!roadmapEntryForTier && !roadmapEntryForTier.maxTier
-    && !!getRoadmapEndpoint();
-
-  // THE THREE MODEL CALLS RUN ONE AFTER ANOTHER, NOT IN PARALLEL (issue 116).
-  const runPhase = (willAttempt, label, call) => (willAttempt ? withSpinner(label, call) : call());
-
-  // talents-ai-score, ADR-051: `aiConsentGranted` is `false` whenever consent for this run was declined, denied in the past, or (on `--json`) simply never granted.
-  let synthesis = null;
-  let evaluation = null;
-  let roadmapPersonalization = null;
-  if (aiConsentGranted && !opts.noAi) {
-    synthesis = await runPhase(
-      willAttemptSynthesis,
-      catalog.cli.synthesizingLabel,
-      () => maybeSynthesizeAgents(report, rootDir),
-    );
-    evaluation = hasAgents
-      ? await runPhase(
-        willAttemptEvaluation,
-        catalog.cli.evaluatingAgentsLabel,
-        () => maybeEvaluateAgents(report, agentRoots, lang),
-      )
-      : null;
-    // issue 123 / ADR-044: `runPhase` runs `call()` whether or not a spinner is shown, so gating the roadmap CANNOT be done by flipping `willAttempt` — that only hides the spinner.
-    roadmapPersonalization = gate.showRoadmap
-      ? await runPhase(
-        willAttemptRoadmapPersonalization,
-        catalog.cli.personalizingRoadmapLabel,
-        () => maybePersonalizeRoadmap(report, maturity, lang),
-      )
-      : null;
-  } else {
-    const skipReason = aiConsentGranted ? REASON.NOT_APPLICABLE : REASON.NO_CONSENT;
-    attachModelCall(report, MODEL_CALL.SYNTHESIS, skipped(skipReason));
-    attachModelCall(report, MODEL_CALL.EVALUATION, skipped(skipReason));
-    attachModelCall(report, MODEL_CALL.ROADMAP, skipped(skipReason));
-  }
-
-  if (synthesis) report.agentSynthesis = synthesis;
-  if (evaluation) report.agentEvaluation = evaluation;
-  if (roadmapPersonalization) report.roadmapPersonalization = roadmapPersonalization;
-}
-
 async function renderAndFinalize({ report, maturity, lang, opts, root, gate, catalog, bypassThrottle = false }) {
   if (opts.json) {
     process.stdout.write(JSON.stringify({ report, maturity }, null, 2) + '\n');
     return;
   }
 
-  // Issue 103: revealed by SECTIONS instead of landing in one write.
+  // Revealed by SECTIONS instead of landing in one write.
   if (gate.sessionStatus === 'expired') {
     process.stdout.write(`\n  ${termColors.warning}${catalog.terminal.sessionExpiredNotice}${termColors.reset}\n`);
   }
@@ -276,7 +127,7 @@ async function renderAndFinalize({ report, maturity, lang, opts, root, gate, cat
     }
   }
 
-  // "Construir el siguiente nivel ahora" (issue 021): optional, only when
+  // "Construir el siguiente nivel ahora": optional, only when
   // explicitly requested — never part of a normal run otherwise.
   if (opts.buildNextLevel) {
     doBuildNextLevel(root, maturity, opts.force, catalog);
@@ -343,11 +194,8 @@ async function maybeRenderAiProfile({ report, maturity, lang, root, save, submit
 }
 
 module.exports = {
-  performScan,
   prepareIdentityAndUsage,
   resolveAiConsent,
-  runAggregation,
-  runModelCalls,
   renderAndFinalize,
   shouldRenderAiProfile,
   maybeRenderAiProfile,

package/src/usage-scan.js

@@ -0,0 +1,235 @@
+'use strict';
+
+const { scan, scanForRoots } = require('./scanner');
+const { classify } = require('./maturity');
+const { reportGateForIdentity } = require('./report-gating');
+const {
+  loadConsentState,
+  getConsentDecision,
+  recordConsent,
+  isValidEmail,
+  normalizeEmail,
+} = require('./share');
+const {
+  parseAgentDescriptions,
+  parseAgentOrgChartForRoots,
+  parseAgentDescriptionsForRoots,
+  parseAgentDefinitionsForRoots,
+} = require('./agent-org-chart');
+const { collectAgentUsage } = require('./agent-usage');
+const { collectSessionSignals } = require('./session-signals');
+const {
+  collectScopedGitActivity,
+  collectScopedWorkStreams,
+  collectScopedDetectionEvidence,
+} = require('./scope-signals');
+const { detectAuthorshipMismatch } = require('./authorship-mismatch');
+const { MODEL_CALL, REASON, skipped, attachModelCall } = require('./model-call-record');
+const {
+  getSynthesisEndpoint,
+  getRoadmapEndpoint,
+  getAgentEvaluationEndpoint,
+} = require('./config');
+const { withStaticStatus, withSpinner } = require('./terminal-progress');
+const { getRoadmapEntry } = require('./roadmap-content');
+const {
+  maybeSynthesizeAgents,
+  maybeEvaluateAgents,
+  maybePersonalizeRoadmap,
+} = require('./usage-model-calls');
+const { parseArgs } = require('./cli-args');
+const { detectReportLang, getCatalog } = require('./i18n');
+const { prefetchGitLogs } = require('./git-log-prefetch');
+const { GIT_ACTIVITY_LOG_ARGS } = require('./git-activity');
+const { WORK_STREAMS_LOG_ARGS } = require('./work-streams');
+const { AUTHORSHIP_LOG_ARGS } = require('./authorship');
+const { resolveRepoScope } = require('./repo-scope');
+
+function performScan({ opts, catalog }) {
+  const root = opts.root;
+  const report = withStaticStatus(catalog.cli.scanningLabel, () => scan({ root }));
+  // `let`, not `const`: this is the cwd tier.
+  const maturity = classify(report);
+
+  if (Array.isArray(report.agents) && report.agents.length > 0) {
+    report.agentDescriptions = parseAgentDescriptions(root || process.cwd());
+  }
+
+  return { report, maturity, root, rootDir: root || process.cwd() };
+}
+
+function collectIdentityAndUsage({ report }) {
+  const hasAgents = Array.isArray(report.agents) && report.agents.length > 0;
+  const gate = reportGateForIdentity();
+  if (hasAgents) report.agentUsage = collectAgentUsage(report.agents);
+  return { gate, hasAgents };
+}
+
+// Re-anchor a reused grant to the session's login-proven email: else a stale consent email ingests the report under another account and this session's AI profile never populates.
+function reanchorReusedGrant({ gate, state }) {
+  if (gate.loggedIn && isValidEmail(gate.email) && state && state.email !== normalizeEmail(gate.email)) {
+    recordConsent('granted', gate.email, { verified: true });
+  }
+}
+
+// `--json` never had an interactive prompt — its whole point is a single parseable stdout document, and it does not gain one now.
+function storedAiConsent({ gate }) {
+  const state = loadConsentState();
+  const granted = getConsentDecision(state) === 'granted' && (!state || state.emailVerified !== false);
+  if (granted) reanchorReusedGrant({ gate, state });
+  return granted;
+}
+
+function runAggregation({ report, scope, consentEmail, agentRoots, root, catalog }) {
+  withStaticStatus(catalog.cli.aggregatingLabel, () => {
+    report.gitActivity = collectScopedGitActivity(scope.toplevels, consentEmail);
+    // Display-only transparency warning (never feeds scoring, see authorship-mismatch.js).
+    report.authorshipMismatch = detectAuthorshipMismatch(scope.toplevels, consentEmail, report.gitActivity);
+    const sessionSignals = collectSessionSignals(process.env, scope.selectedCwds);
+    report.sessions = sessionSignals.sessions;
+    report.workStreams = collectScopedWorkStreams(scope.toplevels);
+    report.steering = sessionSignals.steering;
+    report.decisions = sessionSignals.decisions;
+    report.detectionEvidence = collectScopedDetectionEvidence(
+      scope.toplevels,
+      consentEmail,
+      report,
+    );
+
+    const scoped = scanForRoots(agentRoots, { root });
+    report.tools = scoped.tools;
+    report.summary = scoped.summary;
+    report.technologies = scoped.technologies;
+    report.mcp = scoped.mcp;
+    report.memory = scoped.memory;
+    report.automations = scoped.automations;
+    report.browserTools = scoped.browserTools;
+    report.agentCounts = scoped.agentCounts;
+    report.environment = scoped.environment;
+
+    report.agents = parseAgentOrgChartForRoots(agentRoots);
+    report.agentCounts.agents = report.agents.length;
+    if (report.agents.length > 0) {
+      report.agentDescriptions = parseAgentDescriptionsForRoots(agentRoots);
+      report.agentDefinitions = parseAgentDefinitionsForRoots(agentRoots);
+      report.agentUsage = collectAgentUsage(report.agents);
+    }
+  });
+}
+
+async function runModelCalls({
+  report, maturity, aiConsentGranted, opts, gate, hasAgents, agentRoots, rootDir, lang, catalog,
+}) {
+  // Which of the three will genuinely be ATTEMPTED.
+  const willAttemptSynthesis = aiConsentGranted && hasAgents && !!getSynthesisEndpoint();
+  const willAttemptEvaluation = aiConsentGranted && hasAgents && !!getAgentEvaluationEndpoint();
+  const roadmapEntryForTier = maturity.tierKey ? getRoadmapEntry(maturity.tierKey, lang) : null;
+  const willAttemptRoadmapPersonalization =
+    aiConsentGranted
+    && gate.showRoadmap
+    && !!roadmapEntryForTier && !roadmapEntryForTier.maxTier
+    && !!getRoadmapEndpoint();
+
+  // THE THREE MODEL CALLS RUN ONE AFTER ANOTHER, NOT IN PARALLEL.
+  const runPhase = (willAttempt, label, call) => (willAttempt ? withSpinner(label, call) : call());
+
+  // `aiConsentGranted` is `false` whenever consent for this run was declined, denied in the past, or (on `--json`) simply never granted.
+  let synthesis = null;
+  let evaluation = null;
+  let roadmapPersonalization = null;
+  if (aiConsentGranted && !opts.noAi) {
+    synthesis = await runPhase(
+      willAttemptSynthesis,
+      catalog.cli.synthesizingLabel,
+      () => maybeSynthesizeAgents(report, rootDir),
+    );
+    evaluation = hasAgents
+      ? await runPhase(
+        willAttemptEvaluation,
+        catalog.cli.evaluatingAgentsLabel,
+        () => maybeEvaluateAgents(report, agentRoots, lang),
+      )
+      : null;
+    // `runPhase` runs `call()` whether or not a spinner is shown, so gating the roadmap CANNOT be done by flipping `willAttempt` — that only hides the spinner.
+    roadmapPersonalization = gate.showRoadmap
+      ? await runPhase(
+        willAttemptRoadmapPersonalization,
+        catalog.cli.personalizingRoadmapLabel,
+        () => maybePersonalizeRoadmap(report, maturity, lang),
+      )
+      : null;
+  } else {
+    const skipReason = aiConsentGranted ? REASON.NOT_APPLICABLE : REASON.NO_CONSENT;
+    attachModelCall(report, MODEL_CALL.SYNTHESIS, skipped(skipReason));
+    attachModelCall(report, MODEL_CALL.EVALUATION, skipped(skipReason));
+    attachModelCall(report, MODEL_CALL.ROADMAP, skipped(skipReason));
+  }
+
+  if (synthesis) report.agentSynthesis = synthesis;
+  if (evaluation) report.agentEvaluation = evaluation;
+  if (roadmapPersonalization) report.roadmapPersonalization = roadmapPersonalization;
+}
+
+// Steps 1-6 of a run: scan, scope, aggregate, classify; nothing is rendered or sent.
+async function computeUsage({
+  opts,
+  catalog,
+  lang,
+  inRegistration = false,
+  prepareIdentity = collectIdentityAndUsage,
+  resolveConsent = storedAiConsent,
+  resolveScope = resolveRepoScope,
+}) {
+  // 1. Local scan + classify (always computed and shown).
+  const { report, root, rootDir } = performScan({ opts, catalog });
+
+  // 2. Identity gate + local agent-usage signal. Roadmap only for anonymous runs
+  //    (gate.showRoadmap = !loggedIn) AND never during register/onboarding.
+  const { gate: identityGate } = prepareIdentity({ report, catalog, quiet: opts.json === true });
+  const gate = (inRegistration && identityGate.showRoadmap)
+    ? { ...identityGate, showRoadmap: false }
+    : identityGate;
+
+  // 3. Consent gate before any AI/egress call; a decline still renders.
+  const aiConsentGranted = await resolveConsent({ opts, catalog, gate });
+
+  // 4. Repo scoping (exclude client work).
+  const scope = await resolveScope({ opts, cwd: rootDir, catalog });
+  const consentEmail = (loadConsentState() || {}).email || null;
+  const agentRoots = scope.toplevels;
+
+  // 5. Aggregate scoped signals + rebuild scan/org-chart over the selection, re-classify.
+  await prefetchGitLogs(agentRoots, [GIT_ACTIVITY_LOG_ARGS, WORK_STREAMS_LOG_ARGS, AUTHORSHIP_LOG_ARGS]);
+  runAggregation({ report, scope, consentEmail, agentRoots, root, catalog });
+  const maturity = classify(report);
+  const hasAgents = Array.isArray(report.agents) && report.agents.length > 0;
+  report.analyzedRepos =
+    scope.mode === 'all'
+      ? null
+      : scope.toplevels.map((tl) => tl.split(/[/\\]/).pop() || tl);
+
+  // 6. The three ephemeral model calls, serialized and gated by consent.
+  await runModelCalls({
+    report, maturity, aiConsentGranted, opts, gate, hasAgents, agentRoots, rootDir, lang, catalog,
+  });
+  return { report, maturity, root, gate };
+}
+
+// The MCP's scan: same steps, returned instead of printed, since stdout is its JSON-RPC channel.
+async function scanUsage(argv) {
+  const opts = parseArgs(argv);
+  const lang = opts.lang || detectReportLang();
+  const { report, maturity } = await computeUsage({ opts, catalog: getCatalog(lang), lang });
+  return { report, maturity };
+}
+
+module.exports = {
+  performScan,
+  collectIdentityAndUsage,
+  reanchorReusedGrant,
+  storedAiConsent,
+  runAggregation,
+  runModelCalls,
+  computeUsage,
+  scanUsage,
+};