@stravica-ai/digital-operator-pa 0.1.49 → 0.1.50

package/dist/engineering-pa-cli/src/pa/cli.mjs

@@ -16,6 +16,7 @@ import {
   renderHealthLine,
 } from '../../../engineering-pa-core/src/distill/health.mjs';
 import { main as runMigrateInspect } from '../../../engineering-pa-migrate-inspect/src/cli.mjs';
+import { doOnboard } from './onboard.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -38,6 +39,7 @@ Usage:
   pa migrate-inspect [options]  Host inspection for migration planning
   pa launch --agent=<n> --task=<id> [--dry-run]
                               Boot a scoped agent instance bound to an identity and task
+  pa onboard <verb>           Onboarding walkthrough state (complete)
   pa -h, --help               Show this help
 
 Routed sub-CLIs (also available as standalone bins):
@@ -92,6 +94,8 @@ export async function main(argv) {
       return await runMigrateInspect(rest);
     case 'launch':
       return await doLaunch(rest);
+    case 'onboard':
+      return await doOnboard(rest);
     default:
       process.stderr.write(`[pa] unknown verb: ${verb}\n`);
       process.stderr.write(USAGE);
@@ -174,10 +178,21 @@ async function doStatus(opts = {}) {
   }
 
   // 3. Workspace reachability probe.
+  //
+  // 0.1.50 (item 12): report BOTH the running port (from `.ws.pid` when
+  // present) and the configured port when they differ, so the operator
+  // can see when the auto-probe moved the server onto a different port
+  // than preferences declare. Probe the running port when available,
+  // falling back to the configured port.
   out.write('\nWorkspace:\n');
-  const probeUrl = `http://localhost:${workspacePort}/__api/identity`;
+  const runningPort = readRunningWorkspacePort(repoRoot);
+  const effectivePort = runningPort ?? workspacePort;
+  const probeUrl = `http://localhost:${effectivePort}/__api/identity`;
   const reachability = await probeWorkspace(probeUrl, opts.fetchImpl);
   out.write(`  ${probeUrl}\n`);
+  if (runningPort !== null && runningPort !== workspacePort) {
+    out.write(`  running port: ${runningPort} (configured: ${workspacePort})\n`);
+  }
   out.write(`  status: ${reachability.status}`);
   if (reachability.detail) out.write(` (${reachability.detail})`);
   out.write('\n');
@@ -219,6 +234,37 @@ async function doStatus(opts = {}) {
   return allOk ? 0 : 2;
 }
 
+/**
+ * 0.1.50 (item 12): read the port the workspace is currently listening
+ * on from `.ws.pid`. Returns null when the pidfile is absent, corrupt,
+ * or the recorded PID is not alive. Never throws — callers fall back
+ * to the configured port silently.
+ *
+ * `.ws.pid` is written by `ws.mjs::cmdStart` on foreground spawn.
+ * Supervised installs (launchd / systemd) do NOT write it; when that is
+ * the case we still fall back to the configured port and the reachability
+ * probe hits the identity endpoint from there.
+ */
+function readRunningWorkspacePort(repoRoot) {
+  try {
+    const pidPath = join(repoRoot, '.ws.pid');
+    if (!existsSync(pidPath)) return null;
+    const raw = JSON.parse(readFileSync(pidPath, 'utf8'));
+    if (!raw || typeof raw.pid !== 'number' || typeof raw.port !== 'number') return null;
+    // Verify the process is alive before trusting the port. A stale
+    // pidfile pointing at a dead process should not surface a
+    // running-port line.
+    try {
+      process.kill(raw.pid, 0);
+    } catch {
+      return null;
+    }
+    return raw.port;
+  } catch {
+    return null;
+  }
+}
+
 function resolveWorkspacePort(repoRoot, opts = {}) {
   if (opts.workspacePort) return opts.workspacePort;
   try {

package/dist/engineering-pa-cli/src/pa/onboard.mjs

@@ -0,0 +1,114 @@
+// onboard.mjs — `pa onboard` verb, currently just the `complete` subcommand.
+//
+// Adds a completion guard to the /onboard walkthrough. `.session/onboarding.json`
+// carries per-step state; hand-editing it to set `completedAt` (the pre-0.1.50
+// pattern) skipped the mandatory-step check. This verb refuses when a mandatory
+// step is not `done`, names it, and quotes the remediation. When every mandatory
+// step is done it stamps `completedAt` with an ISO string (UTC, second-precision)
+// and preserves the 2-space indent of the file so subsequent diffs stay clean.
+//
+// Mandatory steps (as of 0.1.50): librarianSchedule. See
+// packages/core/docs/commands/onboard.md §Completion.
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { findRepoRoot } from './repo-root.mjs';
+
+const HELP = `pa onboard - Onboarding walkthrough state
+
+Usage:
+  pa onboard complete       Guard-checked completion of /onboard
+  pa onboard -h, --help     Show this help
+
+Subcommands:
+  complete
+    Reads .session/onboarding.json, refuses when any mandatory step (currently
+    librarianSchedule) is not 'done', otherwise stamps completedAt.
+
+Exit codes:
+  0 ok | 1 usage or a mandatory step is pending | 2 IO failure
+`;
+
+const MANDATORY_STEPS = [
+  {
+    id: 'librarianSchedule',
+    remediation: 'run /onboard and complete the librarianSchedule step (installs the mandatory distillation sweep)',
+  },
+];
+
+export async function doOnboard(argv) {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    process.stdout.write(HELP);
+    return 0;
+  }
+  const sub = argv[0];
+  const rest = argv.slice(1);
+  switch (sub) {
+    case 'complete':
+      return await onboardComplete(rest);
+    default:
+      process.stderr.write(`[pa onboard] unknown subcommand: ${sub}\n`);
+      process.stderr.write(HELP);
+      return 1;
+  }
+}
+
+/**
+ * Run the completion guard against `.session/onboarding.json`. Reads the
+ * file, checks every mandatory step is `done`, and stamps `completedAt`
+ * to the current UTC ISO timestamp (millisecond-truncated) when the
+ * gate passes.
+ *
+ * @param {string[]} argv  reserved; no flags today
+ * @returns {Promise<number>} exit code
+ */
+export async function onboardComplete(argv, deps = {}) {
+  const stderr = deps.stderr || process.stderr;
+  const stdout = deps.stdout || process.stdout;
+  const now = deps.now || (() => new Date().toISOString());
+  const repoRoot = deps.repoRoot
+    || process.env.PA_REPO_ROOT
+    || process.env.DAVE_REPO_ROOT
+    || await findRepoRoot(process.cwd());
+  if (!repoRoot) {
+    stderr.write('[pa onboard complete] could not resolve the operator repo root — set PA_REPO_ROOT or run from inside the instance.\n');
+    return 2;
+  }
+  const path = join(repoRoot, '.session', 'onboarding.json');
+  let raw;
+  try {
+    raw = await readFile(path, 'utf8');
+  } catch (e) {
+    if (e && e.code === 'ENOENT') {
+      stderr.write(`[pa onboard complete] no onboarding state at ${path} — run /onboard first.\n`);
+      return 1;
+    }
+    stderr.write(`[pa onboard complete] failed to read ${path}: ${e.message}\n`);
+    return 2;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    stderr.write(`[pa onboard complete] onboarding state at ${path} is not valid JSON: ${e.message}\n`);
+    return 2;
+  }
+  const steps = parsed.steps || {};
+  const pending = [];
+  for (const step of MANDATORY_STEPS) {
+    if (steps[step.id] !== 'done') pending.push(step);
+  }
+  if (pending.length > 0) {
+    for (const step of pending) {
+      stderr.write(`[pa onboard complete] mandatory step '${step.id}' is not done (currently: ${JSON.stringify(steps[step.id] ?? null)})\n`);
+      stderr.write(`  Remediation: ${step.remediation}\n`);
+    }
+    return 1;
+  }
+  parsed.completedAt = now();
+  const hadTrailingNewline = raw.endsWith('\n');
+  await writeFile(path, JSON.stringify(parsed, null, 2) + (hadTrailingNewline ? '\n' : ''));
+  stdout.write(`Onboarding marked complete at ${parsed.completedAt}\n`);
+  return 0;
+}

package/dist/engineering-pa-core/docs/commands/onboard.md

@@ -97,23 +97,17 @@ line to run; do not run it for them (their shell rc is not our file to write).
 ### 5. workspaceOffer
 
 Ask if they want the local workspace started now. On yes, run
-`pnpm exec pa workspace start` in the background and print the URL from
-`operator/config/preferences.json:workspacePort` (default 4200).
-
-If the start fails because the configured port is already in use (the
-operator has something else on 4200, or the previous session did not
-shut down cleanly), do NOT stop the walkthrough. Instead:
-
-1. Pick a free port at or above 4210 (probe 4210, 4211, 4212 ... in
-   order until one is free).
-2. Retry `pnpm exec pa workspace start --port N` with that port.
-3. On success, update `operator/config/preferences.json` with
-   `"workspacePort": N` so subsequent sessions start on the same port
-   without asking again. Preserve the rest of the file exactly, and
-   round-trip through `JSON.parse` / `JSON.stringify` with a two-space
-   indent to keep the on-disk shape stable.
-4. Tell the operator you moved the workspace off 4200 and named the
-   port that stuck.
+`pnpm exec pa workspace start` in the background. The CLI auto-probes
+for a free port when the configured one is busy (starting at
+max(configured+1, 4210), up to 20 attempts) and persists the chosen
+port to `operator/config/preferences.json:workspacePort`, so no manual
+port dance is needed. Print the URL from the resulting preferences
+file (the workspace start command's own output also names the chosen
+port).
+
+Pass `--port <N>` when the operator wants a specific port, or
+`--no-probe` to keep the strict hard-fail behaviour instead of the
+auto-probe.
 
 On no, note that `pnpm exec pa workspace start` is the verb whenever
 they want it.
@@ -205,6 +199,12 @@ identity each returns.
 
 ## Completion
 
-When every step is done or skipped, write `completedAt` and tell the operator
-onboarding is done. Give them one line: "You are ready. Ask me anything, or
-say `bring me up to speed` and I will run the standard session-boot briefing."
+When every step is done or skipped, run `pnpm exec pa onboard complete`.
+The verb refuses when any mandatory step (currently `librarianSchedule`)
+is not `done`, naming the pending step and its remediation; otherwise
+it stamps `completedAt` in `.session/onboarding.json` with a 2-space
+indent. Never hand-edit the file.
+
+Tell the operator onboarding is done. Give them one line: "You are
+ready. Ask me anything, or say `bring me up to speed` and I will run
+the standard session-boot briefing."

package/dist/engineering-pa-core/src/distill/health.mjs

@@ -23,9 +23,12 @@
 import { readFile, stat } from 'node:fs/promises';
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+import { platform } from 'node:os';
 
 import { readPreferencesSync } from '../preferences.mjs';
 import { countStagedObservations } from './staging.mjs';
+import { launchdLabelPrefix } from '../scheduler/install.mjs';
 
 /**
  * Default sweep cadence in hours. The scaffolded schedule fires every
@@ -104,6 +107,7 @@ export function readScheduleFile(repoRoot, paName) {
       schedule: parsed.schedule ?? null,
       host: parsed.host ?? null,
       id: parsed.id ?? null,
+      agent: parsed.agent ?? null,
     };
   } catch (err) {
     return { path, present: true, parseError: err.message || String(err) };
@@ -125,6 +129,103 @@ export function resolvePaName(repoRoot) {
   return null;
 }
 
+/**
+ * Ask the schedule's declared backend whether it currently carries this
+ * schedule as a registered job. Returns a `{ registered, reason? }`
+ * envelope so callers can render an honest reason for a `false`.
+ *
+ * Semantics:
+ *   - `{ registered: true }`: backend queried and confirms the job.
+ *   - `{ registered: false }`: backend queried and reports no job, OR
+ *     the declared backend is unavailable on this platform (in which
+ *     case a `reason` such as `backend launchd unavailable on linux`
+ *     is attached and the surface renders it).
+ *   - `{ registered: null }`: cannot query at all (no id, unknown
+ *     backend, systemd path we do not probe). The surface keeps the
+ *     "registration unknown" line rather than misreporting a state.
+ *
+ * Costs one small subprocess per call (launchctl list, crontab -l,
+ * schtasks /Query). Called from the SessionStart hook so it must be
+ * cheap; each supported backend's probe is O(1) or O(lines in crontab).
+ *
+ * Backend probes:
+ *   - launchd: `launchctl list <label>` (exit 0 = registered) on darwin.
+ *     Off darwin the backend is unavailable → not registered here, with
+ *     a reason. Label format is `com.<agent||'dave'>.<id>`.
+ *   - cron: `crontab -l` contains `# dave-<id>` (the tag prefix is a
+ *     load-bearing invariant on the removal path; changing it would
+ *     break existing installs — see install.mjs::buildCronLine and the
+ *     0.1.50 release brief item 5). If a future release switches the
+ *     tag to `${agent}-<id>` this probe will need to match either form.
+ *     Cron is treated as available on any POSIX host; a missing crontab
+ *     binary surfaces as `not registered` rather than platform-unavailable.
+ *   - schtasks: `schtasks.exe /Query /TN "<agent>-<id>"` on win32. Off
+ *     win32 the backend is unavailable → not registered here, with a
+ *     reason.
+ *   - systemd + unknown backends: not implemented; returns
+ *     `{ registered: null }` so the surface degrades to "unknown"
+ *     rather than misreporting a state we cannot verify.
+ *
+ * @param {object} schedule  as returned by readScheduleFile (present:true branch)
+ * @param {object} [deps]
+ * @param {(cmd: string, opts?: object) => string|Buffer} [deps.execSync]
+ * @param {() => string} [deps.platform]
+ * @returns {{ registered: boolean|null, reason?: string }}
+ */
+export function checkBackendRegistered(schedule, deps = {}) {
+  if (!schedule || !schedule.present || !schedule.id) return { registered: null };
+  const exec = deps.execSync || execSync;
+  const plat = deps.platform || platform;
+  const backend = schedule.backend;
+  const id = schedule.id;
+  try {
+    if (backend === 'launchd') {
+      const p = plat();
+      if (p !== 'darwin') {
+        return { registered: false, reason: `backend launchd unavailable on ${p}` };
+      }
+      const label = `${launchdLabelPrefix(schedule.agent)}${id}`;
+      try {
+        exec(`launchctl list ${label}`, { stdio: 'pipe' });
+        return { registered: true };
+      } catch {
+        return { registered: false };
+      }
+    }
+    if (backend === 'cron') {
+      let out;
+      try {
+        out = String(exec('crontab -l 2>/dev/null', { stdio: ['ignore', 'pipe', 'ignore'] }));
+      } catch {
+        // exit 1 with an empty crontab is the "no jobs" case, not a
+        // missing binary. Treat both as "not registered" (returning
+        // false rather than null keeps the surface actionable).
+        return { registered: false };
+      }
+      return { registered: out.includes(`# dave-${id}`) };
+    }
+    if (backend === 'schtasks') {
+      const p = plat();
+      if (p !== 'win32') {
+        return { registered: false, reason: `backend schtasks unavailable on ${p}` };
+      }
+      const taskName = `${schedule.agent || 'dave'}-${id}`;
+      try {
+        exec(`schtasks.exe /Query /TN "${taskName}"`, { stdio: 'pipe' });
+        return { registered: true };
+      } catch {
+        return { registered: false };
+      }
+    }
+    // systemd + unknown backends: the surface prefers "unknown" over
+    // "unregistered" here — a false negative would generate a permanent
+    // warning on hosts using a supported-but-unprobed backend.
+    return { registered: null };
+  } catch {
+    return { registered: null };
+  }
+}
+
 /**
  * Compose the full distillation-health object for a given operator repo.
  *
@@ -152,15 +253,34 @@ export async function computeDistillationHealth({
   cadenceHours = DEFAULT_CADENCE_HOURS,
   staleMultiplier = DEFAULT_STALE_MULTIPLIER,
   now = new Date(),
+  checkRegistered = checkBackendRegistered,
+  hqMode = null,
 } = {}) {
   if (!repoRoot) throw new Error('computeDistillationHealth: repoRoot is required');
   const resolvedName = paName ?? resolvePaName(repoRoot);
   const warnings = [];
   let ok = true;
 
+  // HQ-mode signal: preferences.library.mode === 'remote' means the
+  // remote library service owns distillation, and there is no local
+  // schedule to install. Callers can inject `hqMode` for tests; when
+  // omitted we resolve from preferences (best-effort, never throws —
+  // a broken preferences file is a separate warning class).
+  let hq = hqMode;
+  if (hq === null) {
+    try {
+      const prefs = readPreferencesSync(repoRoot);
+      hq = prefs && prefs.library && prefs.library.mode === 'remote';
+    } catch { hq = false; }
+  }
+
   // Schedule file — presence is a hard requirement (without it, no
   // scheduled sweep runs, ever). Missing is a warning, not a throw:
   // the surface still needs to render for pa status.
+  //
+  // In HQ mode the schedule does not live on the local host at all;
+  // the remote library service runs the sweep, so a missing schedule
+  // file is expected and does NOT warn.
   let schedule;
   if (!resolvedName) {
     schedule = { present: false, path: null };
@@ -169,10 +289,12 @@ export async function computeDistillationHealth({
   } else {
     schedule = readScheduleFile(repoRoot, resolvedName);
     if (!schedule.present) {
-      warnings.push(
-        `no distillation schedule at schedules/${distillationScheduleFilename(resolvedName)} — run /onboard to install one`,
-      );
-      ok = false;
+      if (!hq) {
+        warnings.push(
+          `no distillation schedule at schedules/${distillationScheduleFilename(resolvedName)} — run /onboard to install one`,
+        );
+        ok = false;
+      }
     } else if (schedule.parseError) {
       warnings.push(`distillation schedule file is corrupt: ${schedule.parseError}`);
       ok = false;
@@ -182,6 +304,32 @@ export async function computeDistillationHealth({
     }
   }
 
+  // Backend registration check — a scaffolded file the caller never
+  // installed means the sweep will never fire. Distinguish
+  // "installed" from "scaffolded, not registered" so the surface can
+  // point at `scheduler install ... --force-host` when the fix is one
+  // command away.
+  if (schedule && schedule.present && !schedule.parseError && schedule.enabled !== false) {
+    const raw = checkRegistered(schedule);
+    // Accept either the object envelope `{ registered, reason? }` or the
+    // legacy bare boolean|null (kept for injected stubs in older tests).
+    const result = raw && typeof raw === 'object' && 'registered' in raw
+      ? raw
+      : { registered: raw };
+    schedule.registered = result.registered;
+    schedule.registeredReason = result.reason || null;
+    if (result.registered === false) {
+      const reasonSuffix = result.reason ? ` (${result.reason})` : '';
+      warnings.push(
+        `distillation schedule scaffolded but not registered with ${schedule.backend || 'the backend'}${reasonSuffix} — run \`scheduler install schedules/${distillationScheduleFilename(resolvedName)} --force-host\` to register`,
+      );
+      ok = false;
+    }
+  } else if (schedule && schedule.present) {
+    schedule.registered = null;
+    schedule.registeredReason = null;
+  }
+
   // Last-run ledger — null (never run), an error, or the last record.
   const lastRun = await readLastLedgerEntry(repoRoot);
   let annotatedLastRun = lastRun;
@@ -224,6 +372,7 @@ export async function computeDistillationHealth({
     stagingCount,
     warnings,
     ok,
+    hqMode: !!hq,
     generatedAt: now.toISOString(),
   };
 }
@@ -253,8 +402,23 @@ export function formatDuration(seconds) {
  */
 export function renderHealthLine(health) {
   const parts = [];
-  if (health.schedule?.present && health.schedule.enabled !== false) {
-    parts.push(`schedule: installed (${health.schedule.backend || 'backend?'}, ${health.schedule.schedule || '?'})`);
+  // HQ-mode instances have no local schedule at all — the remote
+  // library service owns distillation. Render that state distinctly so
+  // the surface does not scream "MISSING" at an instance whose design
+  // is to have no local schedule (item 6, 0.1.50).
+  if (health.hqMode && !health.schedule?.present) {
+    parts.push('schedule: remote (library service)');
+  } else if (health.schedule?.present && health.schedule.enabled !== false) {
+    // Three states: installed / scaffolded, not registered / installed
+    // (registration unknown — happens on backends we cannot probe).
+    if (health.schedule.registered === false) {
+      const reasonSuffix = health.schedule.registeredReason
+        ? `; ${health.schedule.registeredReason}`
+        : '';
+      parts.push(`schedule: scaffolded, not registered (${health.schedule.backend || 'backend?'}, ${health.schedule.schedule || '?'}${reasonSuffix})`);
+    } else {
+      parts.push(`schedule: installed (${health.schedule.backend || 'backend?'}, ${health.schedule.schedule || '?'})`);
+    }
   } else if (health.schedule?.present === false) {
     parts.push('schedule: MISSING');
   } else if (health.schedule?.enabled === false) {

package/dist/engineering-pa-core/src/distill/run.mjs

@@ -38,6 +38,8 @@ import { basename, join } from 'node:path';
 import { resolvePrereqs } from './prereqs.mjs';
 import { countStagedObservations } from './staging.mjs';
 import { buildDistillPrompt, claudeArgs, resolveDistillModel } from './prompt.mjs';
+import { buildBacklinkIndex } from '../knowledge/retrieval/backlink-indexer.mjs';
+import { buildKnowledgeGraph } from '../knowledge/retrieval/graph-builder.mjs';
 
 function log(line, { stderr = process.stderr } = {}) {
   stderr.write(`[distill] ${line}\n`);
@@ -225,6 +227,23 @@ export async function runDistill({
   // so a deletion at commit time is invisible to git.
   await invalidateRetrievalArtefacts(repoRoot, stderr);
 
+  // Durable post-sweep rebuild (item 8, 0.1.50): same two builders
+  // `pa knowledge` uses on demand, in the same order (backlinks first,
+  // graph reads them). Landing them on disk right after invalidation
+  // means the SessionStart hook and every desk-cache path see the
+  // artefact without paying for an on-demand build on the next boot.
+  // NEVER fail the sweep on a builder error: a durable artefact is a
+  // convenience, on-demand rebuild remains the fallback.
+  try {
+    await buildBacklinkIndex({ root: repoRoot });
+    await buildKnowledgeGraph({ root: repoRoot });
+  } catch (e) {
+    log(
+      `warning: post-sweep retrieval rebuild failed (${e.message}); on-demand fallback remains`,
+      { stderr },
+    );
+  }
+
   // Step 4b — append success audit. Sync will pick up any file changes
   // the librarian produced on its next 30-minute tick.
   await writeAudit(runsLog, {

package/dist/engineering-pa-core/src/instance-root/find.mjs

@@ -0,0 +1,104 @@
+// find.mjs — shared sync resolver for the operator instance root.
+//
+// Promoted from packages/workspace/src/repo-root.mjs so scheduler,
+// knowledge retrieval, and every other core consumer resolves the
+// instance root through ONE primitive instead of ad-hoc walks that
+// each get the pnpm-store trap wrong on their own.
+//
+// Under the published tarball layout, every dist package lives at
+// `node_modules/@stravica-ai/digital-operator-pa/dist/engineering-pa-*/`.
+// A `resolve(__dirname, '..', '..', '..')` walk from `src/` therefore
+// lands inside the digital-operator-pa package directory (a pnpm-store
+// hard-link), NOT at the operator repo root — silently misdirecting
+// every file the caller derives from that path (schedules, retrieval
+// artefacts, `.ws.pid`, `.ws.log`, preferences overlay reads).
+//
+// Precedence:
+//
+//   1. `DAVE_REPO_ROOT` or `PA_REPO_ROOT` env override (tests + operator-set).
+//   2. Walk up from `process.cwd()` looking for a marker that identifies an
+//      operator instance root:
+//        - `.git` (present in every scaffolded instance — pa-init runs `git
+//          init` at scaffold time).
+//        - `operator/config/preferences.json` (the canonical instance marker;
+//          matches instances that lost their `.git` for any reason).
+//        - `pnpm-workspace.yaml` (matches monorepo checkouts, e.g. this
+//          engineering-pa-dev repo itself, so package-local tests still work).
+//   3. Fall back to `process.cwd()` so pre-scaffold and dry-run flows still
+//      have a stable value to render.
+//
+// The `startDir` argument is injectable for tests and callers that need to
+// resolve from a directory other than `process.cwd()`. Prod callers use
+// the default.
+
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+const MARKERS = [
+  '.git',
+  join('operator', 'config', 'preferences.json'),
+  'pnpm-workspace.yaml',
+];
+
+/**
+ * Walk up from `start` looking for the first directory that contains any
+ * marker in {@link MARKERS}. Returns the directory path, or null when the
+ * walk reaches the filesystem root without a hit.
+ *
+ * @param {string} start
+ * @returns {string|null}
+ */
+export function walkUpForMarker(start) {
+  let d = resolve(start);
+  while (d && d !== resolve(d, '..')) {
+    for (const marker of MARKERS) {
+      if (existsSync(join(d, marker))) return d;
+    }
+    d = resolve(d, '..');
+  }
+  return null;
+}
+
+// Process-level guard so the fallback warning fires at most once per
+// process, no matter how many callers hit the resolver. Tests can reset
+// via the exported `_resetFallbackWarningForTests` helper below.
+let _fallbackWarned = false;
+
+/** Test-only reset for the once-per-process fallback warning latch. */
+export function _resetFallbackWarningForTests() {
+  _fallbackWarned = false;
+}
+
+/**
+ * Resolve the operator instance root. Deterministic and synchronous; safe
+ * to call at module top-level. See the header comment for the full
+ * precedence rule.
+ *
+ * When no marker is found AND no env override is set, emit ONE stderr
+ * warning naming the cwd we're falling back to and the two overrides that
+ * would silence it. The walk still returns cwd so pre-scaffold and dry-run
+ * flows keep working — the warning is a diagnostic, not an error.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.startDir=process.cwd()] Directory to start the walk from.
+ * @param {NodeJS.ProcessEnv} [opts.env=process.env] Env source (tests inject).
+ * @param {(msg: string) => void} [opts.warn] Optional warn sink (tests inject).
+ * @returns {string} Absolute path.
+ */
+export function findRepoRootSync(opts = {}) {
+  const env = opts.env || process.env;
+  const startDir = opts.startDir || process.cwd();
+  const envRoot = env.DAVE_REPO_ROOT || env.PA_REPO_ROOT;
+  if (envRoot) return resolve(envRoot);
+  const found = walkUpForMarker(startDir);
+  if (found) return found;
+  const fallback = resolve(startDir);
+  if (!_fallbackWarned) {
+    _fallbackWarned = true;
+    const warn = opts.warn || ((m) => process.stderr.write(m + '\n'));
+    warn(
+      `workspace: no instance marker (.git, operator/config/preferences.json, pnpm-workspace.yaml) found walking up from ${fallback}; falling back to cwd. Set DAVE_REPO_ROOT or PA_REPO_ROOT to silence.`,
+    );
+  }
+  return fallback;
+}

package/dist/engineering-pa-core/src/knowledge/retrieval/backlink-indexer.mjs

@@ -29,9 +29,14 @@ import { join, resolve, dirname, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { buildFileIndex, extractLinks, scanSourcesFor, toPosix, walkFiles } from './links.mjs';
 import { writeJsonAtomic } from './write-atomic.mjs';
+import { findRepoRootSync } from '../../instance-root/find.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const DEFAULT_ROOT = resolve(__dirname, '../../../..');
+const DEFAULT_ROOT = process.env.DAVE_ROOT
+  ? resolve(process.env.DAVE_ROOT)
+  : process.env.PA_ROOT
+    ? resolve(process.env.PA_ROOT)
+    : findRepoRootSync();
 
 const USAGE = `
 backlink-indexer — Build a backlink index from markdown internal links

package/dist/engineering-pa-core/src/knowledge/retrieval/graph-builder.mjs

@@ -29,9 +29,14 @@ import {
   walkFiles,
 } from './links.mjs';
 import { writeJsonAtomic } from './write-atomic.mjs';
+import { findRepoRootSync } from '../../instance-root/find.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const DEFAULT_ROOT = resolve(__dirname, '../../../..');
+const DEFAULT_ROOT = process.env.DAVE_ROOT
+  ? resolve(process.env.DAVE_ROOT)
+  : process.env.PA_ROOT
+    ? resolve(process.env.PA_ROOT)
+    : findRepoRootSync();
 
 const USAGE = `
 graph-builder — Build a knowledge graph from markdown links, index hubs and backlinks