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

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

@@ -15,7 +15,11 @@ import {
   computeDistillationHealth,
   renderHealthLine,
 } from '../../../engineering-pa-core/src/distill/health.mjs';
+import { vaultState } from '../../../engineering-pa-core/src/vault/require.mjs';
+import { enabledToolsNeedingSecrets } from '../../../engineering-pa-core/src/vault/tool-needs.mjs';
+import { resolveDefaultScope } from '../secrets/vault.mjs';
 import { main as runMigrateInspect } from '../../../engineering-pa-migrate-inspect/src/cli.mjs';
+import { doOnboard } from './onboard.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -38,6 +42,7 @@ Usage:
   pa migrate-inspect [options]  Host inspection for migration planning
   pa launch --agent=<n> --task=<id> [--dry-run]
                               Boot a scoped agent instance bound to an identity and task
+  pa onboard <verb>           Onboarding walkthrough state (complete)
   pa -h, --help               Show this help
 
 Routed sub-CLIs (also available as standalone bins):
@@ -92,6 +97,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);
@@ -122,9 +129,11 @@ async function doStatus(opts = {}) {
   const out = opts.stdout ?? process.stdout;
   const err = opts.stderr ?? process.stderr;
   const cwd = opts.cwd ?? process.cwd();
+  const env = opts.env ?? process.env;
+  const home = opts.home;
   const repoRoot = opts.repoRoot
-    ?? process.env.DAVE_REPO_ROOT
-    ?? process.env.PA_REPO_ROOT
+    ?? env.DAVE_REPO_ROOT
+    ?? env.PA_REPO_ROOT
     ?? cwd;
   const workspacePort = resolveWorkspacePort(repoRoot, opts);
 
@@ -174,17 +183,67 @@ 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. Distillation health — schedule installed?, last run, staging
+  // 4. Vault state — three states rendered on one line (initialised /
+  // not needed / NOT INITIALISED). Load-bearing because 0.1.50 shipped
+  // a scaffold that created an empty `.vault/` for every colleague and
+  // then never initialised it: a jira/confluence call after onboard
+  // hit `secrets get` against a vault that did not exist, and the
+  // failure mode was silent misdirection. `not needed` renders when no
+  // enabled tool in operator/extensions/manifest.json declares any
+  // secret keys (via packages/core/src/vault/tool-needs.mjs).
+  out.write('\nVault:\n');
+  try {
+    const needs = enabledToolsNeedingSecrets(repoRoot);
+    // 0.1.51 fix round (w-2026-09-18-dave-007): consult the SAME
+    // default-scope resolver the credentialed tools use so the Vault
+    // line can never say `initialised` while `secrets get` would miss.
+    // In solo mode the resolver returns scope=null (its defaults.json
+    // and identity.json branches are gated off), so `vaultPaths`
+    // targets the instance's own legacy vault — matching what init
+    // seeded. In HQ mode a resolved scope steers `vaultState` at the
+    // scoped file the tools will actually read.
+    const scoped = resolveDefaultScope({ cwd: repoRoot, env, home });
+    const state = vaultState({ repoRoot, home, env, scope: scoped.scope || undefined });
+    if (state.ok) {
+      const n = state.keyCount == null ? '?' : state.keyCount;
+      const scopeSuffix = scoped.scope ? `; scope '${scoped.scope}' from ${scoped.source}` : '';
+      out.write(`  initialised (${n} keys${scopeSuffix})\n`);
+    } else if (needs.length === 0) {
+      out.write('  not needed (no enabled tool declares secret needs)\n');
+    } else if (state.state === 'partial') {
+      const gaps = state.missing.join(', ');
+      const toolLabels = needs.map((t) => t.toolId).join(', ');
+      out.write(`  NOT INITIALISED (partial; missing: ${gaps}) - enabled tools needing secrets: ${toolLabels}. Run: pnpm exec secrets init\n`);
+    } else {
+      const toolLabels = needs.map((t) => t.toolId).join(', ');
+      out.write(`  NOT INITIALISED - enabled tools needing secrets: ${toolLabels}. Run: pnpm exec secrets init\n`);
+    }
+  } catch (e) {
+    out.write(`  vault probe failed: ${e?.message || e}\n`);
+  }
+
+  // 5. 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
@@ -219,6 +278,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,144 @@
+// 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.51): librarianSchedule, plus vault when
+// any enabled tool declares a secrets need (see
+// packages/core/src/vault/tool-needs.mjs::enabledToolsNeedingSecrets).
+// See packages/core/docs/commands/onboard.md §Completion.
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { enabledToolsNeedingSecrets } from '../../../engineering-pa-core/src/vault/tool-needs.mjs';
+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 BASE_MANDATORY_STEPS = [
+  {
+    id: 'librarianSchedule',
+    remediation: 'run /onboard and complete the librarianSchedule step (installs the mandatory distillation sweep)',
+  },
+];
+
+// The vault step is conditionally mandatory: required only when at
+// least one enabled tool declares a secrets need. See
+// packages/core/src/vault/tool-needs.mjs. A `notNeeded` value on this
+// step is a clean pass through the gate; `pending` refuses completion.
+function mandatoryStepsFor(steps, enabledNeedingSecrets) {
+  const list = [...BASE_MANDATORY_STEPS];
+  const vault = steps ? steps.vault : undefined;
+  if (vault === 'notNeeded') return list;
+  if (enabledNeedingSecrets && enabledNeedingSecrets.length > 0) {
+    const toolLabels = enabledNeedingSecrets.map((t) => t.toolId).join(', ');
+    list.push({
+      id: 'vault',
+      remediation: `run /onboard and complete the vault step (initialise the SOPS+age vault used by: ${toolLabels})`,
+    });
+  }
+  return list;
+}
+
+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 enabledNeedingSecrets = deps.enabledToolsNeedingSecrets
+    ? deps.enabledToolsNeedingSecrets(repoRoot)
+    : enabledToolsNeedingSecrets(repoRoot);
+  const mandatory = mandatoryStepsFor(steps, enabledNeedingSecrets);
+  const pending = [];
+  for (const step of mandatory) {
+    // `notNeeded` on the vault step passes; every other terminal value
+    // that is not `done` is pending. Skipped is never valid for a
+    // mandatory step (mirrors librarianSchedule's contract).
+    if (steps[step.id] === 'done') continue;
+    if (step.id === 'vault' && steps.vault === 'notNeeded') continue;
+    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-cli/src/secrets/cli.mjs

@@ -22,7 +22,10 @@ import { resolveScopePaths, VaultError } from './vault.mjs';
 const HELP = `secrets — SOPS+age secrets management
 
 Usage:
-  secrets init              Initialise the vault (generate keys, create empty secrets file)
+  secrets init              Initialise the vault (generate keys, create empty secrets file).
+                             --empty: explicit no-seed init (current default shape).
+                             --stdin-json: after init, seed KEYs from a JSON object
+                             read on stdin (values never echoed; refuses a TTY stdin).
   secrets get KEY           Retrieve a secret (add --exists for a present/absent check that never prints the value)
   secrets set KEY VALUE     Store or update a secret (use \`-\` as VALUE to read from stdin)
                              Since 0.1.20, canonical-first dual-write is
@@ -53,7 +56,18 @@ Usage:
                              --values is required — decrypt-only is never
                              a valid pass (see below). Never prints values.
 
-Private key:      ~/.config/stravica-pa/age-key.txt  (never committed)
+Age private key resolution (0.1.51, w-2026-09-18-dave-007). One shared
+order every verb + pa status + the atlassian resolver consult:
+  1. $SOPS_AGE_KEY_FILE          Explicit override, always wins.
+  2. <repo>/.vault/age-key.txt   Solo-mode key, gitignored. Wins when
+                                 present in either mode.
+  3. ~/.config/stravica-pa/age-key.txt
+                                 Per-user key. Used only when the
+                                 instance is in HQ mode
+                                 (library.mode: remote). Solo mode
+                                 with no in-instance key resolves back
+                                 to #2, init writes there.
+
 Public key:       .vault/recipients.txt       (committed to repo)
 Encrypted store:  .vault/secrets.enc.json     (committed to repo)
 SOPS config:      .vault/.sops.yaml           (committed to repo)
@@ -330,7 +344,7 @@ export async function run(argv, overrides = {}) {
   const cmdOverrides = paths ? { ...overrides, paths } : overrides;
 
   switch (cmd) {
-    case 'init':   return runInit(cmdOverrides);
+    case 'init':   return runInit({ ...cmdOverrides, argv: cmdArgs });
     case 'get':    return runGet(cmdArgs, cmdOverrides);
     case 'set':    return runSet(cmdArgs, cmdOverrides);
     case 'list':   return runList(cmdOverrides);
@@ -353,6 +367,15 @@ export async function run(argv, overrides = {}) {
 }
 
 export async function main(argv, overrides = {}) {
+  // 0.1.51 fix round 2 (w-2026-09-18-dave-007): env defaulted at the
+  // BIN entry so every downstream defaultPaths / resolveScopePaths /
+  // resolveKeyFile call sees the operator's real environment
+  // (SOPS_AGE_KEY_FILE, DAVE_ROOT, etc). The vault.mjs resolvers do NOT
+  // default env from process.env themselves — that leak was breaking
+  // scoped-fixture tests when the developer's shell carried
+  // SOPS_AGE_KEY_FILE. run() is exported for tests to call with an
+  // explicit env; main() is what the packaged bin invokes.
+  if (overrides.env === undefined) overrides = { ...overrides, env: process.env };
   try {
     const code = await run(argv, overrides);
     process.exit(code ?? 0);

package/dist/engineering-pa-cli/src/secrets/commands/init.mjs

@@ -1,6 +1,23 @@
 // init — generate age keypair, write recipients, write SOPS config,
 // create an empty encrypted secrets file if none exists.
+//
+// Two non-interactive paths are exposed for the guided onboarding
+// vault step AND the e2e test to share ONE code path:
+//
+//   secrets init --empty
+//     Explicit "create the key and the empty store, no seeded keys".
+//     The default behaviour has always produced this shape; the flag
+//     is a self-documenting affirmation the caller wanted it.
+//
+//   secrets init --stdin-json
+//     Read {"KEY": "value", ...} from stdin and seed those keys after
+//     the vault is created (never writes to canonical clones — a fresh
+//     init lands values in the workspace vault only). Values are never
+//     echoed to stdout or stderr and never appear in any log line the
+//     tool writes; the tool refuses if stdin is a TTY (no accidental
+//     paste-into-prompt where the value would land in shell history).
 
+import { readFileSync } from 'node:fs';
 import {
   defaultPaths,
   checkDeps,
@@ -14,12 +31,93 @@ import {
   writeSopsConfig,
   keyFileExists,
   secretsFileExists,
+  sopsDecrypt,
   sopsEncrypt,
   VaultError,
 } from '../vault.mjs';
 
+const KEY_NAME_RE = /^[A-Z0-9_]+$/;
+
+function extractInitFlags(argv) {
+  const out = { empty: false, stdinJson: false };
+  for (const a of argv || []) {
+    if (a === '--empty') out.empty = true;
+    else if (a === '--stdin-json') out.stdinJson = true;
+    else if (a === '-h' || a === '--help') out.help = true;
+    else out.unknown = a;
+  }
+  return out;
+}
+
+function readStdinSync() {
+  // Read raw bytes from stdin synchronously. Never printed anywhere.
+  try {
+    return readFileSync(0, 'utf8');
+  } catch (err) {
+    throw new VaultError(`Error: could not read stdin for --stdin-json: ${err && err.message ? err.message : err}`, 1);
+  }
+}
+
+function parseStdinJson(raw) {
+  if (typeof raw !== 'string' || raw.trim().length === 0) {
+    throw new VaultError('Error: --stdin-json received empty input; expected a JSON object of KEY/value pairs.', 1);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new VaultError(`Error: --stdin-json input is not valid JSON: ${err && err.message ? err.message : err}`, 1);
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new VaultError('Error: --stdin-json input must be a JSON OBJECT of KEY/value pairs.', 1);
+  }
+  const out = {};
+  for (const [key, value] of Object.entries(parsed)) {
+    if (!KEY_NAME_RE.test(key)) {
+      throw new VaultError(`Error: --stdin-json key "${key}" must match ${KEY_NAME_RE} (upper snake case).`, 1);
+    }
+    if (typeof value !== 'string') {
+      throw new VaultError(`Error: --stdin-json value for "${key}" must be a string.`, 1);
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
 export async function runInit(overrides = {}) {
   const paths = overrides.paths || defaultPaths({ ...overrides, allowGitRootWithoutVault: true });
+  const argv = overrides.argv || [];
+  const flags = extractInitFlags(argv);
+
+  if (flags.help) {
+    console.log([
+      'Usage: secrets init [--empty | --stdin-json]',
+      '',
+      '  --empty        Create the key and an empty encrypted store (default shape).',
+      '  --stdin-json   After init, seed KEYs from a JSON object read on stdin.',
+      '                 Refuses when stdin is a TTY. Values are never echoed.',
+    ].join('\n'));
+    return 0;
+  }
+
+  if (flags.empty && flags.stdinJson) {
+    console.error('Error: --empty and --stdin-json are mutually exclusive.');
+    throw new VaultError('mutually exclusive flags', 1);
+  }
+
+  // Read stdin BEFORE running the init side effects — a malformed
+  // payload should not leave a partially-initialised vault on disk when
+  // the caller was going to seed it in one shot.
+  let seedPairs = null;
+  if (flags.stdinJson) {
+    const stdinStream = overrides.stdinStream || process.stdin;
+    if (stdinStream && stdinStream.isTTY && !overrides.allowTtyStdin) {
+      console.error('Error: --stdin-json requires piped JSON on stdin; refusing to prompt (would land the value in shell history).');
+      throw new VaultError('stdin is a TTY', 1);
+    }
+    const raw = overrides.stdinRead ? overrides.stdinRead() : readStdinSync();
+    seedPairs = parseStdinJson(raw);
+  }
 
   const missing = await checkDeps();
   if (missing.length > 0) {
@@ -33,6 +131,13 @@ export async function runInit(overrides = {}) {
   ensureKeyDir(paths);
 
   if (keyFileExists(paths)) {
+    // 0.1.51 fix round 2 (w-2026-09-18-dave-007): the shared resolver
+    // routes solo instances to `<repoRoot>/.vault/age-key.txt` and HQ
+    // instances to `~/.config/stravica-pa/age-key.txt`. A pre-existing
+    // key at the resolved path is intentional reuse (init is
+    // idempotent). A foreign per-user key on a fresh solo laptop no
+    // longer meets this check — the solo resolver returns the instance
+    // path, which does not exist, and init generates a NEW key there.
     console.log(`Age private key already exists at ${paths.keyFile}`);
   } else {
     await ageKeygen(paths);
@@ -59,6 +164,29 @@ export async function runInit(overrides = {}) {
     console.log('Encrypted secrets file already exists.');
   }
 
+  // Seed non-interactively. Merge (do not replace) any keys that were
+  // already in the store — this verb is idempotent by design and a
+  // re-run with a new key/value should not clobber the operator's
+  // existing set. Values are never echoed; the summary line at the end
+  // prints only key NAMES and the pair count.
+  if (seedPairs && Object.keys(seedPairs).length > 0) {
+    let data = {};
+    if (secretsFileExists(paths)) {
+      try {
+        data = await sopsDecrypt(paths, paths.secretsFile);
+      } catch (err) {
+        console.error(`Error: could not decrypt ${paths.secretsFile} to merge seeded keys: ${err && err.message ? err.message : err}`);
+        throw new VaultError('seed merge decrypt failed', 2);
+      }
+    }
+    for (const [k, v] of Object.entries(seedPairs)) data[k] = v;
+    await sopsEncrypt(paths, pubKey, data);
+    const names = Object.keys(seedPairs).sort();
+    console.log(`Seeded ${names.length} key(s): ${names.join(', ')}`);
+  } else if (flags.stdinJson) {
+    console.log('--stdin-json input carried no keys; vault created empty.');
+  }
+
   console.log('');
   console.log('Vault initialised.');
   console.log(`  Private key: ${paths.keyFile} (NEVER commit this)`);

package/dist/engineering-pa-cli/src/secrets/commands/set.mjs

@@ -21,6 +21,7 @@
 // "device-side vault mutations must round-trip to canonical immediately").
 
 import { readFileSync } from 'node:fs';
+import { isSoloMode } from '../../../../engineering-pa-core/src/vault/mode.mjs';
 import {
   resolveCommandPaths,
   resolveScopePaths,
@@ -153,19 +154,38 @@ export async function runSet(args, overrides = {}) {
     // callers that build paths themselves and only pass home via
     // overrides, then to homedir() for the real CLI at run time.
     const canonicalHome = paths.home ?? overrides.home;
-    const resolved = overrides.resolveCanonicalCloneTarget
-      ? overrides.resolveCanonicalCloneTarget({ scope: paths.scope, home: canonicalHome, env: overrides.env })
-      : resolveCanonicalCloneTarget({ scope: paths.scope, home: canonicalHome, env: overrides.env });
-    if (resolved.file) {
-      effectiveCanonical = { file: resolved.file, source: resolved.source, detail: resolved.detail };
+
+    // Solo-mode gate (0.1.51, w-2026-09-18-dave-007). Auto-discovery of
+    // a canonical clone via ~/.config/stravica-pa/defaults.json or the
+    // ~/stravica-canonical/*/vault/<scope>.enc.json convention is the
+    // co-existence hazard the fix closes: on a colleague laptop that
+    // already carries ANOTHER instance's vault, a solo `secrets set`
+    // must never silently dual-write across the estate boundary.
+    // Explicit --canonical-clone PATH still wins (above); the gate only
+    // suppresses the AUTO-discovery tier. HQ mode (preferences.library.
+    // mode === 'remote') keeps today's behaviour because there the auto-
+    // discovery IS the desired behaviour — the operator owns every vault
+    // the scan can find. See packages/core/src/vault/mode.mjs.
+    const soloGate = overrides.isSoloMode
+      ? overrides.isSoloMode({ repoRoot: paths.root })
+      : isSoloMode({ repoRoot: paths.root });
+    if (soloGate) {
+      console.error(`notice: solo mode - canonical-clone auto-discovery is off for scope '${paths.scope}'. Workspace-only write. Pass --canonical-clone PATH to force a dual-write.`);
     } else {
-      // Absence notice — never a failure. Explains WHY nothing resolved so
-      // an operator on a host without a canonical layout knows whether to
-      // provision one, pass --no-canonical to silence, or ignore.
-      const tail = resolved.tried && resolved.tried.length > 0
-        ? ` (tried: ${resolved.tried.join('; ')})`
-        : '';
-      console.error(`notice: no canonical clone configured for scope '${paths.scope}' on this host — workspace-only write${tail}`);
+      const resolved = overrides.resolveCanonicalCloneTarget
+        ? overrides.resolveCanonicalCloneTarget({ scope: paths.scope, home: canonicalHome, env: overrides.env })
+        : resolveCanonicalCloneTarget({ scope: paths.scope, home: canonicalHome, env: overrides.env });
+      if (resolved.file) {
+        effectiveCanonical = { file: resolved.file, source: resolved.source, detail: resolved.detail };
+      } else {
+        // Absence notice — never a failure. Explains WHY nothing resolved so
+        // an operator on a host without a canonical layout knows whether to
+        // provision one, pass --no-canonical to silence, or ignore.
+        const tail = resolved.tried && resolved.tried.length > 0
+          ? ` (tried: ${resolved.tried.join('; ')})`
+          : '';
+        console.error(`notice: no canonical clone configured for scope '${paths.scope}' on this host — workspace-only write${tail}`);
+      }
     }
   }