@stravica-ai/digital-operator-pa 0.1.40 → 0.1.42

package/README.md

@@ -20,6 +20,11 @@ New to the platform and setting up a single-person PA on one laptop? Follow
 ten-minute walkthrough from an empty directory to a working PA under your
 own Claude Code subscription.
 
+Want a plain-language tour of what the PA does before you install it? Read
+[`./docs/what-it-can-do.md`](./docs/what-it-can-do.md) — a day-to-day view
+of the capabilities, how it learns you, and what is (and is not) in this
+release.
+
 ## Bins
 
 The wrapper exposes the platform's operator-facing CLIs:

package/bin/confluence

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// confluence - Confluence Cloud CLI (v1 CQL + v2 CRUD). Shares JIRA_* creds.
+// Bundled entry: delegates to the copied @stravica-ai/engineering-pa-core-extensions-atlassian sources.
+import('../dist/engineering-pa-core-extensions-atlassian/src/confluence/cli.mjs').then((m) => {
+  return m.main(process.argv.slice(2));
+}).catch((err) => {
+  process.stderr.write(`[confluence] ${err?.message ?? err}\n`);
+  process.exit(typeof err?.exitCode === 'number' ? err.exitCode : 2);
+});

package/bin/confluence-fetch

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// confluence-fetch - search + fetch + save Confluence pages into operator/notes/.
+// Bundled entry: delegates to the copied @stravica-ai/engineering-pa-core-extensions-atlassian sources.
+import('../dist/engineering-pa-core-extensions-atlassian/src/confluence-fetch/cli.mjs').then((m) => {
+  return m.main(process.argv.slice(2));
+}).catch((err) => {
+  process.stderr.write(`[confluence-fetch] ${err?.message ?? err}\n`);
+  process.exit(typeof err?.exitCode === 'number' ? err.exitCode : 2);
+});

package/bin/jira

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// jira - Jira REST v3 CLI. Auth reads env vars first, else `secrets get JIRA_*`.
+// Bundled entry: delegates to the copied @stravica-ai/engineering-pa-core-extensions-atlassian sources.
+import('../dist/engineering-pa-core-extensions-atlassian/src/jira/cli.mjs').then((m) => {
+  return m.main(process.argv.slice(2));
+}).catch((err) => {
+  process.stderr.write(`[jira] ${err?.message ?? err}\n`);
+  process.exit(typeof err?.exitCode === 'number' ? err.exitCode : 2);
+});

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/knowledge/platform-tooling/workspace-extensions.md

