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

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

@@ -11,6 +11,10 @@ import { fileURLToPath } from 'node:url';
 import { run as runDesk } from '../../../engineering-pa-core/src/desk/cli.mjs';
 import { PA_PACKAGE_NAME } from '../../../engineering-pa-core/src/config/pa-package-name.mjs';
 import { readPreferencesSync } from '../../../engineering-pa-core/src/preferences.mjs';
+import {
+  computeDistillationHealth,
+  renderHealthLine,
+} from '../../../engineering-pa-core/src/distill/health.mjs';
 import { main as runMigrateInspect } from '../../../engineering-pa-migrate-inspect/src/cli.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -180,7 +184,26 @@ async function doStatus(opts = {}) {
   // Workspace-not-running is OK — operators may run pa status before
   // starting the workspace server.
 
-  // 4. Desk overview snapshot.
+  // 4. Distillation health — schedule installed?, last run, staging
+  // count. Load-bearing because the whole self-learning loop dies
+  // silently otherwise (the estate has already been bitten: on the
+  // WSD-laptop cold-install proof of 0.1.41, staged observations piled
+  // up for days without a scheduled sweep to distil them). Rendered on
+  // one line, prefixed `[ok]` or `[warn]` per the health module.
+  out.write('\nDistillation:\n');
+  try {
+    const health = await computeDistillationHealth({ repoRoot });
+    out.write(`  ${renderHealthLine(health)}\n`);
+    // Do NOT flip allOk here — a fresh scaffold with no schedule
+    // installed (the exact moment /onboard is meant to run) would then
+    // exit 2 from pa status, which is the pre-install check for the
+    // scaffold itself. Warnings are visible in the line; exit code is
+    // reserved for structural failures (missing operator/).
+  } catch (e) {
+    out.write(`  distillation health probe failed: ${e?.message || e}\n`);
+  }
+
+  // 5. Desk overview snapshot.
   out.write('\nOverview:\n');
   try {
     const code = await runDesk(['overview']);

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

@@ -28,17 +28,21 @@ Read `.session/onboarding.json` first. Shape:
   "version": 1,
   "startedAt": "<iso>",
   "steps": {
-    "verifyRuntime": "pending" | "done" | "skipped",
-    "verifyVersion": "pending" | "done" | "skipped",
-    "profileIntake": "pending" | "done" | "skipped",
-    "aliasOffer":    "pending" | "done" | "skipped",
-    "workspaceOffer":"pending" | "done" | "skipped",
-    "atlassianOffer":"pending" | "done" | "skipped"
+    "verifyRuntime":     "pending" | "done" | "skipped",
+    "verifyVersion":     "pending" | "done" | "skipped",
+    "profileIntake":     "pending" | "done" | "skipped",
+    "aliasOffer":        "pending" | "done" | "skipped",
+    "workspaceOffer":    "pending" | "done" | "skipped",
+    "librarianSchedule": "pending" | "done",
+    "atlassianOffer":    "pending" | "done" | "skipped"
   },
   "completedAt": null | "<iso>"
 }
 ```
 
+`librarianSchedule` never lands on `skipped`. It is a mandatory step and
+onboarding does not complete until it is `done`.
+
 If the file is missing, the scaffold did not seed it — flag that and stop.
 
 If `completedAt` is set, tell the operator onboarding is already complete and
@@ -114,7 +118,77 @@ shut down cleanly), do NOT stop the walkthrough. Instead:
 On no, note that `pnpm exec pa workspace start` is the verb whenever
 they want it.
 
-### 6. atlassianOffer
+### 6. librarianSchedule (mandatory, no opt-out)
+
+The distillation sweep is what turns staged observations under
+`agents/<paName>/staging/` into knowledge docs under
+`operator/knowledge/`. Without a scheduled sweep the whole self-learning
+loop dies silently: staged notes pile up, no docs get promoted, and
+`pa knowledge search` never sees the new material. The scaffold ships
+the schedule file at `schedules/<paName>-distillation-sweep.json`; this
+step installs it on the OS-native backend and fires one real run to
+prove the wiring.
+
+Do NOT ask the operator whether to do this. State what is happening in
+one short paragraph:
+
+> Installing the librarian distillation sweep so your Digital Operator
+> keeps learning. It runs every four hours in the background, turns your
+> staged observations into knowledge docs, and refreshes the retrieval
+> graph so the new material is searchable straight away. This is the
+> one piece of scheduling every solo instance needs.
+
+Then run:
+
+```
+pnpm exec scheduler install schedules/<paName>-distillation-sweep.json --force-host
+```
+
+Substitute `<paName>` from `operator/config/preferences.json`. The
+`--force-host` is deliberate. macOS hostnames flap between the DHCP
+name and the configured name (Dex 2026-07-16 evidence), and a well-
+formed refusal at first-run onboarding is the worst possible operator
+experience.
+
+Immediately after install, trigger one real sweep through the scheduler
+backend itself (never a shell repro: a shell resolves `node` and PATH
+differently and would hide the launchd/cron spawn behaviour the ledger
+is meant to prove). On macOS/launchd:
+
+```
+launchctl kickstart -k "gui/$(id -u)/com.<paName>.<paName>-distillation-sweep"
+```
+
+On Linux/cron, invoke the exact command line the crontab entry carries,
+from the same working directory, with a minimal PATH the cron job would
+see:
+
+```
+env -i HOME="$HOME" PATH=/usr/local/bin:/usr/bin:/bin \
+  bash -c 'cd <targetDir> && node node_modules/@stravica-ai/digital-operator-pa/bin/distill run'
+```
+
+Wait for the run with a hard timeout of 6 minutes (a real sweep with
+one `claude --print` subprocess is typically 60–120 seconds, but the
+first-ever run on a cold cache can stretch). Poll
+`.cache/distill/logs/runs.jsonl`. A completed run appends one JSON line
+with `"status": "ok"` or `"status": "noop-empty-staging"`. Either
+status is a successful proof: the pipeline ran end to end.
+
+Mark this step `done` only when the ledger shows a completed run. If
+the install fails, or the run times out, or the ledger records a
+`fail-*` status, this step is NOT `done`, onboarding does NOT complete,
+and the operator gets:
+
+1. The exact error message (from the scheduler CLI's stderr, or the
+   ledger's `reason` field, or a timeout notice).
+2. The one command to retry, verbatim:
+   `pnpm exec scheduler install schedules/<paName>-distillation-sweep.json --force-host`
+
+Then stop. Do not silently skip to `atlassianOffer`. The whole
+onboarding is blocked on this step.
+
+### 7. atlassianOffer
 
 Ask if they use Jira or Confluence. On no, mark skipped. On yes, walk them
 through:

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

@@ -10,12 +10,26 @@ import { parseArgs } from 'node:util';
 import { defaultRepoRoot } from './prereqs.mjs';
 import { runDistill } from './run.mjs';
 import { defaultRunner } from './runner.mjs';
+import {
+  buildHealthHookEnvelope,
+  computeDistillationHealth,
+  renderHealthBlock,
+  renderHealthLine,
+} from './health.mjs';
 
 const USAGE = `distill — librarian distillation sweep runner
 
 Usage:
   distill run                Run a real distillation sweep
   distill run --dry-run      Print what would run, don't invoke claude
