kushi-agents 3.4.2 → 3.13.0

package/plugin/skills/pull-onenote/runner.mjs

@@ -0,0 +1,356 @@
+#!/usr/bin/env node
+// pull-onenote runner — browser-scrape via Playwright with persisted profile.
+// Per pull-onenote SKILL.md v2.6.0 (kushi v3.8.0).
+//
+// Usage:
+//   node runner.mjs --bootstrap                                     # first-time interactive sign-in only
+//   node runner.mjs --preflight                                     # check OneNote-for-Web is reachable; exits 0/3
+//   node runner.mjs --project HCA --section-url "<deep-link>"       # full enumerate + fetch
+//   node runner.mjs --project HCA --section-url "..." --headless    # for scheduled / unattended runs
+//   node runner.mjs --project HCA --section-url "..." --titles "4/3 - HCA with Jay and Martin,5/7"
+//
+// Output is a single JSON object on stdout containing:
+//   { project, sectionUrl, pages: [{ title, pos, total, webPageId, last_status, captured_via, body, bodyLen, capturedAt }],
+//     runStatus: 'ok' | 'auth-required' | 'notebook-unavailable' | 'partial',
+//     authRequiredCount, exitedEarly, preflight: { ok, reason?, detail? } }
+//
+// runStatus 'notebook-unavailable' means OneNote-for-Web itself failed to render
+// (Sorry-we-ran-into-a-problem dialog, or root surface never loaded). This is a
+// service/notebook-side failure, NOT an auth problem — the kushi driver MUST surface
+// it as a clear diagnostic and skip the run rather than retry blindly. See SKILL.md §A.4.
+//
+// The skill driver (PowerShell or Clawpilot itself) is responsible for:
+//   - merging the per-page records into m365-mutable.json#knownSections.<projectKey>.one_pages[]
+//   - writing the snapshot pages/*.md files
+//   - writing the run report
+
+import { chromium } from 'playwright';
+import path from 'node:path';
+import os from 'node:os';
+import process from 'node:process';
+
+const args = Object.fromEntries(
+  process.argv.slice(2).reduce((acc, cur, idx, arr) => {
+    if (cur.startsWith('--')) {
+      const key = cur.replace(/^--/, '');
+      const next = arr[idx + 1];
+      acc.push([key, next && !next.startsWith('--') ? next : true]);
+    }
+    return acc;
+  }, [])
+);
+
+const PROFILE_DIR = path.join(os.homedir(), '.copilot', 'playwright-profile', 'onenote');
+const HEADLESS = !!args.headless;
+const BOOTSTRAP = !!args.bootstrap;
+const PREFLIGHT = !!args.preflight;
+const SKIP_PREFLIGHT = !!args['skip-preflight'];
+const PROJECT = args.project || null;
+const SECTION_URL = args['section-url'] || null;
+const TITLES_FILTER = args.titles ? String(args.titles).split(',').map(s => s.trim()) : null;
+const TIMEOUT_MS = parseInt(args.timeout || '60000', 10);
+const SETTLE_MS = parseInt(args.settle || '2500', 10);
+const PREFLIGHT_TIMEOUT_MS = parseInt(args['preflight-timeout'] || '25000', 10);
+
+if (!BOOTSTRAP && !PREFLIGHT && (!PROJECT || !SECTION_URL)) {
+  console.error('Usage: --project <name> --section-url <url> [--headless] [--titles "t1,t2"]');
+  console.error('       --bootstrap      (first-time interactive sign-in)');
+  console.error('       --preflight      (check OneNote-for-Web is reachable; exits 0/3)');
+  process.exit(2);
+}
+
+function isLoginRedirect(url) {
+  return /login\.microsoftonline\.com|login\.live\.com/.test(url);
+}
+
+// kushi v3.11.0 — pre-flight gate for OneNote-for-Web reachability.
+// Distinguishes three end-states at the OneNote SaaS root:
+//   ok                     — notebook list / account chrome rendered → safe to navigate to section
+//   auth-required          — bounced to login.microsoftonline.com
+//   onenote-web-unavailable — "Sorry, we ran into a problem" or render-timeout
+// We must distinguish #3 from #2 because retrying with fresh auth won't fix it —
+// the user has to recover the notebook (open in OneNote desktop, force sync, wait).
+async function preflightOneNoteWeb(page, timeoutMs) {
+  const ERROR_DIALOG_RE = /Sorry, we ran into a problem|Something went wrong|We couldn.?t open|There was a problem|This notebook can.?t be opened/i;
+  try {
+    await page.goto('https://onenote.cloud.microsoft/', { timeout: timeoutMs });
+  } catch (e) {
+    return { ok: false, reason: 'onenote-web-unavailable', detail: `navigation failed: ${e.message}` };
+  }
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (isLoginRedirect(page.url())) {
+      return { ok: false, reason: 'auth-required', detail: `redirected to ${page.url()}` };
+    }
+    // Error dialog text (rendered in any frame).
+    for (const f of page.frames()) {
+      try {
+        const txt = await f.evaluate(() => document.body ? document.body.innerText : '');
+        if (txt && ERROR_DIALOG_RE.test(txt)) {
+          const m = txt.match(ERROR_DIALOG_RE);
+          return { ok: false, reason: 'onenote-web-unavailable', detail: `error dialog: "${m[0]}"` };
+        }
+      } catch (e) { /* frame detached, ignore */ }
+    }
+    // Success indicators — any one is sufficient.
+    const ready = await page.$('[aria-label*="Account manager" i], [data-automationid="NotebookList"], button[aria-label*="notebook" i], iframe[src*="onenoteframe.aspx"]');
+    if (ready) return { ok: true };
+    await page.waitForTimeout(500);
+  }
+  return { ok: false, reason: 'onenote-web-unavailable', detail: `timed out after ${timeoutMs}ms — neither sign-in, error dialog, nor notebook chrome rendered` };
+}
+
+function parseWebPageIdFromUrl(url) {
+  // wd=target(SectionName|sectionFileId/PageTitle|webPageId/)
+  const m = decodeURIComponent(url).match(/\|([0-9a-f-]{36})\/\)/i);
+  return m ? m[1] : null;
+}
+
+(async () => {
+  // v3.10.1: use the user's installed Edge (Intune-compliant) instead of Playwright's
+  // vanilla Chromium. Microsoft tenant Conditional Access blocks non-managed Chromium
+  // with "You can't get there from here" — only Edge (or compliant Chrome with extension)
+  // is permitted. Edge channel = Playwright drives the local Edge install with full
+  // Intune trust. Empirically validated 2026-05-14 against AGCO + HCA.
+  const ctx = await chromium.launchPersistentContext(PROFILE_DIR, {
+    headless: HEADLESS && !BOOTSTRAP,
+    channel: 'msedge',
+    viewport: { width: 1400, height: 900 },
+    args: ['--disable-blink-features=AutomationControlled']
+  });
+  const page = ctx.pages()[0] || await ctx.newPage();
+
+  if (BOOTSTRAP) {
+    // v3.10.1: walk both the OneNote-for-Web SaaS surface AND a SharePoint personal-site URL
+    // so the persisted profile carries cookies for BOTH cookie domains. The runner's section
+    // URLs (Doc.aspx) live on sharepoint(-df).com — those cookies are not set by visiting
+    // onenote.cloud.microsoft alone.
+    const SPO_HOSTS_TO_SEED = [
+      'https://microsoft-my.sharepoint.com/',
+      'https://microsoft-my.sharepoint-df.com/'
+    ];
+    await page.goto('https://onenote.cloud.microsoft/');
+    console.error('[bootstrap] Step 1/2: Sign in to OneNote-for-Web. After your name appears top-right, do NOT close the window — wait for the next prompt.');
+    // Wait for an actual sign-in indicator (notebook chrome / account manager), NOT just the URL —
+    // the URL matches instantly because we just navigated TO onenote.cloud.microsoft, which made
+    // the prior implementation skip the sign-in wait entirely. Up to 5 min for the user to sign in.
+    try {
+      await page.waitForSelector(
+        '[aria-label*="Account manager" i], [data-automationid="NotebookList"], button[aria-label*="notebook" i], iframe[src*="onenoteframe.aspx"]',
+        { timeout: 5 * 60 * 1000 }
+      );
+      await page.waitForTimeout(2000);
+      console.error('[bootstrap] Sign-in detected (OneNote chrome rendered).');
+    } catch (e) {
+      console.error('[bootstrap] WARNING: sign-in indicator not detected within 5 minutes — cookies may not be valid.');
+    }
+
+    // Now seed SharePoint cookies by visiting the personal-site root for each tenant variant.
+    // If the user has a personal site at that host, SSO will complete silently (cookies set).
+    // If the host doesn't exist for the tenant, the page will 404 — harmless.
+    for (const host of SPO_HOSTS_TO_SEED) {
+      try {
+        console.error(`[bootstrap] Step 2/2: Seeding SharePoint cookies at ${host}`);
+        await page.goto(host, { timeout: 60000 });
+        await page.waitForTimeout(4000);
+      } catch (e) {
+        console.error(`[bootstrap] (skipped ${host}: ${e.message})`);
+      }
+    }
+    console.error('[bootstrap] Both surfaces visited. Close the browser window when ready.');
+    try {
+      await page.waitForEvent('close', { timeout: 5 * 60 * 1000 });
+    } catch (e) { /* timeout = user left window open; we still saved cookies on each visit */ }
+    console.error('[bootstrap] Profile saved at: ' + PROFILE_DIR);
+    await ctx.close();
+    process.exit(0);
+  }
+
+  // --preflight standalone mode: just probe the OneNote-for-Web root and exit.
+  // Exit codes: 0 = ok, 3 = onenote-web-unavailable, 4 = auth-required, 1 = unexpected.
+  if (PREFLIGHT) {
+    const pf = await preflightOneNoteWeb(page, PREFLIGHT_TIMEOUT_MS);
+    console.log(JSON.stringify({ preflight: pf }, null, 2));
+    await ctx.close();
+    if (pf.ok) process.exit(0);
+    if (pf.reason === 'auth-required') process.exit(4);
+    if (pf.reason === 'onenote-web-unavailable') process.exit(3);
+    process.exit(1);
+  }
+
+  let runStatus = 'ok';
+  let exitedEarly = false;
+  let authRequiredCount = 0;
+  const out = { project: PROJECT, sectionUrl: SECTION_URL, pages: [] };
+
+  // kushi v3.11.0 — inline pre-flight before navigating to the section URL.
+  // Catches the "OneNote-for-Web is broken / notebook won't open" state EARLY,
+  // so we don't waste TIMEOUT_MS waiting for a canvas frame that will never attach
+  // and then mislabel the failure as auth-required.
+  const pf = SKIP_PREFLIGHT ? { ok: true, skipped: true } : await preflightOneNoteWeb(page, PREFLIGHT_TIMEOUT_MS);
+  out.preflight = pf;
+  if (!pf.ok) {
+    const rs = pf.reason === 'auth-required' ? 'auth-required' : 'notebook-unavailable';
+    console.log(JSON.stringify({
+      ...out,
+      runStatus: rs,
+      exitedEarly: true,
+      error: `pre-flight ${pf.reason}: ${pf.detail}`
+    }, null, 2));
+    await ctx.close();
+    process.exit(0);
+  }
+
+  try {
+    await page.goto(SECTION_URL, { timeout: TIMEOUT_MS });
+
+    // Account picker handling — one quick attempt to pick the only listed account.
+    try {
+      await page.waitForSelector('button:has-text("Sign in with"), iframe[name="WebApplicationFrame"]', { timeout: 15000 });
+      const pickerBtn = await page.$('button:has-text("Sign in with")');
+      if (pickerBtn) await pickerBtn.click();
+    } catch (e) { /* no picker */ }
+
+    // Wait for the OneNote canvas frame to attach. Concurrently watch for the
+    // "Sorry, we ran into a problem" dialog so we can fail fast with the correct
+    // diagnostic (notebook-unavailable, NOT auth-required).
+    const SECTION_ERROR_RE = /Sorry, we ran into a problem|Something went wrong|We couldn.?t open|This notebook can.?t be opened|There was a problem/i;
+    let wac = null;
+    let sectionErrorDetail = null;
+    const deadline = Date.now() + TIMEOUT_MS;
+    while (Date.now() < deadline) {
+      wac = page.frames().find(f => f.url().includes('onenoteframe.aspx'));
+      if (wac) break;
+      if (isLoginRedirect(page.url())) {
+        runStatus = 'auth-required';
+        exitedEarly = true;
+        break;
+      }
+      // Probe every frame for the section-load error dialog.
+      for (const f of page.frames()) {
+        try {
+          const txt = await f.evaluate(() => document.body ? document.body.innerText : '');
+          if (txt && SECTION_ERROR_RE.test(txt)) {
+            const m = txt.match(SECTION_ERROR_RE);
+            sectionErrorDetail = `"${m[0]}" at ${f.url() || page.url()}`;
+            break;
+          }
+        } catch (e) { /* detached */ }
+      }
+      if (sectionErrorDetail) {
+        runStatus = 'notebook-unavailable';
+        exitedEarly = true;
+        break;
+      }
+      await page.waitForTimeout(500);
+    }
+    if (!wac) {
+      if (sectionErrorDetail) {
+        console.log(JSON.stringify({
+          ...out,
+          runStatus: 'notebook-unavailable',
+          exitedEarly: true,
+          error: `OneNote-for-Web returned an error dialog instead of rendering the section: ${sectionErrorDetail}. This is NOT auth-required — recover the notebook (open in OneNote desktop, force sync) or re-capture one_sectionWebUrl from the address bar.`
+        }, null, 2));
+        await ctx.close();
+        process.exit(0);
+      }
+      if (!exitedEarly) runStatus = 'auth-required';
+      console.log(JSON.stringify({ ...out, runStatus, exitedEarly: true, error: 'OneNote canvas frame did not attach (likely auth required).' }, null, 2));
+      await ctx.close();
+      process.exit(0);
+    }
+
+    // Wait for the page-rail to render. Honor --timeout (default 60s) instead of 30s
+    // hardcoded — large notebooks (e.g. AGCO with many sections) can be slow to enumerate.
+    // Single-page sections render as "<title>, Page. Selected." (no "page N of M") so we
+    // accept either format.
+    await wac.waitForFunction(() =>
+      Array.from(document.querySelectorAll('[aria-label]')).some(n => {
+        const l = n.getAttribute('aria-label') || '';
+        return /, page \d+ of \d+, Page\./.test(l) || /, Page\. Selected\./.test(l);
+      })
+    , null, { timeout: TIMEOUT_MS });
+
+    // Step A — enumerate
+    const pages = await wac.evaluate(() => {
+      const out = [];
+      const seen = new Set();
+      for (const n of document.querySelectorAll('[aria-label]')) {
+        const label = n.getAttribute('aria-label') || '';
+        let m = label.match(/^(.*?), page (\d+) of (\d+), Page/);
+        if (m) {
+          const key = `${m[1]}|${m[2]}`;
+          if (!seen.has(key)) { seen.add(key); out.push({ title: m[1], pos: parseInt(m[2]), total: parseInt(m[3]) }); }
+          continue;
+        }
+        m = label.match(/^(.*?), Page\. Selected\./);
+        if (m) {
+          const key = `${m[1]}|1`;
+          if (!seen.has(key)) { seen.add(key); out.push({ title: m[1], pos: 1, total: 1 }); }
+        }
+      }
+      return out;
+    });
+
+    const queue = TITLES_FILTER ? pages.filter(p => TITLES_FILTER.includes(p.title)) : pages;
+
+    // Step B — per-page navigate + extract
+    for (const p of queue) {
+      let captured_via = 'browser';
+      let last_status = 'captured';
+      let webPageId = null;
+      let body = '';
+
+      try {
+        await wac.evaluate((title) => {
+          const tgt = Array.from(document.querySelectorAll('[aria-label]'))
+            .find(n => (n.getAttribute('aria-label') || '').startsWith(title + ', page'));
+          if (tgt) tgt.click();
+        }, p.title);
+        await page.waitForTimeout(SETTLE_MS);
+
+        if (isLoginRedirect(page.url())) {
+          runStatus = 'auth-required';
+          exitedEarly = true;
+          last_status = 'auth-required';
+          authRequiredCount++;
+          out.pages.push({ ...p, webPageId, last_status, captured_via, body: '', bodyLen: 0, capturedAt: new Date().toISOString() });
+          break;
+        }
+
+        webPageId = parseWebPageIdFromUrl(page.url());
+        body = await wac.evaluate(() => {
+          const node = document.querySelector('#PageContentWrapper')
+                    || document.querySelector('.Page')
+                    || document.querySelector('[role="main"]');
+          return node ? node.innerText : '';
+        });
+
+        if (!body || body.length < 50) last_status = 'short-suspect';
+      } catch (e) {
+        last_status = 'browser-error';
+        runStatus = runStatus === 'ok' ? 'partial' : runStatus;
+      }
+
+      out.pages.push({
+        ...p,
+        webPageId,
+        last_status,
+        captured_via,
+        body,
+        bodyLen: body.length,
+        capturedAt: new Date().toISOString()
+      });
+    }
+  } catch (e) {
+    runStatus = isLoginRedirect(page.url()) ? 'auth-required' : 'partial';
+    out.error = String(e && e.message || e);
+  }
+
+  out.runStatus = runStatus;
+  out.exitedEarly = exitedEarly;
+  out.authRequiredCount = authRequiredCount;
+  console.log(JSON.stringify(out, null, 2));
+  await ctx.close();
+})().catch(e => { console.error(e); process.exit(1); });