@@ -0,0 +1,62 @@
+<!--
+  scaffold: workspace-extensions.md
+  bucket: platform-tooling (Bucket 7)
+  audience: the PA, deciding when to propose that the operator build a workspace page.
+  what belongs here:
+    - placement rule (common-use CLIs in core, personal pages as extensions).
+    - triggers the PA watches for.
+    - what to offer, and what NOT to prompt for.
+    - how to prompt.
+    - cross-link to the workspace README for the mechanism.
+-->
+
+# Workspace extensions: when to propose one
+
+## Placement rule
+
+Common-use CLIs live in core. Personal workspace pages are a more personal expression of how the operator works, so they belong in an extension. The PA carries the knowledge that decides when to prompt the operator to build one.
+
+The mechanism itself is already live. Static page overlay under `operator/extensions/workspace/<name>.html`, optional API routes via `operator/extensions/workspace/api.mjs` (exporting `register(addRoute)`), nav registration via `operator/extensions/workspace/nav.json` (or team-scoped `nav.<team>.json` fragments). Full detail: `@stravica-ai/engineering-pa-workspace/README.md` (extension mechanism section).
+
+## Triggers
+
+Three shapes of operator behaviour that mean a workspace page would pay for itself.
+
+1. **Repeated manual view.** The operator opens the same files, runs the same query, or screenshots the same panel more than twice in a week. The manual view is already a page; it just does not exist yet.
+2. **Explicit ask for a dashboard or "one page to see X".** Any request framed as "I want to see all my X in one place", "give me a page for Y", "I want to check Z at a glance". The operator has done the design work already.
+3. **An operator-installed tool with a natural page.** A Jira CLI plus a "my Jira today" habit is the archetype. Any tool the operator installed and now reaches for daily has a page shape latent in it.
+
+## What to offer
+
+Match the surface to the shape.
+
+- **Read-only view of files or state on disk.** Static page overlay. HTML file at `operator/extensions/workspace/<name>.html` served in place of a core same-named page, or as a new page at `/<name>.html`.
+- **Anything that needs server access or a write.** Static page plus an API route in `operator/extensions/workspace/api.mjs`. The route hangs off `register(addRoute)` and lands under `/__api/<name>/<verb>`.
+- **Discoverability in the sidebar.** Add a `nav.json` entry naming the page. If the operator runs multiple teams on the same box, use `nav.<team>.json` fragments so each team's entries survive the library merge.
+
+## What NOT to prompt for
+
+Not every operator habit is a workspace page.
+
+- **One-shot views.** A page for a single question the operator asked once is over-engineering. The answer belongs in the chat, or in a `viewer.html?file=...` link.
+- **Throwaway reports.** If the output has a shelf-life of one day, a workspace page is the wrong home. Stage the file, link it, move on.
+- **Anything that is a workspace page and a knowledge doc and a scheduled task rolled into one.** That is a tool. Propose `tool-developer` under Bucket 7 rule 9, not a workspace extension.
+
+## How to prompt
+
+One sentence. Name the page, the source of data, and the interaction shape.
+
+> "Want me to build a workspace page for X? Reads from Y, refresh on nav-load, no writes."
+
+Get an explicit yes before doing anything durable. On approval, either:
+
+- Invoke `pa-init workspace-extension <name>` for the file skeleton plus nav entry (add `--with-api` if the page needs a server route), then dispatch `tool-developer` for the real page content and any handler logic, OR
+- Skip the scaffold verb and dispatch `tool-developer` directly if the shape is unusual enough that the skeleton would just be deleted.
+
+The scaffold verb is a thirty-second cost saver; it does not replace the design conversation.
+
+## Related
+
+- CLAUDE.md.template Bucket 7 rule 9 (proactive tool proposal): the parent rule; workspace pages count as a tool for that rule.
+- `@stravica-ai/engineering-pa-workspace/README.md`: the extension mechanism, page overlay, API-route registration, nav merge, team scoping.
+- `packages/core/knowledge/platform-tooling/workspace-server.md`: workspace server operations (start, stop, viewer.html).

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/README.md

@@ -1,31 +1,96 @@
 # @stravica-ai/engineering-pa-core-extensions-atlassian
 
-Identity: `@stravica-ai/engineering-pa-core-extensions-atlassian` — optional Atlassian (Jira/Confluence) core extension.
+Atlassian (Jira, Confluence) CLIs and library surface, promoted into core
+for the alpha solo scaffold. Common-use tools ship with the platform; the
+personal workspace pages colleagues build on top ship as extensions.
 
-## Status
+## Bins
 
-**Skeleton — v0.1.0.** Workspace-internal, `"private": true`, not individually published.
+Wrapped by `@stravica-ai/digital-operator-pa` and installed on `PATH` when
+that package is installed:
 
-Phase 2 promotes the existing operator-side Atlassian extension(s) into core via the extension-promotion mechanism: the upgrade tool detects a local extension matching this namespace, deactivates the local copy, copies operator-specific config across, and enables the core version.
+- `jira` - Jira REST v3 CLI. Verbs: `auth`, `mine`, `search`, `issue`,
+  `create`, `update`, `attach`, `transition`, `advance`, `cancel`,
+  `comment`, `worklog`, `projects`, `boards`, `sprint`, `link`,
+  `sync-statuses`, `bulk-transition`, `test`.
+- `confluence` - Confluence Cloud CLI (v1 CQL search, v2 page CRUD).
+  Verbs: `auth`, `spaces`, `pages`, `page`, `search`, `create`, `update`,
+  `comment`, `label`, `tree`, `recent`, `mine`, `mirror-folder`,
+  `mirror-page`, `test`.
+- `confluence-fetch` - convenience wrapper: search + fetch + save a page
+  to `operator/notes/` and open the workspace viewer.
 