+  distill health             Print one-line schedule + last-run + staging summary
+  distill health --json      Print the full health object as JSON
+  distill health --block     Print the multi-line markdown block
+  distill health --hook-envelope
+                             Print a Claude Code SessionStart hook envelope
+                             (JSON, {hookSpecificOutput: {...}}) — the shape
+                             scaffolded into .claude/settings.json so the
+                             summary is injected at session boot.
   distill -h, --help         Show this help
 
 Exit codes:
@@ -106,6 +120,57 @@ async function route(argv) {
     process.exit(code ?? 0);
   }
 
+  if (verb === 'health') {
+    const { values } = parseArgs({
+      args: rest,
+      options: {
+        json: { type: 'boolean', default: false },
+        block: { type: 'boolean', default: false },
+        'hook-envelope': { type: 'boolean', default: false },
+        help: { type: 'boolean', short: 'h', default: false },
+      },
+      strict: true,
+    });
+    if (values.help) {
+      process.stdout.write(USAGE);
+      process.exit(0);
+    }
+    const repoRoot = await defaultRepoRoot();
+    if (!repoRoot) {
+      // Preserve exit-code hygiene: no repo root == prerequisite missing.
+      // Still emit a valid hook envelope on --hook-envelope so a badly
+      // configured Claude session never sees invalid JSON on stdout.
+      const fallback = {
+        repoRoot: null, paName: null, cadenceHours: 4,
+        schedule: { present: false, path: null },
+        lastRun: null, stagingCount: { error: 'no repo root resolved' },
+        warnings: ['no operator repo root resolved from cwd (no `.git` ancestor and no DAVE_REPO_ROOT / PA_REPO_ROOT set)'],
+        ok: false,
+        generatedAt: new Date().toISOString(),
+      };
+      if (values['hook-envelope']) {
+        process.stdout.write(JSON.stringify(buildHealthHookEnvelope(fallback)) + '\n');
+        process.exit(0);
+      }
+      if (values.json) process.stdout.write(JSON.stringify(fallback, null, 2) + '\n');
+      else if (values.block) process.stdout.write(renderHealthBlock(fallback));
+      else process.stdout.write(renderHealthLine(fallback) + '\n');
+      process.exit(2);
+    }
+    const health = await computeDistillationHealth({ repoRoot });
+    if (values['hook-envelope']) {
+      process.stdout.write(JSON.stringify(buildHealthHookEnvelope(health)) + '\n');
+      // Hook path: always exit 0. Failing here would surface as a Claude
+      // Code hook error at every session boot, which is worse than a
+      // rendered warning block.
+      process.exit(0);
+    }
+    if (values.json) process.stdout.write(JSON.stringify(health, null, 2) + '\n');
+    else if (values.block) process.stdout.write(renderHealthBlock(health));
+    else process.stdout.write(renderHealthLine(health) + '\n');
+    process.exit(0);
+  }
+
   process.stderr.write(`[distill] unknown command: ${verb}\n`);
   process.stderr.write(USAGE);
   process.exit(1);

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

