@stravica-ai/digital-operator-pa 0.1.16 → 0.1.18

package/dist/engineering-pa-cli/docs/gsc.md

@@ -37,10 +37,20 @@ Two npm packages (declared in `@stravica-ai/digital-operator-pa`):
 
 5. **Store the SA key in the SOPS vault**:
    ```bash
+   # Legacy single-file vault:
    pnpm exec secrets set GSC_SERVICE_ACCOUNT_KEY -
+   # Scoped-vault estate (workspace or canonical layout):
+   pnpm exec secrets set --scope <scope> GSC_SERVICE_ACCOUNT_KEY -
    # paste the entire JSON contents, then Ctrl-D
    ```
 
+   On scoped-vault hosts, `pa gsc` reads the key from whichever pot
+   `secrets get` would use — i.e. it honours (in order) `SECRETS_DEFAULT_SCOPE`,
+   the `defaultScope` in `~/.config/stravica-pa/defaults.json`, or the
+   calling PA's `identity.json` — before falling back to the legacy
+   single-file vault. Store the key in the pot the host is already
+   configured to read; no `pa gsc`-specific configuration is needed.
+
 6. **Store Cloudflare credentials** (also one-time). Two key shapes are
    supported; pick whichever fits your setup:
 
@@ -70,6 +80,10 @@ Two npm packages (declared in `@stravica-ai/digital-operator-pa`):
    no `--account` flag is passed and the `CLOUDFLARE_PAGES_*` unsuffixed
    pair is absent. Don't rely on it — set the `CLOUDFLARE_PAGES_*` keys.
 
+   Same scoped-vault note as the SA key: on scoped hosts these live in
+   whichever pot `secrets get` reads (see step 5); use `secrets set --scope
+   <scope> ...` to store them there.
+
 ## Per-domain setup (each time you onboard a new property)
 
 7. **Grant the service-account access to the GSC property.** Until the

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

@@ -29,6 +29,7 @@ import { hostname as osHostname } from 'node:os';
 import { dirname, join } from 'node:path';
 
 import { loadBundledManifestSync } from '../../../engineering-pa-core/src/agent-baseline/manifest.mjs';
+import { readPreferencesSync } from '../../../engineering-pa-core/src/preferences.mjs';
 
 import { auditManifest } from './audit.mjs';
 import { getRepoRoot } from '../pa/repo-root.mjs';
