@stravica-ai/digital-operator-pa 0.1.19 → 0.1.20

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

@@ -8,7 +8,7 @@ Dave uses SOPS with age encryption for secrets management. Secrets are encrypted
 
 Implemented: `init`, `get`, `set`, `list`, `delete`, `rotate`, `status`, `backup`, `vaults`, `find` (alias `which`), `verify`. No npm dependencies — shells out to `sops` and `age` via `node:child_process.spawn`.
 
-`set` additionally supports `--canonical-clone PATH` (write a canonical clone's vault file first, then the resolved workspace copy — aborts before touching the workspace copy if the canonical write fails). `verify --values --against PATH` does a byte-level comparison of DECRYPTED values between the resolved vault and a reference vault at PATH — never a decrypt-only pass. See "Value-compare verification" and "Canonical-first writes" below.
+**Canonical-first dual-write is the DEFAULT for scoped `set` since 0.1.20.** A plain `secrets set` on a scoped vault writes canonical FIRST and workspace SECOND whenever a canonical clone for the scope is discoverable on this host (via `~/.config/stravica-pa/defaults.json`'s `canonicalClone` key or the `~/stravica-canonical/*/vault/<scope>.enc.json` estate convention). Absence of a canonical clone is a stderr NOTICE, never a failure. Explicit `--canonical-clone PATH` still wins over auto-discovery (and bootstraps a missing file); `--no-canonical` opts out entirely and suppresses the notice. `verify --values --against PATH` does a byte-level comparison of DECRYPTED values between the resolved vault and a reference vault at PATH — never a decrypt-only pass. See "Value-compare verification" and "Canonical-first writes" below.
 
 `get`/`set` run without `--scope`/`--file` now resolve a **default scope** — `$SECRETS_DEFAULT_SCOPE` env var, then `"defaultScope"` in `~/.config/stravica-pa/defaults.json`, then the calling PA's own `agents/<name>/identity.json`, then the legacy single-file vault as a last resort. Every such invocation prints a one-line stderr notice naming the target vault BEFORE the operation runs, including the legacy-fallback case ("no scope specified and no default configured") — see `secrets --help` → "Default scope" for the full precedence and example notices.
 
@@ -67,11 +67,17 @@ node core/tools/secrets/bin/secrets status
 # Open a browser with a QR code of the master key for backup
 node core/tools/secrets/bin/secrets backup
 
-# Write a canonical clone's vault FIRST, then the workspace copy second.
-# Aborts (exit 2) before touching the workspace copy if the canonical
-# write fails (e.g. the existing canonical store can't be decrypted).
+# Force a specific canonical file (wins over auto-discovery; bootstraps
+# a missing file). Aborts (exit 2) before touching the workspace copy if
+# the canonical write fails (e.g. the existing canonical store can't be
+# decrypted). Auto-discovery is on by default since 0.1.20 — this flag
+# is only for pointing at a specific target.
 node core/tools/secrets/bin/secrets set API_KEY "sk-abc123" --canonical-clone /path/to/canonical/vault/scope.enc.json
 
+# Opt out of canonical dual-write entirely (suppresses the absence
+# notice too). Mutually exclusive with --canonical-clone.
+node core/tools/secrets/bin/secrets set API_KEY "sk-abc123" --no-canonical
+
 # Byte-level comparison of DECRYPTED values against a reference vault.
 # --values is required — there is no decrypt-only verification mode
 # (decrypt-only false-passes a vault that decrypts cleanly but holds the
@@ -79,29 +85,66 @@ node core/tools/secrets/bin/secrets set API_KEY "sk-abc123" --canonical-clone /p
 node core/tools/secrets/bin/secrets verify --values --against /path/to/other/vault/scope.enc.json
 ```
 
-### Canonical-first writes (`set --canonical-clone`)
+### Canonical-first writes
+
+Canonical-first dual-write is the DEFAULT for scoped `set` since 0.1.20 —
+a plain `secrets set` on a scoped vault writes canonical FIRST and the
+workspace SECOND whenever a canonical clone for the scope is discoverable
+on this host. The abort-before-workspace ordering is identical to the
+explicit-flag path it grew out of: if the canonical write fails for any
+reason (existing canonical store undecryptable, sops encrypt failure),
+the command exits 2 and the workspace copy is never touched.
+
+**Resolution order** (first hit wins; every miss recorded in the absence
+notice's tried-tier detail):
+
+1. **Explicit `--canonical-clone PATH`** — always wins, bootstraps a
+   missing file (this is the flag's historical behaviour).
+2. **`"canonicalClone"` in `~/.config/stravica-pa/defaults.json`** — the
+   same file (already read for `workspaceRoot` and `defaultScope`); the
+   CLI never writes it. Two shapes supported:
+   - **Object (scope → file map):**
+     ```json
+     { "canonicalClone": { "seo-ops": "/Users/thefoot/stravica-canonical/stravica-operator-barry/vault/seo-ops.enc.json" } }
+     ```
+   - **String (root dir)** — derives `<root>/vault/<scope>.enc.json`,
+     which fits the estate's operator-repo layout:
+     ```json
+     { "canonicalClone": "/Users/thefoot/stravica-canonical/stravica-operator-barry" }
+     ```
+3. **Estate convention** — `~/stravica-canonical/<repo>/vault/<scope>.enc.json`
+   (glob shape `~/stravica-canonical/*/vault/…enc.json`). This reuses the
+   root the rest of the estate already uses (see
+   `library-sync-cycle`'s `--repos-root` default and
+   `dex-cutover-driver`'s `reposRoot`). Exactly one match wins; ambiguity
+   (multiple matches) or zero matches skips this tier.
+
+**Absence** is a stderr notice, never a failure — a host with no
+canonical layout keeps writing to workspace only:
+
+```
+notice: no canonical clone configured for scope 'seo-ops' on this host — workspace-only write (tried: …)
+```
+
+The `tried:` tail names every tier that missed and why, so an operator on
+a host that ought to have a canonical knows exactly where to configure it
+(or that `--no-canonical` is the intended answer for a host that never
+had one).
 
-Without the flag, `set` behaves exactly as before — it writes only the
-resolved workspace copy. With `--canonical-clone PATH`, `set`:
+**Flags:**
 
-1. Resolves `PATH` the same way `--file` resolves any other vault (its
-   own `.sops.yaml` expected alongside it), reusing this host's own key
-   material (`keyDir`/`keyFile`) — the canonical clone and the workspace
-   copy are expected to share recipients in practice (same operator,
-   same device).
-2. Decrypts the existing canonical store (if any) and writes the new key
-   into it. **If this fails for any reason — the existing canonical
-   store can't be decrypted, or the encrypt itself fails — `set` aborts
-   with exit 2 and the workspace copy is never touched.**
-3. Only on canonical success does it proceed to the existing
-   decrypt-mutate-encrypt cycle against the resolved workspace copy.
+- `--canonical-clone PATH` — force a specific canonical file (wins over
+  auto-discovery; bootstraps a missing file). Backwards-compatible with
+  every prior release.
+- `--no-canonical` — opt out of dual-write entirely, and suppress the
+  absence notice. Mutually exclusive with `--canonical-clone`.
 
 This closes the "device-side vault mutation only round-trips halfway"
-class: a device-side `secrets set` that updates the workspace copy but
-never reaches canonical leaves the two vaults silently diverged until the
-next down-path materialisation clobbers the device's fresher value.
-`--canonical-clone` makes the canonical write the FIRST, gating step —
-the workspace never ends up ahead of canonical.
+class BY DEFAULT rather than opt-in: any workspace write that a
+canonical layout could catch, it now does — no flag required.
+
+Legacy vaults (no scope) never trigger canonical resolution — the notice
+would be pure noise for a fallback that has no natural canonical mirror.
 
 ### Value-compare verification (`verify --values --against`)
 

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

@@ -25,10 +25,17 @@ Usage:
   secrets init              Initialise the vault (generate keys, create empty secrets file)
   secrets get KEY           Retrieve a secret
   secrets set KEY VALUE     Store or update a secret (use \`-\` as VALUE to read from stdin)
-                             --canonical-clone PATH: write the canonical
-                             clone's vault file FIRST, then this workspace
-                             copy. If the canonical write fails, aborts
-                             before touching the workspace copy at all.
+                             Since 0.1.20, canonical-first dual-write is
+                             the DEFAULT for scoped writes when a canonical
+                             clone for the scope is discoverable on this
+                             host. See "Canonical-first writes" below.
+                             --canonical-clone PATH: force a specific
+                             canonical clone's vault file (bootstraps a
+                             missing file; wins over auto-discovery).
+                             --no-canonical: opt out of the dual-write and
+                             the absence notice.
+                             If the canonical write fails, aborts before
+                             touching the workspace copy at all.
   secrets list              List all secret key names (not values)
   secrets delete KEY        Remove a secret
   secrets rotate            Re-encrypt with current recipients
@@ -111,16 +118,30 @@ Default scope (get/set only, when neither --scope nor --file is given):
     note: writing to '(legacy)' pot — no scope specified and no default configured. Use --scope <name> or configure a default.
 
 Canonical-first writes (set only):
-  --canonical-clone PATH    Write PATH (a canonical clone's encrypted
-                             vault file) FIRST, then the resolved
-                             workspace copy SECOND. If the canonical
-                             write fails for any reason (existing store
-                             undecryptable, sops encrypt failure), the
-                             command aborts with exit 2 BEFORE touching
-                             the workspace copy at all — a device-side
-                             vault mutation never round-trips only
-                             halfway. Without this flag, 'set' behaves
-                             exactly as before (workspace copy only).
+  Canonical-first dual-write is DEFAULT for scoped writes since 0.1.20 —
+  a plain 'secrets set' on a scoped vault writes canonical FIRST and
+  workspace SECOND whenever a canonical clone for the scope is
+  discoverable on this host. Discovery order, first hit wins:
+    1. Explicit --canonical-clone PATH (always wins, bootstraps a
+       missing file).
+    2. "canonicalClone" in ~/.config/stravica-pa/defaults.json — either:
+         object (scope → file map):
+           { "canonicalClone": { "seo-ops": "/abs/vault/seo-ops.enc.json" } }
+         string (root dir), derives <root>/vault/<scope>.enc.json:
+           { "canonicalClone": "/Users/thefoot/stravica-canonical/stravica-operator-barry" }
+    3. Estate convention: ~/stravica-canonical/*/vault/<scope>.enc.json
+       (exactly one match; ambiguity or zero matches skips this tier).
+  Absence is a NOTICE, never a failure — a host with no canonical layout
+  keeps writing to workspace only, with a one-line stderr line naming why
+  nothing resolved. If any canonical write fails (existing store
+  undecryptable, sops encrypt failure), the command aborts with exit 2
+  BEFORE touching the workspace copy — the ordering invariant is
+  identical to the flag path since it always was.
+
+  --canonical-clone PATH    Force PATH as the canonical target (wins over
+                             auto-discovery; bootstraps a missing file).
+  --no-canonical            Opt out of dual-write entirely, and suppress
+                             the absence notice.
 
 Value-compare verification:
   secrets verify --values --against <path>
@@ -139,7 +160,7 @@ const USAGE = `Usage: secrets {init|get|set|list|delete|rotate|status|backup|vau
 Commands:
   init              Initialise the vault (generate keys, create config)
   get KEY           Retrieve a secret value
-  set KEY VALUE     Store or update a secret (--canonical-clone PATH: write canonical first)
+  set KEY VALUE     Store or update a secret (canonical-first by default; --no-canonical to opt out)
   list              List all secret key names
   delete KEY        Remove a secret
   rotate            Re-encrypt with current recipients

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

@@ -2,18 +2,29 @@
 // Passing `-` as VALUE reads the secret from stdin (trailing newline stripped),
 // which keeps the value out of argv / process listings / shell history.
 //
-// --canonical-clone PATH: write the canonical clone's vault file FIRST,
-// then this workspace copy SECOND. If the canonical write fails for any
-// reason, the command aborts (exit 2) BEFORE touching the workspace copy
-// at all — a device-side vault mutation never round-trips only halfway
-// (see up-path-single-writer-ownership's vault follow-up: "device-side
-// vault mutations must round-trip to canonical immediately"). Without the
-// flag, behaviour is exactly as before (workspace copy only).
+// Canonical-first dual-write is the DEFAULT for scoped writes since 0.1.20:
+// when a canonical clone for the target scope is discoverable on this host
+// (via ~/.config/stravica-pa/defaults.json "canonicalClone" or the
+// ~/stravica-canonical/*/vault/<scope>.enc.json convention — see
+// resolveCanonicalCloneTarget in ../vault.mjs), set writes canonical FIRST
+// and workspace SECOND, with the same abort-before-workspace ordering the
+// explicit --canonical-clone flag has always had. Absence of a canonical
+// clone is a NOTICE, never a failure (a host that never had a canonical
+// keeps working); --no-canonical opts out (and suppresses the notice).
+// Explicit --canonical-clone PATH still wins over any auto-discovery.
+//
+// Ordering invariant (pinned by tests): if the canonical write fails for
+// any reason (existing canonical store undecryptable, sops encrypt
+// failure), the command aborts with exit 2 BEFORE touching the workspace
+// copy at all — a device-side vault mutation never round-trips only
+// halfway (see up-path-single-writer-ownership's vault follow-up:
+// "device-side vault mutations must round-trip to canonical immediately").
 
 import { readFileSync } from 'node:fs';
 import {
   resolveCommandPaths,
   resolveScopePaths,
+  resolveCanonicalCloneTarget,
   checkDeps,
   depInstallMessage,
   checkVault,
@@ -25,19 +36,21 @@ import {
   VaultError,
 } from '../vault.mjs';
 
-// --canonical-clone may appear anywhere in argv, matching the --scope/
-// --file convention in cli.mjs. Local to `set` (not a global flag) since
-// no other command writes to a second target.
-function extractCanonicalCloneFlag(argv) {
+// --canonical-clone / --no-canonical may appear anywhere in argv, matching
+// the --scope/--file convention in cli.mjs. Local to `set` (not global
+// flags) since no other command writes to a second target.
+function extractCanonicalFlags(argv) {
   const rest = [];
   let canonicalClone;
+  let noCanonical = false;
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
     if (a === '--canonical-clone') { canonicalClone = argv[i + 1]; i += 1; continue; }
     if (a.startsWith('--canonical-clone=')) { canonicalClone = a.slice('--canonical-clone='.length); continue; }
+    if (a === '--no-canonical') { noCanonical = true; continue; }
     rest.push(a);
   }
-  return { canonicalClone, rest };
+  return { canonicalClone, noCanonical, rest };
 }
 
 export async function runSet(args, overrides = {}) {
@@ -45,15 +58,20 @@ export async function runSet(args, overrides = {}) {
   // target vault) whenever --scope/--file wasn't given upstream in
   // cli.mjs — see vault.mjs's default-scope resolution section.
   const paths = resolveCommandPaths(overrides);
-  const { canonicalClone, rest } = extractCanonicalCloneFlag(args);
+  const { canonicalClone, noCanonical, rest } = extractCanonicalFlags(args);
   const key = rest[0];
   let value = rest[1];
 
   if (!key || value == null || value === '') {
-    console.error('Usage: secrets set KEY VALUE [--canonical-clone PATH]   (use `-` as VALUE to read from stdin)');
+    console.error('Usage: secrets set KEY VALUE [--canonical-clone PATH | --no-canonical]   (use `-` as VALUE to read from stdin)');
     throw new VaultError('usage', 1);
   }
 
+  if (canonicalClone && noCanonical) {
+    console.error('Error: --canonical-clone and --no-canonical are mutually exclusive.');
+    throw new VaultError('mutually exclusive canonical flags', 1);
+  }
+
   if (value === '-') {
     const readStdin = overrides.readStdin ?? (() => readFileSync(0, 'utf-8'));
     const raw = readStdin();
@@ -79,16 +97,54 @@ export async function runSet(args, overrides = {}) {
     throw new VaultError(vaultState.reason || 'vault not initialised', vaultState.exitCode ?? 1);
   }
 
+  // Canonical-first resolution order (BEFORE any workspace write):
+  //   1. Explicit --canonical-clone PATH → wins, always. Bootstraps a
+  //      missing canonical file (matches the flag's historical behaviour).
+  //   2. --no-canonical → skip canonical entirely, no notice, no discovery.
+  //   3. Scoped write (paths.scope set) → auto-discover via
+  //      resolveCanonicalCloneTarget. Hit → dual-write canonical-first,
+  //      SAME output lines as the explicit-flag path. Miss → workspace-only
+  //      PLUS a one-line stderr notice naming why nothing resolved.
+  //   4. Legacy fallback (no scope) → no canonical resolution, no notice —
+  //      legacy has no natural canonical mirror.
+  let effectiveCanonical = null;
+  let canonicalPathsFromOverride = overrides.canonicalPaths || null;
+  if (canonicalClone) {
+    effectiveCanonical = { file: canonicalClone, source: 'flag' };
+  } else if (!noCanonical && paths.scope) {
+    // Honour the paths' own `home` first — it carries the caller's
+    // injected home end-to-end so test isolation cannot leak into the
+    // real ~/stravica-canonical/ scan. Falls back to overrides.home for
+    // 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 };
+    } 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}`);
+    }
+  }
+
   // Canonical FIRST. Resolved the same way `--file` already works for
   // every other scope-aware command — an arbitrary path, its own
   // .sops.yaml expected alongside it, reusing THIS host's key material
   // (same recipients in practice for a workspace/canonical-clone pair).
   // Any failure here (existing canonical store undecryptable, sops
   // encrypt failure) throws and propagates straight out of runSet —