@@ -0,0 +1,322 @@
+// distill — librarian schedule + last-run health surface.
+//
+// Reads:
+//   1. the operator's `schedules/<paName>-distillation-sweep.json` (does the
+//      schedule file exist at all — a scaffolded solo instance ships one but
+//      an older upgrade may not).
+//   2. the distill ledger at `<repoRoot>/.cache/distill/logs/runs.jsonl`
+//      (last run: ts, status, durationSec, stagingCount).
+//   3. the current staged-observation count via `countStagedObservations`
+//      (how much material is queued for the next sweep).
+//
+// Consumers:
+//   * `pa status` prints a distillation line built from `renderHealthLine`.
+//   * A scaffolded `SessionStart` hook injects `buildHealthHookEnvelope`'s
+//     output at the top of every session, so the operator sees the same
+//     summary without asking.
+//   * `distill health --json` prints the raw computed object so scripts
+//     can key on it.
+//
+// This module is READ-ONLY. It never invokes claude, never triggers a
+// sweep, never touches the schedule backend. Cheap to call from a hook.
+
+import { readFile, stat } from 'node:fs/promises';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { readPreferencesSync } from '../preferences.mjs';
+import { countStagedObservations } from './staging.mjs';
+
+/**
+ * Default sweep cadence in hours. The scaffolded schedule fires every
+ * four hours; the health surface warns when the last run is older than
+ * `staleMultiplier * cadenceHours` (default 2 * 4 = 8 hours), so a
+ * one-cycle miss is quiet but a two-cycle miss surfaces.
+ */
+export const DEFAULT_CADENCE_HOURS = 4;
+
+/**
+ * How many multiples of the cadence a last-run can lag before the health
+ * surface labels it stale. Two is deliberate: a single missed tick is
+ * common (host asleep, laptop closed at the wrong minute) and would
+ * generate false alarms.
+ */
+export const DEFAULT_STALE_MULTIPLIER = 2;
+
+/**
+ * Read the last non-empty line of the distill ledger. Returns null when
+ * the ledger does not exist or has never seen a real run. All other
+ * read failures surface as a `{ error }` object so the caller can render
+ * something honest instead of crashing.
+ *
+ * The ledger is append-only JSONL and typically small (dozens of lines
+ * over months). Reading the whole file is cheaper than streaming the
+ * tail in every context we call this from.
+ */
+export async function readLastLedgerEntry(repoRoot) {
+  const path = join(repoRoot, '.cache', 'distill', 'logs', 'runs.jsonl');
+  let raw;
+  try {
+    raw = await readFile(path, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    return { error: `ledger read failed: ${err.message || err}` };
+  }
+  const lines = raw.split('\n').filter((l) => l.trim().length > 0);
+  if (lines.length === 0) return null;
+  const last = lines[lines.length - 1];
+  try {
+    return JSON.parse(last);
+  } catch (err) {
+    return { error: `ledger last line unparseable: ${err.message || err}` };
+  }
+}
+
+/**
+ * Resolve the schedule file name a fresh scaffold writes. Kept in one
+ * place so the scaffold, the health surface, and the `/onboard`
+ * walkthrough all agree.
+ */
+export function distillationScheduleId(paName) {
+  return `${paName}-distillation-sweep`;
+}
+
+export function distillationScheduleFilename(paName) {
+  return `${distillationScheduleId(paName)}.json`;
+}
+
+/**
+ * Locate the scaffolded distillation schedule file for a given repo.
+ * Returns `{ path, present }`, and when present also `{ enabled, backend,
+ * schedule, host }` parsed from the JSON (best-effort — a corrupt file
+ * lands as `{ present: true, parseError: '...' }`).
+ */
+export function readScheduleFile(repoRoot, paName) {
+  const path = join(repoRoot, 'schedules', distillationScheduleFilename(paName));
+  if (!existsSync(path)) return { path, present: false };
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    return {
+      path,
+      present: true,
+      enabled: parsed.enabled !== false,
+      backend: parsed.backend ?? null,
+      schedule: parsed.schedule ?? null,
+      host: parsed.host ?? null,
+      id: parsed.id ?? null,
+    };
+  } catch (err) {
+    return { path, present: true, parseError: err.message || String(err) };
+  }
+}
+
+/**
+ * Resolve the PA name from `operator/config/preferences.json`. Falls
+ * back to null (the caller reports missing-preferences instead of
+ * guessing a name).
+ */
+export function resolvePaName(repoRoot) {
+  try {
+    const prefs = readPreferencesSync(repoRoot);
+    if (prefs && typeof prefs.paName === 'string' && prefs.paName.length > 0) {
+      return prefs.paName;
+    }
+  } catch { /* fall through */ }
+  return null;
+}
+
+/**
+ * Compose the full distillation-health object for a given operator repo.
+ *
+ * Shape:
+ * {
+ *   repoRoot, paName, cadenceHours,
+ *   schedule: { path, present, enabled?, backend?, schedule?, host?, id? } | { present: false } | { parseError },
+ *   lastRun: null | { ts, status, exitCode, durationSec, stagingCount, log, reason?, ageSeconds? } | { error },
+ *   stagingCount: number | { error },
+ *   warnings: string[],
+ *   ok: boolean,
+ *   generatedAt: string (ISO)
+ * }
+ *
+ * `ok` is true when the schedule file is present and enabled, staging
+ * is readable, and (if there is any last run at all) that run's status
+ * is not a `fail-*` and its age is inside `staleMultiplier * cadenceHours`.
+ * A brand-new instance with no runs yet is `ok: true` with a warning; the
+ * warning describes the exact next action ("run `distill run` to seed
+ * the ledger").
+ */
+export async function computeDistillationHealth({
+  repoRoot,
+  paName = null,
+  cadenceHours = DEFAULT_CADENCE_HOURS,
+  staleMultiplier = DEFAULT_STALE_MULTIPLIER,
+  now = new Date(),
+} = {}) {
+  if (!repoRoot) throw new Error('computeDistillationHealth: repoRoot is required');
+  const resolvedName = paName ?? resolvePaName(repoRoot);
+  const warnings = [];
+  let ok = true;
+
+  // 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.
+  let schedule;
+  if (!resolvedName) {
+    schedule = { present: false, path: null };
+    warnings.push('no paName in operator/config/preferences.json — cannot resolve the distillation schedule file');
+    ok = false;
+  } else {
+    schedule = readScheduleFile(repoRoot, resolvedName);
+    if (!schedule.present) {
+      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;
+    } else if (schedule.enabled === false) {
+      warnings.push('distillation schedule is disabled (schedule.enabled === false)');
+      ok = false;
+    }
+  }
+
+  // Last-run ledger — null (never run), an error, or the last record.
+  const lastRun = await readLastLedgerEntry(repoRoot);
+  let annotatedLastRun = lastRun;
+  const cadenceSeconds = cadenceHours * 3600;
+  if (lastRun && !lastRun.error && lastRun.ts) {
+    const ageSeconds = Math.max(0, Math.round((now.getTime() - new Date(lastRun.ts).getTime()) / 1000));
+    annotatedLastRun = { ...lastRun, ageSeconds };
+    if (typeof lastRun.status === 'string' && lastRun.status.startsWith('fail-')) {
+      warnings.push(`last distillation run failed: ${lastRun.status}${lastRun.reason ? ` (${lastRun.reason})` : ''}`);
+      ok = false;
+    }
+    if (ageSeconds > staleMultiplier * cadenceSeconds) {
+      warnings.push(
+        `last distillation run was ${formatDuration(ageSeconds)} ago (cadence ${cadenceHours}h) — the scheduled sweep may not be firing`,
+      );
+      ok = false;
+    }
+  } else if (!lastRun) {
+    warnings.push('no distillation runs recorded yet — the ledger will populate on the first sweep');
+  } else if (lastRun && lastRun.error) {
+    warnings.push(lastRun.error);
+    ok = false;
+  }
+
+  // Staging count — how much material is queued.
+  let stagingCount;
+  try {
+    stagingCount = await countStagedObservations(repoRoot);
+  } catch (err) {
+    stagingCount = { error: `staging read failed: ${err.message || err}` };
+    warnings.push(stagingCount.error);
+  }
+
+  return {
+    repoRoot,
+    paName: resolvedName,
+    cadenceHours,
+    schedule,
+    lastRun: annotatedLastRun,
+    stagingCount,
+    warnings,
+    ok,
+    generatedAt: now.toISOString(),
+  };
+}
+
+/**
+ * Format a duration in seconds as a compact human-readable label. Chosen
+ * so the surface stays scan-friendly at both very-recent (`5s ago`) and
+ * very-stale (`3d 4h ago`) extremes without a dependency.
+ */
+export function formatDuration(seconds) {
+  if (typeof seconds !== 'number' || !Number.isFinite(seconds) || seconds < 0) return 'unknown';
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  const rMin = minutes % 60;
+  if (hours < 24) return rMin ? `${hours}h ${rMin}m` : `${hours}h`;
+  const days = Math.floor(hours / 24);
+  const rHr = hours % 24;
+  return rHr ? `${days}d ${rHr}h` : `${days}d`;
+}
+
+/**
+ * Render a single-line summary suitable for the `pa status` output or a
+ * one-line boot briefing. Always fits on a terminal line, and never
+ * omits the warning class when one is present.
+ */
+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 || '?'})`);
+  } else if (health.schedule?.present === false) {
+    parts.push('schedule: MISSING');
+  } else if (health.schedule?.enabled === false) {
+    parts.push('schedule: DISABLED');
+  } else if (health.schedule?.parseError) {
+    parts.push('schedule: CORRUPT');
+  } else {
+    parts.push('schedule: unknown');
+  }
+  if (health.lastRun && !health.lastRun.error && health.lastRun.ts) {
+    const age = typeof health.lastRun.ageSeconds === 'number'
+      ? formatDuration(health.lastRun.ageSeconds) + ' ago'
+      : health.lastRun.ts;
+    parts.push(`last run: ${health.lastRun.status || '?'} (${age})`);
+  } else if (health.lastRun && health.lastRun.error) {
+    parts.push('last run: ledger read failed');
+  } else {
+    parts.push('last run: never');
+  }
+  if (typeof health.stagingCount === 'number') {
+    parts.push(`staging: ${health.stagingCount}`);
+  } else if (health.stagingCount && health.stagingCount.error) {
+    parts.push('staging: unreadable');
+  }
+  const status = health.warnings.length === 0 ? 'ok' : 'warn';
+  return `[${status}] ${parts.join(' | ')}`;
+}
+
+/**
+ * Render a multi-line markdown block suitable for a SessionStart hook's
+ * `additionalContext` — the same shape autonomy-injection uses. Kept
+ * compact: a heading, the one-line summary, the warnings list, and the
+ * remediation command when the surface is not ok.
+ */
+export function renderHealthBlock(health) {
+  const lines = [];
+  lines.push('# distillationHealth (live)');
+  lines.push('');
+  lines.push(renderHealthLine(health));
+  if (health.warnings.length > 0) {
+    lines.push('');
+    lines.push('Warnings:');
+    for (const w of health.warnings) lines.push(`- ${w}`);
+  }
+  if (!health.ok) {
+    lines.push('');
+    lines.push('Remediation: run `/onboard` (idempotent), then `pnpm exec distill run` to seed the ledger.');
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Build the full Claude Code SessionStart hook envelope. The hook prints
+ * this JSON to stdout; Claude Code injects `additionalContext` into the
+ * session.
+ */
+export function buildHealthHookEnvelope(health) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext: renderHealthBlock(health),
+    },
+  };
+}

package/dist/engineering-pa-scaffold/src/generator.mjs

@@ -7,13 +7,19 @@
 // kind: 'dir' (mkdir -p) | 'file' (write file with contents) | 'json'
 // (stringify + write).
 
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import { readFile, readdir } from 'node:fs/promises';
 import { createRequire } from 'node:module';
-import { dirname, join, resolve } from 'node:path';
+import { hostname, platform } from 'node:os';
+import { delimiter as pathDelimiter, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { emptyEnvelope, renderEnvelope } from '../../engineering-pa-core/src/autonomy/envelope.mjs';
+import {
+  DEFAULT_CADENCE_HOURS,
+  distillationScheduleFilename,
+  distillationScheduleId,
+} from '../../engineering-pa-core/src/distill/health.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const requireFromHere = createRequire(import.meta.url);
@@ -553,6 +559,13 @@ export function buildOnboardingStateJson(config) {
       profileIntake: 'pending',
       aliasOffer: 'pending',
       workspaceOffer: 'pending',
+      // Mandatory — no opt-out. The distillation sweep is the only thing
+      // that turns staged observations into knowledge docs; without an
+      // installed schedule the whole self-learning loop is dead. The
+      // /onboard walkthrough runs `scheduler install` on the scaffolded
+      // schedule file and triggers one real run before it marks this
+      // step ok. See packages/core/docs/commands/onboard.md.
+      librarianSchedule: 'pending',
       atlassianOffer: 'pending',
     },
     completedAt: null,
@@ -567,10 +580,180 @@ export function buildGitkeep() {
   return '';
 }
 
+/**
+ * Pick the OS-native scheduler backend the scaffold writes into the
+ * distillation-sweep schedule file. macOS -> launchd, Linux -> cron,
+ * Windows -> schtasks. Every other platform lands on `null`, which
+ * makes `scheduler install` fall back to detect + refusal (with a
+ * clean stderr message).
+ *
+ * Kept as a switch on `process.platform` rather than a call to
+ * scheduler/detect.mjs: the schedule file is written once at scaffold
+ * time and shipped in the repo, so the backend choice must be stable
+ * (a `detect()` reading brew-installed cron vs launchd is a per-host
+ * moment-in-time decision that should not be baked into a tracked
+ * file). Every host later runs `scheduler install --force-host` from
+ * its own real backend; the schedule file's `backend` field just names
+ * the default. Exported for tests.
+ *
+ * @param {string} [plat] - override for tests; defaults to `process.platform`.
+ * @returns {'launchd'|'cron'|'schtasks'|null}
+ */
+export function defaultSchedulerBackend(plat = platform()) {
+  if (plat === 'darwin') return 'launchd';
+  if (plat === 'linux') return 'cron';
+  if (plat === 'win32') return 'schtasks';
+  return null;
+}
+
+// System paths the launchd defaults already carry (see
+// packages/core/src/scheduler/install.mjs withLaunchdDefaults). If
+// `claude` resolves inside any of these, no explicit PATH is needed on
+// the scaffolded schedule — the installer's baked-in PATH covers it.
+const LAUNCHD_DEFAULT_PATHS = [
+  '/opt/homebrew/bin',
+  '/usr/local/bin',
+  '/usr/bin',
+  '/bin',
+  '/usr/sbin',
+  '/sbin',
+];
+
+/**
+ * Walk `process.env.PATH` at scaffold time looking for the `claude`
+ * executable. Returns the resolved directory, or null if nothing on
+ * PATH matches. The scaffold uses this to decide whether to bake an
+ * explicit `environment.PATH` into the schedule file (needed when the
+ * operator's claude install lives somewhere the launchd default PATH
+ * would not find — e.g. ~/.local/bin from a curl-installer). Exported
+ * for tests, which drive it with a fake PATH.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.pathEnv] - override for tests; defaults to process.env.PATH.
+ * @param {string} [opts.binName] - override for tests; defaults to `claude`.
+ * @returns {string|null}
+ */
+export function resolveClaudeBinDir({ pathEnv, binName = 'claude' } = {}) {
+  const raw = pathEnv ?? process.env.PATH ?? '';
+  const dirs = raw.split(pathDelimiter).filter(Boolean);
+  for (const dir of dirs) {
+    const candidate = join(dir, binName);
+    let st;
+    try {
+      st = statSync(candidate);
+    } catch {
+      continue;
+    }
+    if (!st.isFile()) continue;
+    if ((st.mode & 0o111) === 0) continue;
+    return dir;
+  }
+  return null;
+}
+
+/**
+ * Build the operator repo's scaffolded `schedules/<paName>-distillation-sweep.json`.
+ *
+ * This is the single load-bearing artefact that makes the whole
+ * self-learning loop work in a solo instance. Without a scheduled
+ * sweep, `agents/<paName>/staging/` fills up forever and no knowledge
+ * doc is ever distilled. The `/onboard` walkthrough runs
+ * `scheduler install` on this file (with --force-host to survive the
+ * macOS hostname flap) as a mandatory step before onboarding is marked
+ * complete.
+ *
+ * Shape choices, with the estate lore they close:
+ *   - `command: node node_modules/@stravica-ai/digital-operator-pa/bin/distill run`.
+ *     Absolute node path is resolved by the scheduler at install time
+ *     (`resolveLaunchdArgv0('node', ...)` returns `process.execPath`);
+ *     the bin path goes through the stable `node_modules/@stravica-ai/…`
+ *     symlink rather than the versioned `.pnpm` store path, so a
+ *     package upgrade does not silently break the schedule (Dex lore
+ *     w-2026-07-16-006).
+ *   - `workingDirectory` is the absolute `targetDir`. No `${DAVE_ROOT}`
+ *     token — a solo instance is not the estate and does not have that
+ *     env var; a fresh `os.hostname()`-bound scheduler install with an
+ *     unset DAVE_ROOT would otherwise fall through to a bogus
+ *     `node_modules`-rooted path (`validateWorkDir` refuses that at
+ *     install time — good, but the scaffold should not create that
+ *     failure mode in the first place).
+ *   - `host` is the current machine's hostname as `os.hostname()`
+ *     computes it, so `scheduler install` without `--force-host` picks
+ *     up the file cleanly on the scaffolded machine, and refuses on any
+ *     other. The /onboard step passes `--force-host` unconditionally
+ *     because macOS hostnames flap between the DHCP name and the
+ *     configured name (w018 hostname-flap precedent), and a well-formed
+ *     refusal at first-run onboarding is the worst possible operator
+ *     experience.
+ *   - `enabled: true`. This is not opt-in.
+ *   - `schedule: '0 * / 4 * * *'` — every 4 hours, on the hour. Matches
+ *     the estate's original distillation-sweep cadence and cheap enough
+ *     that a solo instance never notices the tick.
+ *   - `environment.PATH` is included ONLY when `claude` resolves at
+ *     scaffold time OUTSIDE the launchd default PATH set (e.g. ~/.local/bin
+ *     from the curl installer). In the common brew case it's covered by
+ *     `withLaunchdDefaults()` and setting an explicit PATH would
+ *     override — not merge — that default and lose the standard
+ *     directories (w-2026-08-05 EnvironmentVariables trap).
+ *
+ * @param {object} config
+ * @param {string} config.paName
+ * @param {string} config.targetDir - absolute
+ * @param {object} [seams]
+ * @param {string} [seams.host] - hostname override (for tests)
+ * @param {'launchd'|'cron'|'schtasks'|null} [seams.backend] - override (for tests)
+ * @param {string|null} [seams.claudeBinDir] - override (for tests)
+ * @returns {object}
+ */
+export function buildDistillationScheduleJson(config, seams = {}) {
+  const backend = seams.backend !== undefined ? seams.backend : defaultSchedulerBackend();
+  const host = seams.host !== undefined ? seams.host : hostname();
+  const claudeBinDir = seams.claudeBinDir !== undefined
+    ? seams.claudeBinDir
+    : resolveClaudeBinDir();
+
+  const out = {
+    id: distillationScheduleId(config.paName),
+    agent: config.paName,
+    name: `Librarian distillation sweep (every ${DEFAULT_CADENCE_HOURS}h)`,
+    schedule: `0 */${DEFAULT_CADENCE_HOURS} * * *`,
+    command: 'node node_modules/@stravica-ai/digital-operator-pa/bin/distill run',
+    workingDirectory: config.targetDir,
+    enabled: true,
+    backend,
+    host,
+    description: [
+      `Solo-instance librarian distillation sweep for ${config.paName}. Turns the`,
+      'staged observations under agents/<paName>/staging/ into promoted knowledge',
+      'docs under operator/knowledge/, then invalidates the retrieval graph so the',
+      'next `pa knowledge search` sees the new material. Installed by the /onboard',
+      'walkthrough (mandatory step) via `scheduler install --force-host`. Removing',
+      'this schedule silently kills the PA\'s self-learning loop; reinstate it by',
+      're-running /onboard.',
+    ].join(' '),
+    // DAVE_ROOT MUST be set explicitly — the scheduler's withLaunchdDefaults()
+    // falls back to `resolve(__dirname, '..','..','..')` which under a
+    // published tarball lands inside the versioned .pnpm store path and
+    // `validateLaunchdDaveRoot` refuses (exit 2) at install time. The
+    // solo colleague running `scheduler install` from their instance
+    // shell also does not typically have DAVE_ROOT set. Baking it into
+    // the schedule closes both cases (w-2026-07-15-003 + w-2026-07-16-006
+    // trap class). PATH is only added when `claude` lives outside the
+    // launchd default PATH set.
+    environment: { DAVE_ROOT: config.targetDir },
+  };
+
+  if (claudeBinDir && !LAUNCHD_DEFAULT_PATHS.includes(claudeBinDir)) {
+    out.environment.PATH = [claudeBinDir, ...LAUNCHD_DEFAULT_PATHS].join(pathDelimiter);
+  }
+
+  return out;
+}
+
 /**
  * Build the .claude/settings.json contents.
  *
- * Two things:
+ * Three things:
  *   1. `permissions.deny` for the built-in `deep-research` skill and
  *      workflow. The core operating model (Bucket 4) directs the PA to
  *      the `/research` verb, which persists a session and promotes
@@ -584,12 +767,16 @@ export function buildGitkeep() {
  *      scaffold ships the wiring inert. A per-repo overlay slot is
  *      scaffolded alongside as `.claude/coordinator-overlay.json`.
  *
- * SessionStart hooks (boot-context style injection) are deliberately
- * NOT scaffolded — the boot-context tool lives in the HQ estate, not
- * the published package. Scaffolding a hook that names a binary the
- * colleague does not have would fire on every session boot with a
- * non-blocking error. Documented in docs/onboarding-solo.md under
- * "what is not included in solo mode".
+ *   3. `hooks.SessionStart` wiring `distill health --hook-envelope` so
+ *      every session boots with a `distillationHealth (live)` block at
+ *      the top of the context. Reads the local distill ledger + the
+ *      scaffolded schedule file — never spawns claude, never triggers a
+ *      sweep, cheap to run. The block warns loudly when the schedule is
+ *      missing (fresh scaffold pre-/onboard), disabled, or the last run
+ *      is stale, so the whole self-learning loop cannot die silently
+ *      the way it did on the WSD-laptop cold install of 0.1.41. Invoked
+ *      through `pnpm exec` because Claude Code hook subprocesses do not
+ *      inherit the pnpm-augmented PATH the interactive session enjoys.
  */
 export function buildClaudeSettingsJson() {
   return {
@@ -608,6 +795,17 @@ export function buildClaudeSettingsJson() {
           ],
         },
       ],
+      SessionStart: [
+        {
+          matcher: '',
+          hooks: [
+            {
+              type: 'command',
+              command: 'pnpm exec distill health --hook-envelope',
+            },
+          ],
+        },
+      ],
     },
   };
 }
@@ -810,12 +1008,23 @@ export function buildPlanFromTemplates(config, templates) {
   plan.push({ kind: 'file', path: `agents/${paName}/autonomy-envelope.md`, contents: autonomyEnvelope });
   plan.push({ kind: 'json', path: `agents/${paName}/spawn-log.json`, contents: spawnLog });
 
-  // Empty-directory markers — git won't track empty dirs.
+  // Load-bearing: the scaffolded distillation-sweep schedule the
+  // /onboard walkthrough installs and fires as a mandatory step. See
+  // buildDistillationScheduleJson for the shape rationale.
+  const distillSched = buildDistillationScheduleJson(config);
+  plan.push({
+    kind: 'json',
+    path: `schedules/${distillationScheduleFilename(paName)}`,
+    contents: distillSched,
+  });
+
+  // Empty-directory markers — git won't track empty dirs. `schedules/`
+  // now ships with a real file (the distillation sweep) so it never
+  // needs a .gitkeep.
   for (const d of [
     `agents/${paName}/staging`,
     'work',
     'projects',
-    'schedules',
     '.vault',
     'operator/extensions/roles',
     'operator/extensions/tools',

package/docs/onboarding-solo.md

@@ -37,7 +37,7 @@ cd $HOME/<pa-name>-instance
 pnpm exec pa session
 ```
 
