kushi-agents 6.3.0 → 6.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kushi-agents",
-  "version": "6.3.0",
+  "version": "6.5.0",
   "description": "Install Kushi — multi-source project evidence agent with Comprehensive Structured Capture (CSC) into weekly-only files across Email, Teams, OneNote, Loop, SharePoint, Meetings, CRM, ADO. Meetings retain a sibling verbatim/ audit folder. WorkIQ-only for M365 sources (Graph / m365_* FORBIDDEN as fallbacks; user-paste is first-class). Host-agnostic.",
   "type": "module",
   "bin": {

package/plugin/runners/bootstrap.mjs

@@ -29,7 +29,7 @@ import { writeAtomic, pathExists } from './lib/evidence.mjs';
 import { writeRefreshReport, writeBootstrapStatus, appendRunLog } from './lib/runlog.mjs';
 
 function parseArgs(argv) {
-  const args = { force: false, dryRun: false, lookbackDays: null, interactive: false };
+  const args = { force: false, dryRun: false, lookbackDays: null, interactive: false, full: false, since: null };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--project') args.project = argv[++i];
@@ -38,6 +38,8 @@ function parseArgs(argv) {
     else if (a === '--dry-run') args.dryRun = true;
     else if (a === '--lookback-days') args.lookbackDays = Number(argv[++i]);
     else if (a === '--interactive' || a === '-i') args.interactive = true;
+    else if (a === '--full') args.full = true;
+    else if (a === '--since') args.since = argv[++i];
     else if (a === '--help' || a === '-h') args.help = true;
   }
   return args;
@@ -48,6 +50,12 @@ function help() {
     'Usage: node bootstrap.mjs --project <P> --alias <A> [options]',
     '',
     'Options:',
+    '  --full              After scaffolding, also run `discover` and `refresh',
+    '                      --since <floor>` so that on first run you get a fully',
+    '                      populated Evidence/ tree across all weeks back to the',
+    '                      lookback floor (default: 2026-03-01 if --since not set).',
+    '  --since YYYY-MM-DD  Used with --full. Lookback floor for refresh week loop.',
+    '                      Defaults to 2026-03-01 (engagement start) if omitted.',
     '  --interactive       Prompt for the 3 fields that most affect discover speed',
     '                      (email folders, look-back days, OneNote notebook) and',
     '                      stamp them into .kushi/config/user/m365-auth.json. Non-',
@@ -226,8 +234,8 @@ async function interactiveSetup({ workspace, dryRun }) {
 function emit(obj) { process.stdout.write(JSON.stringify(obj) + '\n'); }
 
 const INTEGRATIONS_TEMPLATE = {
-  crm: { instance: 'https://iscrm.crm.dynamics.com', table: 'incidents', request_id: null, record_id: null },
-  ado: { organization: 'IndustrySolutions', project: 'IS Engagements', apiVersion: '7.1', engagement_id: null },
+  crm: { instance: 'https://iscrm.crm.dynamics.com', table: 'incidents', request_id: '<__FILL_ME_IN__>', record_id: '<__FILL_ME_IN__>' },
+  ado: { organization: 'IndustrySolutions', project: 'IS Engagements', apiVersion: '7.1', engagement_id: '<__FILL_ME_IN__>' },
   sharepoint: { allowed_tenants: [] },
 };
 
@@ -417,6 +425,15 @@ async function main() {
     } catch { /* bootstrap-report is diagnostics-only, never block */ }
   }
 
+  // v6.4.0: --full flag — after scaffolding, also run discover + refresh
+  // --since <floor> so a first-run on a fresh project produces a fully
+  // populated Evidence/ tree without manual orchestration.
+  let chainResults = null;
+  if (args.full && !args.dryRun) {
+    const since = args.since || '2026-03-01';
+    chainResults = await runFullChain({ project: args.project, alias: args.alias, since });
+  }
+
   emit({
     status: 'ok',
     project: root,
@@ -428,10 +445,43 @@ async function main() {
     ...(statusPath ? { status_md: path.relative(root, statusPath) } : {}),
     ...(dateFloorReport ? { date_floor: dateFloorReport } : {}),
     ...(interactiveReport ? { interactive: interactiveReport } : {}),
+    ...(chainResults ? { full_chain: chainResults } : {}),
   });
   return 0;
 }
 
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+async function runFullChain({ project, alias, since }) {
+  const HERE = path.dirname(fileURLToPath(import.meta.url));
+  const out = { since, discover: null, refresh: null };
+
+  process.stderr.write(`\n[bootstrap --full] step 1/2: discover\n`);
+  out.discover = await spawnAndCapture(path.join(HERE, 'discover.mjs'), ['--project', project, '--alias', alias]);
+  process.stderr.write(`[bootstrap --full] discover exit=${out.discover.exit_code}\n`);
+
+  process.stderr.write(`[bootstrap --full] step 2/2: refresh --since ${since}\n`);
+  out.refresh = await spawnAndCapture(path.join(HERE, 'refresh.mjs'), ['--project', project, '--alias', alias, '--since', since]);
+  process.stderr.write(`[bootstrap --full] refresh exit=${out.refresh.exit_code}\n`);
+
+  return out;
+}
+
+function spawnAndCapture(runner, argv) {
+  return new Promise(resolve => {
+    const proc = spawn(process.execPath, [runner, ...argv], { stdio: ['ignore', 'pipe', 'inherit'] });
+    let stdout = '';
+    proc.stdout.on('data', d => { stdout += d.toString(); process.stderr.write(d); });
+    proc.on('close', code => {
+      let parsed = null;
+      const lastLine = stdout.trim().split('\n').filter(Boolean).pop();
+      try { parsed = lastLine ? JSON.parse(lastLine) : null; } catch { /* not JSON */ }
+      resolve({ exit_code: code, parsed });
+    });
+  });
+}
+
 main().then(code => { process.exitCode = code; }).catch(e => {
   emit({ status: 'failed', errors: [{ message: e.message }] });
   process.exit(1);

package/plugin/runners/discover.mjs

@@ -252,17 +252,26 @@ function applyRows(source, rows, currentBounds, currentInteg) {
   }
   if (source === 'meetings') {
     const existing = currentBounds.meetings?.joinUrls || [];
+    // v6.5.0: meeting boundaries MUST be real http(s) join URLs — pull-meetings
+    // can't resolve a subject string into a meeting at the WorkIQ layer (unlike
+    // teams chat topics). Reject anything that isn't a URL; track rejected
+    // subjects in `accepted` log via reason field for discover-report visibility.
+    const rejectedSubjects = [];
     const incoming = rows.map(r => {
       const url = r.join_url;
-      if (url && !isPlaceholder(url) && isValidValueFor('meetings', 'join_url', url) && url.startsWith('http')) return url;
+      if (url && !isPlaceholder(url) && isValidValueFor('meetings', 'join_url', url) && /^https?:\/\//.test(url)) return url;
       const subj = r.subject;
-      if (subj && !isPlaceholder(subj)) return subj;
+      if (subj && !isPlaceholder(subj)) rejectedSubjects.push(subj);
       return null;
     }).filter(Boolean);
     const merged = dedup([...existing, ...incoming]);
     const added = merged.filter(v => !existing.includes(v));
     if (added.length) accepted.push(...added);
-    return { boundariesPatch: added.length ? { meetings: { joinUrls: merged } } : null, accepted };
+    return {
+      boundariesPatch: added.length ? { meetings: { joinUrls: merged } } : null,
+      accepted,
+      rejected: rejectedSubjects.length ? rejectedSubjects.map(s => ({ subject: s, reason: 'no-join-url' })) : undefined,
+    };
   }
   if (source === 'onenote') {
     const existing = currentBounds.onenote?.section_file_ids || [];
@@ -303,7 +312,7 @@ function applyRows(source, rows, currentBounds, currentInteg) {
       isValidValueFor('crm', 'request_id', r.request_id) ||
       isValidValueFor('crm', 'incident_number', r.incident_number)
     );
-    if (!top) return { integrationsPatch: null, accepted: [] };
+    if (!top) return { integrationsPatch: null, accepted: [], unresolved: 'crm.request_id' };
     const id = isValidValueFor('crm', 'request_id', top.request_id) ? top.request_id : top.incident_number;
     const patch = { crm: { ...cur, request_id: id } };
     accepted.push(id);
@@ -318,7 +327,7 @@ function applyRows(source, rows, currentBounds, currentInteg) {
       isValidValueFor('ado', 'engagement_id', r.engagement_id) ||
       isValidValueFor('ado', 'work_item_id', r.work_item_id)
     );
-    if (!top) return { integrationsPatch: null, accepted: [] };
+    if (!top) return { integrationsPatch: null, accepted: [], unresolved: 'ado.engagement_id' };
     const id = isValidValueFor('ado', 'engagement_id', top.engagement_id) ? top.engagement_id : top.work_item_id;
     const patch = { ado: { ...cur, engagement_id: id } };
     accepted.push(id);
@@ -448,7 +457,7 @@ async function main() {
         : `${skipReason} after ${elapsed}ms: ${(e.message || '').split('\n')[0].slice(0, 200)}`;
       log(`  ${source}: ✗ ${detail}`);
     }
-    const { boundariesPatch, integrationsPatch, accepted } = applyRows(source, rows, bounds, integ);
+    const { boundariesPatch, integrationsPatch, accepted, rejected, unresolved } = applyRows(source, rows, bounds, integ);
     if (boundariesPatch) {
       Object.assign(bounds, mergeShallow(bounds, boundariesPatch));
       boundsDirty = true;
@@ -457,7 +466,7 @@ async function main() {
       Object.assign(integ, mergeShallow(integ, integrationsPatch));
       integDirty = true;
     }
-    sourceResults.push({ source, asked, found: rows.length, accepted, skipped_reason: skipReason });
+    sourceResults.push({ source, asked, found: rows.length, accepted, rejected, unresolved, skipped_reason: skipReason });
   }
 
   log(`done: ${sourceResults.filter(r => r.found > 0).length}/${total} sources returned data`);

package/plugin/runners/refresh.mjs

@@ -1,317 +1,362 @@
-#!/usr/bin/env node
-// plugin/runners/refresh.mjs
-// Deterministic orchestrator: reads boundaries.yml + integrations.yml,
-// expands into target cells (source, entity, week), invokes per-source
-// pull-*.mjs runners as subprocesses, aggregates JSON results.
-//
-// Usage:
-//   node plugin/runners/refresh.mjs --project <P> --alias <A>
-//     [--week YYYY-MM-DD]            # default: current ISO Monday
-//     [--source <src>]               # only run one source
-//     [--entity <e>]                 # only run one entity (requires --source)
-//     [--mode bootstrap|refresh]     # default: refresh
-//     [--force] [--dry-run] [--fixture-dir <dir>]
-//     [--max-parallel <n>]           # default 1 (serial)
-//
-// Stdout: JSON object { project, alias, week, mode, results: [<per-runner JSON>...] }
-// Exit 0 always (per-runner failures surface in results[].status).
-
-import path from 'node:path';
-import { promises as fs } from 'node:fs';
-import { spawn } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-import { loadConfig, assertProject } from './lib/config.mjs';
-import { readLedger, needsPull } from './lib/ledger.mjs';
-import { currentIsoMonday, ymd } from './lib/weeks.mjs';
-import { readCandidateCount } from './lib/learnings.mjs';
-import { writeRefreshReport, appendRunLog } from './lib/runlog.mjs';
-
-const HERE = path.dirname(fileURLToPath(import.meta.url));
-
-const SOURCE_RUNNERS = {
-  crm: 'pull-crm.mjs',
-  ado: 'pull-ado.mjs',
-  email: 'pull-email.mjs',
-  teams: 'pull-teams.mjs',
-  meetings: 'pull-meetings.mjs',
-  onenote: 'pull-onenote.mjs',
-  sharepoint: 'pull-sharepoint.mjs',
-};
-
-function parseArgs(argv) {
-  const args = { force: false, dryRun: false, mode: 'refresh', maxParallel: 1 };
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === '--project') args.project = argv[++i];
-    else if (a === '--alias') args.alias = argv[++i];
-    else if (a === '--week') args.week = argv[++i];
-    else if (a === '--source') args.source = argv[++i];
-    else if (a === '--entity') args.entity = argv[++i];
-    else if (a === '--mode') args.mode = argv[++i];
-    else if (a === '--force') args.force = true;
-    else if (a === '--dry-run') args.dryRun = true;
-    else if (a === '--fixture-dir') args.fixtureDir = argv[++i];
-    else if (a === '--max-parallel') args.maxParallel = Math.max(1, parseInt(argv[++i], 10) || 1);
-    else if (a === '--help' || a === '-h') args.help = true;
-  }
-  return args;
-}
-
-function help() {
-  return `Usage: node refresh.mjs --project <P> --alias <A> [--week YYYY-MM-DD]
-  [--source <crm|ado|email|teams|meetings|onenote|sharepoint>] [--entity <e>]
-  [--mode bootstrap|refresh] [--force] [--dry-run] [--max-parallel <n>]
-  [--fixture-dir <dir>]   # use <fixture-dir>/<source>.json for each runner`;
-}
-
-function emit(obj) { process.stdout.write(JSON.stringify(obj) + '\n'); }
-
-/**
- * Build the (source, entity) target list from integrations + boundaries config.
- * Returns: [{ source, entity }, ...]
- */
-export function buildTargets(merged) {
-  const targets = [];
-  // crm: from integrations
-  const crm = merged.crm || {};
-  const crmEntity = crm.request_id || crm.record_id;
-  if (crmEntity) targets.push({ source: 'crm', entity: String(crmEntity) });
-  // ado
-  const ado = merged.ado || {};
-  if (ado.engagement_id) targets.push({ source: 'ado', entity: String(ado.engagement_id) });
-  // email: per-user mailbox folders
-  const email = merged.email || {};
-  for (const f of (email.folders || [])) {
-    const entity = typeof f === 'string' ? f : (f.displayName || f.name || f.id);
-    if (entity) targets.push({ source: 'email', entity: String(entity), mailbox: typeof f === 'object' ? f.mailbox : email.mailbox });
-  }
-  // teams: chat ids
-  const teams = merged.teams || {};
-  for (const c of (teams.chats || [])) {
-    const entity = typeof c === 'string' ? c : (c.chat_id || c.id);
-    if (entity) targets.push({ source: 'teams', entity: String(entity) });
-  }
-  // meetings: joinUrls
-  const meetings = merged.meetings || {};
-  const meetingList = meetings.joinUrls || meetings.meetings || [];
-  for (const m of meetingList) {
-    const entity = typeof m === 'string' ? m : (m.joinUrl || m.id);
-    if (entity) targets.push({ source: 'meetings', entity: String(entity) });
-  }
-  // onenote: section_file_ids
-  const on = merged.onenote || {};
-  for (const s of (on.section_file_ids || [])) {
-    const entity = typeof s === 'string' ? s : (s.id || s.section_file_id);
-    if (entity) targets.push({ source: 'onenote', entity: String(entity) });
-  }
-  // sharepoint: site urls
-  const sp = merged.sharepoint || {};
-  for (const s of (sp.sites || [])) {
-    const entity = typeof s === 'string' ? s : (s.url || s.site_url);
-    if (entity) targets.push({ source: 'sharepoint', entity: String(entity) });
-  }
-  return targets;
-}
-
-function spawnRunner(runner, args) {
-  return new Promise(resolve => {
-    const proc = spawn(process.execPath, [runner, ...args], { stdio: ['ignore', 'pipe', 'pipe'] });
-    let stdout = '', stderr = '';
-    proc.stdout.on('data', d => stdout += d.toString());
-    proc.stderr.on('data', d => stderr += d.toString());
-    proc.on('close', code => {
-      let parsed = null;
-      const lastLine = stdout.trim().split('\n').filter(Boolean).pop();
-      try { parsed = lastLine ? JSON.parse(lastLine) : null; } catch { /* not JSON */ }
-      resolve({ exitCode: code, stdout, stderr, parsed });
-    });
-  });
-}
-
-async function runOne(target, weekStart, args) {
-  const runner = path.join(HERE, SOURCE_RUNNERS[target.source]);
-  const argv = ['--project', args.project, '--alias', args.alias, '--entity', target.entity, '--week', weekStart];
-  if (args.force) argv.push('--force');
-  // NOTE: orchestrator-level --dry-run is handled by skipping runOne entirely
-  // (see main()). We deliberately do not propagate --dry-run to children.
-  if (target.mailbox) { argv.push('--mailbox', target.mailbox); }
-  // source-specific config from integrations
-  if (target.source === 'crm' && target.instance) { argv.push('--instance', target.instance); }
-  if (target.source === 'ado') {
-    if (target.organization) argv.push('--organization', target.organization);
-    if (target.adoProject) argv.push('--ado-project', target.adoProject);
-    if (target.apiVersion) argv.push('--api-version', target.apiVersion);
-  }
-  if (target.source === 'sharepoint' && target.allowedTenants) argv.push('--allowed-tenants', target.allowedTenants);
-  if (args.fixtureDir) {
-    const fx = path.join(args.fixtureDir, `${target.source}.json`);
-    argv.push('--fixture', fx);
-  }
-  const res = await spawnRunner(runner, argv);
-  return {
-    source: target.source,
-    entity: target.entity,
-    week: weekStart,
-    exit_code: res.exitCode,
-    parsed: res.parsed,
-    stderr: res.stderr ? res.stderr.split('\n').slice(0, 5).join('\n') : '',
-  };
-}
-
-async function pMap(items, limit, fn) {
-  const results = new Array(items.length);
-  let i = 0;
-  const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
-    while (true) {
-      const idx = i++;
-      if (idx >= items.length) return;
-      results[idx] = await fn(items[idx], idx);
-    }
-  });
-  await Promise.all(workers);
-  return results;
-}
-
-async function main() {
-  const args = parseArgs(process.argv.slice(2));
-  if (args.help) { console.log(help()); return 0; }
-  if (!args.project || !args.alias) {
-    console.error(help());
-    emit({ status: 'failed', errors: [{ signature: 'bad-args' }] });
-    return 2;
-  }
-
-  await assertProject(args.project);
-  const cfg = await loadConfig(args.project, args.alias);
-  const weekStart = args.week || ymd(currentIsoMonday());
-
-  let targets = buildTargets(cfg.merged);
-
-  // Attach source-specific config
-  for (const t of targets) {
-    if (t.source === 'crm') t.instance = cfg.merged.crm && cfg.merged.crm.instance;
-    if (t.source === 'ado') {
-      t.organization = cfg.merged.ado && cfg.merged.ado.organization;
-      t.adoProject = cfg.merged.ado && cfg.merged.ado.project;
-      t.apiVersion = cfg.merged.ado && cfg.merged.ado.apiVersion;
-    }
-    if (t.source === 'sharepoint') {
-      const allowed = cfg.merged.sharepoint && cfg.merged.sharepoint.allowed_tenants;
-      if (Array.isArray(allowed) && allowed.length) t.allowedTenants = allowed.join(',');
-    }
-  }
-
-  // Filter by --source / --entity
-  if (args.source) targets = targets.filter(t => t.source === args.source);
-  if (args.entity) targets = targets.filter(t => t.entity === args.entity);
-
-  // Apply needsPull filter (unless --force)
-  const ledger = await readLedger(args.project, args.alias);
-  const planned = [];
-  const skipped = [];
-  for (const t of targets) {
-    const cellKey = `${t.source}::${t.entity}::${weekStart}`;
-    const cell = ledger.entries[cellKey];
-    const decision = needsPull(cell, weekStart, { mode: args.mode, force: args.force });
-    if (decision.pull) planned.push({ ...t, reason: decision.reason });
-    else skipped.push({ source: t.source, entity: t.entity, reason: decision.reason });
-  }
-
-  // Run planned targets. At the orchestrator level, --dry-run means
-  // "show the plan without spawning workers" — we do NOT delegate dry-run
-  // to children, because per-runner dry-run semantics vary (some skip
-  // writes but still HTTP). Refresh-level dry-run is plan-only.
-  const results = args.dryRun
-    ? planned.map(t => ({ source: t.source, entity: t.entity, week: weekStart, dry_run: true, reason: t.reason }))
-    : await pMap(planned, args.maxParallel, t => runOne(t, weekStart, args));
-
-  // v5.9.0: post-pass — unified references pool. Scans Evidence for URLs and
-  // builds a project-shared dedup index with HTTP snapshots for external links.
-  let referencesResult = null;
-  let stateResult = null;
-  if (!args.dryRun) {
-    const refsRunner = path.join(HERE, 'pull-references.mjs');
-    const refsArgv = ['--project', args.project];
-    if (args.force) refsArgv.push('--refresh');
-    const r = await spawnRunner(refsRunner, refsArgv);
-    referencesResult = { source: 'references', exit_code: r.exitCode, stdout: r.stdout?.slice(0, 4000), stderr: r.stderr?.slice(0, 1000) };
-
-    // v5.9.0 / v6.2.0: post-pass — deterministic State/ generator. Inventory
-    // only; build-state LLM skill remains the synthesis layer.
-    const stateRunner = path.join(HERE, 'pull-state.mjs');
-    const s = await spawnRunner(stateRunner, ['--project', args.project]);
-    stateResult = { source: 'state', exit_code: s.exitCode, stdout: s.stdout?.slice(0, 4000), stderr: s.stderr?.slice(0, 1000) };
-  }
-
-  const learning_candidates_total = args.dryRun ? 0 : await readCandidateCount(args.project);
-
-  // v6.0.1: orchestrator-level diagnostics — write a refresh report and append
-  // run-log entries for EVERY result (captured / no-activity / partial /
-  // deferred / failed). Per-runner appendRunLog calls only fired on success
-  // before, so failures left no audit trail beyond the ephemeral stdout JSON.
-  const counts = { captured: 0, 'no-activity': 0, partial: 0, deferred: 0, failed: 0, other: 0 };
-  for (const r of results) {
-    const status = r?.parsed?.status || (r?.dry_run ? 'dry-run' : 'unknown');
-    if (counts[status] !== undefined) counts[status]++; else counts.other++;
-  }
-  if (!args.dryRun) {
-    try {
-      await writeRefreshReport(args.project, args.alias, {
-        type: args.mode,
-        summary: `${args.mode} ${weekStart}: planned=${planned.length} skipped=${skipped.length} captured=${counts.captured} no-activity=${counts['no-activity']} partial=${counts.partial} deferred=${counts.deferred} failed=${counts.failed}`,
-        details: {
-          week: weekStart,
-          mode: args.mode,
-          planned: planned.length,
-          skipped: skipped.length,
-          counts,
-          results: results.map(r => ({
-            source: r.source,
-            entity: r.entity,
-            status: r?.parsed?.status,
-            exit_code: r.exit_code,
-            errors: r?.parsed?.errors,
-          })),
-        },
-      });
-    } catch (e) { /* refresh-report is diagnostics-only, never block */ }
-
-    for (const r of results) {
-      const status = r?.parsed?.status;
-      if (!status || status === 'captured') continue; // captured already logged by per-runner
-      try {
-        await appendRunLog(args.project, {
-          runner: `pull-${r.source}`,
-          alias: args.alias,
-          entity: r.entity,
-          week: weekStart,
-          status,
-          via: 'refresh-orchestrator',
-          errors: r?.parsed?.errors,
-        });
-      } catch (e) { /* run-log is append-only diagnostics */ }
-    }
-  }
-
-  emit({
-    status: 'ok',
-    project: args.project,
-    alias: args.alias,
-    week: weekStart,
-    mode: args.mode,
-    dry_run: args.dryRun,
-    planned: planned.length,
-    skipped: skipped.length,
-    results,
-    skipped_targets: skipped,
-    references: referencesResult,
-    state: stateResult,
-    learning_candidates_total,
-  });
-  return 0;
-}
-
-main().then(code => { process.exitCode = code; }).catch(e => {
-  emit({ status: 'failed', errors: [{ message: e.message }] });
-  process.exit(1);
-});
+#!/usr/bin/env node
+// plugin/runners/refresh.mjs
+// Deterministic orchestrator: reads boundaries.yml + integrations.yml,
+// expands into target cells (source, entity, week), invokes per-source
+// pull-*.mjs runners as subprocesses, aggregates JSON results.
+//
+// Usage:
+//   node plugin/runners/refresh.mjs --project <P> --alias <A>
+//     [--week YYYY-MM-DD]            # default: current ISO Monday
+//     [--source <src>]               # only run one source
+//     [--entity <e>]                 # only run one entity (requires --source)
+//     [--mode bootstrap|refresh]     # default: refresh
+//     [--force] [--dry-run] [--fixture-dir <dir>]
+//     [--max-parallel <n>]           # default 1 (serial)
+//
+// Stdout: JSON object { project, alias, week, mode, results: [<per-runner JSON>...] }
+// Exit 0 always (per-runner failures surface in results[].status).
+
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { loadConfig, assertProject } from './lib/config.mjs';
+import { readLedger, needsPull } from './lib/ledger.mjs';
+import { currentIsoMonday, ymd, isoWeeksBetween, isoMondayString } from './lib/weeks.mjs';
+import { readCandidateCount } from './lib/learnings.mjs';
+import { writeRefreshReport, appendRunLog } from './lib/runlog.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+const SOURCE_RUNNERS = {
+  crm: 'pull-crm.mjs',
+  ado: 'pull-ado.mjs',
+  email: 'pull-email.mjs',
+  teams: 'pull-teams.mjs',
+  meetings: 'pull-meetings.mjs',
+  onenote: 'pull-onenote.mjs',
+  sharepoint: 'pull-sharepoint.mjs',
+};
+
+function parseArgs(argv) {
+  const args = { force: false, dryRun: false, mode: 'refresh', maxParallel: 1 };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--project') args.project = argv[++i];
+    else if (a === '--alias') args.alias = argv[++i];
+    else if (a === '--week') args.week = argv[++i];
+    else if (a === '--since') args.since = argv[++i];
+    else if (a === '--source') args.source = argv[++i];
+    else if (a === '--entity') args.entity = argv[++i];
+    else if (a === '--mode') args.mode = argv[++i];
+    else if (a === '--force') args.force = true;
+    else if (a === '--dry-run') args.dryRun = true;
+    else if (a === '--fixture-dir') args.fixtureDir = argv[++i];
+    else if (a === '--max-parallel') args.maxParallel = Math.max(1, parseInt(argv[++i], 10) || 1);
+    else if (a === '--help' || a === '-h') args.help = true;
+  }
+  return args;
+}
+
+function help() {
+  return `Usage: node refresh.mjs --project <P> --alias <A> [--week YYYY-MM-DD]
+  [--source <crm|ado|email|teams|meetings|onenote|sharepoint>] [--entity <e>]
+  [--mode bootstrap|refresh] [--force] [--dry-run] [--max-parallel <n>]
+  [--fixture-dir <dir>]   # use <fixture-dir>/<source>.json for each runner`;
+}
+
+function emit(obj) { process.stdout.write(JSON.stringify(obj) + '\n'); }
+
+/**
+ * Build the (source, entity) target list from integrations + boundaries config.
+ * Returns: [{ source, entity }, ...]
+ */
+export function buildTargets(merged) {
+  const targets = [];
+  const isPlaceholder = (v) => v == null || /^<.*>$/.test(String(v).trim()) || /^(unknown|n\/a|none|null|tbd|todo)$/i.test(String(v).trim());
+  // crm: from integrations
+  const crm = merged.crm || {};
+  const crmEntity = crm.request_id || crm.record_id;
+  if (crmEntity && !isPlaceholder(crmEntity)) targets.push({ source: 'crm', entity: String(crmEntity) });
+  // ado
+  const ado = merged.ado || {};
+  if (ado.engagement_id && !isPlaceholder(ado.engagement_id)) targets.push({ source: 'ado', entity: String(ado.engagement_id) });
+  // email: per-user mailbox folders
+  const email = merged.email || {};
+  for (const f of (email.folders || [])) {
+    const entity = typeof f === 'string' ? f : (f.displayName || f.name || f.id);
+    if (entity) targets.push({ source: 'email', entity: String(entity), mailbox: typeof f === 'object' ? f.mailbox : email.mailbox });
+  }
+  // teams: chat ids
+  const teams = merged.teams || {};
+  for (const c of (teams.chats || [])) {
+    const entity = typeof c === 'string' ? c : (c.chat_id || c.id);
+    if (entity) targets.push({ source: 'teams', entity: String(entity) });
+  }
+  // meetings: joinUrls
+  const meetings = merged.meetings || {};
+  const meetingList = meetings.joinUrls || meetings.meetings || [];
+  for (const m of meetingList) {
+    const entity = typeof m === 'string' ? m : (m.joinUrl || m.id);
+    if (entity) targets.push({ source: 'meetings', entity: String(entity) });
+  }
+  // onenote: section_file_ids
+  const on = merged.onenote || {};
+  for (const s of (on.section_file_ids || [])) {
+    const entity = typeof s === 'string' ? s : (s.id || s.section_file_id);
+    if (entity) targets.push({ source: 'onenote', entity: String(entity) });
+  }
+  // sharepoint: site urls — boundaries first, integrations fallback (sharepoint
+  // is a SHARED source; sites usually live in integrations.yml since they
+  // don't vary per contributor)
+  const sp = merged.sharepoint || {};
+  let spSites = sp.sites || [];
+  if (!spSites.length && merged.__integrations_sharepoint_sites) {
+    spSites = merged.__integrations_sharepoint_sites;
+  }
+  for (const s of spSites) {
+    const entity = typeof s === 'string' ? s : (s.url || s.site_url);
+    if (entity) targets.push({ source: 'sharepoint', entity: String(entity) });
+  }
+  return targets;
+}
+
+function spawnRunner(runner, args) {
+  return new Promise(resolve => {
+    const proc = spawn(process.execPath, [runner, ...args], { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '', stderr = '';
+    proc.stdout.on('data', d => stdout += d.toString());
+    proc.stderr.on('data', d => stderr += d.toString());
+    proc.on('close', code => {
+      let parsed = null;
+      const lastLine = stdout.trim().split('\n').filter(Boolean).pop();
+      try { parsed = lastLine ? JSON.parse(lastLine) : null; } catch { /* not JSON */ }
+      resolve({ exitCode: code, stdout, stderr, parsed });
+    });
+  });
+}
+
+async function runOne(target, weekStart, args) {
+  const runner = path.join(HERE, SOURCE_RUNNERS[target.source]);
+  const argv = ['--project', args.project, '--alias', args.alias, '--entity', target.entity, '--week', weekStart];
+  if (args.force) argv.push('--force');
+  // NOTE: orchestrator-level --dry-run is handled by skipping runOne entirely
+  // (see main()). We deliberately do not propagate --dry-run to children.
+  if (target.mailbox) { argv.push('--mailbox', target.mailbox); }
+  // source-specific config from integrations
+  if (target.source === 'crm' && target.instance) { argv.push('--instance', target.instance); }
+  if (target.source === 'ado') {
+    if (target.organization) argv.push('--organization', target.organization);
+    if (target.adoProject) argv.push('--ado-project', target.adoProject);
+    if (target.apiVersion) argv.push('--api-version', target.apiVersion);
+  }
+  if (target.source === 'sharepoint' && target.allowedTenants) argv.push('--allowed-tenants', target.allowedTenants);
+  if (args.fixtureDir) {
+    const fx = path.join(args.fixtureDir, `${target.source}.json`);
+    argv.push('--fixture', fx);
+  }
+  const res = await spawnRunner(runner, argv);
+  return {
+    source: target.source,
+    entity: target.entity,
+    week: weekStart,
+    exit_code: res.exitCode,
+    parsed: res.parsed,
+    stderr: res.stderr ? res.stderr.split('\n').slice(0, 5).join('\n') : '',
+  };
+}
+
+async function pMap(items, limit, fn) {
+  const results = new Array(items.length);
+  let i = 0;
+  const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+    while (true) {
+      const idx = i++;
+      if (idx >= items.length) return;
+      results[idx] = await fn(items[idx], idx);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) { console.log(help()); return 0; }
+  if (!args.project || !args.alias) {
+    console.error(help());
+    emit({ status: 'failed', errors: [{ signature: 'bad-args' }] });
+    return 2;
+  }
+
+  await assertProject(args.project);
+  const cfg = await loadConfig(args.project, args.alias);
+
+  // v6.4.0: SharePoint sites fallback. Boundaries.yml almost never lists SP
+  // sites (WorkIQ doesn't reliably resolve them); they live in the project's
+  // integrations.yml. mergeConfigs uses arrayMode='replace' so an empty
+  // boundaries.sharepoint.sites would otherwise wipe integrations sites.
+  const intgSpSites = cfg.integrations?.sharepoint?.sites || [];
+  if (intgSpSites.length) cfg.merged.__integrations_sharepoint_sites = intgSpSites;
+
+  // v6.4.0: --since iterates ISO Mondays from `since` through current week.
+  // --week pins a single week (back-compat). Default = current week only.
+  const todayMonday = ymd(currentIsoMonday());
+  const weekList = args.since
+    ? isoWeeksBetween(args.since, new Date())
+    : [args.week || todayMonday];
+
+  let allResults = [];
+  let allPlanned = 0;
+  let allSkipped = 0;
+  const allCounts = { captured: 0, 'no-activity': 0, partial: 0, deferred: 0, failed: 0, other: 0 };
+  const skippedTargetsByWeek = [];
+
+  for (const weekStart of weekList) {
+    const weekRes = await runOneWeek({ args, cfg, weekStart });
+    allResults = allResults.concat(weekRes.results);
+    allPlanned += weekRes.planned;
+    allSkipped += weekRes.skipped;
+    for (const k of Object.keys(allCounts)) allCounts[k] += weekRes.counts[k] || 0;
+    skippedTargetsByWeek.push({ week: weekStart, skipped: weekRes.skipped_targets });
+  }
+
+  // v5.9.0: post-pass — unified references pool. Scans Evidence for URLs and
+  // builds a project-shared dedup index with HTTP snapshots for external links.
+  let referencesResult = null;
+  let stateResult = null;
+  if (!args.dryRun) {
+    const refsRunner = path.join(HERE, 'pull-references.mjs');
+    const refsArgv = ['--project', args.project];
+    if (args.force) refsArgv.push('--refresh');
+    const r = await spawnRunner(refsRunner, refsArgv);
+    referencesResult = { source: 'references', exit_code: r.exitCode, stdout: r.stdout?.slice(0, 4000), stderr: r.stderr?.slice(0, 1000) };
+
+    // v5.9.0 / v6.2.0: post-pass — deterministic State/ generator. Inventory
+    // only; build-state LLM skill remains the synthesis layer.
+    const stateRunner = path.join(HERE, 'pull-state.mjs');
+    const s = await spawnRunner(stateRunner, ['--project', args.project]);
+    stateResult = { source: 'state', exit_code: s.exitCode, stdout: s.stdout?.slice(0, 4000), stderr: s.stderr?.slice(0, 1000) };
+  }
+
+  const learning_candidates_total = args.dryRun ? 0 : await readCandidateCount(args.project);
+
+  // Aggregate report across all weeks
+  if (!args.dryRun) {
+    try {
+      const span = weekList.length === 1 ? weekList[0] : `${weekList[0]}..${weekList[weekList.length - 1]} (${weekList.length} wk)`;
+      await writeRefreshReport(args.project, args.alias, {
+        type: args.mode,
+        summary: `${args.mode} ${span}: planned=${allPlanned} skipped=${allSkipped} captured=${allCounts.captured} no-activity=${allCounts['no-activity']} partial=${allCounts.partial} deferred=${allCounts.deferred} failed=${allCounts.failed}`,
+        details: {
+          weeks: weekList,
+          mode: args.mode,
+          planned: allPlanned,
+          skipped: allSkipped,
+          counts: allCounts,
+          results: allResults.map(r => ({
+            source: r.source,
+            entity: r.entity,
+            week: r.week,
+            status: r?.parsed?.status,
+            exit_code: r.exit_code,
+            errors: r?.parsed?.errors,
+          })),
+        },
+      });
+    } catch (e) { /* refresh-report is diagnostics-only, never block */ }
+
+    for (const r of allResults) {
+      const status = r?.parsed?.status;
+      if (!status || status === 'captured') continue;
+      try {
+        await appendRunLog(args.project, {
+          runner: `pull-${r.source}`,
+          alias: args.alias,
+          entity: r.entity,
+          week: r.week,
+          status,
+          via: 'refresh-orchestrator',
+          errors: r?.parsed?.errors,
+        });
+      } catch (e) { /* run-log is append-only diagnostics */ }
+    }
+  }
+
+  emit({
+    status: 'ok',
+    project: args.project,
+    alias: args.alias,
+    weeks: weekList,
+    mode: args.mode,
+    dry_run: args.dryRun,
+    planned: allPlanned,
+    skipped: allSkipped,
+    counts: allCounts,
+    results: allResults,
+    skipped_targets_by_week: skippedTargetsByWeek,
+    references: referencesResult,
+    state: stateResult,
+    learning_candidates_total,
+  });
+  return 0;
+}
+
+async function runOneWeek({ args, cfg, weekStart }) {
+  let targets = buildTargets(cfg.merged);
+
+  // Attach source-specific config
+  for (const t of targets) {
+    if (t.source === 'crm') t.instance = cfg.merged.crm && cfg.merged.crm.instance;
+    if (t.source === 'ado') {
+      t.organization = cfg.merged.ado && cfg.merged.ado.organization;
+      t.adoProject = cfg.merged.ado && cfg.merged.ado.project;
+      t.apiVersion = cfg.merged.ado && cfg.merged.ado.apiVersion;
+    }
+    if (t.source === 'sharepoint') {
+      const allowed = cfg.merged.sharepoint && cfg.merged.sharepoint.allowed_tenants;
+      if (Array.isArray(allowed) && allowed.length) t.allowedTenants = allowed.join(',');
+    }
+  }
+
+  if (args.source) targets = targets.filter(t => t.source === args.source);
+  if (args.entity) targets = targets.filter(t => t.entity === args.entity);
+
+  const ledger = await readLedger(args.project, args.alias);
+  const planned = [];
+  const skipped = [];
+  for (const t of targets) {
+    const cellKey = `${t.source}::${t.entity}::${weekStart}`;
+    const cell = ledger.entries[cellKey];
+    const decision = needsPull(cell, weekStart, { mode: args.mode, force: args.force });
+    if (decision.pull) planned.push({ ...t, reason: decision.reason });
+    else skipped.push({ source: t.source, entity: t.entity, reason: decision.reason });
+  }
+
+  const results = args.dryRun
+    ? planned.map(t => ({ source: t.source, entity: t.entity, week: weekStart, dry_run: true, reason: t.reason }))
+    : await pMap(planned, args.maxParallel, t => runOne(t, weekStart, args));
+
+  // Tag results with their week for aggregate reporting
+  for (const r of results) { if (!r.week) r.week = weekStart; }
+
+  const counts = { captured: 0, 'no-activity': 0, partial: 0, deferred: 0, failed: 0, other: 0 };
+  for (const r of results) {
+    const status = r?.parsed?.status || (r?.dry_run ? 'dry-run' : 'unknown');
+    if (counts[status] !== undefined) counts[status]++; else counts.other++;
+  }
+
+  return {
+    week: weekStart,
+    planned: planned.length,
+    skipped: skipped.length,
+    skipped_targets: skipped,
+    counts,
+    results,
+  };
+}
+
+main().then(code => { process.exitCode = code; }).catch(e => {
+  emit({ status: 'failed', errors: [{ message: e.message }] });
+  process.exit(1);
+});