-  // the workspace write below is never reached.
-  if (canonicalClone) {
-    const canonicalPaths = overrides.canonicalPaths || resolveScopePaths({
-      file: canonicalClone,
+  // the workspace write below is never reached. Ordering pinned by
+  // canonical-clone.test.mjs — do not reorder.
+  if (effectiveCanonical) {
+    const canonicalPaths = canonicalPathsFromOverride || resolveScopePaths({
+      file: effectiveCanonical.file,
       keyDir: paths.keyDir,
       keyFile: paths.keyFile,
     });

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

@@ -165,6 +165,11 @@ export function defaultPaths(overrides = {}) {
     sopsConfig: join(vaultDir, '.sops.yaml'),
     keyDir,
     keyFile: join(keyDir, 'age-key.txt'),
+    // Retained on the paths object so downstream consumers (canonical-
+    // clone auto-discovery in commands/set.mjs) can honour the SAME home
+    // the caller injected, instead of falling back to the real user's
+    // homedir() and cross-contaminating test isolation.
+    home,
   };
 }
 
@@ -220,6 +225,7 @@ export function resolveScopePaths(opts = {}) {
       scope: opts.scope ?? null,
       scoped: true,
       layout: 'file',
+      home,
     };
   }
 
@@ -260,6 +266,7 @@ export function resolveScopePaths(opts = {}) {
       scope: opts.scope,
       scoped: true,
       layout: 'workspace',
+      home,
     };
   }
 
@@ -275,6 +282,7 @@ export function resolveScopePaths(opts = {}) {
       scope: opts.scope,
       scoped: true,
       layout: 'canonical',
+      home,
     };
   }
 