-Inside the session, type `/onboard`. The PA verifies the runtime, checks the installed version against npm, asks you a few profile questions, offers an optional shell alias, offers to start the local workspace, and offers to wire up Atlassian (Jira, Confluence) if you use it. Every step is idempotent; re-run `/onboard` anytime to redo a specific step.
+Inside the session, type `/onboard`. The PA verifies the runtime, checks the installed version against npm, asks you a few profile questions, offers an optional shell alias, offers to start the local workspace, installs and proves the librarian distillation sweep as a mandatory step, and offers to wire up Atlassian (Jira, Confluence) if you use it. Every step is idempotent; re-run `/onboard` anytime to redo a specific step. Onboarding does not complete until the librarian schedule is installed and proven. That is the one piece of scheduling every solo instance needs so staged observations get distilled into knowledge over time.
 
 ## 3. Alias (optional)
 
@@ -56,11 +56,11 @@ After that, typing `<pa-name>` from anywhere starts a session.
 - The read-only `desk` CLI: overview, today, projects, work.
 - A local workspace server on `http://localhost:4200` (start with `pnpm exec pa workspace start`).
 - A SIMPLE-mode local knowledge library: `pa knowledge search / related / domain / orphans / path / context`, seeded with the five base domains.
-- Self-learning loop primitives: `agents/<pa-name>/staging/`, `journal.md`, `next-session.md`, `spawn-log.json`, autonomy envelope, and the Librarian distillation sweep via `pnpm exec distill run`.
+- Self-learning loop primitives: `agents/<pa-name>/staging/`, `journal.md`, `next-session.md`, `spawn-log.json`, autonomy envelope, and the Librarian distillation sweep, scaffolded as `schedules/<pa-name>-distillation-sweep.json` (every 4 hours) and installed by `/onboard` on the OS-native backend (launchd on macOS, cron on Linux). One immediate run is fired at install time so the ledger at `.cache/distill/logs/runs.jsonl` proves the schedule wiring end to end before onboarding completes.
 - The `research` CLI with the light / normal / deep session store persisted under `.cache/research/`.
 - Scheduler (cron on Linux, launchd on macOS): `pnpm exec scheduler --help`.
 - Secrets vault (SOPS + age) if you opt in: `pnpm exec secrets --help`.
