@stravica-ai/digital-operator-pa 0.1.41 → 0.1.43

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

@@ -205,6 +205,13 @@ function resolveWorkspacePort(repoRoot, opts = {}) {
   return 4200;
 }
 
+/**
+ * The `server` field the workspace's own /__api/identity endpoint returns
+ * (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';
+
 async function probeWorkspace(url, fetchImpl) {
   const fetchFn = fetchImpl ?? globalThis.fetch;
   if (typeof fetchFn !== 'function') {
@@ -214,8 +221,25 @@ async function probeWorkspace(url, fetchImpl) {
   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) {
-      return { status: 'reachable', detail: `HTTP ${res.status}` };
+      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) {

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

@@ -35,6 +35,7 @@ import {
   sopsEncryptScoped,
   VaultError,
 } from '../vault.mjs';
+import { runInit } from './init.mjs';
 
 // --canonical-clone / --no-canonical may appear anywhere in argv, matching
 // the --scope/--file convention in cli.mjs. Local to `set` (not global
@@ -91,7 +92,41 @@ export async function runSet(args, overrides = {}) {
     throw new VaultError('missing dependencies', 1);
   }
 
-  const vaultState = checkVault(paths);
+  let vaultState = checkVault(paths);
+  // Self-init on `secrets set` when the legacy vault has not been
+  // initialised on this host yet. WSD-laptop cold install of 0.1.41
+  // (2026-09-16): the onboarding guide's Atlassian setup asks the
+  // colleague to run three `secrets set` commands, and the first one
+  // died with `Error: No recipients file at .vault/recipients.txt —
+  // Run 'secrets init' to set up the vault.` The guide's two-step
+  // Atlassian setup never named that mandatory extra step. `set` now
+  // runs the same `runInit()` code path in-process before the first
+  // write when the vault is uninitialised, emitting one stderr notice
+  // so the operator can see what happened.
+  //
+  // The self-init fires only when it is SAFE — the legacy (non-scoped)
+  // vault, no encrypted store already on disk (otherwise a fresh key
+  // would orphan the existing contents; that failure mode still surfaces
+  // as `missing-key` exit 2 with the "restore your key from backup"
+  // guidance). `missing-recipients` on a solo host is always safe (a
+  // present store with no recipients file would already have failed
+  // decryption elsewhere; the case the WSD laptop hit was "no vault at
+  // all yet"). `missing-key` on a solo host is also safe when the
+  // encrypted store is absent — pure first-run state. Scoped vaults
+  // (`paths.scoped`) are provisioned by scope-registration tooling and
+  // are never self-inited here; a `secrets set --scope <name>` against
+  // a missing scope surfaces the not-provisioned error unchanged.
+  const canSelfInit = !vaultState.ok
+    && !paths.scoped
+    && (vaultState.reason === 'missing-recipients' || vaultState.reason === 'missing-key')
+    && !secretsFileExists(paths);
+  if (canSelfInit) {
+    console.error(
+      `notice: no vault at ${paths.vaultDir}: self-initialising before first write (equivalent to running \`secrets init\`).`,
+    );
+    await runInit({ paths });
+    vaultState = checkVault(paths);
+  }
   if (!vaultState.ok) {
     console.error(vaultState.message);
     throw new VaultError(vaultState.reason || 'vault not initialised', vaultState.exitCode ?? 1);

package/dist/engineering-pa-core/src/distill/run.mjs

@@ -32,7 +32,7 @@
 //   omitted on `ok`. `log` is null on exits that happened before the
 //   per-run log file was created.
 
-import { appendFile, readFile } from 'node:fs/promises';
+import { appendFile, readFile, unlink } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 
 import { resolvePrereqs } from './prereqs.mjs';
@@ -211,7 +211,21 @@ export async function runDistill({
   log(`distillation OK (${durationSec}s) — log: ${runLogPath}`, { stderr });
   log('changes (if any) will be committed by the next sync run', { stderr });
 
-  // Step 4 — append success audit. Sync will pick up any file changes
+  // Step 4a — invalidate the retrieval artefacts so the next
+  // `pa knowledge` call rebuilds them and sees any doc the librarian just
+  // promoted. Macbook re-proof of 0.1.41 (2026-09-16): on a solo install
+  // there is no `library-sync-cycle:graph-rebuild` leg running behind the
+  // scenes, so a distilled knowledge doc stayed invisible to
+  // `pa knowledge search` until `.graph.json` was deleted by hand. Delete
+  // is safer than in-process rebuild here: the retrieval loader in
+  // `packages/cli/src/knowledge/graph.mjs` already self-heals on a
+  // missing artefact (`loadGraph:on-demand`), and a full-mode host has
+  // its scheduled graph-rebuild leg rebuild both files on the next cycle
+  // regardless. Both are untracked per the 2026-07-29 per-device ruling,
+  // so a deletion at commit time is invisible to git.
+  await invalidateRetrievalArtefacts(repoRoot, stderr);
+
+  // Step 4b — append success audit. Sync will pick up any file changes
   // the librarian produced on its next 30-minute tick.
   await writeAudit(runsLog, {
     ts: tsIso,
@@ -224,6 +238,35 @@ export async function runDistill({
   return 0;
 }
 
+/**
+ * Delete `operator/knowledge/.graph.json` and `.backlinks.json` under
+ * `root` if they exist. Missing files are a no-op; any other error is
+ * swallowed with a stderr note so a stale artefact never masks an
+ * otherwise-successful distillation exit code. Exported for tests.
+ */
+export async function invalidateRetrievalArtefacts(root, stderr = process.stderr) {
+  const targets = [
+    join(root, 'operator', 'knowledge', '.graph.json'),
+    join(root, 'operator', 'knowledge', '.backlinks.json'),
+  ];
+  const removed = [];
+  for (const path of targets) {
+    try {
+      await unlink(path);
+      removed.push(basename(path));
+    } catch (e) {
+      if (e && e.code === 'ENOENT') continue;
+      log(`warning: failed to invalidate ${basename(path)}: ${e.message}`, { stderr });
+    }
+  }
+  if (removed.length > 0) {
+    log(
+      `invalidated retrieval artefacts (${removed.join(', ')}); pa knowledge rebuilds on demand`,
+      { stderr },
+    );
+  }
+}
+
 function isoCompactForSession(d) {
   // Matches the historical `$(date -u +%Y%m%d-%H%M)` shape used pre-Node.
   const pad = (n) => String(n).padStart(2, '0');

package/dist/engineering-pa-core-extensions-atlassian/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/engineering-pa-core-extensions-atlassian",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Atlassian (Jira, Confluence, confluence-fetch) CLIs and library surface. Promoted into core for the alpha solo scaffold.",
   "type": "module",
   "main": "./index.mjs",

package/dist/engineering-pa-core-extensions-atlassian/src/confluence/client.mjs

@@ -9,6 +9,7 @@
 // Zero external dependencies - uses Node.js built-in fetch() and child_process.
 
 import { loadAtlassianCredentials } from '../common/secrets.mjs';
+import { readBody, formatHttpError } from '../jira/client.mjs';
 
 // ---- Exit-code-aware error ----------------------------------------------
 
@@ -145,33 +146,12 @@ export function createClient(options = {}) {
       // Parse response
       let data = null;
       if (res.status !== 204) {
-        const contentType = res.headers.get('Content-Type') || '';
-        if (contentType.includes('application/json')) {
-          data = await res.json();
-        } else {
-          const text = await res.text();
-          if (text) data = text;
-        }
+        data = await readBody(res);
       }
 
       // 4xx errors
       if (res.status >= 400) {
-        const msgs = [];
-        if (data && data.errorMessages) msgs.push(...data.errorMessages);
-        if (data && data.errors) {
-          if (Array.isArray(data.errors)) {
-            for (const e of data.errors) {
-              msgs.push(e.title || e.message || JSON.stringify(e));
-            }
-          } else {
-            for (const [field, msg] of Object.entries(data.errors)) {
-              msgs.push(`${field}: ${msg}`);
-            }
-          }
-        }
-        if (data && data.message) msgs.push(data.message);
-        const detail = msgs.length > 0 ? msgs.join('; ') : `HTTP ${res.status}`;
-        throw new ConfluenceError(`Confluence API error (${res.status}): ${detail}`, 2);
+        throw new ConfluenceError(formatHttpError('Confluence', res.status, data), 2);
       }
 
       return { status: res.status, data, headers: res.headers };

package/dist/engineering-pa-core-extensions-atlassian/src/jira/client.mjs

@@ -17,6 +17,71 @@ export class JiraError extends Error {
   }
 }
 
+// ---- Shared response parsing --------------------------------------------
+
+/**
+ * Read a fetch Response body without ever throwing on a bad body.
+ *
+ * Atlassian sometimes returns a non-JSON body (bare text, an HTML error
+ * page from Cloudflare, a proxy edge string) with a `Content-Type` that
+ * still says `application/json`, and a raw `res.json()` on that body throws
+ * `SyntaxError: Unexpected token 'C', "Client mus"... is not valid JSON`,
+ * which surfaces as an unhandled stack trace instead of an
+ * "authentication failed" message. Falls back to raw text on any parse
+ * failure and returns null for empty bodies.
+ *
+ * @param {Response} res
+ * @returns {Promise<any|string|null>}
+ */
+export async function readBody(res) {
+  const contentType = res.headers.get('Content-Type') || '';
+  const wantsJson = contentType.includes('application/json');
+  const raw = await res.text();
+  if (!raw) return null;
+  if (wantsJson) {
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return raw.trim();
+    }
+  }
+  return raw.trim();
+}
+
+/**
+ * Turn a parsed error body into a one-line, colleague-facing HTTP
+ * error message. `data` may be a parsed JSON object (Atlassian error
+ * shape), a plain string (non-JSON body), or null.
+ *
+ * @param {string} product   "Jira" or "Confluence"
+ * @param {number} status    HTTP status
+ * @param {any} data         Parsed body, string, or null
+ * @returns {string}
+ */
+export function formatHttpError(product, status, data) {
+  const parts = [];
+  if (data && typeof data === 'object') {
+    if (Array.isArray(data.errorMessages)) parts.push(...data.errorMessages);
+    if (data.errors) {
+      if (Array.isArray(data.errors)) {
+        for (const e of data.errors) {
+          parts.push(e.title || e.message || JSON.stringify(e));
+        }
+      } else if (typeof data.errors === 'object') {
+        for (const [field, msg] of Object.entries(data.errors)) {
+          parts.push(`${field}: ${msg}`);
+        }
+      }
+    }
+    if (data.message && parts.length === 0) parts.push(data.message);
+  } else if (typeof data === 'string' && data.length > 0) {
+    const trimmed = data.length > 120 ? `${data.slice(0, 120)}...` : data;
+    parts.push(trimmed);
+  }
+  const detail = parts.length > 0 ? parts.join('; ') : `HTTP ${status}`;
+  return `${product} API error (${status}): ${detail}`;
+}
+
 // ---- Credential loading -------------------------------------------------
 
 /**
@@ -142,26 +207,12 @@ export function createClient(options = {}) {
       // Parse response
       let data = null;
       if (res.status !== 204) {
-        const contentType = res.headers.get('Content-Type') || '';
-        if (contentType.includes('application/json')) {
-          data = await res.json();
-        } else {
-          const text = await res.text();
-          if (text) data = text;
-        }
+        data = await readBody(res);
       }
 
       // 4xx errors
       if (res.status >= 400) {
-        const msgs = [];
-        if (data && data.errorMessages) msgs.push(...data.errorMessages);
-        if (data && data.errors) {
-          for (const [field, msg] of Object.entries(data.errors)) {
-            msgs.push(`${field}: ${msg}`);
-          }
-        }
-        const detail = msgs.length > 0 ? msgs.join('; ') : `HTTP ${res.status}`;
-        throw new JiraError(`Jira API error (${res.status}): ${detail}`, 2);
+        throw new JiraError(formatHttpError('Jira', res.status, data), 2);
       }
 
       return { status: res.status, data, headers: res.headers };
@@ -309,19 +360,11 @@ export function createClient(options = {}) {
 
       let data = null;
       if (res.status !== 204) {
-        const contentType = res.headers.get('Content-Type') || '';
-        if (contentType.includes('application/json')) data = await res.json();
-        else { const text = await res.text(); if (text) data = text; }
+        data = await readBody(res);
       }
 
       if (res.status >= 400) {
-        const msgs = [];
-        if (data && data.errorMessages) msgs.push(...data.errorMessages);
-        if (data && data.errors) {
-          for (const [field, msg] of Object.entries(data.errors)) msgs.push(`${field}: ${msg}`);
-        }
-        const detail = msgs.length > 0 ? msgs.join('; ') : `HTTP ${res.status}`;
-        throw new JiraError(`Jira API error (${res.status}): ${detail}`, 2);
+        throw new JiraError(formatHttpError('Jira', res.status, data), 2);
       }
 
       return { status: res.status, data, headers: res.headers };

package/dist/engineering-pa-scaffold/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/engineering-pa-scaffold",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "pa-init scaffolder + onboarding flows (solo, lead, member).",
   "type": "module",
   "main": "./index.mjs",

package/dist/engineering-pa-scaffold/src/commands/init.mjs

@@ -10,9 +10,10 @@
 //
 // Errors carry an `exitCode`. The CLI translates to `process.exit`.
 
-import { resolve } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 
-import { buildPlan, buildRenderConfig } from '../generator.mjs';
+import { buildPlan, buildRenderConfig, resolveInstalledDopVersion } from '../generator.mjs';
 import {
   defaultSeam,
   promptValues,
@@ -35,7 +36,14 @@ export async function runInit(options) {
   const config = await gatherConfig(options);
 
   process.stdout.write(`\npa-init: scaffolding ${config.paName} for ${config.operatorName}\n`);
-  process.stdout.write(`         target: ${config.targetDir}\n`);
+  process.stdout.write(`         target:  ${config.targetDir}\n`);
+  // Announce the exact version pa-init pinned into the instance's
+  // package.json (or `<default>` when the resolver could not verify the
+  // installed umbrella version — dev-only edge case). This is the
+  // load-bearing signal for the "you got the right version" contract.
+  process.stdout.write(
+    `         package: @stravica-ai/digital-operator-pa@${config.pkgVersion}\n`,
+  );
 
   await assertTargetIsEmptyOrMissing(config.targetDir);
 
@@ -63,6 +71,27 @@ export async function runInit(options) {
     return 2;
   }
 
+  // Version-drift safety net (WSD-laptop cold install of 0.1.41, second-
+  // machine re-run of 0.1.42). The scaffold pins an exact version and
+  // ships a `pnpm-workspace.yaml` with `minimumReleaseAgeExclude` for
+  // this package, so pnpm should never resolve a different version, but
+  // if the guard ever misses, this prints one line naming the mismatch
+  // so a colleague can see it immediately instead of hitting a "Command
+  // X not found" on an older bin surface. Read from the SAME source
+  // `pa status` reads: the resolved package.json inside the instance's
+  // node_modules.
+  const scaffoldedVersion = config.pkgVersion;
+  const installedVersion = readInstalledDopVersion(config.targetDir);
+  if (scaffoldedVersion && installedVersion && installedVersion !== scaffoldedVersion) {
+    process.stderr.write(
+      `pa-init: WARNING - scaffold pinned @stravica-ai/digital-operator-pa@${scaffoldedVersion} `
+      + `but pnpm resolved ${installedVersion}. This usually means pnpm's `
+      + `minimumReleaseAge gate filtered the pinned version out; the shipped `
+      + `pnpm-workspace.yaml excludes @stravica-ai/digital-operator-pa from the gate `
+      + `which normally cures it. Run \`pnpm install\` inside ${config.targetDir} again to reconcile.\n`,
+    );
+  }
+
   process.stdout.write('\npa-init: running pa status …\n');
   const statusCode = await paStatus({ targetDir: config.targetDir });
   if (statusCode !== 0) {
@@ -142,6 +171,11 @@ async function gatherConfig(options) {
     operatorName: resolvedValues.operatorName,
     targetDir: resolvedValues.targetDir,
     purpose: options.purpose,
+    // Pin the EXACT version of `@stravica-ai/digital-operator-pa` that is
+    // running pa-init right now. `resolveInstalledDopVersion()` returns
+    // null when it cannot verify a version (dev-only edge case); the
+    // downstream default in `buildRenderConfig` catches that safely.
+    pkgVersion: resolveInstalledDopVersion() ?? undefined,
   });
 }
 
@@ -168,3 +202,26 @@ function applyValidatorsOrThrow(supplied) {
 function countEntries(plan) {
   return plan.length;
 }
+
+/**
+ * Read the installed version of `@stravica-ai/digital-operator-pa` from
+ * the instance's own `node_modules`. Returns null if the package is
+ * missing or its `package.json` cannot be parsed — the caller treats
+ * null as "no verifiable install" and does not warn.
+ */
+function readInstalledDopVersion(targetDir) {
+  const pkgPath = join(
+    targetDir,
+    'node_modules',
+    '@stravica-ai',
+    'digital-operator-pa',
+    'package.json',
+  );
+  if (!existsSync(pkgPath)) return null;
+  try {
+    const meta = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    return typeof meta.version === 'string' ? meta.version : null;
+  } catch {
+    return null;
+  }
+}