-For v0.1.0, this is an empty slot so the manifest-toggleable extension model is established from day one.
+Run `jira --help`, `confluence --help`, `confluence-fetch --help` for the
+full verb list; each verb has its own `--help`.
 
-## Layout
+## Auth
+
+Both CLIs read three credentials from the environment first, else from the
+platform `secrets` bin. The keys are shared because Jira and Confluence
+target the same Atlassian site:
+
+- `JIRA_DOMAIN` - subdomain of `atlassian.net` (`foo` for `foo.atlassian.net`)
+- `JIRA_EMAIL` - your Atlassian account email
+- `JIRA_API_TOKEN` - a token from `https://id.atlassian.com/manage-profile/security/api-tokens`
+
+Two-step colleague setup, after installing `@stravica-ai/digital-operator-pa`:
 
 ```
-packages/core-extensions/atlassian/
-  index.mjs            # placeholder export
-  package.json         # name, version, scripts
-  README.md            # this file
-  test/index.test.mjs
+secrets set JIRA_DOMAIN yoursite
+secrets set JIRA_EMAIL   you@example.com
+secrets set JIRA_API_TOKEN <paste-token>
+```
+
+Resolution order for each key:
+
+1. Environment variable of the same name (`JIRA_DOMAIN`, ...).
+2. `secrets get <prefix>JIRA_DOMAIN` (etc.), where `<prefix>` comes from
+   `ATLASSIAN_SECRETS_PREFIX` (e.g. an org slug like `acme/` picks the `acme` vault scope in
+   an operator estate; empty by default so a solo colleague's single scope
+   just works).
+
+The tool never prints or logs the values; child-process reads use
+`stdio: ['ignore', 'pipe', 'pipe']`.
+
+## Configuration
+
+- `config/jira-workflow-chains.default.json` - shipped empty. `jira advance
+  <KEY> <STATUS>` walks a per-site chain of statuses; override by writing
+  `operator/config/jira-workflow-chains.json` in your workspace root.
+- `operator/config/jira-status-mappings.json` - per-project status mapping
+  used by `jira sync-statuses`; not shipped by default.
+- `JIRA_DEFAULT_PROJECT` (optional, env or vault key of the same name) -
+  when set, `jira mine` narrows to that project unless `--project KEY`
+  or `--all` is passed. With nothing configured, `jira mine` returns
+  issues across every project the account can see.
+
+## Library surface
+
+```js
+import {
+  createJiraClient,
+  createConfluenceClient,
+  storageToMarkdown,
+} from '@stravica-ai/digital-operator-pa/dist/engineering-pa-core-extensions-atlassian/index.mjs';
+
+const jira = createJiraClient();
+const { data } = await jira.get('/rest/api/3/myself');
 ```
 
-## Tests
+For tests, inject a stub credential resolver rather than the vault:
 
-```bash
-pnpm --filter @stravica-ai/engineering-pa-core-extensions-atlassian test
+```js
+const client = createJiraClient({
+  domain: 'yoursite',
+  email:  'you@example.com',
+  apiToken: 'test-token',
+  fetchFn: mockFetch,
+});
 ```
 
-## Standards
+## Workspace hook
 
-Follows the [tooling standard](../../../CONTRIBUTING.md#standards): JS only, zero npm deps, `node:test`, camelCase JSON.
+`jira` writes POST to `http://127.0.0.1:<workspacePort>/__api/jira/invalidate`
+after mutating verbs, so a workspace page can refresh cached data on
+change. The endpoint is a workspace-extension concern; the CLI treats a
+timeout or refused connection as fine (the write succeeded regardless).

