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

package/dist/engineering-pa-workspace/src/repo-root.mjs

@@ -55,14 +55,30 @@ export function walkUpForMarker(start) {
   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 = {}) {
@@ -71,5 +87,14 @@ export function findRepoRootSync(opts = {}) {
   const envRoot = env.DAVE_REPO_ROOT || env.PA_REPO_ROOT;
   if (envRoot) return resolve(envRoot);
   const found = walkUpForMarker(startDir);
-  return found || resolve(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-workspace/src/server.mjs

@@ -218,8 +218,9 @@ function resetIdle() {
 // palette block, which broke the theme toggle on the content-calendar
 // preview iframe (operator-reported, 2026-06-27). The fix matches what
 // viewer.html does: link the shared theme.css, defer-load theme.js, pre-paint
-// init reads localStorage 'dave.theme', body in humanist sans for prose, and
-// .md-body strong uses the new --emphasis token (matching .content strong).
+// init reads localStorage 'dop.theme' (with a one-time legacy 'dave.theme'
+// fallback), body in humanist sans for prose, and .md-body strong uses the
+// new --emphasis token (matching .content strong).
 // Exported so unit tests can assert on the output without spinning up the
 // HTTP server.
 export function markdownPage(rawContent, filePath) {
@@ -234,7 +235,7 @@ export function markdownPage(rawContent, filePath) {
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>${title}</title>
-<script>(function(){try{var t=localStorage.getItem('dave.theme');document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
+<script>(function(){try{var t=localStorage.getItem('dop.theme');if(!t){var legacy=localStorage.getItem('dave.theme');if(legacy==='light'||legacy==='dark'){t=legacy;try{localStorage.setItem('dop.theme',legacy);}catch(_){}}}document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
 <link rel="stylesheet" href="/core/tools/workspace/app/assets/theme.css">
 <script src="/core/tools/workspace/app/assets/theme.js" defer></script>
 <style>

package/dist/engineering-pa-workspace/src/workspace-page-contract.mjs

@@ -0,0 +1,98 @@
+// workspace-page-contract.mjs — the single source of truth for the head
+// and top-of-body markup every workspace HTML page must ship.
+//
+// Every page served by the workspace (core pages under `packages/workspace/app/`
+// and extension pages scaffolded by `pa-init workspace-extension`) has to
+// carry the same four head tags in the same order:
+//
+//   1. Inline pre-paint script that reads the theme from localStorage and
+//      sets `documentElement.dataset.theme` BEFORE first paint. Without
+//      this, dark-preference users see a light-flash (FOUC).
+//   2. Link to `/core/tools/workspace/app/assets/theme.css` (the shared
+//      palette + `[data-theme=...]` token blocks).
+//   3. Deferred `/core/tools/workspace/app/assets/theme.js` (toggle button,
+//      cross-frame coordination, storage sync).
+//   4. Deferred `/banner.js` (the global status banner poller).
+//
+// And the body's first child must be `<div id="global-banner"></div>` so
+// `banner.js` has a mount point.
+//
+// This module owns the string forms of all four so a scaffold-generated
+// extension page and a hand-authored core page can never drift. Core pages
+// still hand-copy the block for now (their inline `<style>` sits after
+// theme.js in the head, so a full migration is more than a mechanical
+// substitution and is left as a follow-up); the scaffold and the theme
+// parity test import from here.
+//
+// Storage-key policy: the theme key is `'dop.theme'` (product-generic —
+// `dop` = Digital Operator PA). Legacy stores under `'dave.theme'` are
+// migrated on first read (see `theme.js`) so nobody re-picks their theme
+// after the rename.
+
+/**
+ * localStorage key the theme selection persists under. Product-generic;
+ * shared by the pre-paint bootstrap, theme.js, and every consuming page.
+ */
+export const THEME_STORAGE_KEY = 'dop.theme';
+
+/**
+ * Legacy localStorage key. Read once on first boot when the new key is
+ * absent and copied forward. Never written. Kept exported so tests can
+ * pin the migration path without hardcoding the literal.
+ */
+export const THEME_LEGACY_STORAGE_KEY = 'dave.theme';
+
+/**
+ * postMessage type the shell uses to broadcast a theme change into
+ * same-origin iframed pages. Product-generic; renamed alongside the
+ * storage key.
+ */
+export const THEME_MESSAGE_TYPE = 'dop.theme.set';
+
+/**
+ * The inline pre-paint bootstrap. Reads the new key, falls back to the
+ * legacy key when the new one is unset, applies to
+ * `documentElement.dataset.theme` before first paint. Same shape the
+ * markdownPage renderer emits so a fresh direct-load never flashes.
+ *
+ * Returned as a self-contained `<script>...</script>` tag; embed it in
+ * `<head>` BEFORE the theme.css link and before any body content.
+ */
+export function prepaintScriptTag() {
+  return `<script>(function(){try{var t=localStorage.getItem('${THEME_STORAGE_KEY}');if(!t){var legacy=localStorage.getItem('${THEME_LEGACY_STORAGE_KEY}');if(legacy==='light'||legacy==='dark'){t=legacy;try{localStorage.setItem('${THEME_STORAGE_KEY}',legacy);}catch(_){}}}document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>`;
+}
+
+/** Link tag for the shared theme stylesheet. */
+export const THEME_CSS_LINK = '<link rel="stylesheet" href="/core/tools/workspace/app/assets/theme.css">';
+
+/** Deferred script tag for the shared theme.js toggle + storage coordinator. */
+export const THEME_JS_TAG = '<script src="/core/tools/workspace/app/assets/theme.js" defer></script>';
+
+/** Deferred script tag for the global status banner. */
+export const BANNER_JS_TAG = '<script src="/banner.js" defer></script>';
+
+/**
+ * The mount point banner.js expects. Insert as the first child of `<body>`.
+ */
+export const GLOBAL_BANNER_HTML = '<div id="global-banner"></div>';
+
+/**
+ * Build the standard `<head>` inner markup a workspace page must ship.
+ * Charset, viewport, `<title>`, then the four theme + banner tags in the
+ * documented order. Callers append their own `<style>` block (if any) AFTER
+ * the returned string and BEFORE closing `</head>`.
+ *
+ * @param {object} opts
+ * @param {string} opts.title  page title (already HTML-escaped by caller)
+ */
+export function standardHeadInner({ title }) {
+  return [
+    '<meta charset="utf-8" />',
+    '<meta name="viewport" content="width=device-width, initial-scale=1" />',
+    `<title>${title}</title>`,
+    prepaintScriptTag(),
+    THEME_CSS_LINK,
+    THEME_JS_TAG,
+    BANNER_JS_TAG,
+  ].join('\n');
+}

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

@@ -336,6 +336,7 @@ async function cmdStart() {
       const who = holder ? ` (held by PID ${holder.pid}${holder.command ? ` — ${holder.command}` : ''})` : '';
       console.error(`Error: Stale PID file references dead PID ${existing.pid}, but port ${existing.port} is in use${who}.`);
       console.error('Refusing to kill an unrelated process. Remove the PID file manually or use a different port.');
+      console.error('Hint: run `pa workspace start --port <N>` with a free port, or set `workspacePort` in operator/config/preferences.json.');
       process.exit(1);
     }
     removePid();
@@ -344,6 +345,7 @@ async function cmdStart() {
   // Check if port is already in use by something else
   if (await checkPort(port)) {
     console.error(`Error: Port ${port} is already in use by another process.`);
+    console.error('Hint: run `pa workspace start --port <N>` with a free port, or set `workspacePort` in operator/config/preferences.json.');
     process.exit(1);
   }
 

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.47",
+  "version": "0.1.49",
   "description": "Digital Operator PA — single-bundled public package surface (bins + library) for the platform.",
   "type": "module",
   "main": "./index.mjs",
@@ -40,6 +40,7 @@
   ],
   "license": "MIT",
   "homepage": "https://stravica.ai",
+  "bugs": "https://stravica.ai",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"