package/plugin/skills/pull-onenote/scripts/recapture-section-url.mjs

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+// recapture-section-url.mjs
+//
+// Usage:
+//   node recapture-section-url.mjs --project <name> --engagement-root <path> [--url <url>] [--check]
+//
+// Purpose:
+//   Fill / repair the browser-required OneNote registry fields for a project so
+//   pull-onenote's Playwright runner can navigate directly to the section URL.
+//
+//   Browser-required keys (all must be present):
+//     - one_sectionName          (e.g. "AGCO.one")
+//     - one_sectionFileId        (GUID inside wd=target(...|<GUID>/))
+//     - one_notebookSourceDoc    (GUID inside sourcedoc={<GUID>})
+//     - one_notebookSpoBaseUrl   (https://<host>/personal/<upn>)
+//     - one_sectionWebUrl        (full Doc.aspx URL — regenerated)
+//
+// Modes:
+//   --check  : exit 0 if all five present, 1 if missing. Prints JSON status.
+//   --url U  : non-interactive parse + persist (used when caller already has the URL).
+//   default  : interactive — prompt user to paste the URL on stdin.
+//
+// Doctrine:
+//   This is the canonical "self-heal browser fields" path used by both
+//   bootstrap-project (Step 4a) and refresh-project (Step 2 OneNote pre-dispatch).
+//   It is NOT re-discovery — wdsectionfileid is preserved if already present and
+//   only the browser-side fields are added/repaired.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+
+const args = Object.fromEntries(process.argv.slice(2).reduce((acc, a, i, arr) => {
+  if (a.startsWith('--')) {
+    const k = a.slice(2);
+    const v = (arr[i + 1] && !arr[i + 1].startsWith('--')) ? arr[i + 1] : 'true';
+    acc.push([k, v]);
+  }
+  return acc;
+}, []));
+
+const PROJECT = args.project;
+const ENGAGEMENT_ROOT = args['engagement-root'];
+const URL_ARG = args.url && args.url !== 'true' ? args.url : null;
+const CHECK_ONLY = args.check === 'true';
+
+if (!PROJECT || !ENGAGEMENT_ROOT) {
+  console.error('Usage: --project <name> --engagement-root <path> [--url <url>] [--check]');
+  process.exit(2);
+}
+
+const REG_PATH = path.join(ENGAGEMENT_ROOT, '.project-evidence', 'm365', 'm365-mutable.json');
+if (!fs.existsSync(REG_PATH)) {
+  console.error(`[recapture-section-url] Registry not found: ${REG_PATH}`);
+  process.exit(3);
+}
+
+const REQUIRED_KEYS = [
+  'one_sectionName',
+  'one_sectionFileId',
+  'one_notebookSourceDoc',
+  'one_notebookSpoBaseUrl',
+  'one_sectionWebUrl'
+];
+
+function loadRegistry() {
+  return JSON.parse(fs.readFileSync(REG_PATH, 'utf8'));
+}
+
+function findEntry(reg, project) {
+  const sections = reg?.m365Mutable?.knownSections || {};
+  // exact > prefix > contains, case-insensitive
+  const keys = Object.keys(sections);
+  const lower = project.toLowerCase();
+  let key = keys.find(k => k.toLowerCase() === lower)
+        || keys.find(k => k.toLowerCase().startsWith(lower))
+        || keys.find(k => k.toLowerCase().includes(lower));
+  if (!key) return { key: null, entry: null };
+  return { key, entry: sections[key] };
+}
+
+function completeness(entry) {
+  const missing = REQUIRED_KEYS.filter(k => !entry || !entry[k] || String(entry[k]).trim() === '');
+  return { complete: missing.length === 0, missing };
+}
+
+// HARD RULE (kushi v3.10.2+): one_sectionWebUrl MUST be the URL the user actually copied
+// from the OneNote-for-Web address bar. There is NO reliable formula to synthesize it.
+// Two formulas were tried and both failed:
+//   - wd=target(<name>|<fileId>/)   → "Sorry, we ran into a problem"
+//   - wd=target(/<name>/)           → "Sorry, we ran into a problem" for some sections
+// Even when the section name and notebook GUIDs are correct, OneNote's routing requires
+// query params we cannot reverse-engineer (likely a wd token or session-bound parameter).
+// HCA's URL works because the user opened it once and copied it; AGCO's must do the same.
+//
+// Auto-heal MAY inherit notebook-level fields from siblings (one_notebookSourceDoc,
+// one_notebookSpoBaseUrl, one_notebookName) — these are identical across all sections
+// in the same notebook. But one_sectionWebUrl MUST NOT be synthesized — the gate must
+// fall through to the interactive paste prompt.
+
+function tryAutoHeal(reg, key, entry) {
+  // Inherit ONLY notebook-level fields (sourceDoc, spoBaseUrl, name). The section URL
+  // itself cannot be inherited or synthesized — it must be user-pasted.
+  let sourcedocGuid = entry.one_notebookSourceDoc;
+  let baseUrl = entry.one_notebookSpoBaseUrl;
+  let notebookName = entry.one_notebookName;
+  let inheritedFrom = null;
+
+  if (!sourcedocGuid || !baseUrl) {
+    const sections = reg.m365Mutable.knownSections;
+    for (const [siblingKey, sibling] of Object.entries(sections)) {
+      if (siblingKey === key) continue;
+      if (!sibling.one_notebookSourceDoc || !sibling.one_notebookSpoBaseUrl) continue;
+      if (sibling.one_confidence !== 'high') continue;
+      sourcedocGuid = sourcedocGuid || sibling.one_notebookSourceDoc;
+      baseUrl = baseUrl || sibling.one_notebookSpoBaseUrl;
+      notebookName = notebookName || sibling.one_notebookName;
+      inheritedFrom = siblingKey;
+      break;
+    }
+  }
+
+  if (!sourcedocGuid || !baseUrl) return null;
+
+  // Return notebook-level fields ONLY. Caller must still prompt for one_sectionWebUrl
+  // unless the entry already has one (preserved from a prior --url paste).
+  return {
+    fields: {
+      one_notebookSourceDoc: sourcedocGuid,
+      one_notebookSpoBaseUrl: baseUrl,
+      one_notebookName: notebookName || null
+    },
+    inheritedFrom,
+    stillNeedsPaste: !entry.one_sectionWebUrl
+  };
+}
+
+function parseUrl(rawUrl) {
+  // Decode in case of %-escaped wd= and sourcedoc= fragments.
+  let url;
+  try {
+    url = new URL(rawUrl);
+  } catch (e) {
+    throw new Error('Not a valid URL.');
+  }
+  if (!/sharepoint(-df)?\.com/i.test(url.host)) {
+    throw new Error('URL host does not look like SharePoint (must contain sharepoint.com or sharepoint-df.com).');
+  }
+  if (!/Doc\.aspx$/i.test(url.pathname)) {
+    throw new Error('URL path must end with Doc.aspx (open the section in OneNote-for-Web and copy the address bar URL).');
+  }
+
+  const sourcedoc = url.searchParams.get('sourcedoc');
+  if (!sourcedoc) throw new Error('URL is missing the sourcedoc query parameter.');
+  const sourcedocGuid = sourcedoc.replace(/[{}]/g, '').trim();
+  if (!/^[0-9a-f-]{36}$/i.test(sourcedocGuid)) throw new Error(`sourcedoc is not a GUID: ${sourcedoc}`);
+
+  const wdRaw = url.searchParams.get('wd');
+  if (!wdRaw) throw new Error('URL is missing the wd query parameter (open the section, not just the notebook).');
+  const wdDecoded = decodeURIComponent(wdRaw);
+  // Accept either form — both are valid wd= shapes that OneNote emits at different times.
+  // Form 1: target(<name>|<GUID>/...)
+  // Form 2: target(/<name>/)
+  let sectionName = null;
+  let sectionFileId = null;
+  let m1 = wdDecoded.match(/^target\(([^|)/]+)\|([0-9a-f-]{36})/i);
+  if (m1) {
+    sectionName = m1[1];
+    sectionFileId = m1[2];
+  } else {
+    let m2 = wdDecoded.match(/^target\(\/([^/)]+)\//i);
+    if (m2) sectionName = m2[1];
+  }
+  if (!sectionName) throw new Error(`wd target could not be parsed: ${wdDecoded}`);
+
+  const personalMatch = url.pathname.match(/^(\/personal\/[^/]+)/i);
+  if (!personalMatch) throw new Error('URL pathname does not contain /personal/<upn> — is this a personal OneDrive notebook?');
+  const baseUrl = `${url.origin}${personalMatch[1]}`;
+
+  // PRESERVE the user's URL verbatim — no reformulation. This is the URL the runner
+  // navigates to. Empirically, only user-captured URLs route correctly in OneNote-for-Web.
+  return {
+    one_sectionName: sectionName,
+    one_sectionFileId: sectionFileId,  // may be null if user pasted form 2; that's OK
+    one_notebookSourceDoc: sourcedocGuid,
+    one_notebookSpoBaseUrl: baseUrl,
+    one_sectionWebUrl: rawUrl
+  };
+}
+
+function persist(reg, key, fields) {
+  const sections = reg.m365Mutable.knownSections;
+  if (!sections[key]) sections[key] = {};
+  const entry = sections[key];
+  for (const [k, v] of Object.entries(fields)) {
+    entry[k] = v;
+  }
+  entry.one_discoveredOn = new Date().toISOString().slice(0, 10);
+  entry.one_confidence = 'high';
+  // Bump file metadata.
+  reg.m365Mutable.metadata.lastUpdated = new Date().toISOString().slice(0, 10);
+  reg.m365Mutable.metadata.lastUpdatedAt = new Date().toISOString();
+  reg.m365Mutable.metadata.lastUpdatedBy = 'kushi-recapture-section-url v0.1.0';
+  fs.writeFileSync(REG_PATH, JSON.stringify(reg, null, 2) + '\n', 'utf8');
+}
+
+async function promptUrl() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+  console.error('');
+  console.error(`[recapture-section-url] Browser-required OneNote fields are missing for project "${PROJECT}".`);
+  console.error('');
+  console.error('To fix this:');
+  console.error('  1. Open https://onenote.cloud.microsoft/ in your normal browser (Edge).');
+  console.error('  2. Open the project notebook and CLICK INTO the project section (e.g. <Project>.one).');
+  console.error('  3. Copy the entire URL from the address bar.');
+  console.error('  4. Paste it here and press Enter.');
+  console.error('');
+  return new Promise(resolve => {
+    rl.question('Paste OneNote section URL: ', answer => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+(async () => {
+  const reg = loadRegistry();
+  const { key, entry } = findEntry(reg, PROJECT);
+
+  if (!key) {
+    if (CHECK_ONLY) {
+      console.log(JSON.stringify({ status: 'no-entry', project: PROJECT, missing: REQUIRED_KEYS }));
+      process.exit(1);
+    }
+    console.error(`[recapture-section-url] No knownSections entry for "${PROJECT}". Run bootstrap-project first.`);
+    process.exit(4);
+  }
+
+  const status = completeness(entry);
+  if (CHECK_ONLY) {
+    console.log(JSON.stringify({ status: status.complete ? 'ok' : 'incomplete', project: key, missing: status.missing }));
+    process.exit(status.complete ? 0 : 1);
+  }
+
+  if (status.complete && !URL_ARG) {
+    console.error(`[recapture-section-url] Project "${key}" already has all browser-required fields. Nothing to do.`);
+    console.log(JSON.stringify({ status: 'ok', project: key, missing: [] }));
+    process.exit(0);
+  }
+
+  // Auto-heal path: if we have wdsectionfileid + section name and a sibling project shares the notebook,
+  // infer notebookSourceDoc + spoBaseUrl from that sibling. No human input required.
+  if (!URL_ARG) {
+    const auto = tryAutoHeal(reg, key, entry);
+    if (auto) {
+      // Cross-check existing one_sectionWebUrl: if it differs from the canonical we'd write, warn (we'll overwrite).
+      if (entry.one_sectionWebUrl && entry.one_sectionWebUrl !== auto.fields.one_sectionWebUrl) {
+        console.error(`[recapture-section-url] Replacing stale one_sectionWebUrl with canonical form (auto-healed from sibling "${auto.inheritedFrom}").`);
+      } else {
+        console.error(`[recapture-section-url] Auto-healing browser fields for "${key}" using shared-notebook pattern (sibling: "${auto.inheritedFrom}").`);
+      }
+      persist(reg, key, auto.fields);
+      console.error(`[recapture-section-url] ✅ Persisted ${Object.keys(auto.fields).length} browser fields for "${key}" → m365-mutable.json#knownSections.${key}`);
+      console.log(JSON.stringify({ status: 'persisted', project: key, mode: 'auto-heal', inheritedFrom: auto.inheritedFrom, fields: auto.fields }));
+      process.exit(0);
+    }
+  }
+
+  let rawUrl = URL_ARG;
+  if (!rawUrl) {
+    rawUrl = await promptUrl();
+    if (!rawUrl) {
+      console.error('[recapture-section-url] No URL provided. Aborting.');
+      process.exit(5);
+    }
+  }
+
+  let fields;
+  try {
+    fields = parseUrl(rawUrl);
+  } catch (e) {
+    console.error(`[recapture-section-url] Could not parse URL: ${e.message}`);
+    process.exit(6);
+  }
+
+  // Cross-check: if registry already had a one_sectionFileId, warn (don't block) on mismatch.
+  if (entry.one_sectionFileId && entry.one_sectionFileId !== fields.one_sectionFileId) {
+    console.error(`[recapture-section-url] WARNING: existing one_sectionFileId (${entry.one_sectionFileId}) differs from URL (${fields.one_sectionFileId}). Overwriting with URL value (browser path is canonical).`);
+  }
+
+  persist(reg, key, fields);
+  console.error(`[recapture-section-url] ✅ Persisted browser fields for "${key}" → m365-mutable.json#knownSections.${key}`);
+  console.log(JSON.stringify({ status: 'persisted', project: key, fields }));
+  process.exit(0);
+})();