@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-workspace/src/api.mjs

@@ -0,0 +1,2086 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve, relative } from 'node:path';
+import { execSync, execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+import { hostname } from 'node:os';
+
+import { getSecretsStatus, setSecret, MISSING_TARGET_ERROR } from './secrets-api.mjs';
+import { detect as schedulerDetect, list as schedulerList } from '../../engineering-pa-core/src/scheduler/index.mjs';
+
+/**
+ * handleApi -- route handler for all API endpoints.
+ *
+ * Returns true if the request was handled, false otherwise.
+ * The caller (server.mjs) should fall through to static file serving
+ * when this returns false.
+ *
+ * @param {import('http').IncomingMessage} req
+ * @param {import('http').ServerResponse} res
+ * @param {URL} url
+ * @param {string} repoRoot  -- absolute path to the project root
+ * @param {object} [deps]    -- injectable bridges (tests only). Currently:
+ *                              deps.scheduler = { detect, list }.
+ * @returns {boolean}
+ */
+const SERVER_STARTED_AT = new Date().toISOString();
+
+export function handleApi(req, res, url, repoRoot, deps = {}) {
+  const pathname = url.pathname;
+  const method = req.method;
+
+  // GET /__api/identity -- lets the launcher recognise its own server
+  // so it can restart on an occupied port (and pick up server-side
+  // changes) instead of silently skipping.
+  if (method === 'GET' && pathname === '/__api/identity') {
+    sendJson(res, 200, {
+      server: 'dave-workspace',
+      repoRoot: repoRoot,
+      pid: process.pid,
+      startedAt: SERVER_STARTED_AT,
+    });
+    return true;
+  }
+
+  // POST /api/onboard
+  if (method === 'POST' && pathname === '/api/onboard') {
+    readBody(req).then((raw) => {
+      try {
+        const body = JSON.parse(raw);
+        const result = processOnboarding(body, repoRoot);
+        sendJson(res, 200, result);
+      } catch (err) {
+        sendJson(res, 400, { success: false, error: err.message });
+      }
+    }).catch((err) => {
+      sendJson(res, 500, { success: false, error: err.message });
+    });
+    return true;
+  }
+
+  // GET /__api/config
+  if (method === 'GET' && pathname === '/__api/config') {
+    try {
+      const prefsFile = join(repoRoot, 'operator', 'config', 'preferences.json');
+      let operator = { name: 'Operator', role: 'Operator' };
+      let pa = { name: 'PA', role: 'PA' };
+      if (existsSync(prefsFile)) {
+        const prefs = JSON.parse(readFileSync(prefsFile, 'utf-8'));
+        if (prefs.operator && prefs.operator.name) operator = prefs.operator;
+        if (prefs.pa && prefs.pa.name) pa = prefs.pa;
+      }
+      sendJson(res, 200, { operator, pa });
+    } catch (err) {
+      sendJson(res, 500, { error: err.message });
+    }
+    return true;
+  }
+
+  // GET /__api/projects
+  if (method === 'GET' && pathname === '/__api/projects') {
+    try {
+      const projects = walkProjects(repoRoot);
+      sendJson(res, 200, { projects });
+    } catch (err) {
+      sendJson(res, 500, { error: err.message });
+    }
+    return true;
+  }
+
+  // GET /__api/work
+  if (method === 'GET' && pathname === '/__api/work') {
+    try {
+      const work = walkWork(repoRoot);
+      sendJson(res, 200, { work });
+    } catch (err) {
+      sendJson(res, 500, { error: err.message });
+    }
+    return true;
+  }
+
+  // GET /__api/overview
+  if (method === 'GET' && pathname === '/__api/overview') {
+    try {
+      const projects = walkProjects(repoRoot);
+      const work = walkWork(repoRoot);
+      const overview = buildOverview(projects, work, repoRoot);
+      sendJson(res, 200, overview);
+    } catch (err) {
+      sendJson(res, 500, { error: err.message });
+    }
+    return true;
+  }
+
+  // GET /__api/knowledge
+  if (method === 'GET' && pathname === '/__api/knowledge') {
+    try {
+      const indexFile = join(repoRoot, 'operator', 'knowledge', 'index.json');
+      if (!existsSync(indexFile)) {
+        sendJson(res, 200, { domains: [], stats: { totalDocuments: 0, totalDomains: 0 } });
+        return true;
+      }
+      const index = JSON.parse(readFileSync(indexFile, 'utf-8'));
+      let totalDocs = 0;
+      const domains = (index.domains || []).map(function(d) {
+        // index.json paths are relative to operator/ (e.g. "knowledge/hr")
+        const domainPath = join(repoRoot, 'operator', d.path);
+        const documents = [];
+        if (existsSync(domainPath)) {
+          walkDocuments(domainPath, repoRoot, documents);
+        }
+        totalDocs += documents.length;
+        return {
+          id: d.id,
+          name: d.id,
+          description: d.description || '',
+          documentCount: documents.length,
+          documents: documents,
+        };
+      });
+      sendJson(res, 200, {
+        domains: domains,
+        stats: { totalDocuments: totalDocs, totalDomains: domains.length },
+      });
+    } catch (err) {
+      sendJson(res, 500, { error: err.message });
+    }
+    return true;
+  }
+
+  // GET /__api/profile
+  if (method === 'GET' && pathname === '/__api/profile') {
+    try {
+      const profileMd = join(repoRoot, 'operator', 'profile', 'profile.md');
+      const profileContent = existsSync(profileMd) ? readFileSync(profileMd, 'utf-8') : '';
+      const obsDir = join(repoRoot, 'operator', 'profile', 'observations');
+      const observations = [];
+      if (existsSync(obsDir)) {
+        readdirSync(obsDir)
+          .filter(function(f) { return f.endsWith('.md'); })
+          .sort()
+          .forEach(function(f) {
+            observations.push({ name: f, path: 'operator/profile/observations/' + f });
+          });
+      }
+      const slicesDir = join(repoRoot, 'operator', 'profile', 'slices');
+      const slices = [];
+      if (existsSync(slicesDir)) {
+        readdirSync(slicesDir)
+          .filter(function(f) { return f.endsWith('.md'); })
+          .sort()
+          .forEach(function(f) {
+            slices.push({ name: f, path: 'operator/profile/slices/' + f });
+          });
+      }
+      sendJson(res, 200, { profile: profileContent, observations: observations, slices: slices });
+    } catch (err) {
+      sendJson(res, 500, { error: err.message });
+    }
+    return true;
+  }
+
+  // GET /__api/file
+  if (method === 'GET' && pathname === '/__api/file') {
+    try {
+      const filePath = url.searchParams.get('path');
+      if (!filePath) {
+        sendJson(res, 400, { error: 'Missing path parameter' });
+        return true;
+      }
+      const absPath = resolve(repoRoot, filePath);
+      const rel = relative(repoRoot, absPath);
+      if (rel.startsWith('..') || resolve(repoRoot, rel) !== absPath) {
+        sendJson(res, 403, { error: 'Path must be within the project root' });
+        return true;
+      }
+      if (!existsSync(absPath)) {
+        sendJson(res, 404, { error: 'File not found' });
+        return true;
+      }
+      const content = readFileSync(absPath, 'utf-8');
+      sendJson(res, 200, { path: filePath, content });
+    } catch (err) {
+      sendJson(res, 500, { error: err.message });
+    }
+    return true;
+  }
+
+  // GET /__api/notes
+  if (method === 'GET' && pathname === '/__api/notes') {
+    try {
+      const notes = walkNotes(repoRoot);
+      sendJson(res, 200, { notes });
+    } catch (err) {
+      sendJson(res, 500, { error: err.message });
+    }
+    return true;
+  }
+
+  // GET /__api/secrets
+  // v0.5.3: scoped-vault aware. Enumerates EVERY vault visible from the
+  // workspace (legacy .vault/secrets.enc.json, workspace scopes
+  // .vault/scopes/*.enc.json, canonical vault/*.enc.json) with key NAMES
+  // read from the plaintext sops JSON structure — no decryption, no age
+  // key, no binaries required to list. Response:
+  //   { initialised, vaults: [{scope, layout, path, keys}], keys }
+  // `keys` is the deduplicated flat union kept for pre-0.5.3 consumers.
+  // Values are never present in any response.
+  if (method === 'GET' && pathname === '/__api/secrets') {
+    getSecretsStatus(repoRoot)
+      .then((result) => { sendJson(res, 200, result); })
+      .catch((err) => { sendJson(res, 500, { error: err.message }); });
+    return true;
+  }
+
+  // POST /__api/secrets
+  // v0.5.3: body is { key, value, vault } — `vault` is the REQUIRED explicit
+  // target ('legacy' or a scope name). A missing target is a 400, never a
+  // silent write to the legacy store.
+  if (method === 'POST' && pathname === '/__api/secrets') {
+    readBody(req).then(async (raw) => {
+      try {
+        const parsed = JSON.parse(raw);
+        const result = await setSecret(repoRoot, parsed.key, parsed.value, parsed.vault);
+        if (result.success) {
+          sendJson(res, 200, { success: true });
+        } else {
+          // Missing key/value/target are caller errors (400); anything else
+          // is a vault/system failure (500).
+          const isCallerError = result.error === 'Missing key or value'
+            || result.error === MISSING_TARGET_ERROR;
+          sendJson(res, isCallerError ? 400 : 500, { success: false, error: result.error });
+        }
+      } catch (err) {
+        sendJson(res, 500, { success: false, error: err.message });
+      }
+    }).catch((err) => {
+      sendJson(res, 500, { success: false, error: err.message });
+    });
+    return true;
+  }
+
+  // GET /__api/schedules
+  //
+  // v0.5.3: live backend detection is an IN-PROCESS import of the core
+  // scheduler module. The previous code shelled out to
+  // `core/tools/scheduler/{detect,list}.mjs` — v1 paths that don't exist in
+  // v2 installs — behind existsSync guards, so on every live estate host it
+  // silently skipped detection and reported backend:null / liveStatus:null
+  // ("0 installed") with no explanation. `schedulerError` is now ALWAYS
+  // present in the response: null exclusively when detect+list both
+  // succeeded, otherwise an explicit message — a silent null is impossible.
+  if (method === 'GET' && pathname === '/__api/schedules') {
+    try {
+      const scheduler = deps.scheduler || { detect: schedulerDetect, list: schedulerList };
+      const schedules = walkSchedules(repoRoot);
+      let liveStatus = null;
+      let backend = null;
+      let schedulerError = null;
+      try {
+        const detected = scheduler.detect();
+        const available = (detected && detected.available) || [];
+        const rec = available.find(function(b) { return b.recommended; });
+        backend = rec ? rec.backend : (available[0] ? available[0].backend : null);
+        if (!backend) {
+          schedulerError = 'no scheduling backend detected on this host (os: ' + (detected && detected.os ? detected.os : 'unknown') + ')';
+        }
+      } catch (err) {
+        schedulerError = 'scheduler detect failed: ' + (err && err.message ? err.message : String(err));
+      }
+      if (backend) {
+        try {
+          liveStatus = String(scheduler.list(backend)).trim();
+        } catch (err) {
+          schedulerError = 'scheduler list failed for backend "' + backend + '": ' + (err && err.message ? err.message : String(err));
+        }
+      }
+      const now = new Date();
+      const agenda = buildAgenda(schedules, now);
+      // Tab 1 (active schedules) needs a single next-run time per schedule —
+      // the agenda computes every occurrence within the next 7 days for its
+      // own bucketing, which is a different shape. Attach the same
+      // nextCronRuns computation, capped to one hit, directly onto each
+      // schedule so the compact list needs no separate round trip.
+      for (const s of schedules) {
+        s.nextRunAt = computeNextRunAt(s, now);
+      }
+      // Hostname is surfaced so the UI can clarify "managed here vs installed
+      // on a remote host" — HQ schedules frequently target smarthome01 while
+      // the operator may view the page from a laptop.
+      let host = null;
+      try { host = hostname(); } catch { /* non-fatal */ }
+      sendJson(res, 200, { schedules, liveStatus, backend, schedulerError, agenda, hostname: host });
+    } catch (err) {
+      // Always return 200 with empty data rather than 500 — but the failure
+      // itself is named, never silent.
+      let host = null;
+      try { host = hostname(); } catch { /* non-fatal */ }
+      sendJson(res, 200, {
+        schedules: [],
+        liveStatus: null,
+        backend: null,
+        schedulerError: 'schedules handler failed: ' + (err && err.message ? err.message : String(err)),
+        agenda: { today: [], tomorrow: [], thisWeek: [] },
+        hostname: host,
+      });
+    }
+    return true;
+  }
+
+  // GET /__api/repos
+  if (method === 'GET' && pathname === '/__api/repos') {
+    try {
+      // Check if gh CLI is available
+      try {
+        execSync('gh --version', { stdio: 'pipe', timeout: 5000 });
+      } catch {
+        sendJson(res, 200, { available: false, reason: 'gh CLI not installed. Install it from https://cli.github.com/ to enable repository features.' });
+        return true;
+      }
+      // Check if gh is authenticated
+      try {
+        execSync('gh auth status', { stdio: 'pipe', timeout: 5000 });
+      } catch {
+        sendJson(res, 200, { available: false, reason: 'gh CLI not authenticated. Run: gh auth login' });
+        return true;
+      }
+      // Fetch repos owned by user, sorted by pushed date
+      const reposRaw = execSync("gh repo list --json name,description,url,primaryLanguage,pushedAt,stargazerCount,isFork,isPrivate --limit 30 --no-archived", {
+        encoding: 'utf-8',
+        timeout: 15000,
+      }).trim();
+      let repos = [];
+      try {
+        repos = JSON.parse(reposRaw || '[]').map(function(r) {
+          return {
+            name: r.name,
+            description: r.description,
+            html_url: r.url,
+            language: r.primaryLanguage ? r.primaryLanguage.name : null,
+            pushed_at: r.pushedAt,
+            stargazers_count: r.stargazerCount || 0,
+            fork: r.isFork || false,
+            private: r.isPrivate || false,
+            open_issues_count: 0,
+          };
+        }).sort(function(a, b) {
+          return (b.pushed_at || '').localeCompare(a.pushed_at || '');
+        });
+      } catch { /* parse error — empty */ }
+      // Fetch open PRs authored by user
+      let prs = [];
+      try {
+        const prsRaw = execSync("gh search prs --author=@me --state=open --json title,url,repository,createdAt,updatedAt,isDraft --limit 20", {
+          encoding: 'utf-8',
+          timeout: 15000,
+        }).trim();
+        const parsed = JSON.parse(prsRaw || '[]');
+        prs = parsed.map(function(pr) {
+          return {
+            title: pr.title,
+            html_url: pr.url,
+            repo: pr.repository ? pr.repository.nameWithOwner : null,
+            created_at: pr.createdAt,
+            updated_at: pr.updatedAt,
+            draft: pr.isDraft || false,
+          };
+        });
+      } catch { /* non-fatal */ }
+      sendJson(res, 200, { available: true, repos: repos.slice(0, 30), openPrs: prs });
+    } catch (err) {
+      sendJson(res, 200, { available: false, reason: err.message });
+    }
+    return true;
+  }
+
+  // GET /__api/git-overview
+  // Rich cross-repo overview: owned repos, open PRs, configured-org repo
+  // activity, branch staleness, recent commits, contributor leaderboard.
+  // Configuration source: operator/config/preferences.json .gitOrgs (string[]).
+  // Always returns 200 — missing gh, auth, or orgs gracefully degrade.
+  //
+  // buildGitOverview is async because the owned-recent-commits fallback
+  // spawns `gh api` calls in parallel (see buildOwnedRecentCommits). We fire
+  // the promise and let it resolve the response — same shape either branch.
+  if (method === 'GET' && pathname === '/__api/git-overview') {
+    buildGitOverview(repoRoot).then(function(data) {
+      sendJson(res, 200, data);
+    }).catch(function(err) {
+      sendJson(res, 200, { available: false, reason: err.message });
+    });
+    return true;
+  }
+
+  // GET /__api/delegations
+  // Walks agents/*/spawn-log.json and aggregates into per-PA totals,
+  // recent spawns, and in-flight items. Generic — works in any deployment.
+  if (method === 'GET' && pathname === '/__api/delegations') {
+    try {
+      sendJson(res, 200, buildDelegations(repoRoot));
+    } catch (err) {
+      sendJson(res, 200, { agents: [], spawns: [], stats: {}, error: err.message });
+    }
+    return true;
+  }
+
+  // GET /__api/knowledge-map
+  // Reads operator/knowledge/domains.json + optional .graph.json /
+  // .backlinks.json and walks each domain tree for per-doc mtimes.
+  if (method === 'GET' && pathname === '/__api/knowledge-map') {
+    try {
+      sendJson(res, 200, buildKnowledgeMap(repoRoot));
+    } catch (err) {
+      sendJson(res, 200, { domains: [], stats: {}, error: err.message });
+    }
+    return true;
+  }
+
+  // GET /__api/staging
+  // Walks agents/*/staging/*.md, categorises by filename suffix, and
+  // returns age + short preview per file.
+  if (method === 'GET' && pathname === '/__api/staging') {
+    try {
+      sendJson(res, 200, buildStaging(repoRoot));
+    } catch (err) {
+      sendJson(res, 200, { agents: [], items: [], stats: {}, error: err.message });
+    }
+    return true;
+  }
+
+  // GET /__api/next-session
+  // Parses the PA's next-session.md ("## Top priority — start here", the
+  // "## On boot" checklist, the last-updated marker, and the raw body) so
+  // the homepage can render a pickup card without each consumer re-parsing
+  // the file. Absent file → present=false.
+  if (method === 'GET' && pathname === '/__api/next-session') {
+    try {
+      sendJson(res, 200, buildNextSession(repoRoot));
+    } catch (err) {
+      sendJson(res, 200, { present: false, error: err.message });
+    }
+    return true;
+  }
+
+  // GET /__api/status-mon
+  // Returns the state file written by the status-mon poller (see
+  // core/tools/status-mon/README.md). The endpoint never triggers a fetch —
+  // page loads stay fast regardless of upstream latency. Missing file →
+  // 404 (poller hasn't run yet); read/parse error → 500.
+  if (method === 'GET' && pathname === '/__api/status-mon') {
+    try {
+      const statePath = join(repoRoot, '.state', 'status-mon.json');
+      if (!existsSync(statePath)) {
+        sendJson(res, 404, { error: 'status-mon state file not found' });
+        return true;
+      }
+      const raw = readFileSync(statePath, 'utf-8');
+      const parsed = JSON.parse(raw);
+      sendJson(res, 200, parsed);
+    } catch (err) {
+      sendJson(res, 500, { error: err.message });
+    }
+    return true;
+  }
+
+  // Not an API route
+  return false;
+}
+
+
+// -- Onboarding logic -------------------------------------------------
+
+function processOnboarding(body, repoRoot) {
+  const name = body.name;
+  const email = body.email;
+  const role = body.role;
+  const skills = body.skills;
+  const purpose = body.purpose;
+  const paName = body.paName;
+  const communicationStyle = body.communicationStyle;
+  const taskManagement = body.taskManagement;
+
+  // Validation
+  if (!name || typeof name !== 'string') throw new Error('name is required');
+  if (!email || typeof email !== 'string') throw new Error('email is required');
+  if (!purpose || typeof purpose !== 'string') throw new Error('purpose is required');
+  if (!paName || typeof paName !== 'string') throw new Error('paName is required');
+  if (!communicationStyle || typeof communicationStyle !== 'string') throw new Error('communicationStyle is required');
+  if (!taskManagement || typeof taskManagement !== 'string') throw new Error('taskManagement is required');
+
+  // Sanitise paName: lowercase, alphanumeric + hyphens only
+  const safePaName = paName.toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
+  if (!safePaName) throw new Error('paName must contain at least one alphanumeric character');
+
+  const today = new Date().toISOString().slice(0, 10);
+
+  // Parse skills
+  const skillList = skills
+    ? skills.split(',').map(function(s) { return s.trim(); }).filter(Boolean)
+    : [];
+
+  // Resolve communication style text
+  const styleMap = {
+    'mirror-me': "Mirror the operator's tone and style. Match their energy, vocabulary, and formality level.",
+    'professional': 'Professional and clear. Well-structured responses, precise language, minimal informality.',
+    'casual': 'Casual and direct. Short sentences, contractions, light humour welcome. No corporate speak.',
+  };
+  const styleText = styleMap[communicationStyle] || communicationStyle;
+
+  // 1. operator/profile/operator.json
+  const profileDir = join(repoRoot, 'operator', 'profile');
+  mkdirSync(profileDir, { recursive: true });
+  writeJson(join(profileDir, 'operator.json'), {
+    name: name,
+    email: email,
+    role: role || '',
+    skills: skillList,
+    purpose: purpose,
+    created: today,
+  });
+
+  // 2. operator/config/preferences.json
+  const configDir = join(repoRoot, 'operator', 'config');
+  mkdirSync(configDir, { recursive: true });
+  writeJson(join(configDir, 'preferences.json'), {
+    paName: safePaName,
+    communicationStyle: communicationStyle,
+    taskManagement: taskManagement,
+    gitWorkflow: 'pr',
+    workspacePort: 4200,
+  });
+
+  // 3. agents/{paName}/ directory
+  const agentDir = join(repoRoot, 'agents', safePaName);
+  mkdirSync(join(agentDir, 'staging'), { recursive: true });
+
+  // CLAUDE.md from template
+  const templatePath = join(repoRoot, 'core', 'prompts', 'CLAUDE.md.template');
+  if (existsSync(templatePath)) {
+    let template = readFileSync(templatePath, 'utf-8');
+    template = template.replace(/\{PA_NAME\}/g, safePaName);
+    template = template.replace(/\{OPERATOR_NAME\}/g, name);
+    template = template.replace(/\{COMMUNICATION_STYLE\}/g, styleText);
+    template = template.replace(/\{PURPOSE\}/g, purpose);
+    writeFileSync(join(agentDir, 'CLAUDE.md'), template, 'utf-8');
+  }
+
+  // journal.md
+  writeFileSync(
+    join(agentDir, 'journal.md'),
+    '# ' + safePaName + ' Journal\n\nStarted: ' + today + '\n',
+    'utf-8'
+  );
+
+  // spawn-log.json
+  writeJson(join(agentDir, 'spawn-log.json'), { version: '1.0', spawns: [] });
+
+  // learned-rules.md
+  writeFileSync(
+    join(agentDir, 'learned-rules.md'),
+    '# Learned Rules\n\nOperational rules accumulated from corrections and experience.\nMaintained by the librarian during distillation sweeps.\nThe PA reads this file on every boot — rules here carry the same weight as CLAUDE.md.\n\n---\n\n_No rules yet. Rules will appear here as the librarian processes corrections from your sessions._\n',
+    'utf-8'
+  );
+
+  // next-session.md
+  writeFileSync(
+    join(agentDir, 'next-session.md'),
+    '# Next session\n\nFirst session! Welcome aboard.\n',
+    'utf-8'
+  );
+
+  // 4. projects/onboarding/project.json
+  const projectDir = join(repoRoot, 'projects', 'onboarding');
+  mkdirSync(projectDir, { recursive: true });
+  writeJson(join(projectDir, 'project.json'), {
+    id: 'onboarding',
+    name: 'Getting Started',
+    status: 'in-progress',
+    priority: 1,
+    owner: safePaName,
+    created: today,
+    summary: 'Your first project -- get set up and comfortable with your PA.',
+  });
+
+  // 5. Initial work items
+  const workDir = join(repoRoot, 'work');
+  mkdirSync(workDir, { recursive: true });
+
+  writeJson(join(workDir, 'w-' + today + '-001.json'), {
+    id: 'w-' + today + '-001',
+    title: 'Review and refine your profile',
+    category: 'chore',
+    status: 'planned',
+    priority: 1,
+    projectId: 'onboarding',
+    assignee: 'operator',
+    summary: 'Check your profile at operator/profile/operator.json and the dashboard Profile page. Add any missing details, correct anything that looks wrong, and add skills or context that will help your PA work better for you.',
+    created: today,
+  });
+
+  writeJson(join(workDir, 'w-' + today + '-002.json'), {
+    id: 'w-' + today + '-002',
+    title: 'Set up integrations',
+    category: 'chore',
+    status: 'planned',
+    priority: 2,
+    projectId: 'onboarding',
+    assignee: safePaName,
+    summary: 'Connect external tools your PA should work with: GitHub (gh CLI), MCP servers, IDE extensions. Check the blueprints directory for integration guides.',
+    created: today,
+  });
+
+  writeJson(join(workDir, 'w-' + today + '-003.json'), {
+    id: 'w-' + today + '-003',
+    title: 'Create your first knowledge entry',
+    category: 'chore',
+    status: 'planned',
+    priority: 2,
+    projectId: 'onboarding',
+    assignee: 'operator',
+    summary: 'Add something to operator/knowledge/ — a technical decision, a process you follow, a reference document. This seeds the knowledge system so your PA has context to work with.',
+    created: today,
+  });
+
+  writeJson(join(workDir, 'w-' + today + '-004.json'), {
+    id: 'w-' + today + '-004',
+    title: 'Set up scheduled tasks (distillation, backups)',
+    category: 'chore',
+    status: 'planned',
+    priority: 2,
+    projectId: 'onboarding',
+    assignee: safePaName,
+    summary: 'Configure recurring tasks: knowledge distillation sweep (critical — this is how your PA learns between sessions), and any backups or maintenance. Use the /schedule command or run core/tools/scheduler/install.mjs. The distillation sweep should run at least daily.',
+    created: today,
+  });
+
+  writeJson(join(workDir, 'w-' + today + '-005.json'), {
+    id: 'w-' + today + '-005',
+    title: 'Verify secrets vault and back up master key',
+    category: 'chore',
+    status: 'planned',
+    priority: 1,
+    projectId: 'onboarding',
+    assignee: 'operator',
+    summary: 'Check vault status with: pnpm exec secrets status. If not initialised, run pnpm exec secrets init. Back up your master key with pnpm exec secrets backup (opens QR code in browser).',
+    created: today,
+  });
+
+  // 6. Git init + initial commit
+  try {
+    const gitDir = join(repoRoot, '.git');
+    if (!existsSync(gitDir)) {
+      execSync('git init', { cwd: repoRoot, stdio: 'pipe' });
+    }
+    execSync('git add -A', { cwd: repoRoot, stdio: 'pipe' });
+    execSync('git commit -m "Initial setup via onboarding"', {
+      cwd: repoRoot,
+      stdio: 'pipe',
+      env: Object.assign({}, process.env, { GIT_AUTHOR_NAME: name, GIT_AUTHOR_EMAIL: email }),
+    });
+  } catch (e) {
+    // Non-fatal: git may not be available or commit may fail
+  }
+
+  // 7. Vault initialisation (non-fatal)
+  //
+  // NOTE (v0.1.5 — w-2026-05-18-014 follow-up): this code path still spawns
+  // a v1 stale path (`core/tools/secrets/bin/secrets`) that doesn't exist
+  // in v2 installs, and reads `~/.config/dave/age-key.txt` instead of the
+  // v2 `~/.config/stravica-pa/age-key.txt`. v0.1.5 fixes the live GET/POST
+  // /__api/secrets endpoints in-process; converting this onboarding flow
+  // to in-process requires making processOnboarding async, which is a
+  // larger refactor (callers of processOnboarding are sync). Tracked
+  // separately — see Notes in the v0.1.5 PR description.
+  var vault = { initialised: false, publicKey: null, privateKey: null, error: null };
+  try {
+    const vaultBin = join(repoRoot, 'core', 'tools', 'secrets', 'bin', 'secrets');
+    execSync('node "' + vaultBin + '" init', {
+      cwd: repoRoot,
+      stdio: 'pipe',
+      timeout: 30000,
+    });
+
+    // Read the private key for one-time QR backup display
+    const keyDir = join(process.env.HOME || '/tmp', '.config', 'dave');
+    const keyFile = join(keyDir, 'age-key.txt');
+    if (existsSync(keyFile)) {
+      const keyContents = readFileSync(keyFile, 'utf-8');
+      vault.initialised = true;
+      // Extract only the secret key line for QR code
+      const secretLine = keyContents.split('\n').find(function(l) { return l.startsWith('AGE-SECRET-KEY-'); });
+      vault.privateKey = secretLine || null;
+      // Read public key
+      const recipientsFile = join(repoRoot, '.vault', 'recipients.txt');
+      if (existsSync(recipientsFile)) {
+        vault.publicKey = readFileSync(recipientsFile, 'utf-8').trim();
+      }
+    }
+  } catch (e) {
+    vault.error = e.message;
+  }
+
+  return { success: true, redirect: '/', vault: vault };
+}
+
+
+// -- Data walkers -----------------------------------------------------
+
+function walkProjects(repoRoot) {
+  const projectsDir = join(repoRoot, 'projects');
+  if (!existsSync(projectsDir)) return [];
+  const entries = readdirSync(projectsDir, { withFileTypes: true });
+  const projects = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const manifest = join(projectsDir, entry.name, 'project.json');
+    if (existsSync(manifest)) {
+      try {
+        projects.push(JSON.parse(readFileSync(manifest, 'utf-8')));
+      } catch (e) {
+        // skip malformed
+      }
+    }
+  }
+  return projects;
+}
+
+function walkWork(repoRoot) {
+  const workDir = join(repoRoot, 'work');
+  if (!existsSync(workDir)) return [];
+  const files = readdirSync(workDir).filter(function(f) { return f.endsWith('.json'); });
+  const items = [];
+  for (const file of files) {
+    try {
+      items.push(JSON.parse(readFileSync(join(workDir, file), 'utf-8')));
+    } catch (e) {
+      // skip malformed
+    }
+  }
+  return items;
+}
+
+function walkNotes(repoRoot) {
+  const notesDir = join(repoRoot, 'operator', 'notes');
+  if (!existsSync(notesDir)) return [];
+  const files = readdirSync(notesDir).filter(function(f) { return f.endsWith('.md'); });
+  var prefixes = ['discuss-', 'research-', 'draft-', 'spec-', 'pickup-', 'marketing-'];
+  var notes = [];
+  for (var i = 0; i < files.length; i++) {
+    var name = files[i];
+    var absPath = join(notesDir, name);
+    var st;
+    try { st = statSync(absPath); } catch(e) { continue; }
+    var title = name.replace(/\.md$/, '');
+    for (var j = 0; j < prefixes.length; j++) {
+      if (title.startsWith(prefixes[j])) { title = title.slice(prefixes[j].length); break; }
+    }
+    title = title.replace(/-/g, ' ').replace(/\b\w/g, function(c) { return c.toUpperCase(); });
+    notes.push({
+      name: name,
+      title: title,
+      path: 'operator/notes/' + name,
+      modified: st.mtime.toISOString(),
+    });
+  }
+  notes.sort(function(a, b) { return b.modified.localeCompare(a.modified); });
+  return notes;
+}
+
+function walkDocuments(dir, repoRoot, result) {
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      walkDocuments(join(dir, e.name), repoRoot, result);
+    } else if (e.name !== 'index.json' && (e.name.endsWith('.md') || e.name.endsWith('.json'))) {
+      result.push({
+        name: e.name,
+        path: relative(repoRoot, join(dir, e.name)),
+      });
+    }
+  }
+}
+
+function walkSchedules(repoRoot) {
+  const schedulesDir = join(repoRoot, 'schedules');
+  if (!existsSync(schedulesDir)) return [];
+  const files = readdirSync(schedulesDir).filter(function(f) { return f.endsWith('.json'); });
+  const schedules = [];
+  for (const file of files) {
+    try {
+      const data = JSON.parse(readFileSync(join(schedulesDir, file), 'utf-8'));
+      data._file = file;
+      schedules.push(data);
+    } catch (e) {
+      // skip malformed
+    }
+  }
+  return schedules;
+}
+
+function buildOverview(projects, work, repoRoot) {
+  const projectCount = projects.length;
+  const workByStatus = {};
+  for (const item of work) {
+    const status = item.status || 'unknown';
+    workByStatus[status] = (workByStatus[status] || 0) + 1;
+  }
+  // Read PA name from preferences if available
+  let paName = null;
+  try {
+    const prefsFile = join(repoRoot, 'operator', 'config', 'preferences.json');
+    if (existsSync(prefsFile)) {
+      const prefs = JSON.parse(readFileSync(prefsFile, 'utf-8'));
+      paName = prefs.paName || null;
+    }
+  } catch (e) { /* non-fatal */ }
+  // Read operator name and role from profile
+  let operatorName = null;
+  let operatorRole = null;
+  try {
+    const profileFile = join(repoRoot, 'operator', 'profile', 'operator.json');
+    if (existsSync(profileFile)) {
+      const profile = JSON.parse(readFileSync(profileFile, 'utf-8'));
+      operatorName = profile.name || null;
+      operatorRole = profile.role || null;
+    }
+  } catch (e) { /* non-fatal */ }
+  return {
+    paName: paName,
+    operatorName: operatorName,
+    operatorRole: operatorRole,
+    projectCount: projectCount,
+    workItemCount: work.length,
+    workByStatus: workByStatus,
+    // Return the full project and work objects. Consumers (home page, the
+    // E2E harness) expect the complete shape — the previous trimmed summary
+    // dropped priority, owner, summary, etc., which forced every consumer
+    // to fetch /__api/projects a second time.
+    projects: projects,
+    work: work,
+  };
+}
+
+
+// -- Helpers ----------------------------------------------------------
+
+function readBody(req) {
+  return new Promise(function(resolve, reject) {
+    const chunks = [];
+    req.on('data', function(chunk) { chunks.push(chunk); });
+    req.on('end', function() { resolve(Buffer.concat(chunks).toString()); });
+    req.on('error', reject);
+  });
+}
+
+function sendJson(res, status, data) {
+  const body = JSON.stringify(data);
+  res.writeHead(status, {
+    'Content-Type': 'application/json',
+    'Content-Length': Buffer.byteLength(body),
+  });
+  res.end(body);
+}
+
+function writeJson(filePath, data) {
+  writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}
+
+
+// -- Git overview -----------------------------------------------------
+
+/**
+ * Build the /__api/git-overview payload. Shape:
+ *
+ *   {
+ *     available: boolean,
+ *     reason?: string,                // when available === false
+ *     generatedAt: ISO string,
+ *     orgs: string[],                 // configured GitHub orgs
+ *     repos: RepoRow[],               // user's owned repos (from gh repo list)
+ *     openPrs: PrRow[],               // user's open PRs
+ *     orgRepos: OrgRepoRow[],         // recent activity across configured orgs
+ *     branches: BranchRow[],          // staleness warnings across top repos
+ *     recentCommits: CommitRow[],     // flat cross-org commit feed (30d)
+ *     leaderboard: {                  // contributor leaderboard per org
+ *       org: string,
+ *       contributors: { login: string, commits: number }[],
+ *     }[],
+ *   }
+ *
+ * All gh/git calls have short timeouts and fail-soft — the page must render
+ * partial data rather than error.
+ */
+async function buildGitOverview(repoRoot) {
+  const generatedAt = new Date().toISOString();
+
+  // Check gh availability first. Missing or unauthenticated gh → graceful
+  // degradation, same contract as /__api/repos.
+  try {
+    execSync('gh --version', { stdio: 'pipe', timeout: 5000 });
+  } catch {
+    return {
+      available: false,
+      reason: 'gh CLI not installed. Install it from https://cli.github.com/ to enable Git Overview.',
+      generatedAt: generatedAt,
+    };
+  }
+  try {
+    execSync('gh auth status', { stdio: 'pipe', timeout: 5000 });
+  } catch {
+    return {
+      available: false,
+      reason: 'gh CLI not authenticated. Run: gh auth login',
+      generatedAt: generatedAt,
+    };
+  }
+
+  // Read configured orgs. Missing preferences is fine — leaderboard/orgRepos
+  // just come back empty and the page renders the user's own repos only.
+  let orgs = [];
+  try {
+    const prefsFile = join(repoRoot, 'operator', 'config', 'preferences.json');
+    if (existsSync(prefsFile)) {
+      const prefs = JSON.parse(readFileSync(prefsFile, 'utf-8'));
+      if (Array.isArray(prefs.gitOrgs)) {
+        orgs = prefs.gitOrgs.filter(function(o) { return typeof o === 'string' && o.length > 0; });
+      }
+    }
+  } catch { /* non-fatal */ }
+
+  // Owned repos — same call shape as /__api/repos, but we also pull
+  // `owner.login` so we can group by org for the no-`gitOrgs` fallback, and
+  // `defaultBranchRef` so we can surface a branch-staleness signal from
+  // owned repos alone.
+  let repos = [];
+  try {
+    const reposRaw = execSync(
+      'gh repo list --json name,description,url,primaryLanguage,pushedAt,stargazerCount,isFork,isPrivate,owner,defaultBranchRef --limit 30 --no-archived',
+      { encoding: 'utf-8', timeout: 15000 }
+    ).trim();
+    const parsed = JSON.parse(reposRaw || '[]');
+    repos = parsed.map(function(r) {
+      return {
+        name: r.name,
+        description: r.description,
+        html_url: r.url,
+        language: r.primaryLanguage ? r.primaryLanguage.name : null,
+        pushed_at: r.pushedAt,
+        stargazers_count: r.stargazerCount || 0,
+        fork: r.isFork || false,
+        private: r.isPrivate || false,
+        owner_login: r.owner && r.owner.login ? r.owner.login : null,
+        default_branch: r.defaultBranchRef && r.defaultBranchRef.name ? r.defaultBranchRef.name : 'main',
+      };
+    }).sort(function(a, b) {
+      return (b.pushed_at || '').localeCompare(a.pushed_at || '');
+    });
+  } catch { /* non-fatal */ }
+
+  // Open PRs authored by user.
+  let openPrs = [];
+  try {
+    const prsRaw = execSync(
+      'gh search prs --author=@me --state=open --json title,url,repository,createdAt,updatedAt,isDraft,number --limit 20',
+      { encoding: 'utf-8', timeout: 15000 }
+    ).trim();
+    const parsed = JSON.parse(prsRaw || '[]');
+    openPrs = parsed.map(function(pr) {
+      return {
+        title: pr.title,
+        html_url: pr.url,
+        repo: pr.repository ? pr.repository.nameWithOwner : null,
+        created_at: pr.createdAt,
+        updated_at: pr.updatedAt,
+        draft: pr.isDraft || false,
+        number: pr.number || null,
+      };
+    });
+  } catch { /* non-fatal */ }
+
+  // Build "30 days ago" ISO string for activity windows.
+  const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000;
+  const sinceIso = new Date(Date.now() - THIRTY_DAYS_MS).toISOString();
+
+  // For each configured org, list its top repos by pushedAt and pull per-repo
+  // commit activity over the last 30 days. Each gh call has a short timeout
+  // and failures are swallowed.
+  const orgRepos = [];
+  const leaderboard = [];
+  const recentCommits = [];
+  const branches = [];
+
+  for (const org of orgs) {
+    let orgReposRaw = [];
+    try {
+      const raw = execSync(
+        'gh repo list ' + shellQuote(org) + ' --json name,description,url,pushedAt,isArchived,isFork,defaultBranchRef --limit 20 --no-archived',
+        { encoding: 'utf-8', timeout: 15000 }
+      ).trim();
+      orgReposRaw = JSON.parse(raw || '[]');
+    } catch { /* skip this org */ }
+
+    const contribCounts = Object.create(null);
+
+    // Only look at top 5 most recently active per org to bound API work.
+    const topForOrg = orgReposRaw.slice(0, 5);
+
+    for (const r of topForOrg) {
+      const repoFull = org + '/' + r.name;
+      // Commits since 30d ago
+      let repoCommits = [];
+      try {
+        const raw = execSync(
+          'gh api ' + shellQuote('/repos/' + repoFull + '/commits?since=' + sinceIso + '&per_page=100') +
+          ' --paginate',
+          { encoding: 'utf-8', timeout: 20000, maxBuffer: 8 * 1024 * 1024 }
+        ).trim();
+        // --paginate concatenates JSON arrays by default. Try parse; on fail,
+        // attempt to repair concatenated arrays.
+        try {
+          repoCommits = JSON.parse(raw || '[]');
+        } catch {
+          const merged = raw.replace(/\]\s*\[/g, ',');
+          repoCommits = JSON.parse(merged || '[]');
+        }
+      } catch { /* skip this repo */ }
+
+      // Aggregate contributor counts and build flat commit feed (top 3 per repo).
+      let commits30d = 0;
+      for (const c of repoCommits) {
+        const login = (c.author && c.author.login)
+          || (c.commit && c.commit.author && c.commit.author.name)
+          || 'unknown';
+        contribCounts[login] = (contribCounts[login] || 0) + 1;
+        commits30d += 1;
+      }
+      const topCommits = repoCommits.slice(0, 3);
+      for (const c of topCommits) {
+        recentCommits.push({
+          repo: repoFull,
+          sha: (c.sha || '').slice(0, 7),
+          message: (c.commit && c.commit.message ? String(c.commit.message).split('\n')[0] : ''),
+          author: (c.author && c.author.login) || (c.commit && c.commit.author && c.commit.author.name) || 'unknown',
+          date: c.commit && c.commit.author && c.commit.author.date ? c.commit.author.date : null,
+          html_url: c.html_url || null,
+        });
+      }
+
+      // Default branch staleness signal: warn if no commits in 30 days,
+      // based on the pushedAt field we already have.
+      const lastCommitIso = r.pushedAt || null;
+      const lastMs = lastCommitIso ? Date.parse(lastCommitIso) : 0;
+      const ageDays = lastMs ? Math.floor((Date.now() - lastMs) / (24 * 60 * 60 * 1000)) : null;
+      const defaultBranch = r.defaultBranchRef && r.defaultBranchRef.name ? r.defaultBranchRef.name : 'main';
+      branches.push({
+        repo: repoFull,
+        branch: defaultBranch,
+        lastCommit: lastCommitIso,
+        ageDays: ageDays,
+        stale: ageDays !== null && ageDays > 30,
+      });
+
+      orgRepos.push({
+        org: org,
+        name: r.name,
+        full_name: repoFull,
+        description: r.description,
+        html_url: r.url,
+        pushed_at: r.pushedAt,
+        commits30d: commits30d,
+      });
+    }
+
+    const contributors = Object.keys(contribCounts).map(function(login) {
+      return { login: login, commits: contribCounts[login] };
+    }).sort(function(a, b) {
+      return b.commits - a.commits;
+    }).slice(0, 10);
+    leaderboard.push({ org: org, contributors: contributors });
+  }
+
+  // Sort aggregated outputs for deterministic rendering.
+  orgRepos.sort(function(a, b) { return (b.pushed_at || '').localeCompare(a.pushed_at || ''); });
+  recentCommits.sort(function(a, b) { return (b.date || '').localeCompare(a.date || ''); });
+  branches.sort(function(a, b) {
+    // Stale first, then by ageDays desc.
+    if (a.stale !== b.stale) return a.stale ? -1 : 1;
+    return (b.ageDays || 0) - (a.ageDays || 0);
+  });
+
+  // Owned-repos fallback ladder: when the operator has not configured
+  // gitOrgs, the page would otherwise show three flat empty panels. Derive
+  // the same three signals from the user's owned repos so the page is
+  // useful out of the box. The gitOrgs prompt stays as a dim hint in the
+  // UI; these fallbacks are additive.
+  //
+  // `ownedBranches` and `ownedOrgActivity` are cheap — computed from data
+  // already in hand. `ownedRecentCommits` makes real `gh api` calls in
+  // parallel (capped concurrency — see buildOwnedRecentCommits), so we only
+  // pay that cost when the org-driven feed is empty (typically means no
+  // gitOrgs configured). The parallel fan-out keeps latency bounded even
+  // for accounts with dozens of owned repos, so no env-var gate is needed.
+  let ownedBranches = [];
+  let ownedRecentCommits = [];
+  let ownedOrgActivity = [];
+  if (Array.isArray(repos) && repos.length) {
+    ownedBranches = buildOwnedBranchStaleness(repos);
+    ownedOrgActivity = buildOwnedOrgActivity(repos);
+    if (!recentCommits.length) {
+      ownedRecentCommits = await buildOwnedRecentCommits(repos);
+    }
+  }
+
+  return {
+    available: true,
+    generatedAt: generatedAt,
+    orgs: orgs,
+    repos: repos,
+    openPrs: openPrs,
+    orgRepos: orgRepos,
+    branches: branches,
+    recentCommits: recentCommits.slice(0, 30),
+    leaderboard: leaderboard,
+    // Fallback signals derived purely from the user's owned repos — always
+    // populated (cheap), the UI chooses whether to render them based on
+    // whether the org-driven signals are empty.
+    ownedBranches: ownedBranches,
+    ownedRecentCommits: ownedRecentCommits,
+    ownedOrgActivity: ownedOrgActivity,
+  };
+}
+
+/**
+ * Branch-staleness fallback: walk the user's owned repos and flag any whose
+ * default branch hasn't been pushed to in a while. Cheap — uses the pushedAt
+ * field already fetched by `gh repo list`, no extra API calls.
+ *
+ * Ranking: stalest first. Capped at 20 entries. Marked stale when ageDays
+ * exceeds 60 (the yellow threshold) so the panel has something to show even
+ * for active repos; the page decides colour ramp from ageDays itself.
+ */
+export function buildOwnedBranchStaleness(repos) {
+  const WARN_DAYS = 60;
+  const out = [];
+  const now = Date.now();
+  for (const r of repos) {
+    if (!r.pushed_at) continue;
+    const lastMs = Date.parse(r.pushed_at);
+    if (!Number.isFinite(lastMs)) continue;
+    const ageDays = Math.floor((now - lastMs) / (24 * 60 * 60 * 1000));
+    const repoFull = (r.owner_login ? r.owner_login + '/' : '') + r.name;
+    out.push({
+      repo: repoFull,
+      branch: r.default_branch || 'main',
+      lastCommit: r.pushed_at,
+      ageDays: ageDays,
+      stale: ageDays >= WARN_DAYS,
+    });
+  }
+  // Stalest first.
+  out.sort(function(a, b) { return (b.ageDays || 0) - (a.ageDays || 0); });
+  return out.slice(0, 20);
+}
+
+/**
+ * Recent-commits fallback: a flat feed of the user's latest commits across
+ * the user's owned repos, last 30 days, capped at 30 entries.
+ *
+ * Makes one `gh api /repos/{repo}/commits?since=…` call per candidate repo,
+ * fanned out in parallel with a bounded concurrency window so GitHub's
+ * secondary rate-limiter stays happy and we don't hold sockets open forever
+ * on a slow connection. Per-repo failures are swallowed (Promise.allSettled)
+ * so one 404 / permission denial / timeout doesn't poison the batch.
+ *
+ * Before this was serial `execSync`, which scaled linearly with repo count
+ * and capped the probe list at 3 to keep total latency tolerable. With
+ * parallel fan-out the probe set can be wider (15) while wall-clock stays
+ * within the timeout of a single call, so the Playwright webserver no
+ * longer needs the WS_SKIP_OWNED_COMMITS escape hatch.
+ */
+export async function buildOwnedRecentCommits(repos) {
+  const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000;
+  const sinceIso = new Date(Date.now() - THIRTY_DAYS_MS).toISOString();
+  // Parallel fan-out means total wall-clock is ~max(per-call) rather than
+  // sum, so we can afford a wider probe set than the serial version. 15 is
+  // a sensible ceiling: enough to surface a rich feed for active users,
+  // still bounded so an account with hundreds of repos can't explode the
+  // work queue. Cap concurrency at 8 to stay well inside GitHub's
+  // secondary rate-limit envelope (no per-endpoint quota hits observed
+  // below ~100 req/min).
+  const MAX_REPOS_PROBED = 15;
+  const CONCURRENCY = 8;
+  const PER_CALL_TIMEOUT_MS = 5000;
+
+  const active = repos.filter(function(r) {
+    if (!r.pushed_at) return false;
+    const t = Date.parse(r.pushed_at);
+    return Number.isFinite(t) && (Date.now() - t) < THIRTY_DAYS_MS;
+  }).slice(0, MAX_REPOS_PROBED);
+
+  if (!active.length) return [];
+
+  // Fetch one repo's commits. Resolves to a list of already-normalised row
+  // objects; rejects never — any error (timeout, non-zero exit, bad JSON)
+  // collapses to [] so the caller can safely merge.
+  async function fetchRepoCommits(r) {
+    const repoFull = (r.owner_login ? r.owner_login + '/' : '') + r.name;
+    const apiPath = '/repos/' + repoFull + '/commits?since=' + sinceIso + '&per_page=10';
+    try {
+      const { stdout } = await execFileAsync(
+        'gh',
+        ['api', apiPath],
+        { encoding: 'utf-8', timeout: PER_CALL_TIMEOUT_MS, maxBuffer: 2 * 1024 * 1024 }
+      );
+      const commits = JSON.parse((stdout || '').trim() || '[]');
+      return commits.map(function(c) {
+        return {
+          repo: repoFull,
+          sha: (c.sha || '').slice(0, 7),
+          message: (c.commit && c.commit.message ? String(c.commit.message).split('\n')[0] : ''),
+          author: (c.author && c.author.login) || (c.commit && c.commit.author && c.commit.author.name) || 'unknown',
+          date: c.commit && c.commit.author && c.commit.author.date ? c.commit.author.date : null,
+          html_url: c.html_url || null,
+        };
+      });
+    } catch {
+      return [];
+    }
+  }
+
+  // Chunked Promise.allSettled keeps at most CONCURRENCY gh processes in
+  // flight. allSettled so a single failure doesn't short-circuit the
+  // batch — fetchRepoCommits already swallows its own errors, but
+  // allSettled is belt-and-braces in case that contract ever changes.
+  const out = [];
+  for (let i = 0; i < active.length; i += CONCURRENCY) {
+    const chunk = active.slice(i, i + CONCURRENCY);
+    const settled = await Promise.allSettled(chunk.map(fetchRepoCommits));
+    for (const s of settled) {
+      if (s.status === 'fulfilled' && Array.isArray(s.value)) {
+        for (const row of s.value) out.push(row);
+      }
+    }
+  }
+
+  out.sort(function(a, b) { return (b.date || '').localeCompare(a.date || ''); });
+  return out.slice(0, 30);
+}
+
+/**
+ * Org-activity fallback: group the user's owned repos by owner.login and
+ * emit per-org aggregates. No extra API calls — all inputs come from the
+ * already-fetched repo list.
+ */
+export function buildOwnedOrgActivity(repos) {
+  const byOrg = Object.create(null);
+  for (const r of repos) {
+    const org = r.owner_login || 'unknown';
+    if (!byOrg[org]) {
+      byOrg[org] = { org: org, repoCount: 0, lastTouched: null, lastTouchedRepo: null, activeRepos30d: 0 };
+    }
+    byOrg[org].repoCount++;
+    if (r.pushed_at && (!byOrg[org].lastTouched || r.pushed_at > byOrg[org].lastTouched)) {
+      byOrg[org].lastTouched = r.pushed_at;
+      byOrg[org].lastTouchedRepo = (r.owner_login ? r.owner_login + '/' : '') + r.name;
+    }
+    if (r.pushed_at) {
+      const t = Date.parse(r.pushed_at);
+      if (Number.isFinite(t) && (Date.now() - t) < 30 * 24 * 60 * 60 * 1000) {
+        byOrg[org].activeRepos30d++;
+      }
+    }
+  }
+  const out = Object.keys(byOrg).map(function(k) { return byOrg[k]; });
+  out.sort(function(a, b) { return (b.lastTouched || '').localeCompare(a.lastTouched || ''); });
+  return out;
+}
+
+// Minimal shell-quoting helper for embedded strings. We trust the caller to
+// pass a well-formed org/repo slug, but quote defensively to avoid injection
+// via preferences.json content.
+function shellQuote(s) {
+  return "'" + String(s).replace(/'/g, "'\\''") + "'";
+}
+
+// -- Delegations / spawn-log aggregation --------------------------------
+
+/**
+ * Walk agents/<pa>/spawn-log.json and aggregate.
+ *
+ * Returns:
+ *   {
+ *     generatedAt: ISO,
+ *     agents: [{ name, total, inFlight, success, failed, byRole, byTier }],
+ *     spawns: [{ agent, id, timestamp, role, tier, objective, outcome, notes, ... }],
+ *     stats: { total, inFlight, success, failed, byRole: {...}, byTier: {...} },
+ *   }
+ */
+function buildDelegations(repoRoot) {
+  const agentsDir = join(repoRoot, 'agents');
+  const spawns = [];
+  const agents = [];
+  if (existsSync(agentsDir)) {
+    const entries = readdirSync(agentsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const logFile = join(agentsDir, entry.name, 'spawn-log.json');
+      if (!existsSync(logFile)) continue;
+      let data;
+      try { data = JSON.parse(readFileSync(logFile, 'utf-8')); } catch { continue; }
+      const paSpawns = Array.isArray(data.spawns) ? data.spawns : [];
+      const agentAgg = {
+        name: entry.name,
+        total: 0,
+        inFlight: 0,
+        success: 0,
+        failed: 0,
+        byRole: Object.create(null),
+        byTier: Object.create(null),
+      };
+      for (const sp of paSpawns) {
+        const normalised = {
+          agent: entry.name,
+          id: sp.id || null,
+          timestamp: sp.timestamp || null,
+          role: sp.role || 'unknown',
+          tier: (typeof sp.tier === 'number') ? sp.tier : null,
+          objective: sp.objective || '',
+          outcome: sp.outcome || 'unknown',
+          notes: sp.notes || '',
+          tokens: sp.tokens || null,
+          durationMs: sp.durationMs || null,
+          toolUses: sp.toolUses || null,
+        };
+        spawns.push(normalised);
+        agentAgg.total++;
+        const oc = String(normalised.outcome).toLowerCase();
+        if (oc === 'success' || oc === 'done' || oc === 'complete' || oc === 'completed') {
+          agentAgg.success++;
+        } else if (oc === 'failed' || oc === 'failure' || oc === 'error') {
+          agentAgg.failed++;
+        } else if (oc === 'in-flight' || oc === 'in-progress' || oc === 'dispatched' || oc === 'running') {
+          agentAgg.inFlight++;
+        }
+        agentAgg.byRole[normalised.role] = (agentAgg.byRole[normalised.role] || 0) + 1;
+        const tierKey = normalised.tier == null ? 'unknown' : String(normalised.tier);
+        agentAgg.byTier[tierKey] = (agentAgg.byTier[tierKey] || 0) + 1;
+      }
+      agents.push(agentAgg);
+    }
+  }
+
+  spawns.sort(function(a, b) { return (b.timestamp || '').localeCompare(a.timestamp || ''); });
+
+  const stats = { total: 0, inFlight: 0, success: 0, failed: 0, byRole: {}, byTier: {} };
+  for (const a of agents) {
+    stats.total += a.total;
+    stats.inFlight += a.inFlight;
+    stats.success += a.success;
+    stats.failed += a.failed;
+    for (const r of Object.keys(a.byRole)) stats.byRole[r] = (stats.byRole[r] || 0) + a.byRole[r];
+    for (const t of Object.keys(a.byTier)) stats.byTier[t] = (stats.byTier[t] || 0) + a.byTier[t];
+  }
+
+  return {
+    generatedAt: new Date().toISOString(),
+    agents: agents,
+    spawns: spawns.slice(0, 100),
+    stats: stats,
+  };
+}
+
+
+// -- Knowledge map -----------------------------------------------------
+
+/**
+ * Parse a leading `---`-delimited YAML-ish front-matter block on a domain
+ * README. Supports the flat `key: value` pairs needed for the homepage
+ * (displayName). Matches the behaviour of core/knowledge/retrieval's
+ * stripFrontMatter / parseFrontMatter helpers (duplicated here to keep the
+ * workspace server zero-dep and independent of the retrieval pipeline).
+ */
+export function parseDomainFrontMatter(content) {
+  if (typeof content !== 'string' || !content.startsWith('---')) return {};
+  const lines = content.split(/\r?\n/);
+  if (lines[0].trim() !== '---') return {};
+  const out = {};
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === '---') return out;
+    const m = /^([A-Za-z_][\w-]*)\s*:\s*(.*)$/.exec(line);
+    if (!m) continue;
+    let value = m[2].trim();
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    out[m[1]] = value;
+  }
+  return {};
+}
+
+/**
+ * Read operator/knowledge/domains.json + .graph.json + .backlinks.json, and
+ * walk each domain tree for per-file mtimes. Produces an audit ready for
+ * rendering: staleness (60d warn / 120d red), thin-domain (<3 docs), edge
+ * counts and backlink totals.
+ */
+function buildKnowledgeMap(repoRoot) {
+  const knowledgeDir = join(repoRoot, 'operator', 'knowledge');
+  if (!existsSync(knowledgeDir)) {
+    return {
+      generatedAt: new Date().toISOString(),
+      available: false,
+      reason: 'No operator/knowledge/ directory found.',
+      domains: [],
+      stats: { totalDomains: 0, totalDocuments: 0, totalEdges: 0 },
+    };
+  }
+
+  const STALE_WARN_DAYS = 60;
+  const STALE_RED_DAYS = 120;
+  const THIN_DOCS = 3;
+
+  // Try domains.json first; fall back to walking subdirs if absent.
+  let domainDefs = [];
+  const domainsFile = join(knowledgeDir, 'domains.json');
+  if (existsSync(domainsFile)) {
+    try {
+      const raw = JSON.parse(readFileSync(domainsFile, 'utf-8'));
+      if (Array.isArray(raw.domains)) domainDefs = raw.domains;
+    } catch { /* fallthrough */ }
+  }
+  if (!domainDefs.length) {
+    const indexFile = join(knowledgeDir, 'index.json');
+    if (existsSync(indexFile)) {
+      try {
+        const raw = JSON.parse(readFileSync(indexFile, 'utf-8'));
+        if (Array.isArray(raw.domains)) {
+          // index.json stores paths relative to operator/
+          domainDefs = raw.domains.map(function(d) {
+            return {
+              id: d.id,
+              name: d.id,
+              path: d.path && d.path.startsWith('operator/') ? d.path : 'operator/' + (d.path || ('knowledge/' + d.id)),
+              description: d.description || null,
+              displayName: d.displayName || null,
+            };
+          });
+        }
+      } catch { /* fallthrough */ }
+    }
+  }
+
+  // Runtime fallback: if `displayName` isn't set in domains.json (i.e. the
+  // index hasn't been regenerated since the field was added), read it from
+  // the README's front-matter directly. Cheap — one small file read per
+  // domain on the homepage path.
+  for (const d of domainDefs) {
+    if (d.displayName) continue;
+    const domainPath = d.path && d.path.indexOf('/') !== -1 ? d.path : join('operator', 'knowledge', d.id);
+    const readmePath = join(repoRoot, domainPath, 'README.md');
+    if (!existsSync(readmePath)) continue;
+    try {
+      const content = readFileSync(readmePath, 'utf-8');
+      const fm = parseDomainFrontMatter(content);
+      if (fm.displayName) d.displayName = fm.displayName;
+    } catch { /* non-fatal */ }
+  }
+
+  // Load graph edges / backlinks if present.
+  let edges = [];
+  const graphFile = join(knowledgeDir, '.graph.json');
+  if (existsSync(graphFile)) {
+    try {
+      const raw = JSON.parse(readFileSync(graphFile, 'utf-8'));
+      if (Array.isArray(raw.edges)) edges = raw.edges;
+    } catch { /* non-fatal */ }
+  }
+  let backlinks = {};
+  const backlinksFile = join(knowledgeDir, '.backlinks.json');
+  if (existsSync(backlinksFile)) {
+    try {
+      const raw = JSON.parse(readFileSync(backlinksFile, 'utf-8'));
+      if (raw.backlinks && typeof raw.backlinks === 'object') backlinks = raw.backlinks;
+    } catch { /* non-fatal */ }
+  }
+
+  // Walk each domain for file list + mtimes.
+  function walkFiles(dir, outAbs, outRel, root) {
+    if (!existsSync(dir)) return;
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const e of entries) {
+      const full = join(dir, e.name);
+      if (e.isDirectory()) {
+        walkFiles(full, outAbs, outRel, root);
+      } else if (e.name.endsWith('.md')) {
+        let mtimeMs = 0;
+        try { mtimeMs = statSync(full).mtimeMs; } catch { /* non-fatal */ }
+        outAbs.push(full);
+        outRel.push({ path: relative(root, full), mtimeMs: mtimeMs });
+      }
+    }
+  }
+
+  const now = Date.now();
+  const domainsOut = [];
+  let totalDocs = 0;
+  let totalBacklinks = 0;
+
+  for (const d of domainDefs) {
+    const domainPath = d.path && d.path.indexOf('/') !== -1 ? d.path : join('operator', 'knowledge', d.id);
+    const absDomainPath = join(repoRoot, domainPath);
+    const absList = [];
+    const relList = [];
+    walkFiles(absDomainPath, absList, relList, repoRoot);
+    const docs = relList.map(function(r) {
+      const ageDays = r.mtimeMs ? Math.floor((now - r.mtimeMs) / (24 * 60 * 60 * 1000)) : null;
+      const bl = backlinks[r.path] ? backlinks[r.path].length : 0;
+      totalBacklinks += bl;
+      return {
+        path: r.path,
+        lastUpdated: r.mtimeMs ? new Date(r.mtimeMs).toISOString() : null,
+        ageDays: ageDays,
+        backlinkCount: bl,
+      };
+    });
+    docs.sort(function(a, b) { return (b.ageDays || 0) - (a.ageDays || 0); });
+    totalDocs += docs.length;
+
+    const stalest = docs.length
+      ? docs.reduce(function(acc, x) { return (x.ageDays || 0) > (acc.ageDays || 0) ? x : acc; }, docs[0])
+      : null;
+    const freshest = docs.length
+      ? docs.reduce(function(acc, x) { return (x.ageDays || 999999) < (acc.ageDays || 999999) ? x : acc; }, docs[0])
+      : null;
+
+    const staleCount = docs.filter(function(x) { return x.ageDays != null && x.ageDays >= STALE_WARN_DAYS; }).length;
+    const redCount = docs.filter(function(x) { return x.ageDays != null && x.ageDays >= STALE_RED_DAYS; }).length;
+
+    let health = 'good';
+    if (docs.length < THIN_DOCS) health = 'thin';
+    else if (redCount > 0) health = 'red';
+    else if (staleCount > 0) health = 'warn';
+
+    domainsOut.push({
+      id: d.id,
+      name: d.name || d.id,
+      displayName: d.displayName || null,
+      description: d.description || null,
+      path: domainPath,
+      documentCount: docs.length,
+      staleCount: staleCount,
+      redCount: redCount,
+      health: health,
+      stalestDoc: stalest,
+      freshestDoc: freshest,
+      docs: docs.slice(0, 30), // cap per domain — full list not needed for audit view
+    });
+  }
+
+  return {
+    generatedAt: new Date().toISOString(),
+    available: true,
+    thresholds: { staleWarnDays: STALE_WARN_DAYS, staleRedDays: STALE_RED_DAYS, thinDocs: THIN_DOCS },
+    domains: domainsOut,
+    stats: {
+      totalDomains: domainsOut.length,
+      totalDocuments: totalDocs,
+      totalEdges: edges.length,
+      totalBacklinks: totalBacklinks,
+    },
+  };
+}
+
+
+// -- Staging inbox -----------------------------------------------------
+
+/**
+ * Walk agents/<pa>/staging/*.md and return a flat list of items plus
+ * per-agent aggregates. Filenames follow `{timestamp}_{category}.md`
+ * (librarian-processed). Categories: preference, correction, decision,
+ * pattern, contact, domain, feedback. Unknown suffixes bucket as "other".
+ */
+function buildStaging(repoRoot) {
+  const CATEGORIES = ['preference', 'correction', 'decision', 'pattern', 'contact', 'domain', 'feedback'];
+  const agentsDir = join(repoRoot, 'agents');
+  const items = [];
+  const agents = [];
+  if (!existsSync(agentsDir)) {
+    return {
+      generatedAt: new Date().toISOString(),
+      agents: [],
+      items: [],
+      stats: { totalItems: 0, byCategory: {}, oldestAgeDays: null },
+    };
+  }
+  const entries = readdirSync(agentsDir, { withFileTypes: true });
+  const now = Date.now();
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const stagingDir = join(agentsDir, entry.name, 'staging');
+    if (!existsSync(stagingDir)) continue;
+    let fileEntries;
+    try {
+      fileEntries = readdirSync(stagingDir, { withFileTypes: true });
+    } catch { continue; }
+    const agentAgg = {
+      name: entry.name,
+      total: 0,
+      byCategory: Object.create(null),
+      oldestAgeDays: null,
+    };
+    for (const fe of fileEntries) {
+      if (!fe.isFile()) continue;
+      if (!fe.name.endsWith('.md')) continue;
+      const full = join(stagingDir, fe.name);
+      let st;
+      try { st = statSync(full); } catch { continue; }
+      // Parse filename: {timestamp}_{category}.md
+      const base = fe.name.replace(/\.md$/, '');
+      const idx = base.lastIndexOf('_');
+      let category = 'other';
+      let timestamp = null;
+      if (idx !== -1) {
+        const possibleCat = base.slice(idx + 1);
+        if (CATEGORIES.indexOf(possibleCat) !== -1) {
+          category = possibleCat;
+          timestamp = base.slice(0, idx);
+        }
+      }
+      // Preview: first non-empty line of the file (trimmed, first 160 chars).
+      let preview = '';
+      try {
+        const content = readFileSync(full, 'utf-8');
+        const lines = content.split(/\r?\n/).map(function(l) { return l.trim(); });
+        preview = lines.find(function(l) { return l.length > 0; }) || '';
+        // Strip a leading markdown heading marker for preview.
+        preview = preview.replace(/^#{1,6}\s+/, '').slice(0, 160);
+      } catch { /* non-fatal */ }
+      const ageDays = Math.floor((now - st.mtimeMs) / (24 * 60 * 60 * 1000));
+      const item = {
+        agent: entry.name,
+        name: fe.name,
+        path: 'agents/' + entry.name + '/staging/' + fe.name,
+        category: category,
+        timestamp: timestamp,
+        modified: new Date(st.mtimeMs).toISOString(),
+        ageDays: ageDays,
+        sizeBytes: st.size,
+        preview: preview,
+      };
+      items.push(item);
+      agentAgg.total++;
+      agentAgg.byCategory[category] = (agentAgg.byCategory[category] || 0) + 1;
+      if (agentAgg.oldestAgeDays == null || ageDays > agentAgg.oldestAgeDays) agentAgg.oldestAgeDays = ageDays;
+    }
+    agents.push(agentAgg);
+  }
+
+  items.sort(function(a, b) { return b.modified.localeCompare(a.modified); });
+
+  const byCategory = {};
+  let oldest = null;
+  for (const it of items) {
+    byCategory[it.category] = (byCategory[it.category] || 0) + 1;
+    if (oldest == null || it.ageDays > oldest) oldest = it.ageDays;
+  }
+
+  return {
+    generatedAt: new Date().toISOString(),
+    agents: agents,
+    items: items,
+    stats: {
+      totalItems: items.length,
+      byCategory: byCategory,
+      oldestAgeDays: oldest,
+    },
+  };
+}
+
+// -- Agenda / cron -----------------------------------------------------
+
+/**
+ * Build the schedules agenda for the next 7 days starting from `now`.
+ *
+ * Returns `{ today, tomorrow, thisWeek }` where each bucket is an array of
+ * `{ id, name, cron, nextRunAt, description, command, host }` entries,
+ * sorted by nextRunAt ascending. A single schedule may appear multiple times
+ * within a bucket (e.g. an hourly job shows every run inside today). `host`
+ * is the raw `schedules/{id}.json` host field (or null) — the client
+ * normalises it for the host-filter chips; buildAgenda itself does not.
+ *
+ * Only the managed-schedule definitions at schedules/*.json are used.
+ * Non-cron schedules (empty/invalid cron) are skipped.
+ */
+function buildAgenda(schedules, now) {
+  const today = [];
+  const tomorrow = [];
+  const thisWeek = [];
+
+  const startOfToday = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+  const startOfTomorrow = new Date(startOfToday.getTime() + 24 * 60 * 60 * 1000);
+  const startOfDayAfter = new Date(startOfToday.getTime() + 2 * 24 * 60 * 60 * 1000);
+  const endOfWeek = new Date(startOfToday.getTime() + 7 * 24 * 60 * 60 * 1000);
+
+  for (const s of schedules || []) {
+    if (s.enabled === false) continue;
+    const cronExpr = s.schedule || s.cron;
+    if (!cronExpr || typeof cronExpr !== 'string') continue;
+
+    let runs;
+    try {
+      runs = nextCronRuns(cronExpr, now, endOfWeek, 50);
+    } catch {
+      continue; // unparseable cron — skip rather than break the endpoint
+    }
+
+    for (const runAt of runs) {
+      const entry = {
+        id: s.id || s._file || 'unknown',
+        name: s.name || s.id || s._file || 'Unnamed',
+        cron: cronExpr,
+        nextRunAt: runAt.toISOString(),
+        description: s.description || null,
+        command: s.command || s.cmd || null,
+        // Carried through so the client can filter the agenda by the same
+        // host chip that filters the Active-schedules table, off ONE fetch
+        // — a per-chip refetch would mean an extra round trip on every
+        // click for data we already have server-side. `s.host` is a raw
+        // pass-through (undefined -> null); the client owns normalisation
+        // (short host vs FQDN) since that's purely a display/matching
+        // concern, not something the server needs to resolve.
+        host: s.host || null,
+      };
+      if (runAt < startOfTomorrow) {
+        today.push(entry);
+      } else if (runAt < startOfDayAfter) {
+        tomorrow.push(entry);
+      } else if (runAt < endOfWeek) {
+        thisWeek.push(entry);
+      }
+    }
+  }
+
+  function sortByRun(a, b) { return a.nextRunAt.localeCompare(b.nextRunAt); }
+  today.sort(sortByRun);
+  tomorrow.sort(sortByRun);
+  thisWeek.sort(sortByRun);
+
+  return { today, tomorrow, thisWeek };
+}
+
+/**
+ * Compute the single next run time for one schedule, for the compact
+ * Tab 1 list (as distinct from `buildAgenda`, which enumerates every
+ * occurrence within a 7-day window for its bucketed view). Disabled
+ * schedules and unparseable/missing cron expressions yield `null` rather
+ * than throwing — a malformed schedule file must not break the list for
+ * every other schedule.
+ *
+ * @returns {string|null} ISO timestamp, or null
+ */
+function computeNextRunAt(schedule, now) {
+  if (schedule.enabled === false) return null;
+  const cronExpr = schedule.schedule || schedule.cron;
+  if (!cronExpr || typeof cronExpr !== 'string') return null;
+  try {
+    // One year is a generous horizon — long enough to find a hit for any
+    // valid cron expression (including annual-only fields), short enough
+    // that the minute-by-minute walk's HARD_STEP_CAP is never the limiter
+    // for a 5-field cron.
+    const until = new Date(now.getTime() + 366 * 24 * 60 * 60 * 1000);
+    const runs = nextCronRuns(cronExpr, now, until, 1);
+    return runs.length ? runs[0].toISOString() : null;
+  } catch {
+    return null; // unparseable cron — degrade gracefully, same as buildAgenda
+  }
+}
+
+/**
+ * Compute the next run times of a 5-field cron expression between `from`
+ * (exclusive) and `until` (exclusive), capped at `max` entries.
+ *
+ * Grammar supported (per field):
+ *   *              any value
+ *   a              literal
+ *   a-b            range, inclusive
+ *   a,b,c          list
+ *   (* | a-b)/N    step
+ *
+ * Throws on unparseable input.
+ */
+export function nextCronRuns(cronExpr, from, until, max) {
+  const parts = String(cronExpr).trim().split(/\s+/);
+  if (parts.length !== 5) {
+    throw new Error('cron expression must have 5 fields: minute hour dom month dow');
+  }
+  const [fMin, fHour, fDom, fMonth, fDow] = parts;
+
+  const mins   = expandField(fMin,   0, 59);
+  const hours  = expandField(fHour,  0, 23);
+  const doms   = expandField(fDom,   1, 31);
+  const months = expandField(fMonth, 1, 12);
+  const dows   = expandField(fDow,   0, 6); // 0 = Sunday
+
+  const domRestricted = fDom !== '*';
+  const dowRestricted = fDow !== '*';
+
+  const results = [];
+  let t = new Date(from.getTime());
+  t.setSeconds(0, 0);
+  t = new Date(t.getTime() + 60 * 1000);
+
+  // Safety bound: walk minute-by-minute with fast-forward on mismatches.
+  const HARD_STEP_CAP = 20000;
+  let steps = 0;
+
+  while (t < until && results.length < max && steps < HARD_STEP_CAP) {
+    steps++;
+    if (!months.has(t.getMonth() + 1)) {
+      t = new Date(t.getFullYear(), t.getMonth() + 1, 1, 0, 0, 0, 0);
+      continue;
+    }
+    const domOk = doms.has(t.getDate());
+    const dowOk = dows.has(t.getDay());
+    let dateOk;
+    if (domRestricted && dowRestricted) dateOk = domOk || dowOk;
+    else if (domRestricted)             dateOk = domOk;
+    else if (dowRestricted)             dateOk = dowOk;
+    else                                dateOk = true;
+    if (!dateOk) {
+      t = new Date(t.getFullYear(), t.getMonth(), t.getDate() + 1, 0, 0, 0, 0);
+      continue;
+    }
+    if (!hours.has(t.getHours())) {
+      t = new Date(t.getFullYear(), t.getMonth(), t.getDate(), t.getHours() + 1, 0, 0, 0);
+      continue;
+    }
+    if (!mins.has(t.getMinutes())) {
+      t = new Date(t.getTime() + 60 * 1000);
+      continue;
+    }
+    results.push(new Date(t.getTime()));
+    t = new Date(t.getTime() + 60 * 1000);
+  }
+  return results;
+}
+
+function expandField(expr, lo, hi) {
+  const result = new Set();
+  const parts = expr.split(',');
+  for (const part of parts) {
+    let step = 1;
+    let base = part;
+    const slashIdx = part.indexOf('/');
+    if (slashIdx !== -1) {
+      base = part.slice(0, slashIdx);
+      step = parseInt(part.slice(slashIdx + 1), 10);
+      if (!Number.isFinite(step) || step < 1) throw new Error('invalid step: ' + part);
+    }
+    let rangeLo, rangeHi;
+    if (base === '*') {
+      rangeLo = lo; rangeHi = hi;
+    } else if (base.indexOf('-') !== -1) {
+      const [a, b] = base.split('-').map(function(s) { return parseInt(s, 10); });
+      if (!Number.isFinite(a) || !Number.isFinite(b)) throw new Error('invalid range: ' + part);
+      rangeLo = a; rangeHi = b;
+    } else {
+      const n = parseInt(base, 10);
+      if (!Number.isFinite(n)) throw new Error('invalid value: ' + part);
+      rangeLo = n; rangeHi = n;
+    }
+    if (rangeLo < lo || rangeHi > hi) throw new Error('out of range: ' + part);
+    for (let i = rangeLo; i <= rangeHi; i += step) result.add(i);
+  }
+  return result;
+}
+
+
+// -- Next-session pickup ----------------------------------------------
+
+/**
+ * Build the /__api/next-session payload. Locates the active PA's
+ * next-session.md under agents/{paName}/ (paName resolved from
+ * operator/config/preferences.json; falls back to the only agent directory
+ * that contains a next-session.md file; or to 'dave' for deployments that
+ * predate preferences). Parses the canonical section shape:
+ *
+ *   # Next session
+ *
+ *   **Last updated:** 2026-04-17 (...)
+ *
+ *   ## Top priority — start here
+ *   <paragraph>
+ *
+ *   ## On boot
+ *   1. step one
+ *   2. step two
+ *
+ * Absent file or absent "Top priority" section → { present: false }.
+ *
+ * Shape:
+ *   {
+ *     present: boolean,
+ *     agent: string | null,      // e.g. 'dave'
+ *     path: string | null,       // repo-relative
+ *     lastUpdated: string | null, // free text as written
+ *     topPriority: {             // populated iff the section was found
+ *       title: string,           // first bold/em phrase of the paragraph, or
+ *                                // the first sentence if no emphasis
+ *       body: string,            // full paragraph, markdown-stripped enough
+ *                                // for prose rendering (bold → **..**, kept)
+ *       raw: string,             // the paragraph as written
+ *     } | null,
+ *     onBoot: string[] | null,   // ordered list items, markdown-stripped
+ *     raw: string,               // the full file contents
+ *   }
+ */
+export function buildNextSession(repoRoot) {
+  // Resolve the PA name. Preference order:
+  //   1. operator/config/preferences.json → paName
+  //   2. The single agents/* directory that contains next-session.md
+  //   3. 'dave' (canonical default for legacy deployments)
+  let paName = null;
+  try {
+    const prefsFile = join(repoRoot, 'operator', 'config', 'preferences.json');
+    if (existsSync(prefsFile)) {
+      const prefs = JSON.parse(readFileSync(prefsFile, 'utf-8'));
+      if (prefs && typeof prefs.paName === 'string' && prefs.paName.length) {
+        paName = prefs.paName;
+      }
+    }
+  } catch { /* non-fatal */ }
+
+  if (!paName) {
+    const agentsDir = join(repoRoot, 'agents');
+    if (existsSync(agentsDir)) {
+      let candidates;
+      try { candidates = readdirSync(agentsDir, { withFileTypes: true }); } catch { candidates = []; }
+      const hits = [];
+      for (const c of candidates) {
+        if (!c.isDirectory()) continue;
+        const nsFile = join(agentsDir, c.name, 'next-session.md');
+        if (existsSync(nsFile)) hits.push(c.name);
+      }
+      if (hits.length === 1) paName = hits[0];
+      else if (hits.length > 1 && hits.indexOf('dave') !== -1) paName = 'dave';
+    }
+  }
+  if (!paName) paName = 'dave';
+
+  const nsRel = 'agents/' + paName + '/next-session.md';
+  const nsPath = join(repoRoot, 'agents', paName, 'next-session.md');
+  if (!existsSync(nsPath)) {
+    return {
+      present: false,
+      agent: paName,
+      path: null,
+      lastUpdated: null,
+      topPriority: null,
+      onBoot: null,
+      raw: '',
+    };
+  }
+
+  let raw = '';
+  try { raw = readFileSync(nsPath, 'utf-8'); } catch (err) {
+    return {
+      present: false,
+      agent: paName,
+      path: nsRel,
+      lastUpdated: null,
+      topPriority: null,
+      onBoot: null,
+      raw: '',
+      error: err.message,
+    };
+  }
+
+  const lastUpdated = parseNextSessionLastUpdated(raw);
+  const topPriority = parseNextSessionTopPriority(raw);
+  const onBoot = parseNextSessionOnBoot(raw);
+
+  return {
+    present: true,
+    agent: paName,
+    path: nsRel,
+    lastUpdated: lastUpdated,
+    topPriority: topPriority,
+    onBoot: onBoot,
+    raw: raw,
+  };
+}
+
+// Extracts the first `**Last updated:**` marker text. Returns the trimmed
+// phrase after the marker or null if absent.
+export function parseNextSessionLastUpdated(raw) {
+  const m = /\*\*Last updated:\*\*\s*(.+)/i.exec(raw);
+  if (!m) return null;
+  return m[1].trim().replace(/\s+$/, '') || null;
+}
+
+// Extracts the paragraph under "## Top priority — start here" (em dash or
+// hyphen tolerated). Returns null if the section is absent.
+export function parseNextSessionTopPriority(raw) {
+  // Match either the em-dash (—) or a plain hyphen; case-insensitive on the
+  // phrasing. We intentionally accept trailing whitespace / varied spacing.
+  const re = /^##\s+Top priority\s*[—-]\s*start here\s*$/im;
+  const match = re.exec(raw);
+  if (!match) return null;
+  const after = raw.slice(match.index + match[0].length);
+  // Take content up to the next heading (## or #).
+  const endMatch = /^#{1,6}\s+/m.exec(after);
+  const block = endMatch ? after.slice(0, endMatch.index) : after;
+  const paragraph = block.trim();
+  if (!paragraph) return null;
+
+  // Derive a short title: the first bold phrase (between double-asterisks),
+  // or the first sentence up to ~80 chars if no bold lead exists.
+  const boldMatch = /\*\*([^*]+)\*\*/.exec(paragraph);
+  let title;
+  if (boldMatch) {
+    title = boldMatch[1].trim();
+  } else {
+    const firstSentence = paragraph.split(/(?<=[.!?])\s+/)[0];
+    title = firstSentence.length > 90 ? firstSentence.slice(0, 87) + '…' : firstSentence;
+  }
+  // Body — strip leading/trailing whitespace; keep markdown for downstream
+  // prose rendering. The caller decides how to display it.
+  return {
+    title: title,
+    body: paragraph,
+    raw: paragraph,
+  };
+}
+
+// Extracts the numbered/bulleted list under "## On boot". Returns an array of
+// plain-text steps (markdown stripped lightly). Null if section is absent.
+export function parseNextSessionOnBoot(raw) {
+  const re = /^##\s+On boot\s*$/im;
+  const match = re.exec(raw);
+  if (!match) return null;
+  const after = raw.slice(match.index + match[0].length);
+  const endMatch = /^#{1,6}\s+/m.exec(after);
+  const block = (endMatch ? after.slice(0, endMatch.index) : after).trim();
+  if (!block) return null;
+  const lines = block.split(/\r?\n/);
+  const out = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    // Accept numbered (1. 2.) or dashed (- *) list items.
+    const m = /^(?:\d+\.|[-*])\s+(.+)$/.exec(trimmed);
+    if (!m) continue;
+    // Light markdown strip: unwrap inline code, bold, italic, links.
+    let text = m[1]
+      .replace(/`([^`]+)`/g, '$1')
+      .replace(/\*\*([^*]+)\*\*/g, '$1')
+      .replace(/\*([^*]+)\*/g, '$1')
+      .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1');
+    out.push(text.trim());
+  }
+  return out.length ? out : null;
+}
+