@@ -201,12 +202,9 @@ function isStale(cache, stalenessMinutes) {
 
 function readStalenessMinutes(repoRoot) {
   try {
-    const prefsPath = join(repoRoot, 'operator', 'config', 'preferences.json');
-    if (existsSync(prefsPath)) {
-      const prefs = JSON.parse(readFileSync(prefsPath, 'utf8'));
-      const value = prefs?.agentAudit?.cacheStalenessMinutes;
-      if (typeof value === 'number' && value > 0) return value;
-    }
+    const prefs = readPreferencesSync(repoRoot);
+    const value = prefs?.agentAudit?.cacheStalenessMinutes;
+    if (typeof value === 'number' && value > 0) return value;
   } catch {
     // fall through
   }
@@ -215,11 +213,8 @@ function readStalenessMinutes(repoRoot) {
 
 function readPaName(repoRoot) {
   try {
-    const prefsPath = join(repoRoot, 'operator', 'config', 'preferences.json');
-    if (existsSync(prefsPath)) {
-      const prefs = JSON.parse(readFileSync(prefsPath, 'utf8'));
-      if (typeof prefs.paName === 'string' && prefs.paName.length > 0) return prefs.paName;
-    }
+    const prefs = readPreferencesSync(repoRoot);
+    if (prefs && typeof prefs.paName === 'string' && prefs.paName.length > 0) return prefs.paName;
   } catch {
     // fall through
   }

package/dist/engineering-pa-cli/src/coordinator-hook/self.mjs

@@ -11,15 +11,15 @@
 //
 // Returns a string paName, or null when unresolved.
 
-import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { readPreferences } from '../../../engineering-pa-core/src/preferences.mjs';
 
 export async function resolveSelfAgent(repoRoot, env = process.env) {
   if (env.PA_SELF_AGENT) return env.PA_SELF_AGENT;
   if (!repoRoot) return null;
   try {
-    const raw = await readFile(join(repoRoot, 'operator', 'config', 'preferences.json'), 'utf8');
-    const config = JSON.parse(raw);
+    // Overlay-aware: preferences.local.json shallow-merges OVER the shared
+    // preferences.json so a device-local paName wins for the coordinator hook.
+    const config = await readPreferences(repoRoot);
     if (config && typeof config.paName === 'string' && config.paName.trim()) {
       return config.paName.trim();
     }

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

@@ -22,6 +22,7 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { getRepoRoot } from '../pa/repo-root.mjs';
+import { readPreferencesSync } from '../../../engineering-pa-core/src/preferences.mjs';
 import {
   probePlatform,
   probeRuntimes,
@@ -252,12 +253,9 @@ function isStale(cache, stalenessMinutes) {
 
 function readStalenessMinutes(repoRoot) {
   try {
-    const prefsPath = join(repoRoot, 'operator', 'config', 'preferences.json');
-    if (existsSync(prefsPath)) {
-      const prefs = JSON.parse(readFileSync(prefsPath, 'utf8'));
-      const value = prefs?.environment?.cacheStalenessMinutes;
-      if (typeof value === 'number' && value > 0) return value;
-    }
+    const prefs = readPreferencesSync(repoRoot);
+    const value = prefs?.environment?.cacheStalenessMinutes;
+    if (typeof value === 'number' && value > 0) return value;
   } catch {
     // fall through
   }

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

@@ -10,6 +10,7 @@ import { arch, platform, release, homedir } from 'node:os';
 import { basename, join, resolve, dirname } from 'node:path';
 import { resolve4 } from 'node:dns/promises';
 import { fileURLToPath } from 'node:url';
+import { readPreferencesSync } from '../../../engineering-pa-core/src/preferences.mjs';
 
 const execFileP = promisify(execFile);
 
@@ -234,11 +235,8 @@ export async function probeWorkspace(repoRoot) {
 
 function readWorkspacePort(repoRoot) {
   try {
-    const prefsPath = join(repoRoot, 'operator', 'config', 'preferences.json');
-    if (existsSync(prefsPath)) {
-      const prefs = JSON.parse(readFileSync(prefsPath, 'utf8'));
-      if (typeof prefs.workspacePort === 'number') return prefs.workspacePort;
-    }
+    const prefs = readPreferencesSync(repoRoot);
+    if (prefs && typeof prefs.workspacePort === 'number') return prefs.workspacePort;
   } catch {
     // fall through
   }

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

@@ -8,7 +8,7 @@
 // override and never touch the network. The SA-key read also accepts an
 // override so tests can pass in a synthetic key without going through SOPS.
 
-import { defaultPaths, checkVault, secretsFileExists, sopsDecrypt, VaultError } from '../secrets/vault.mjs';
+import { resolveCommandPaths, checkVault, secretsFileExists, sopsDecrypt, VaultError } from '../secrets/vault.mjs';
 
 // Read-only scope: searchanalytics.query + sites.list + sitemaps.list.
 // Read-write scope: sites.add, sitemaps.submit, site verification.
@@ -25,9 +25,26 @@ const DEFAULT_VAULT_KEY = 'GSC_SERVICE_ACCOUNT_KEY';
 /**
  * Load the service-account JSON object from the SOPS vault.
  *
+ * Vault path resolution goes through `resolveCommandPaths` — the same
+ * resolver `secrets get`/`set` use — so this honours all the same layouts
+ * without duplicating logic: an explicit `overrides.paths` (from a
+ * pre-resolved `--scope`/`--file`) is a pass-through; otherwise the
+ * default-scope resolver runs (SECRETS_DEFAULT_SCOPE env, defaultScope in
+ * ~/.config/stravica-pa/defaults.json, or the calling PA's identity.json)
+ * and points at a scoped `.vault/scopes/<scope>.enc.json`; if nothing is
+ * configured anywhere it falls back to the legacy single-file vault.
+ *
+ * A stderr `note: writing to '<scope>' pot ...` line is printed by the
+ * resolver on the default-scope path — same behaviour as `secrets get`,
+ * kept intentionally consistent so operators see the same routing signal
+ * from every consumer of the vault.
+ *
  * @param {object} overrides
- * @param {object} [overrides.paths]      Vault paths (from defaultPaths()).
+ * @param {object} [overrides.paths]      Vault paths already resolved (e.g. from --scope upstream).
  * @param {string} [overrides.vaultKey]   Vault key name (default GSC_SERVICE_ACCOUNT_KEY).
+ * @param {string} [overrides.cwd]        Test seam — cwd used for workspace resolution.
+ * @param {object} [overrides.env]        Test seam — env used for scope-default resolution.
+ * @param {string} [overrides.home]       Test seam — home used for keyfile + defaults.json lookup.
  * @param {string} [overrides.serviceAccountKey]
  *        Raw SA JSON string. If provided, skips vault entirely (testing).
  * @returns {Promise<object>} Parsed service-account JSON.
@@ -39,34 +56,39 @@ export async function loadServiceAccountKey(overrides = {}) {
       : overrides.serviceAccountKey;
   }
 
-  const paths = overrides.paths || defaultPaths();
+  const paths = resolveCommandPaths(overrides);
   const vaultKey = overrides.vaultKey || DEFAULT_VAULT_KEY;
 
   const state = checkVault(paths);
   if (!state.ok) {
+    // Print then throw — main() suppresses messages for errors that carry
+    // an exitCode (the throw-site is expected to have reported), so
+    // omitting the console.error would exit silently through the pa gsc
+    // binary.
+    console.error(state.message);
     throw new VaultError(state.message, state.exitCode ?? 1);
   }
   if (!secretsFileExists(paths)) {
-    throw new VaultError(
-      `No secrets file at ${paths.secretsFile}. Run 'secrets init' first.`,
-      1,
-    );
+    const message = `No secrets file at ${paths.secretsFile}.` + (paths.scoped
+      ? ` Store the service-account JSON with:\n  secrets set --scope ${paths.scope} ${vaultKey} -\n(then paste the JSON, then Ctrl-D)`
+      : " Run 'secrets init' first.");
+    console.error(message);
+    throw new VaultError(message, 1);
   }
   const data = await sopsDecrypt(paths, paths.secretsFile);
   if (!(vaultKey in data)) {
-    throw new VaultError(
-      `Vault key "${vaultKey}" not found. Store the service-account JSON with:\n  secrets set ${vaultKey} -\n(then paste the JSON, then Ctrl-D)`,
-      1,
-    );
+    const scopeHint = paths.scoped ? ` --scope ${paths.scope}` : '';
+    const message = `Vault key "${vaultKey}" not found in ${paths.secretsFile}. Store the service-account JSON with:\n  secrets set${scopeHint} ${vaultKey} -\n(then paste the JSON, then Ctrl-D)`;
+    console.error(message);
+    throw new VaultError(message, 1);
   }
   const raw = data[vaultKey];
   try {
     return typeof raw === 'string' ? JSON.parse(raw) : raw;
   } catch (e) {
-    throw new VaultError(
-      `Vault key "${vaultKey}" is not valid JSON: ${e.message}`,
-      2,
-    );
+    const message = `Vault key "${vaultKey}" is not valid JSON: ${e.message}`;
+    console.error(message);
+    throw new VaultError(message, 2);
   }
 }
 

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

@@ -24,7 +24,7 @@
 //
 // `fetchImpl` and `now` are injectable for tests.
 
-import { defaultPaths, checkVault, secretsFileExists, sopsDecrypt, VaultError } from '../secrets/vault.mjs';
+import { resolveCommandPaths, checkVault, secretsFileExists, sopsDecrypt, VaultError } from '../secrets/vault.mjs';
 
 const CF_API = 'https://api.cloudflare.com/client/v4';
 
@@ -122,14 +122,23 @@ export async function loadCloudflareCreds(overrides = {}) {
   if (overrides.vaultData) {
     data = overrides.vaultData;
   } else {
-    const paths = overrides.paths || defaultPaths();
+    // resolveCommandPaths honours --scope/--file (via a pre-resolved
+    // overrides.paths), the SECRETS_DEFAULT_SCOPE env, defaults.json's
+    // defaultScope, and the calling PA's identity.json, before falling
+    // back to the legacy single-file vault. Same routing as `secrets get`
+    // and `pa gsc`'s SA-key loader — one resolver, one routing signal.
+    const paths = resolveCommandPaths(overrides);
     const state = checkVault(paths);
-    if (!state.ok) throw new VaultError(state.message, state.exitCode ?? 1);
+    if (!state.ok) {
+      console.error(state.message);
+      throw new VaultError(state.message, state.exitCode ?? 1);
+    }
     if (!secretsFileExists(paths)) {
-      throw new VaultError(
-        `No secrets file at ${paths.secretsFile}. Run 'secrets init' first.`,
-        1,
-      );
+      const message = `No secrets file at ${paths.secretsFile}.` + (paths.scoped
+        ? ` Store Cloudflare credentials with 'secrets set --scope ${paths.scope} <KEY> <value>'.`
+        : " Run 'secrets init' first.");
+      console.error(message);
+      throw new VaultError(message, 1);
     }
     data = await sopsDecrypt(paths, paths.secretsFile);
   }

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

@@ -10,6 +10,7 @@ import { dirname, join, resolve } from 'node:path';
 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 { main as runMigrateInspect } from '../../../engineering-pa-migrate-inspect/src/cli.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -198,11 +199,8 @@ async function doStatus(opts = {}) {
 function resolveWorkspacePort(repoRoot, opts = {}) {
   if (opts.workspacePort) return opts.workspacePort;
   try {
-    const prefsPath = join(repoRoot, 'operator', 'config', 'preferences.json');
-    if (existsSync(prefsPath)) {
-      const prefs = JSON.parse(readFileSync(prefsPath, 'utf8'));
-      if (typeof prefs.workspacePort === 'number') return prefs.workspacePort;
-    }
+    const prefs = readPreferencesSync(repoRoot);
+    if (prefs && typeof prefs.workspacePort === 'number') return prefs.workspacePort;
   } catch { /* fall through to default */ }
   return 4200;
 }

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

@@ -21,6 +21,8 @@ import { readFile, stat } from 'node:fs/promises';
 import { spawn } from 'node:child_process';
 import { dirname, join, resolve } from 'node:path';
 
+import { mergePreferences } from '../../../engineering-pa-core/src/preferences.mjs';
+
 /**
  * Resolve the operator repo root with the priority documented in the brief:
  *   1. process.env.DAVE_REPO_ROOT (if set and the directory exists)
@@ -93,12 +95,22 @@ export class SessionError extends Error {
  * and confirm `agents/<paName>/` exists. Returns a plan object describing
  * what the verb is about to do — `runSession` then either execs `claude`
  * or hands the plan to a test seam.
+ *
+ * The optional device-local overlay `operator/config/preferences.local.json`
+ * shallow-merges OVER the base so a device-scoped paName can win on this
+ * host without editing the shared file (part of w-2026-08-07-002's overlay
+ * sweep). An absent/malformed overlay is silently ignored so behaviour
+ * without an overlay is byte-identical to the pre-overlay implementation;
+ * every error path (missing/malformed/non-object/missing-paName) still
+ * points the operator at the SHARED base file, which is the one they need
+ * to fix to make this device bootable at all.
  */
 export async function buildSessionPlan(repoRoot, seam = {}) {
   const readFileImpl = seam.readFile ?? readFile;
   const pathExists = seam.pathExists ?? defaultPathExists;
 
   const preferencesPath = join(repoRoot, 'operator', 'config', 'preferences.json');
+  const overlayPath = join(repoRoot, 'operator', 'config', 'preferences.local.json');
 
   let raw;
   try {
@@ -133,7 +145,18 @@ export async function buildSessionPlan(repoRoot, seam = {}) {
     );
   }
 
-  const paName = prefs.paName;
+  // Device-local overlay: fail-open. Missing file (ENOENT) OR malformed JSON
+  // OR non-object shape leaves the merged view equal to the base.
+  let overlay = null;
+  try {
+    const overlayRaw = await readFileImpl(overlayPath, 'utf8');
+    try {
+      overlay = JSON.parse(overlayRaw);
+    } catch { overlay = null; }
+  } catch { overlay = null; }
+  const merged = mergePreferences(prefs, overlay) || prefs;
+
+  const paName = merged.paName;
   if (typeof paName !== 'string' || paName.trim().length === 0) {
     throw new SessionError(
       `preferences.json at ${preferencesPath} is missing required field \`paName\`.`,

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

@@ -8,8 +8,7 @@
 // PA name (for --mine resolution) is read from
 // operator/config/preferences.json. Falls back to 'pa' if missing.
 
-import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { readPreferences } from '../../../engineering-pa-core/src/preferences.mjs';
 
 import { createWork, setWorkStatus, listWork } from './work.mjs';
 import { getRepoRoot } from './repo-root.mjs';
@@ -80,11 +79,10 @@ function parseFlags(args) {
 async function getPaName() {
   try {
     const repoRoot = await getRepoRoot();
-    const raw = await readFile(
-      join(repoRoot, 'operator', 'config', 'preferences.json'),
-      'utf8',
-    );
-    const config = JSON.parse(raw);
+    // Overlay-aware: preferences.local.json shallow-merges OVER the shared
+    // preferences.json so any device-local paName wins on this device.
+    const config = await readPreferences(repoRoot);
+    if (!config) return 'pa';
     return config.paName || config.agentName || 'pa';
   } catch {
     return 'pa';

package/dist/engineering-pa-core/src/desk/team-scope.mjs

@@ -32,9 +32,11 @@
 // desk/pa (show everything). This is load-bearing — existing installs must
 // not silently start hiding projects on a package bump.
 
-import { readFile } from 'node:fs/promises';
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { readPreferences, readPreferencesSync, mergePreferences } from '../preferences.mjs';
+
+// Re-export the merge helper so callers that still reach for it through
+// team-scope keep working. Preferences.mjs is the single source of truth.
+export { mergePreferences };
 
 /**
  * Resolve the agent identity a project is scoped to, or null if the
@@ -106,59 +108,6 @@ export function filterProjectsByTeam(projects, opts = {}) {
  * Absent/blank -> null, which means "do not team-scope nav" (fail open,
  * backwards compatible: pre-team devices show every nav fragment).
  */
-/**
- * Read + JSON-parse a file, returning the parsed value or null on any error
- * (missing file, unreadable, malformed JSON). Shared by the base + overlay
- * reads so both fail-open identically.
- */
-function readJsonSync(path) {
-  try {
-    return JSON.parse(readFileSync(path, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-async function readJsonAsync(path) {
-  try {
-    return JSON.parse(await readFile(path, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Shallow-merge the optional device-local overlay
- * (operator/config/preferences.local.json) OVER the parsed base
- * preferences.json.
- *
- * The overlay is device-local state that must NOT round-trip through
- * library-sync. preferences.json is down-path-materialised from a shared
- * canonical source (see the estate's .library-sync manifest — the barry
- * `config/` mount), so a device-scoped field (e.g. `team`) written into the
- * synced file would be clobbered on the next cycle, and a canonical edit
- * would stamp one device's identity onto every device. The overlay lives
- * outside every mount source, so down-path reconciliation never tracks or
- * deletes it (computeDeletions is manifest-driven — it only removes
- * previously-materialised files), and it is gitignored so estate git-sync
- * never carries it between hosts (see scaffold buildGitignore).
- *
- * Precedence: overlay keys win; keys the overlay omits fall through to the
- * base. An absent/malformed overlay leaves the base exactly as-is, so a
- * device with no overlay behaves identically to pre-overlay releases.
- *
- * `base`/`overlay` are already-parsed values (a plain object, or null when
- * the file was missing/malformed). Returns null only when BOTH are absent,
- * preserving the "no config at all -> fail-open defaults" path through
- * normaliseTeamScopeConfig.
- */
-function mergePreferences(base, overlay) {
-  const b = base && typeof base === 'object' && !Array.isArray(base) ? base : null;
-  const o = overlay && typeof overlay === 'object' && !Array.isArray(overlay) ? overlay : null;
-  if (!b && !o) return null;
-  return { ...(b || {}), ...(o || {}) };
-}
-
 function normaliseTeamScopeConfig(config) {
   const c = config && typeof config === 'object' ? config : {};
   const paName = c.paName || c.agentName || 'pa';
@@ -189,11 +138,9 @@ function normaliseTeamScopeConfig(config) {
  * @returns {Promise<{ paName: string, teamIdentities: string[], scopeEnabled: boolean, team: string|null }>}
  */
 export async function readTeamScopeConfig(repoRoot) {
-  // Base (synced) preferences, then the device-local overlay merged OVER it.
+  // Base + device-local overlay via the shared overlay-aware reader.
   // Missing/malformed either file -> null for that layer -> defaults.
-  const base = await readJsonAsync(join(repoRoot, 'operator', 'config', 'preferences.json'));
-  const overlay = await readJsonAsync(join(repoRoot, 'operator', 'config', 'preferences.local.json'));
-  return normaliseTeamScopeConfig(mergePreferences(base, overlay));
+  return normaliseTeamScopeConfig(await readPreferences(repoRoot));
 }
 
 /**
@@ -207,11 +154,9 @@ export async function readTeamScopeConfig(repoRoot) {
  * @returns {{ paName: string, teamIdentities: string[], scopeEnabled: boolean, team: string|null }}
  */
 export function readTeamScopeConfigSync(repoRoot) {
-  // Base (synced) preferences, then the device-local overlay merged OVER it.
+  // Base + device-local overlay via the shared overlay-aware reader.
   // Missing/malformed either file -> null for that layer -> defaults.
-  const base = readJsonSync(join(repoRoot, 'operator', 'config', 'preferences.json'));
-  const overlay = readJsonSync(join(repoRoot, 'operator', 'config', 'preferences.local.json'));
-  return normaliseTeamScopeConfig(mergePreferences(base, overlay));
+  return normaliseTeamScopeConfig(readPreferencesSync(repoRoot));
 }
 
 /**

package/dist/engineering-pa-core/src/preferences.mjs

@@ -0,0 +1,133 @@
+// preferences.mjs — overlay-aware reader for the operator preferences file.
+//
+// The estate ships a shared `operator/config/preferences.json` (down-path-
+// materialised from a canonical source via library-sync) plus an optional
+// device-local overlay at `operator/config/preferences.local.json` that
+// shallow-merges OVER the base. The overlay lives outside every mount source
+// so down-path reconciliation never tracks it, and it is gitignored so
+// estate git-sync never carries it between hosts.
+//
+// This module is the ONE place every consumer reaches for merged
+// preferences. Before this module existed, ~15 consumer sites (workspace
+// API surfaces, workspace server bind, CLI verbs, environment probes,
+// coordinator-hook) each read `preferences.json` directly with
+// `readFileSync`/`readFile`, which ignored the overlay and made every
+// device-local identity field (paName, pa.*, workspacePort) invisible on
+// every surface except the two `desk/team-scope` readers that had the
+// overlay baked in. See w-2026-08-07-002 and d-2026-08-07-005 for the
+// decision to sweep every reader onto a single overlay-aware helper.
+//
+// Merge semantics: SHALLOW. Overlay keys win at the top level; keys the
+// overlay omits fall through to the base. Deep-merge was considered and
+// rejected at ratification — the existing team-scope reader is shallow,
+// every existing overlay caller already assumes shallow, and deep-merge
+// changes the behaviour of nested-object fields (e.g. `pa: { name, role,
+// roleTitle }`) in ways that would silently reshape callers if we upgraded
+// under them. If a caller needs deep-merge for one field it can compose
+// itself; the shared helper stays predictable.
+//
+// Fail-open posture: an absent or malformed EITHER file yields null for
+// that layer, exactly as before. A device with no overlay reads
+// byte-identically to pre-overlay releases; a device with a malformed
+// overlay falls back to base-only rather than erroring; a device with
+// neither file yields null (the "no config at all" signal every caller
+// already handles).
+
+import { readFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Path to the shared preferences file for a given repo root.
+ * Exported so callers that still need the raw path (e.g. `pa session`'s
+ * error messages) can compute it without duplicating the join.
+ *
+ * @param {string} repoRoot
+ * @returns {string}
+ */
+export function preferencesPath(repoRoot) {
+  return join(repoRoot, 'operator', 'config', 'preferences.json');
+}
+
+/**
+ * Path to the device-local overlay file for a given repo root.
+ * @param {string} repoRoot
+ * @returns {string}
+ */
+export function preferencesOverlayPath(repoRoot) {
+  return join(repoRoot, 'operator', 'config', 'preferences.local.json');
+}
+
+/**
+ * Shallow-merge the optional device-local overlay OVER the parsed base
+ * preferences. Both inputs are already-parsed values (a plain object, or
+ * null when the file was missing/malformed). Non-object / array inputs are
+ * treated as null (fail-open). Returns null only when BOTH are absent,
+ * preserving the "no config at all" signal every caller already handles.
+ *
+ * @param {object|null} base
+ * @param {object|null} overlay
+ * @returns {object|null}
+ */
+export function mergePreferences(base, overlay) {
+  const b = base && typeof base === 'object' && !Array.isArray(base) ? base : null;
+  const o = overlay && typeof overlay === 'object' && !Array.isArray(overlay) ? overlay : null;
+  if (!b && !o) return null;
+  return { ...(b || {}), ...(o || {}) };
+}
+
+/**
+ * Read + JSON-parse a file, returning the parsed value or null on any error
+ * (missing file, unreadable, malformed JSON). Shared by the base + overlay
+ * reads so both fail-open identically.
+ */
+function readJsonSync(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+async function readJsonAsync(path) {
+  try {
+    return JSON.parse(await readFile(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read the merged preferences for a repo root: the shared base file
+ * (`operator/config/preferences.json`) with the device-local overlay
+ * (`operator/config/preferences.local.json`) shallow-merged OVER it.
+ *
+ * Returns the merged plain object, or null when NEITHER file is
+ * present/parseable. A malformed either file is treated as absent for
+ * that layer (fail-open). This is deliberately a plain reader — callers
+ * that need typed shapes (e.g. `desk/team-scope` normalising for scoping)
+ * layer their own extraction on top.
+ *
+ * @param {string} repoRoot
+ * @returns {Promise<object|null>}
+ */
+export async function readPreferences(repoRoot) {
+  const base = await readJsonAsync(preferencesPath(repoRoot));
+  const overlay = await readJsonAsync(preferencesOverlayPath(repoRoot));
+  return mergePreferences(base, overlay);
+}
+
+/**
+ * Synchronous mirror of {@link readPreferences}. Used by hot boot paths
+ * (workspace server bind, workspace API handlers, environment probes)
+ * where the async surface would force a whole call chain to become async
+ * for no functional gain.
+ *
+ * @param {string} repoRoot
+ * @returns {object|null}
+ */
+export function readPreferencesSync(repoRoot) {
+  const base = readJsonSync(preferencesPath(repoRoot));
+  const overlay = readJsonSync(preferencesOverlayPath(repoRoot));
+  return mergePreferences(base, overlay);
+}

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

@@ -9,6 +9,7 @@ import { hostname } from 'node:os';
 import { getSecretsStatus, setSecret, MISSING_TARGET_ERROR } from './secrets-api.mjs';
 import { detect as schedulerDetect, list as schedulerList } from '../../engineering-pa-core/src/scheduler/index.mjs';
 import { filterProjectsByTeam, readTeamScopeConfig } from '../../engineering-pa-core/src/desk/team-scope.mjs';
+import { readPreferencesSync } from '../../engineering-pa-core/src/preferences.mjs';
 
 /**
  * handleApi -- route handler for all API endpoints.
@@ -63,11 +64,10 @@ export function handleApi(req, res, url, repoRoot, deps = {}) {
   // GET /__api/config
   if (method === 'GET' && pathname === '/__api/config') {
     try {
-      const prefsFile = join(repoRoot, 'operator', 'config', 'preferences.json');
       let operator = { name: 'Operator', role: 'Operator' };
       let pa = { name: 'PA', role: 'PA' };
-      if (existsSync(prefsFile)) {
-        const prefs = JSON.parse(readFileSync(prefsFile, 'utf-8'));
+      const prefs = readPreferencesSync(repoRoot);
+      if (prefs) {
         if (prefs.operator && prefs.operator.name) operator = prefs.operator;
         if (prefs.pa && prefs.pa.name) pa = prefs.pa;
       }
@@ -855,9 +855,8 @@ function buildOverview(projects, work, repoRoot) {
   let paName = null;
   let paRoleTitle = null;
   try {
-    const prefsFile = join(repoRoot, 'operator', 'config', 'preferences.json');
-    if (existsSync(prefsFile)) {
-      const prefs = JSON.parse(readFileSync(prefsFile, 'utf-8'));
+    const prefs = readPreferencesSync(repoRoot);
+    if (prefs) {
       paName = prefs.paName || null;
       if (prefs.pa && typeof prefs.pa.roleTitle === 'string' && prefs.pa.roleTitle.length) {
         paRoleTitle = prefs.pa.roleTitle;
@@ -970,12 +969,9 @@ async function buildGitOverview(repoRoot) {
   // just come back empty and the page renders the user's own repos only.
   let orgs = [];
   try {
-    const prefsFile = join(repoRoot, 'operator', 'config', 'preferences.json');
-    if (existsSync(prefsFile)) {
-      const prefs = JSON.parse(readFileSync(prefsFile, 'utf-8'));
-      if (Array.isArray(prefs.gitOrgs)) {
-        orgs = prefs.gitOrgs.filter(function(o) { return typeof o === 'string' && o.length > 0; });
-      }
+    const prefs = readPreferencesSync(repoRoot);
+    if (prefs && Array.isArray(prefs.gitOrgs)) {
+      orgs = prefs.gitOrgs.filter(function(o) { return typeof o === 'string' && o.length > 0; });
     }
   } catch { /* non-fatal */ }
 
@@ -1975,12 +1971,9 @@ export function buildNextSession(repoRoot) {
   //   3. 'dave' (canonical default for legacy deployments)
   let paName = null;
   try {
-    const prefsFile = join(repoRoot, 'operator', 'config', 'preferences.json');
-    if (existsSync(prefsFile)) {
-      const prefs = JSON.parse(readFileSync(prefsFile, 'utf-8'));
-      if (prefs && typeof prefs.paName === 'string' && prefs.paName.length) {
-        paName = prefs.paName;
-      }
+    const prefs = readPreferencesSync(repoRoot);
+    if (prefs && typeof prefs.paName === 'string' && prefs.paName.length) {
+      paName = prefs.paName;
     }
   } catch { /* non-fatal */ }
 

package/dist/engineering-pa-workspace/src/install-daemon.mjs

@@ -27,10 +27,11 @@
  */
 
 import { execSync } from 'node:child_process';
-import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync, realpathSync } from 'node:fs';
+import { writeFileSync, mkdirSync, existsSync, unlinkSync, realpathSync } from 'node:fs';
 import { homedir, platform } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { readPreferencesSync } from '../../engineering-pa-core/src/preferences.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -55,7 +56,6 @@ function findRepoRoot(start) {
 const envRoot = process.env.DAVE_REPO_ROOT || process.env.PA_REPO_ROOT;
 const REPO_ROOT = envRoot ? resolve(envRoot) : (findRepoRoot(process.cwd()) || process.cwd());
 const SERVER_SCRIPT = join(__dirname, 'server.mjs');
-const PREFS_FILE = join(REPO_ROOT, 'operator', 'config', 'preferences.json');
 
 const LABEL = 'com.dave.workspace';
 const UNIT_NAME = 'dave-workspace.service';
@@ -80,7 +80,8 @@ function defaultLogPaths() {
 /**
  * Resolve the workspace port at install time. Precedence:
  *   1. CLI --port flag
- *   2. operator/config/preferences.json workspacePort
+ *   2. operator/config/preferences.json workspacePort (with device-local
+ *      preferences.local.json overlay applied)
  *   3. default 4200
  * @param {string|undefined} flagPort
  * @returns {number}
@@ -94,8 +95,8 @@ export function resolvePort(flagPort) {
     return parsed;
   }
   try {
-    const prefs = JSON.parse(readFileSync(PREFS_FILE, 'utf-8'));
-    if (prefs.workspacePort) return prefs.workspacePort;
+    const prefs = readPreferencesSync(REPO_ROOT);
+    if (prefs && prefs.workspacePort) return prefs.workspacePort;
   } catch { /* fall through to default */ }
   return 4200;
 }

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

@@ -20,13 +20,14 @@
 
 import { createServer } from 'node:http';
 import { readFile, stat, readdir } from 'node:fs/promises';
-import { readFileSync, existsSync, realpathSync } from 'node:fs';
+import { existsSync, realpathSync } from 'node:fs';
 import { execSync } from 'node:child_process';
 import { resolve, join, extname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { handleApi } from './api.mjs';
 import { loadNav } from './nav.mjs';
 import { readTeamScopeConfigSync } from '../../engineering-pa-core/src/desk/team-scope.mjs';
+import { readPreferencesSync } from '../../engineering-pa-core/src/preferences.mjs';
 import { startPoller as startStatusMonPoller } from './status-mon/poller.mjs';
 
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
@@ -89,11 +90,11 @@ let autoOpen = true;
 let timeoutMinutes = 120;
 let noTimeout = false;
 
-// Read configured port from preferences if available
+// Read configured port from preferences if available (device-local overlay
+// wins over the shared base — see @stravica-ai/engineering-pa-core/src/preferences.mjs).
 try {
-  const prefsPath = join(REPO_ROOT, 'operator', 'config', 'preferences.json');
-  const prefs = JSON.parse(readFileSync(prefsPath, 'utf-8'));
-  if (prefs.workspacePort) port = prefs.workspacePort;
+  const prefs = readPreferencesSync(REPO_ROOT);
+  if (prefs && prefs.workspacePort) port = prefs.workspacePort;
 } catch { /* no prefs yet — use default */ }
 
 // CLI flags override preferences

package/dist/engineering-pa-workspace/src/status-mon/poller.mjs

@@ -12,20 +12,11 @@
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { readPreferencesSync } from '../../../engineering-pa-core/src/preferences.mjs';
 import { poll, resolveSources, mergeWithPrevious } from './poll.mjs';
 
 const DEFAULT_INTERVAL_MS = 60_000;
 
-function readPreferences(repoRoot) {
-  try {
-    const prefsPath = join(repoRoot, 'operator', 'config', 'preferences.json');
-    if (!existsSync(prefsPath)) return null;
-    return JSON.parse(readFileSync(prefsPath, 'utf-8'));
-  } catch {
-    return null;
-  }
-}
-
 function readState(statePath) {
   try {
     if (!existsSync(statePath)) return null;
@@ -68,7 +59,9 @@ export function startPoller(options) {
   async function runOnce() {
     if (stopped) return null;
     try {
-      const prefs = readPreferences(repoRoot);
+      // Overlay-aware read: any device-scoped statusMonSources override in
+      // preferences.local.json shallow-merges OVER the shared base.
+      const prefs = readPreferencesSync(repoRoot);
       const sources = resolveSources(prefs);
       const previous = readState(statePath);
       const fresh = await poll({ sources, fetcher, nowMs: Date.now() });

package/dist/engineering-pa-workspace/src/status-mon/run.mjs

@@ -23,10 +23,11 @@
  * Exit codes: 0 ok | 1 usage | 2 fetch failure (all sources) | 3 write failure
  */
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, realpathSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { readPreferencesSync } from '../../../engineering-pa-core/src/preferences.mjs';
 import { poll, resolveSources, mergeWithPrevious } from './poll.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -81,23 +82,15 @@ function readPreviousState(statePath) {
   }
 }
 
-function readPreferences(repoRoot) {
-  try {
-    const prefsPath = join(repoRoot, 'operator', 'config', 'preferences.json');
-    if (!existsSync(prefsPath)) return null;
-    return JSON.parse(readFileSync(prefsPath, 'utf-8'));
-  } catch {
-    return null;
-  }
-}
-
 async function main() {
   const parsed = parseArgs(process.argv.slice(2));
   if (!parsed) { printHelp(); process.exit(1); }
   if (parsed.help) { printHelp(); process.exit(0); }
 
   const repoRoot = findRepoRoot();
-  const prefs = readPreferences(repoRoot);
+  // Overlay-aware read: preferences.local.json shallow-merges OVER
+  // preferences.json so any device-scoped statusMonSources override wins.
+  const prefs = readPreferencesSync(repoRoot);
   const sources = resolveSources(prefs);
   const outPath = parsed.outPath || join(repoRoot, '.state', 'status-mon.json');
 
@@ -127,7 +120,28 @@ async function main() {
   process.exit(allFailed && !state.lastSuccessfulPollAt ? 2 : 0);
 }
 
-main().catch((err) => {
-  process.stderr.write(`unexpected: ${err && err.stack ? err.stack : err}\n`);
-  process.exit(1);
-});
+// Entry-point guard: only run main() when this file is the process entry
+// point. Under the single-bundle rewriter, dist-imports.test.mjs dynamically
+// imports every "rewritten" module (one that crosses into another bundled
+// package) to walk the ESM graph; before this file added its own
+// cross-package import it stayed off that list, so the top-level
+// main().catch() was tolerated. Rebuilding without a guard now runs main()
+// during that dynamic import and the parseArgs sees the outer test process's
+// argv. Matches the isMainModule pattern already used by ws.mjs /
+// server.mjs / install-daemon.mjs (realpath both sides for pnpm-hoisted
+// layouts where argv[1] is a symlink).
+const isMainModule = (() => {
+  if (!process.argv[1]) return false;
+  try {
+    return fileURLToPath(import.meta.url) === realpathSync(resolve(process.argv[1]));
+  } catch {
+    return false;
+  }
+})();
+
+if (isMainModule) {
+  main().catch((err) => {
+    process.stderr.write(`unexpected: ${err && err.stack ? err.stack : err}\n`);
+    process.exit(1);
+  });
+}

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

@@ -20,6 +20,7 @@ import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { platform } from 'node:os';
 import { get } from 'node:http';
+import { readPreferencesSync } from '../../engineering-pa-core/src/preferences.mjs';
 import {
   detectSupervisor,
   readSupervisorState,
@@ -36,7 +37,6 @@ const SERVER_SCRIPT = join(__dirname, 'server.mjs');
 // .ws.pid / .ws.log are never written to during the subprocess test runs.
 const PID_FILE = process.env.WS_PID_FILE || join(REPO_ROOT, '.ws.pid');
 const LOG_FILE = process.env.WS_LOG_FILE || join(REPO_ROOT, '.ws.log');
-const PREFS_FILE = join(REPO_ROOT, 'operator', 'config', 'preferences.json');
 
 // Test-only override: lets e2e tests assert cross-platform parity by forcing
 // the supervisor probe to behave as if it were running on a different OS.
@@ -75,10 +75,11 @@ function resolvePort() {
   // 1. Default
   let port = 4200;
 
-  // 2. Preferences override
+  // 2. Preferences override — device-local overlay wins over the shared base
+  // (see @stravica-ai/engineering-pa-core/src/preferences.mjs).
   try {
-    const prefs = JSON.parse(readFileSync(PREFS_FILE, 'utf-8'));
-    if (prefs.workspacePort) port = prefs.workspacePort;
+    const prefs = readPreferencesSync(REPO_ROOT);
+    if (prefs && prefs.workspacePort) port = prefs.workspacePort;
   } catch { /* no prefs — use default */ }
 
   // 3. CLI flag override

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stravica-ai/digital-operator-pa",
-  "version": "0.1.16",
-  "description": "Digital Operator PA — single-bundled public package surface (bins + library) for the platform.",
+  "version": "0.1.18",
+  "description": "Digital Operator PA \u2014 single-bundled public package surface (bins + library) for the platform.",
   "type": "module",
   "main": "./index.mjs",
   "exports": {
@@ -49,10 +49,11 @@
   "engines": {
     "node": ">=24"
   },
-  "//": "test pins --test-isolation=none: default process-isolation mode silently undercounts (drops passed tests from totals) when a test awaits async work while stdout is patched by a capture() helper — see packages/cli/test/secrets. Counts must never lie.",
   "scripts": {
     "build": "node build.mjs",
+    "prepack": "node build.mjs",
     "test": "node --test --test-isolation=none test/*.test.mjs",
     "dry-publish": "node build.mjs && node scripts/dry-publish.mjs"
-  }
-}
+  },
+  "//": "test pins --test-isolation=none: default process-isolation mode silently undercounts (drops passed tests from totals) when a test awaits async work while stdout is patched by a capture() helper \u2014 see packages/cli/test/secrets. Counts must never lie."
+}