package/dist/engineering-pa-core-extensions-atlassian/bin/confluence

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../src/confluence/cli.mjs').then((m) => m.main(process.argv.slice(2)));

package/dist/engineering-pa-core-extensions-atlassian/bin/confluence-fetch

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../src/confluence-fetch/cli.mjs').then((m) => m.main(process.argv.slice(2)));

package/dist/engineering-pa-core-extensions-atlassian/bin/jira

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../src/jira/cli.mjs').then((m) => m.main(process.argv.slice(2)));

package/dist/engineering-pa-core-extensions-atlassian/config/jira-workflow-chains.default.json

@@ -0,0 +1,4 @@
+{
+  "_note": "Per-site Jira workflow chains for `jira advance <KEY> <STATUS>`. Ships empty because every Atlassian instance has its own workflows. Override by writing operator/config/jira-workflow-chains.json in your workspace root; the CLI reads that path first and falls back to this shipped default.",
+  "chains": []
+}

package/dist/engineering-pa-core-extensions-atlassian/index.mjs

@@ -1,9 +1,20 @@
-// @stravica-ai/engineering-pa-core-extensions-atlassian — optional Atlassian
-// integration (Jira/Confluence tooling + workspace pages).
+// @stravica-ai/engineering-pa-core-extensions-atlassian
 //
-// Status: skeleton. Phase 2 promotes the existing operator-side Atlassian
-// extension(s) into core. Until then, this is a placeholder slot so the
-// manifest-toggleable extension model is established from day one.
+// Common-use Atlassian CLIs (jira, confluence, confluence-fetch), promoted
+// into core so the alpha solo scaffold ships them out of the box. The bins
+// live under bin/ and are wrapped from @stravica-ai/digital-operator-pa's
+// bin map. Auth reads env vars first, else `secrets get JIRA_*` (see
+// src/common/secrets.mjs).
+
+export { createClient as createJiraClient, getCredentials as getJiraCredentials, JiraError } from './src/jira/client.mjs';
+export { createClient as createConfluenceClient, getCredentials as getConfluenceCredentials, ConfluenceError } from './src/confluence/client.mjs';
+export {
+  storageToMarkdown,
+  markdownToStorage,
+  storageToText,
+  textToStorage,
+} from './src/confluence/storage.mjs';
+export { loadAtlassianCredentials, resolveSecret, CredentialResolutionError } from './src/common/secrets.mjs';
 
 export const name = './';
-export const status = 'skeleton';
+export const status = 'active';

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

@@ -1,11 +1,18 @@
 {
   "name": "@stravica-ai/engineering-pa-core-extensions-atlassian",
-  "version": "0.1.1",
-  "description": "Atlassian (Jira/Confluence) core extension — optional, manifest-toggleable.",
+  "version": "0.2.0",
+  "description": "Atlassian (Jira, Confluence, confluence-fetch) CLIs and library surface. Promoted into core for the alpha solo scaffold.",
   "type": "module",
   "main": "./index.mjs",
   "exports": {
-    ".": "./index.mjs"
+    ".": "./index.mjs",
+    "./jira": "./src/jira/client.mjs",
+    "./confluence": "./src/confluence/client.mjs"
+  },
+  "bin": {
+    "jira": "bin/jira",
+    "confluence": "bin/confluence",
+    "confluence-fetch": "bin/confluence-fetch"
   },
   "private": true,
   "license": "MIT",
@@ -15,5 +22,5 @@
   "scripts": {
     "test": "node --test --test-isolation=none test/*.test.mjs"
   },
-  "//": "test pins --test-isolation=none: default process-isolation mode silently undercounts (drops passed tests from totals) when a test awaits async work while stdout is patched by a capture() helper — see packages/cli/test/secrets. Counts must never lie."
+  "//": "test pins --test-isolation=none: default process-isolation mode silently undercounts (drops passed tests from totals) when a test awaits async work while stdout is patched by a capture() helper - see packages/cli/test/secrets. Counts must never lie."
 }

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

