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

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

@@ -11,7 +11,12 @@ 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';
+import { doOnboard } from './onboard.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -34,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):
@@ -88,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);
@@ -170,17 +178,47 @@ 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');
   // 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']);
@@ -196,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

@@ -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
@@ -93,28 +97,92 @@ 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.
 
-### 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:
@@ -131,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/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);