-- `.claude/settings.json` with the `pa-coordinator-hook` wired in as a `PreToolUse` hook (inert until you export `PA_COORDINATOR_MODE=1`) and `deep-research` denied at the permission layer.
+- `.claude/settings.json` with the `pa-coordinator-hook` wired in as a `PreToolUse` hook (inert until you export `PA_COORDINATOR_MODE=1`), a `SessionStart` hook that injects a live `distillationHealth` block at the top of every session (schedule state + last-run age + staging count), and `deep-research` denied at the permission layer.
 - Two slash commands out of the box: `/research` (persisted research sessions) and `/onboard` (this walkthrough).
 - Workspace-extension prompting: `operator/knowledge/platform-tooling/workspace-extensions.md` teaches your PA when to propose a workspace page and `pa-init workspace-extension <name>` scaffolds the HTML skeleton plus a `nav.json` entry. Add `--with-api` when the page needs a server route.
 
@@ -70,7 +70,7 @@ Your PA has the `rcf-lite-engineer` role baked in. It builds greenfield applicat
 
 ## What is not included in solo mode
 
-- **`SessionStart` boot-context hook.** In some estates a `SessionStart` hook injects a live workState block at the top of every session. That hook is not in this package. If you want it, write your own `SessionStart` hook in `.claude/settings.json`.
+- **A full workState boot-context hook.** In some estates a `SessionStart` hook injects the live in-flight work items, active projects, and on-you list at the top of every session. Solo mode ships the narrower distillation-health hook (schedule + last-run + staging count) rather than a full workState block. If you want the broader one, extend `.claude/settings.json` with your own `SessionStart` hook.
 - **Team modes.** `pa-init --mode=lead` and `--mode=member` exit with "not implemented". The SIMPLE-mode local library is single-operator by design.
 - **Remote knowledge library.** The `remote` library mode requires a service on a persistent host, an age keypair, and a tunnel. Solo mode stays SIMPLE and runs entirely on your one laptop.
 - **HQ-specialised roles.** The bundled role set is the core seven plus `product-engineer` and `rcf-lite-engineer` from the engineering types pack. Other tier-ladder roles and estate-specific extensions are not shipped.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/digital-operator-pa",
-  "version": "0.1.48",
+  "version": "0.1.49",
   "description": "Digital Operator PA — single-bundled public package surface (bins + library) for the platform.",
   "type": "module",
   "main": "./index.mjs",