@stravica-ai/digital-operator-pa 0.1.53 → 0.1.55

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

@@ -20,7 +20,7 @@
 import { readFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { homedir } from 'node:os';
+import { resolveHome } from '../../../engineering-pa-core/src/home/resolve.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const CORE_CONFIG_PATH = resolve(__dirname, '..', '..', 'config', 'coordinator-allowlist.json');
@@ -98,7 +98,7 @@ export function mergeOverlay(config, overlay, warnings = []) {
  * lives at `.claude/coordinator-overlay.json` under that directory.
  */
 export function overlayPaths({ repoRoot, cwd, env = process.env }) {
-  const home = env.HOME || homedir();
+  const home = resolveHome({ env });
   const workspaceBase = repoRoot || cwd;
   return {
     home: home ? join(home, '.claude', 'coordinator-overlay.json') : null,

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

@@ -6,11 +6,12 @@
 import { execFile } from 'node:child_process';
 import { existsSync, readdirSync, statSync, readFileSync } from 'node:fs';
 import { promisify } from 'node:util';
-import { arch, platform, release, homedir } from 'node:os';
+import { arch, platform, release } 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';
+import { resolveWorkspace as coreResolveWorkspace } from '../../../engineering-pa-core/src/workspace/resolve.mjs';
 
 const execFileP = promisify(execFile);
 
@@ -204,45 +205,33 @@ async function withTimeout(promise, ms) {
 }
 
 /**
- * Workspace port + reachability. Reads port from operator preferences if
- * present; probes with a TCP connect (fast — no HTTP round-trip). Timeout
- * capped at 1s.
+ * Workspace port + identity, resolved through the ONE shared resolver
+ * in @stravica-ai/engineering-pa-core/src/workspace/resolve.mjs (0.1.54
+ * fix, w-2026-09-21-dave-002, F6/F7b). The 0.1.53 probe read a bare TCP
+ * connect on the default port and called any accepting listener
+ * `running` — which reported Docker on 4200 as our workspace and made
+ * every viewer link the PA handed out wrong. The shared resolver reads
+ * the persisted `workspacePort`, honours the running-port pidfile, and
+ * identifies the incumbent via `/__api/identity` before reporting
+ * `running`.
  */
 export async function probeWorkspace(repoRoot) {
-  const port = readWorkspacePort(repoRoot);
-  const net = await import('node:net');
-  const running = await new Promise((res) => {
-    const socket = new net.Socket();
-    let done = false;
-    const finish = (value) => {
-      if (done) return;
-      done = true;
-      try { socket.destroy(); } catch { /* ignore */ }
-      res(value);
-    };
-    socket.setTimeout(1000);
-    socket.once('connect', () => finish(true));
-    socket.once('error', () => finish(false));
-    socket.once('timeout', () => finish(false));
-    socket.connect(port, '127.0.0.1');
-  });
+  const resolved = await coreResolveWorkspace({ repoRoot });
   return {
-    port,
-    running,
-    url: `http://localhost:${port}`,
+    port: resolved.effectivePort,
+    configuredPort: resolved.configuredPort,
+    runningPort: resolved.runningPort,
+    // Legacy boolean kept for callers that still read `running`. True
+    // only when identity matched — a foreign process on the port is
+    // never running as far as this probe is concerned.
+    running: resolved.state === 'running',
+    state: resolved.state,
+    identity: resolved.identity,
+    detail: resolved.detail,
+    url: resolved.url,
   };
 }
 
-function readWorkspacePort(repoRoot) {
-  try {
-    const prefs = readPreferencesSync(repoRoot);
-    if (prefs && typeof prefs.workspacePort === 'number') return prefs.workspacePort;
-  } catch {
-    // fall through
-  }
-  return 4200;
-}
-
 /**
  * Working directory + project root resolution. Search-upward for an
  * `agents/<name>/CLAUDE.md` marker or a `.git` ancestor. Env var override

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

@@ -17,6 +17,10 @@ import {
 } 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 {
+  resolveWorkspace as coreResolveWorkspace,
+  formatIncumbentClause,
+} from '../../../engineering-pa-core/src/workspace/resolve.mjs';
 import { resolveDefaultScope } from '../secrets/vault.mjs';
 import { main as runMigrateInspect } from '../../../engineering-pa-migrate-inspect/src/cli.mjs';
 import { doOnboard } from './onboard.mjs';
@@ -63,6 +67,34 @@ export async function main(argv) {
     return 0;
   }
 
+  // 0.1.55 item 4 (w-2026-09-21-dave-004): `pa --version` / `pa -v`
+  // prints the installed package version. Before this landing there
+  // was no way to ask an installed CLI which version it was, so the
+  // 0.1.54 sweep had to `cat node_modules/.../package.json` by hand.
+  if (argv[0] === '--version' || argv[0] === '-v') {
+    const { readFile } = await import('node:fs/promises');
+    const { fileURLToPath } = await import('node:url');
+    const { dirname: dn, join: jn } = await import('node:path');
+    try {
+      // packages/cli/src/pa/cli.mjs -> ../../..(three-up)/package.json
+      // works in-repo. The installed tarball layout resolves the
+      // package.json via the exports map added in this same release.
+      let pkgJson;
+      try {
+        pkgJson = await import('@stravica-ai/digital-operator-pa/package.json', { with: { type: 'json' } });
+      } catch {
+        const here = dn(fileURLToPath(import.meta.url));
+        const local = jn(here, '..', '..', '..', 'engineering-pa', 'package.json');
+        pkgJson = { default: JSON.parse(await readFile(local, 'utf8')) };
+      }
+      process.stdout.write((pkgJson.default?.version || 'unknown') + '\n');
+      return 0;
+    } catch (e) {
+      process.stderr.write(`[pa] failed to resolve version: ${e?.message || e}\n`);
+      return 1;
+    }
+  }
+
   const verb = argv[0];
   const rest = argv.slice(1);
 
@@ -184,23 +216,32 @@ 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.
+  // 0.1.54 (w-2026-09-21-dave-002, A2/A3): resolved through the ONE
+  // shared workspace resolver in core/workspace/resolve.mjs so `pa
+  // status`, `pa environment` and `pa workspace start`'s auto-probe
+  // all report the same fact. The 0.1.53 F1 finding — the "nothing of
+  // yours to reclaim" clause landed only on `workspace start`'s
+  // hard-fail branch and never on `pa status` — is closed by rendering
+  // the clause here whenever the incumbent is not ours.
   out.write('\nWorkspace:\n');
-  const runningPort = readRunningWorkspacePort(repoRoot);
-  const effectivePort = runningPort ?? workspacePort;
-  const probeUrl = `http://localhost:${effectivePort}/__api/identity`;
-  const reachability = await probeWorkspace(probeUrl, opts.fetchImpl);
+  const resolved = await coreResolveWorkspace({ repoRoot, fetchImpl: opts.fetchImpl });
+  const probeUrl = `${resolved.url}/__api/identity`;
   out.write(`  ${probeUrl}\n`);
-  if (runningPort !== null && runningPort !== workspacePort) {
-    out.write(`  running port: ${runningPort} (configured: ${workspacePort})\n`);
+  if (resolved.runningPort !== null && resolved.runningPort !== resolved.configuredPort) {
+    out.write(`  running port: ${resolved.runningPort} (configured: ${resolved.configuredPort})\n`);
   }
-  out.write(`  status: ${reachability.status}`);
-  if (reachability.detail) out.write(` (${reachability.detail})`);
+  const statusLabel = resolved.state === 'running'
+    ? 'reachable'
+    : resolved.state === 'other-process'
+      ? 'in use by another process'
+      : 'not running';
+  out.write(`  status: ${statusLabel}`);
+  if (resolved.detail) out.write(` (${resolved.detail})`);
   out.write('\n');
+  const incumbent = formatIncumbentClause(resolved);
+  if (incumbent) {
+    out.write(`  Note: ${incumbent}.\n`);
+  }
   // Workspace-not-running is OK — operators may run pa status before
   // starting the workspace server.
 
@@ -323,48 +364,27 @@ function resolveWorkspacePort(repoRoot, opts = {}) {
  * (see packages/workspace/src/api.mjs). Any other body on the port means
  * the port is bound by an unrelated process, not our workspace.
  */
-const WORKSPACE_IDENTITY_SERVER = 'digital-operator-pa-workspace';
+import { probeWorkspaceIdentity, WORKSPACE_IDENTITY_SERVER as CORE_WORKSPACE_IDENTITY_SERVER } from '../../../engineering-pa-core/src/workspace/resolve.mjs';
+const WORKSPACE_IDENTITY_SERVER = CORE_WORKSPACE_IDENTITY_SERVER;
 
+/**
+ * Legacy signature retained for existing tests. All new callers go via
+ * `coreResolveWorkspace` in packages/core/src/workspace/resolve.mjs.
+ * The `{status, detail}` shape is preserved for the WSD-laptop probe
+ * tests; internally it delegates to the shared identity probe.
+ */
 async function probeWorkspace(url, fetchImpl) {
-  const fetchFn = fetchImpl ?? globalThis.fetch;
-  if (typeof fetchFn !== 'function') {
-    return { status: 'error', detail: 'fetch unavailable' };
+  const probe = await probeWorkspaceIdentity(url, { fetchImpl });
+  if (probe.state === 'running') {
+    return { status: 'reachable', detail: probe.detail };
   }
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), 1500);
-  try {
-    const res = await fetchFn(url, { signal: controller.signal });
-    // Any HTTP response has to be positively identified as OUR workspace
-    // before the probe reports "reachable". WSD-laptop cold install of
-    // 0.1.41 (2026-09-16): a docker container bound to :4200 answered
-    // /__api/identity with HTTP 404 and `pa status` reported the
-    // workspace "reachable (HTTP 404)". Identity-gate the probe so a
-    // foreign process on the port surfaces as "in use by another
-    // process" instead of a false green.
-    if (res.status >= 200 && res.status < 500) {
-      let body = null;
-      try {
-        body = await res.json();
-      } catch { /* not JSON — falls through to the identity-mismatch branch */ }
-      if (body && body.server === WORKSPACE_IDENTITY_SERVER) {
-        return { status: 'reachable', detail: `HTTP ${res.status}` };
-      }
-      return {
-        status: 'in use by another process',
-        detail: `HTTP ${res.status}, /__api/identity did not identify as ${WORKSPACE_IDENTITY_SERVER}`,
-      };
-    }
-    return { status: 'error', detail: `HTTP ${res.status}` };
-  } catch (e) {
-    // ECONNREFUSED / abort / DNS — server is not running.
-    const code = e && (e.cause?.code || e.code);
-    if (code === 'ECONNREFUSED' || code === 'ENOTFOUND' || e?.name === 'AbortError') {
-      return { status: 'not running', detail: null };
-    }
-    return { status: 'error', detail: e?.message || String(e) };
-  } finally {
-    clearTimeout(timer);
+  if (probe.state === 'other-process') {
+    return { status: 'in use by another process', detail: probe.detail };
+  }
+  if (probe.detail === null) {
+    return { status: 'not running', detail: null };
   }
+  return { status: probe.detail && probe.detail.startsWith('HTTP') ? 'error' : 'error', detail: probe.detail };
 }
 
 export { doStatus, probeWorkspace, resolveWorkspacePort };

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

@@ -17,6 +17,7 @@ import { writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import { getRepoRoot } from './repo-root.mjs';
+import { findRepoRootSync } from '../../../engineering-pa-core/src/instance-root/find.mjs';
 import { readJson, writeJson, ensureDir, listSubdirs, today } from './io.mjs';
 import { addDoc, removeDocByPath, setDocStatus, DEFAULT_GROUP, VALID_DOC_STATUSES } from './doc-groups.mjs';
 import { normaliseDocPath } from './doc-path.mjs';
@@ -111,6 +112,12 @@ export async function createProject(opts) {
   validateCategory(opts.category);
   validatePriority(opts.priority);
 
+  // 0.1.55 F1: refuse a project create from outside any operator instance
+  // with the strict findRepoRootSync error (exit 2, message naming the
+  // start directory and the markers walked). Keeps the failure shape
+  // aligned with pa work create and the scaffold write paths.
+  findRepoRootSync({ strict: true });
+
   const repoRoot = await getRepoRoot();
   const projDir = join(repoRoot, 'projects', opts.id);
   const projectJsonPath = join(projDir, 'project.json');

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

@@ -126,8 +126,34 @@ async function readPreferencesPaName() {
   }
 }
 
+// 0.1.55 item 4 (w-2026-09-21-dave-004): refuse unknown flags loudly.
+// The pre-0.1.55 parser silently dropped anything not consumed downstream,
+// so a typo like `--status` (only valid on `work status`) or an assumed
+// `--description` (there is no such flag; the field is `summary`) went
+// unnoticed and the created record was missing the value the operator
+// meant to set. Recorded as an incident in w-2026-09-21-dave-002's
+// summary.
+const CREATE_ALLOWED_FLAGS = new Set([
+  'project',
+  'title',
+  'category',
+  'priority',
+  'summary',
+  'owner',
+  'assignee',
+  'author',
+]);
+
 async function doCreate(args) {
   const { flags } = parseFlags(args);
+  const unknown = Object.keys(flags).filter((k) => !CREATE_ALLOWED_FLAGS.has(k));
+  if (unknown.length > 0) {
+    const list = unknown.map((k) => `--${k}`).join(', ');
+    const known = Array.from(CREATE_ALLOWED_FLAGS).map((k) => `--${k}`).sort().join(', ');
+    process.stderr.write(`[pa work create] unknown flag(s): ${list}\n`);
+    process.stderr.write(`  accepted flags: ${known}\n`);
+    return 1;
+  }
   const priority = flags.priority != null && flags.priority !== true
     ? Number(flags.priority)
     : null;

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

@@ -25,6 +25,7 @@ import {
   maxNForAuthorOnDate,
 } from '../../../engineering-pa-core/src/workItemId/index.mjs';
 
+import { findRepoRootSync } from '../../../engineering-pa-core/src/instance-root/find.mjs';
 import { getRepoRoot } from './repo-root.mjs';
 import {
   readJson,
@@ -128,6 +129,14 @@ export async function createWork(opts) {
   validateCategory(opts.category);
   validatePriority(opts.priority);
 
+  // 0.1.55 F1: refuse a mint from outside any operator instance BEFORE the
+  // author-token check. Pre-fix the flow bailed with the author-token error
+  // (exit 1), which read as a config problem in the caller's terminal; the
+  // real cause is that the cwd carries none of the instance markers. Strict
+  // findRepoRootSync throws with exit 2 and names both the start directory
+  // and the markers walked, matching the sibling rule in projects.mjs.
+  findRepoRootSync({ strict: true });
+
   let author;
   try {
     author = resolveAuthorToken({

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

@@ -19,7 +19,7 @@ import { runFind } from './commands/find.mjs';
 import { runVerify } from './commands/verify.mjs';
 import { resolveScopePaths, VaultError } from './vault.mjs';
 
-const HELP = `secrets — SOPS+age secrets management
+const HELP = `secrets: SOPS+age secrets management
 
 Usage:
   secrets init              Initialise the vault (generate keys, create empty secrets file).
@@ -27,7 +27,8 @@ Usage:
                              --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)
+  secrets set KEY -         Read the value from stdin. Safe form: keeps the value out of shell history and argv (0.1.54, w-2026-09-21-dave-002, D4)
+  secrets set KEY VALUE     Store or update a secret (the argv form is retained but records the value in shell history and the process listing)
                              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
@@ -45,7 +46,7 @@ Usage:
   secrets status            Check vault health and report key info
   secrets backup            Show QR code of master key for backup (opens browser)
   secrets vaults            List every vault visible from the workspace
-                             (scope, layout, key count, path — no decryption)
+                             (scope, layout, key count, path; no decryption)
   secrets find KEY          Report which vault(s) contain KEY by name
                              (alias: which; names/paths only, never values;
                               exits 1 when not found)
@@ -53,7 +54,7 @@ Usage:
                              Byte-level comparison of DECRYPTED values
                              between this vault and a reference vault at
                              <path>. Reports per-key same/differs/missing.
-                             --values is required — decrypt-only is never
+                             --values is required; decrypt-only is never
                              a valid pass (see below). Never prints values.
 
 Age private key resolution (0.1.51, w-2026-09-18-dave-007). One shared
@@ -75,13 +76,13 @@ SOPS config:      .vault/.sops.yaml           (committed to repo)
 Workspace resolution (all verbs), in order:
   1. Walk up from the current directory for a vault-bearing workspace
      (.vault/ or vault/*.enc.json). A git repo WITHOUT a vault does not
-     stop resolution — it falls through to the next tiers with a stderr
+     stop resolution; it falls through to the next tiers with a stderr
      notice naming the store actually targeted.
   2. $DAVE_ROOT (or $DAVE_REPO_ROOT / $PA_REPO_ROOT).
   3. "workspaceRoot" in ~/.config/stravica-pa/defaults.json (written by
      you or provisioning; the CLI never creates it).
   4. Error listing what was tried.
-  NOTE: this precedence is a change — the environment variable used to be
+  NOTE: this precedence is a change; the environment variable used to be
   checked BEFORE the directory walk. Standing inside a workspace now
   always targets THAT workspace, even when $DAVE_ROOT points elsewhere.
   Exception: 'secrets init' inside a vault-less git repo initialises the
@@ -93,7 +94,7 @@ Scoped vaults:
                              up to the repo root and checking, in order:
                                .vault/scopes/NAME.enc.json   (workspace layout)
                                vault/NAME.enc.json           (canonical layout)
-                             Both present is an error — pass --file to
+                             Both present is an error; pass --file to
                              disambiguate. Supported on: get, set, list,
                              delete, rotate, status, vaults, find.
   --file PATH                Bypass scope resolution and operate directly on
@@ -145,38 +146,38 @@ Default scope (get/set only, when neither --scope nor --file is given):
   in order:
     1. $SECRETS_DEFAULT_SCOPE env var.
     2. "defaultScope" in ~/.config/stravica-pa/defaults.json (same file
-       as "workspaceRoot" above; written by you or provisioning — the
+       as "workspaceRoot" above; written by you or provisioning; the
        CLI never creates it).
     3. The calling PA's own agents/<name>/identity.json "defaultScope"
        field, found by walking up from the current directory (or, for
        Dave specifically, $DAVE_ROOT/agents/dave/identity.json). A
        malformed identity.json is a stderr warning, not a crash.
-    4. Legacy fallback: the single-file .vault/ vault — the notice says
+    4. Legacy fallback: the single-file .vault/ vault; the notice says
        so explicitly ("no scope specified and no default configured").
   Example notices:
     note: writing to 'hq-estate' pot (default from SECRETS_DEFAULT_SCOPE env var)
     note: writing to 'wsd' pot (default from /home/dex/agents/barry/dex/identity.json)
-    note: writing to '(legacy)' pot — no scope specified and no default configured. Use --scope <name> or configure a default.
+    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-first dual-write is DEFAULT for scoped writes since 0.1.20 —
+  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:
+    2. "canonicalClone" in ~/.config/stravica-pa/defaults.json, in one of two shapes:
          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
+  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
+  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
@@ -187,13 +188,13 @@ Canonical-first writes (set only):
 Value-compare verification:
   secrets verify --values --against <path>
     Decrypts BOTH the resolved vault and the vault at <path>, then
-    compares every key's VALUE byte-for-byte — never decrypt-only. A
+    compares every key's VALUE byte-for-byte; never decrypt-only. A
     vault clobbered by an always-take-canonical materialisation still
     decrypts cleanly with placeholder/stale values (same recipients);
     only a value comparison against a known-good reference catches that.
     Reports per-key same/differs/missing-in-working/missing-in-reference.
     Exits 2 if any key differs or is missing on either side. Never
-    prints a decrypted value — only the comparison result per key name.
+    prints a decrypted value; only the comparison result per key name.
 `;
 
 const USAGE = `Usage: secrets {init|get|set|list|delete|rotate|status|backup|vaults|find|verify} [KEY] [VALUE]
@@ -201,6 +202,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 -         Read the value from stdin (safe form; 0.1.54)
   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

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

@@ -30,7 +30,12 @@ export async function runGet(args, overrides = {}) {
   // resolveCommandPaths prints the interim stderr notice (naming the
   // target vault) whenever --scope/--file wasn't given upstream in
   // cli.mjs. See vault.mjs's default-scope resolution section.
-  const paths = resolveCommandPaths(overrides);
+  //
+  // 0.1.54 fix (w-2026-09-21-dave-002, D4): suppress the legacy-pot
+  // notice on value-blind reads. `--exists` is scripted-friendly and
+  // an interactive operator running `get KEY --exists` doesn't need
+  // the routing tip on every call.
+  const paths = resolveCommandPaths({ ...overrides, suppressLegacyNotice: exists });
   const key = rest[0];
 
   if (!key) {

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

@@ -65,7 +65,7 @@ export async function runSet(args, overrides = {}) {
   let value = rest[1];
 
   if (!key || value == null || value === '') {
-    console.error('Usage: secrets set KEY VALUE [--canonical-clone PATH | --no-canonical]   (use `-` as VALUE to read from stdin)');
+    console.error('Usage: secrets set KEY - [--canonical-clone PATH | --no-canonical]   (reads the value from stdin; the safe form)\n       secrets set KEY VALUE [--canonical-clone PATH | --no-canonical]   (records the value in shell history and argv)');
     throw new VaultError('usage', 1);
   }
 
@@ -82,7 +82,7 @@ export async function runSet(args, overrides = {}) {
     // legitimately contains it.
     value = raw.replace(/\r?\n$/, '');
     if (value === '') {
-      console.error('Empty value on stdin — refusing to store an empty secret.');
+      console.error('Empty value on stdin; refusing to store an empty secret.');
       throw new VaultError('empty stdin', 1);
     }
   }
@@ -184,7 +184,7 @@ export async function runSet(args, overrides = {}) {
         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}`);
+        console.error(`notice: no canonical clone configured for scope '${paths.scope}' on this host; workspace-only write${tail}`);
       }
     }
   }

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

@@ -13,6 +13,7 @@ import {
   sopsConfigExists,
   sopsDecrypt,
 } from '../vault.mjs';
+import { resolveKeyFile as coreResolveKeyFile } from '../../../../engineering-pa-core/src/vault/require.mjs';
 
 async function printDepVersions() {
   console.log('');
@@ -42,6 +43,22 @@ export async function runStatus(overrides = {}) {
   console.log('============');
   console.log('');
 
+  // 0.1.54 (w-2026-09-21-dave-002, A1 diagnostic): print the resolver
+  // datapoint on one line so anyone hitting a decrypt-failure has the
+  // resolved keyFile + source + mode value-blind. Barry ruling
+  // 2026-09-21 (post-QA): the secrets surfaces make the datapoint
+  // visible without asking; the F4 root cause is only findable when
+  // every failing host reports the same shape.
+  try {
+    const keyResolved = coreResolveKeyFile({
+      repoRoot: paths.root,
+      home: paths.home,
+      env: {},
+      mode: 'auto',
+    });
+    console.log(`Key resolver: ${keyResolved.keyFile}  (source: ${keyResolved.source}, mode: ${keyResolved.mode})`);
+  } catch { /* non-fatal; render nothing */ }
+
   // Private key
   if (keyFileExists(paths)) {
     console.log(`Private key: ${paths.keyFile} (present)`);