@@ -332,6 +340,138 @@ function readDefaultsDefaultScope(home) {
   }
 }
 
+// ── Canonical-clone target resolution (set only) ─────────────────────
+//
+// When `set` runs on a scoped vault WITHOUT --canonical-clone (and WITHOUT
+// --no-canonical), auto-discover the canonical clone's vault file for the
+// resolved scope. Resolution order (each tier tried in turn, first hit
+// wins; every miss recorded in `tried` for the absence-notice detail):
+//
+//   1. "canonicalClone" in ~/.config/stravica-pa/defaults.json — two
+//      shapes supported:
+//        - object (scope → file map):
+//            { "canonicalClone": { "seo-ops": "/abs/path/seo-ops.enc.json" } }
+//        - string (root dir): derives <root>/vault/<scope>.enc.json:
+//            { "canonicalClone": "/Users/thefoot/stravica-canonical/stravica-operator-barry" }
+//      This CLI never writes defaults.json.
+//   2. Estate convention discovery under ~/stravica-canonical/*/vault/
+//      <scope>.enc.json — the ~/stravica-canonical/ layout is the
+//      established root for canonical clones on every host (see
+//      library-sync-cycle's default --repos-root, dex-cutover-driver's
+//      reposRoot, and the routine references across projects/). Exactly
+//      one match wins; zero matches or multiple matches skips this tier
+//      (multiple is recorded as ambiguity so the notice explains WHY the
+//      auto-write did not happen).
+//
+// A resolved-but-nonexistent file (config points at a path that isn't
+// there) is treated as a miss with a `tried` line, not a bootstrap — the
+// auto-write path only ever writes to canonicals that already exist.
+// Explicit --canonical-clone still bootstraps missing files (it always did).
+
+function readDefaultsCanonicalClone(home) {
+  const file = defaultsFilePath(home);
+  if (!existsSync(file)) return { file, shape: null, value: null, reason: 'file not present' };
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(file, 'utf-8'));
+  } catch {
+    return { file, shape: null, value: null, reason: 'file is not valid JSON' };
+  }
+  if (!parsed || typeof parsed !== 'object' || !('canonicalClone' in parsed)) {
+    return { file, shape: null, value: null, reason: 'canonicalClone key not set' };
+  }
+  const v = parsed.canonicalClone;
+  if (typeof v === 'string' && v.trim() !== '') {
+    return { file, shape: 'root', value: resolve(v.trim()), reason: null };
+  }
+  if (v && typeof v === 'object' && !Array.isArray(v)) {
+    return { file, shape: 'map', value: v, reason: null };
+  }
+  return { file, shape: null, value: null, reason: 'canonicalClone must be a non-empty string or a scope→file object' };
+}
+
+// Directory scan for the estate convention: ~/stravica-canonical/<repo>/
+// vault/<scope>.enc.json (glob-shape ~/stravica-canonical/*/vault/…enc.json;
+// slash-star notation avoided in this comment because JSDoc closes on */).
+// Returns { file, source, detail } on exactly-one hit, or
+// { file: null, reason } describing the miss (none / ambiguous / root
+// absent / unreadable). Never throws — a scan failure is a miss, not a
+// secrets-set failure.
+function discoverConventionalCanonical(home, scope) {
+  const root = join(home, 'stravica-canonical');
+  if (!existsSync(root)) {
+    return { file: null, reason: `no ${root} directory` };
+  }
+  let entries;
+  try {
+    entries = readdirSync(root, { withFileTypes: true });
+  } catch (err) {
+    return { file: null, reason: `${root} unreadable (${err && err.code ? err.code : 'error'})` };
+  }
+  const hits = [];
+  for (const ent of entries) {
+    if (!ent.isDirectory()) continue;
+    const candidate = join(root, ent.name, 'vault', `${scope}.enc.json`);
+    if (existsSync(candidate)) hits.push(candidate);
+  }
+  if (hits.length === 1) {
+    return { file: hits[0], source: 'convention', detail: `~/stravica-canonical/*/vault/${scope}.enc.json` };
+  }
+  if (hits.length === 0) {
+    return { file: null, reason: `no ~/stravica-canonical/*/vault/${scope}.enc.json` };
+  }
+  return { file: null, reason: `ambiguous — ${hits.length} matches under ~/stravica-canonical: ${hits.join(', ')}` };
+}
+
+/**
+ * Resolve the canonical clone's vault file for `scope`. Returns
+ *   { file, source, detail, tried }  on hit  — file is an absolute path,
+ *                                             source is 'defaults-map' |
+ *                                             'defaults-root' | 'convention'.
+ *   { file: null, tried }             on miss — tried is a list of the
+ *                                             per-tier miss reasons, in
+ *                                             priority order.
+ * Never throws. Never a failure — absence is a notice case, not an error.
+ * Scope is required; callers must not invoke this on the legacy vault
+ * fall-through (no scope → no natural canonical mirror).
+ */
+export function resolveCanonicalCloneTarget(opts = {}) {
+  const home = opts.home ?? homedir();
+  const scope = opts.scope;
+  const tried = [];
+  if (!scope) return { file: null, tried: ['no scope resolved (legacy fallback)'] };
+
+  const defaults = readDefaultsCanonicalClone(home);
+  if (defaults.shape === 'map') {
+    const entry = defaults.value[scope];
+    if (typeof entry === 'string' && entry.trim() !== '') {
+      const file = resolve(entry.trim());
+      if (existsSync(file)) {
+        return { file, source: 'defaults-map', detail: `${defaults.file} → canonicalClone["${scope}"]`, tried };
+      }
+      tried.push(`${defaults.file} → canonicalClone["${scope}"] = ${file} (path not present)`);
+    } else {
+      tried.push(`${defaults.file} → canonicalClone map has no entry for "${scope}"`);
+    }
+  } else if (defaults.shape === 'root') {
+    const file = join(defaults.value, 'vault', `${scope}.enc.json`);
+    if (existsSync(file)) {
+      return { file, source: 'defaults-root', detail: `${defaults.file} → canonicalClone root ${defaults.value}`, tried };
+    }
+    tried.push(`${defaults.file} → canonicalClone root ${defaults.value} → ${file} (path not present)`);
+  } else {
+    tried.push(`${defaults.file} canonicalClone: ${defaults.reason}`);
+  }
+
+  const conv = discoverConventionalCanonical(home, scope);
+  if (conv.file) {
+    return { file: conv.file, source: conv.source, detail: conv.detail, tried };
+  }
+  tried.push(`convention: ${conv.reason}`);
+
+  return { file: null, tried };
+}
+
 /**
  * Walk up from `cwd` for the nearest ancestor directory that sits under
  * an "agents" path segment AND contains identity.json. Returns the file

package/package.json

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