package/dist/engineering-pa-scaffold/src/generator.mjs

@@ -7,14 +7,92 @@
 // kind: 'dir' (mkdir -p) | 'file' (write file with contents) | 'json'
 // (stringify + write).
 
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { readFile, readdir } from 'node:fs/promises';
+import { createRequire } from 'node:module';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { emptyEnvelope, renderEnvelope } from '../../engineering-pa-core/src/autonomy/envelope.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
+const requireFromHere = createRequire(import.meta.url);
+
+/**
+ * Resolve the exact version of `@stravica-ai/digital-operator-pa` that is
+ * running `pa-init` right now. Two lookup paths:
+ *
+ *   1. `require.resolve('@stravica-ai/digital-operator-pa/package.json')` — hits
+ *      when pa-init runs out of a real installed tarball
+ *      (`node_modules/@stravica-ai/digital-operator-pa/dist/engineering-pa-scaffold/src/generator.mjs`
+ *      → `node_modules/@stravica-ai/digital-operator-pa/package.json`).
+ *   2. Sibling walk to `packages/engineering-pa/package.json` — hits when
+ *      pa-init runs out of the source monorepo (dev + CI test runs).
+ *
+ * Returns the version string, or `null` if neither path resolves. `null`
+ * is the "no verifiable version" outcome — the caller falls back to the
+ * old `^0.1.0` default so a broken lookup never breaks the scaffold.
+ *
+ * Why this exists: on the WSD-laptop cold install of 0.1.41, pnpm's
+ * default `minimumReleaseAge` gated the freshly-published tarball out of
+ * `^0.1.0` and the instance silently resolved to 0.1.39 — a version with
+ * no `jira` / `confluence` / `confluence-fetch` bins. Pinning the exact
+ * version the running scaffolder came from kills that class of drift.
+ */
+export function resolveInstalledDopVersion() {
+  // Path 1: `require.resolve` from another consumer's tree — hits when
+  // pa-init is invoked from the bootstrap dir, where the tarball sits at
+  // `node_modules/@stravica-ai/digital-operator-pa/`. The scaffold module
+  // itself lives INSIDE the tarball, so this resolve typically fails
+  // when this module runs from within `dist/engineering-pa-scaffold/`;
+  // path 3 catches that case.
+  try {
+    const pkgPath = requireFromHere.resolve('@stravica-ai/digital-operator-pa/package.json');
+    const meta = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    if (meta && typeof meta.version === 'string' && meta.version.length > 0) {
+      return meta.version;
+    }
+  } catch { /* fall through */ }
+  // Path 2: monorepo sibling walk — hits when pa-init runs directly
+  // from the source tree (dev + CI test runs). `packages/scaffold/src/`
+  // -> `packages/engineering-pa/package.json`.
+  const monorepoUmbrella = resolve(__dirname, '..', '..', 'engineering-pa', 'package.json');
+  if (existsSync(monorepoUmbrella)) {
+    try {
+      const meta = JSON.parse(readFileSync(monorepoUmbrella, 'utf8'));
+      if (meta && typeof meta.version === 'string' && meta.version.length > 0) {
+        return meta.version;
+      }
+    } catch { /* fall through */ }
+  }
+  // Path 3: packed-tarball walk — hits when this module runs from
+  // inside the umbrella tarball's dist tree. Layout is:
+  //   <install>/node_modules/@stravica-ai/digital-operator-pa/package.json  <-- want this
+  //   <install>/node_modules/@stravica-ai/digital-operator-pa/dist/engineering-pa-scaffold/src/generator.mjs
+  // Walk upwards from `__dirname` looking for a `package.json` whose
+  // `name` is `@stravica-ai/digital-operator-pa`.
+  let cursor = __dirname;
+  for (let i = 0; i < 8; i += 1) {
+    const candidate = resolve(cursor, 'package.json');
+    if (existsSync(candidate)) {
+      try {
+        const meta = JSON.parse(readFileSync(candidate, 'utf8'));
+        if (
+          meta
+          && meta.name === '@stravica-ai/digital-operator-pa'
+          && typeof meta.version === 'string'
+          && meta.version.length > 0
+        ) {
+          return meta.version;
+        }
+      } catch { /* keep walking */ }
+    }
+    const next = resolve(cursor, '..');
+    if (next === cursor) break;
+    cursor = next;
+  }
+  return null;
+}
 
 /** Path to the CLAUDE.md template (relative to this module). */
 export const CLAUDE_MD_TEMPLATE_PATH = resolve(__dirname, '..', 'templates', 'CLAUDE.md.template');