@@ -0,0 +1,137 @@
+// client.mjs - Shared fail-silent transport for notifying the local
+// workspace server that a CLI tool's backing data changed.
+//
+// Extracted so any Atlassian CLI (jira today; confluence or others later) can
+// fire a lightweight "hey, invalidate your cache" POST at a tool-specific
+// endpoint without re-implementing the fetch/timeout/disable-flag plumbing.
+// Callers bind their own endpoint, body shape, and disable env var (see
+// operator/extensions/tools/jira/src/invalidate.mjs for the reference
+// caller); this module only owns the wire mechanics.
+//
+// Contract (binding on every caller):
+//   - Fail-silent. Never throws - always resolves to { ok, error? }. A
+//     workspace-notify feature must never block or crash the CLI command
+//     whose actual job is mutating the upstream system (Jira, Confluence, ...).
+//   - Non-blocking by design. Bounded by timeoutMs (default 500ms) via
+//     AbortController; the caller gets an answer promptly either way.
+//   - Zero runtime deps. Node 20+ globalThis.fetch + AbortController only.
+//
+// Port resolution: opts.port wins; else the workspacePort from the merged
+// preferences (device-local preferences.local.json over the synced
+// preferences.json); else the platform default (4200) - same convention as
+// operator/extensions/tools/confluence-fetch/src/fetch.mjs.
+//
+// The overlay (preferences.local.json) is the operator's device-scoped
+// escape hatch: gitignored, so a per-device workspacePort never travels
+// through the synced base file. Precedence matches the platform's own
+// reader in engineering-pa-core src/desk/team-scope.mjs mergePreferences().
+
+import { resolve } from 'node:path';
+import { readFileSync } from 'node:fs';
+
+// Repo root: env override, else cwd. The tool is invoked from a workspace
+// root so cwd is the correct default; keeps preferences.local.json overlay
+// resolution working under a downstream install.
+const REPO_ROOT =
+  process.env.PA_REPO_ROOT || process.env.DAVE_ROOT || process.cwd();
+const PREFERENCES_PATH = resolve(REPO_ROOT, 'operator', 'config', 'preferences.json');
+const PREFERENCES_LOCAL_PATH = resolve(REPO_ROOT, 'operator', 'config', 'preferences.local.json');
+
+const DEFAULT_TIMEOUT_MS = 500;
+const PLATFORM_DEFAULT_PORT = 4200;
+
+function readJsonObject(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    // Missing or malformed - that layer contributes nothing.
+    return null;
+  }
+}
+
+/**
+ * Resolve the local workspace port from the merged preferences.
+ * Overlay keys win; keys it omits fall through to the synced base; a device
+ * with no overlay behaves exactly as before this change.
+ *
+ * Paths are injectable for tests only - production callers pass nothing.
+ *
+ * @param {object} [paths]
+ * @param {string} [paths.base]   preferences.json path.
+ * @param {string} [paths.local]  preferences.local.json path.
+ * @returns {number}
+ */
+export function resolveWorkspacePort({ base = PREFERENCES_PATH, local = PREFERENCES_LOCAL_PATH } = {}) {
+  const prefs = { ...(readJsonObject(base) || {}), ...(readJsonObject(local) || {}) };
+  return typeof prefs.workspacePort === 'number' ? prefs.workspacePort : PLATFORM_DEFAULT_PORT;
+}
+
+function resolvePort(overridePort) {
+  if (typeof overridePort === 'number') return overridePort;
+  return resolveWorkspacePort();
+}
+
+/**
+ * Fire a fail-silent POST notify against the local workspace server.
+ * Always resolves; never throws.
+ *
+ * @param {object} opts
+ * @param {string} opts.endpoint       Path to POST to, e.g. '/__api/jira/invalidate'.
+ * @param {string} [opts.disableEnv]   Env var name; value '0' short-circuits
+ *                                      (skips the network call entirely).
+ * @param {object} [opts.body]         JSON body to send. Defaults to {}.
+ * @param {number} [opts.port]         Override the resolved workspace port.
+ * @param {number} [opts.timeoutMs]    Override the abort timeout (default 500ms).
+ * @param {Function} [opts.fetchImpl]  Override fetch (test injection).
+ * @returns {Promise<{ok: boolean, error?: string}>}
+ */
+export async function notifyInvalidate(opts = {}) {
+  const { endpoint, disableEnv, body = {}, timeoutMs = DEFAULT_TIMEOUT_MS, fetchImpl } = opts;
+
+  if (disableEnv && process.env[disableEnv] === '0') {
+    return { ok: false, error: 'disabled' };
+  }
+
+  const fetchFn = typeof fetchImpl === 'function' ? fetchImpl : (fetchImpl || globalThis.fetch);
+  if (typeof fetchFn !== 'function') {
+    return { ok: false, error: 'fetch unavailable' };
+  }
+
+  const port = resolvePort(opts.port);
+  const url = `http://127.0.0.1:${port}${endpoint}`;
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetchFn(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      return { ok: false, error: `http ${res.status}` };
+    }
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err && err.message ? err.message : String(err) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Fire-and-forget wrapper. Returns immediately usable promise that never
+ * rejects, even if the caller doesn't await it - safe to call without a
+ * trailing .catch().
+ *
+ * @param {object} [opts]  Same shape as notifyInvalidate.
+ * @returns {Promise<{ok: boolean, error?: string}>}
+ */
+export function notifyInvalidateAsync(opts = {}) {
+  return notifyInvalidate(opts).catch((err) => ({
+    ok: false,
+    error: err && err.message ? err.message : String(err),
+  }));
+}

package/dist/engineering-pa-core-extensions-atlassian/src/common/pa-name.mjs

@@ -0,0 +1,58 @@
+// pa-name.mjs - Resolve the configured PA name for colleague-visible
+// artefacts (e.g. the marker prefix on Jira comments the CLIs post).
+//
+// Precedence:
+//   1. env PA_NAME - explicit per-shell override, wins outright.
+//   2. paName in the operator preferences (device-local
+//      preferences.local.json overlay over the synced preferences.json) -
+//      the scaffold writes this at pa-init time; it matches the
+//      `agents/<paName>/` directory shape.
+//   3. `'pa'` - a generic fallback so the marker is never blank.
+//
+// The reader mirrors invalidate-client.mjs on repo-root resolution and
+// preferences layering so operators get one story.
+
+import { resolve } from 'node:path';
+import { readFileSync } from 'node:fs';
+
+const REPO_ROOT =
+  process.env.PA_REPO_ROOT || process.env.DAVE_ROOT || process.cwd();
+const PREFERENCES_PATH = resolve(REPO_ROOT, 'operator', 'config', 'preferences.json');
+const PREFERENCES_LOCAL_PATH = resolve(REPO_ROOT, 'operator', 'config', 'preferences.local.json');
+
+const DEFAULT_PA_NAME = 'pa';
+
+function readJsonObject(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function isNonEmptyString(v) {
+  return typeof v === 'string' && v.trim().length > 0;
+}
+
+/**
+ * Resolve the configured PA name.
+ *
+ * Paths are injectable for tests only - production callers pass nothing.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.envValue]  Override the PA_NAME env value (test injection).
+ * @param {string} [opts.base]      preferences.json path.
+ * @param {string} [opts.local]     preferences.local.json path.
+ * @returns {string}
+ */
+export function resolvePaName({
+  envValue = process.env.PA_NAME,
+  base = PREFERENCES_PATH,
+  local = PREFERENCES_LOCAL_PATH,
+} = {}) {
+  if (isNonEmptyString(envValue)) return envValue.trim();
+  const prefs = { ...(readJsonObject(base) || {}), ...(readJsonObject(local) || {}) };
+  if (isNonEmptyString(prefs.paName)) return prefs.paName.trim();
+  return DEFAULT_PA_NAME;
+}