@@ -248,6 +326,47 @@ export function buildGitignore() {
   ].join('\n');
 }
 
+/**
+ * Build the instance-level `pnpm-workspace.yaml` contents.
+ *
+ * Excludes `@stravica-ai/digital-operator-pa` from pnpm's supply-chain
+ * age gate (`minimumReleaseAge`) BY NAME. Everything else the instance
+ * ever installs still honours whatever `minimumReleaseAge` the operator
+ * has set. The exclude ships instead of the older `.npmrc` line because
+ * pnpm reads `minimumReleaseAge` / `minimumReleaseAgeExclude` from
+ * `pnpm-workspace.yaml` only; `.npmrc` is not honoured for these
+ * settings (empirically verified on pnpm 10.32 against the live
+ * registry: `.npmrc @stravica-ai:minimumReleaseAge=0` did not defeat a
+ * `minimumReleaseAge=10080` set at the same scope; a
+ * `pnpm-workspace.yaml` with `minimumReleaseAgeExclude: [<pkg>]` did).
+ *
+ * Rationale from the second-machine re-run of 0.1.42 (2026-09-16): the
+ * `.npmrc` override written into the instance was a no-op, so the
+ * belt-and-brace promised alongside the exact pin never bit. This file
+ * is the real belt-and-brace: `pnpm install` inside the instance always
+ * resolves the pinned version even when the operator's pnpm carries a
+ * non-zero `minimumReleaseAge` (pnpm 11 ships one by default).
+ *
+ * The file also marks the instance as its own pnpm workspace root,
+ * which is fine: instances never nest inside another pnpm workspace
+ * (the onboarding guide's warning covers the reverse direction).
+ */
+export function buildInstanceWorkspaceYaml() {
+  return [
+    '# @stravica-ai/digital-operator-pa exclusion for pnpm supply-chain gating.',
+    '# pa-init pins the exact @stravica-ai/digital-operator-pa version in package.json,',
+    '# but pnpm\'s minimumReleaseAge (default 0 on pnpm 10, non-zero on some 11 defaults)',
+    '# can still filter that pin out during `pnpm install` and drop the instance onto a',
+    '# previous version with a different bin surface (WSD-laptop cold-install regression,',
+    '# 0.1.41 / 0.1.42). pnpm reads minimumReleaseAge only from pnpm-workspace.yaml, so',
+    '# the exclusion has to live here rather than in .npmrc.',
+    '# Non-@stravica-ai packages still honour any minimumReleaseAge set globally.',
+    'minimumReleaseAgeExclude:',
+    '  - "@stravica-ai/digital-operator-pa"',
+    '',
+  ].join('\n');
+}
+
 /**
  * Build the operator/config/preferences.json contents.
  *
@@ -546,6 +665,7 @@ export function buildPlanFromTemplates(config, templates) {
   plan.push({ kind: 'json', path: 'package.json', contents: pkg });
   plan.push({ kind: 'file', path: '.gitignore', contents: gitignore });
   plan.push({ kind: 'file', path: '.nvmrc', contents: '24\n' });
+  plan.push({ kind: 'file', path: 'pnpm-workspace.yaml', contents: buildInstanceWorkspaceYaml() });
 
   plan.push({ kind: 'json', path: '.claude/settings.json', contents: buildClaudeSettingsJson() });
   // /research slash command: rendered from the packaged core doc so the

package/docs/onboarding-solo.md

@@ -21,17 +21,44 @@ Linux and WSL are equivalent. Install Node 24 through your platform's normal cha
 
 ```sh
 mkdir ~/pa-bootstrap && cd ~/pa-bootstrap
-pnpm init -y
+# Two files, one heredoc each. `pnpm init -y` writes a `devEngines.packageManager`
+# line pnpm 11.14 then rejects, and `-y` is silently ignored, so write a minimal
+# package.json directly. The `pnpm-workspace.yaml` is the load-bearing file:
+# pnpm holds packages published in the last week back by default (the
+# `minimumReleaseAge` supply-chain gate; it defaults to 0 on pnpm 10 and to a
+# non-zero window on some pnpm 11 defaults), and this repo releases often, so
+# without an explicit exclude an unversioned `pnpm add` silently resolves down
+# to a previous version with a different bin surface. pnpm reads
+# `minimumReleaseAge*` settings ONLY from `pnpm-workspace.yaml` (not from
+# `.npmrc`), and the exclude below trusts only this one package by name so
+# every other dependency your bootstrap ever pulls still honours the operator's
+# global gate.
+cat > package.json <<'JSON'
+{ "name": "pa-bootstrap", "private": true }
+JSON
+cat > pnpm-workspace.yaml <<'YAML'
+minimumReleaseAgeExclude:
+  - "@stravica-ai/digital-operator-pa"
+YAML
 pnpm add @stravica-ai/digital-operator-pa
 pnpm exec pa-init --mode=solo --name=<pa-name> --operator=<your-name> \
   --target=$HOME/<pa-name>-instance --non-interactive
 cd $HOME/<pa-name>-instance
-pnpm install
+git config user.name  "Your Name"           # cold laptops have no global git identity
+git config user.email "you@example.com"      # local to this repo; skip if you already have a global one
 git add -A && git commit -m "scaffold"
 ```
 
 Pick a `<pa-name>` in lowercase kebab-case (`alex`, `sam`, `hal-9000`). It becomes the agent directory (`agents/<pa-name>/`) and shows up in every log line.
 
+`pa-init` writes the instance's `package.json` with an EXACT `@stravica-ai/digital-operator-pa` dependency (the version it just installed into `pa-bootstrap`, not a caret range) and drops a `pnpm-workspace.yaml` inside the instance that excludes `@stravica-ai/digital-operator-pa` from the same age gate. Together they belt-and-brace pnpm's supply-chain gate: without them a freshly-published tarball can silently resolve down to the previous version, which may ship a different bin surface.
+
+**Sanity check the version.** `pa-init` prints `package: @stravica-ai/digital-operator-pa@<version>` right after the target line. If the version you see is older than the one `npm view @stravica-ai/digital-operator-pa version` reports, the exclude in your bootstrap `pnpm-workspace.yaml` did not take (rare; usually a stale pnpm store or a typo in the yaml). The `@latest` tag does NOT bypass the release-age gate, so the recovery is to pin the version npm names: `pnpm add @stravica-ai/digital-operator-pa@<version npm view prints>` inside the bootstrap dir, then re-run `pa-init`. When pnpm 11 sees a pinned version that would otherwise be gated, it adds an entry of its own to `pnpm-workspace.yaml` under `minimumReleaseAgeExclude`; the file the guide already asked you to write covers that write.
+
+`pnpm install` in the instance runs automatically as the last step of `pa-init` (skip it with `--skip-install` for CI). The `pa status` verification also runs at the end and prints the resolved package version; a mismatch between the scaffold pin and the installed version prints a WARNING line naming both, so a broken guard surfaces immediately instead of hiding behind a "Command not found" later.
+
+**Do not put the instance under a directory that already contains a `pnpm-workspace.yaml`.** pnpm treats the instance as a workspace member, `pnpm install` silently no-ops, and `node_modules/.bin/pa` never appears. Keep `--target` outside any pnpm workspace root (a top-level `$HOME/<pa-name>-instance`, as shown above, is safe; `~/pa-bootstrap` itself is such a workspace root now, so never nest the `--target` inside it).
+
 ## 2. Sanity-check the install
 
 ```sh
@@ -45,10 +72,11 @@ pnpm exec pa knowledge context     # first line: library.mode = simple  (variant
 ## 3. Start the workspace
 
 ```sh
-pnpm exec pa workspace start       # opens http://localhost:4200
+pnpm exec pa workspace start                     # opens http://localhost:4200
+pnpm exec pa workspace start --port 4300         # pick a different port if 4200 is taken
 ```
 
-The workspace serves a viewer, a home page, and an onboarding form. Long notes from your PA land here rather than in chat.
+The workspace serves a viewer, a home page, and an onboarding form. Long notes from your PA land here rather than in chat. The default port is `4200` (localhost only); the server refuses to start with `Error: Port 4200 is already in use by another process.` when the port is bound by something else (a docker container, another dev server). Pick a free port with `--port N` or set `WORKSPACE_PORT` in your environment; `pa status` reads the resolved port from `operator/config/preferences.json` so keep the two in step for the port to persist across restarts.
 
 ## 4. Start your first session
 
@@ -114,7 +142,7 @@ Your PA has the `rcf-lite-engineer` role baked in. It builds greenfield applicat
 
 The `@stravica-ai/digital-operator-pa` package ships three Atlassian CLIs on `PATH`: `jira` (issues, search, transitions, worklogs), `confluence` (spaces, pages, CQL search, mirror), and `confluence-fetch` (search + fetch + save a page under `operator/notes/`). Run `pnpm exec jira --help`, `pnpm exec confluence --help`, `pnpm exec confluence-fetch --help` for the verbs.
 
-Both CLIs share three credentials pointing at the same Atlassian site. Two-step setup:
+Both CLIs share three credentials pointing at the same Atlassian site. Setup:
 
 ```sh
 pnpm exec secrets set JIRA_DOMAIN yoursite               # for yoursite.atlassian.net
@@ -122,6 +150,10 @@ pnpm exec secrets set JIRA_EMAIL   you@example.com       # your Atlassian accoun
 pnpm exec secrets set JIRA_API_TOKEN <paste-token>       # id.atlassian.com/manage-profile/security/api-tokens
 ```
 
+`secrets set` self-initialises the vault (age keypair, `.vault/recipients.txt`, empty encrypted store) on the first write when there is nothing at `.vault/` yet. It prints a one-line notice on stderr saying so and continues. You do not need to run `secrets init` manually first. Every `secrets set` also prints one stderr line naming which vault it wrote to; on a fresh solo install with no scope configured that says the write went to the `(legacy)` pot (no scope specified, no default configured). Informational, safe to ignore. Set `SECRETS_DEFAULT_SCOPE` in your environment or configure `defaultScope` in `~/.config/stravica-pa/defaults.json` if you want a named scope; solo mode does not require one.
+
+The age key that self-init generates lives at `~/.config/stravica-pa/age-key.txt` (one per laptop, not per instance). If that file already exists when you scaffold a second PA on the same machine, self-init reuses it, so both instances read and write the same encrypted vault content when a `.vault/` sits under both. That is the point: a single key per operator per machine. To force a fresh key, move the existing one aside (`mv ~/.config/stravica-pa/age-key.txt ~/.config/stravica-pa/age-key.txt.prev`) before the first `secrets set` in the new instance; the vault contents in the old instance will then be unreadable to the new key.
+
 Verify with `pnpm exec jira auth` and `pnpm exec confluence auth`; each prints the current user on success. Credentials also resolve from environment variables of the same names, so a `.env` or shell profile works as an alternative to `secrets`. The `atlassian` entry in `operator/extensions/manifest.json` records the extension is enabled and repeats the setup line.
 
 `jira mine` returns your open issues across every project the account can see. If you spend most of your Jira time in one project, set `JIRA_DEFAULT_PROJECT` (env var or a vault key of the same name) and `jira mine` narrows to it unless you pass `--project KEY` or `--all`:

package/package.json

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