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

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

@@ -360,9 +360,11 @@ Usage:
 Bind host defaults to loopback (127.0.0.1). Use --host <addr> (or the
 WORKSPACE_HOST env var) to expose the workspace on another interface.
 
-When the workspace is supervised by launchd (~/Library/LaunchAgents/com.dave.workspace.plist)
-or systemd (~/.config/systemd/user/dave-workspace.service), \`stop\` is refused and \`restart\`
+When the workspace is supervised by launchd (~/Library/LaunchAgents/com.<paName>.workspace.plist)
+or systemd (~/.config/systemd/user/<paName>-workspace.service), \`stop\` is refused and \`restart\`
 delegates to the supervisor — this is the in-place version-pickup path after \`pnpm update\`.
+Unit labels are derived from operator/config/preferences.json:paName; the legacy
+com.dave.workspace / dave-workspace.service is still recognised for pre-0.1.44 installs.
 
 Exit codes (tooling standard §6):
   0 ok | 1 usage error | 2 operational failure | 3 transport/IO failure

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

@@ -18,8 +18,8 @@ import { existsSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 
-import { runSync } from './run.mjs';
 import { defaultRunner } from './runner.mjs';
+import { runSyncWithStatus } from './status-record.mjs';
 
 const USAGE = `estate-sync — single-writer-per-host git sync for ESTATE-NATIVE content.
 
@@ -134,7 +134,7 @@ async function route(argv) {
     await mkdir(logDir, { recursive: true });
     const runsLog = join(logDir, 'runs.jsonl');
     const lockPath = join(repoRoot, '.cache/estate-sync/.lock');
-    const code = await runSync({
+    const code = await runSyncWithStatus({
       repoRoot,
       logDir,
       runsLog,

package/dist/engineering-pa-cli/src/sync/status-record.mjs

@@ -0,0 +1,347 @@
+// estate-sync — synced end-of-pass status record.
+//
+// After every real pass, estate-sync writes a tiny per-host status file
+// at `<repoRoot>/agents/estate-sync/<paName>/<host>.json`. This path is
+// TRACKED and — critically — sits OUTSIDE every registry mount `to`
+// subtree, so estate-sync's own registry-scoped commit stages it (a
+// path inside `agents/<paName>/` would be silently excluded by the
+// mount filter and never leave the writing host). The consequence: the
+// pass's own commit + push carries every host's most recent pass
+// result into every clone. A reader on any host (e.g. the HQ boot-
+// context hook) can then flag a stuck cron on any other host at
+// session boot without ssh or a separate publisher.
+//
+// Location choice: `agents/estate-sync/` is not under any mount `to`
+// path in the current registry (`operator/registry/repos.json` mounts
+// `agents/<name>/`, one per agent, not `agents/` itself). Every host
+// therefore commits its own file directly, no per-host registry
+// change needed.
+//
+// Design notes:
+//   - Overwrite semantics: one JSON file per host, small (< 1 KB). The
+//     writer never appends; the previous pass's record is replaced.
+//   - The record is derived from the audit record estate-sync already
+//     writes to runs.jsonl (same source of truth) — so a change to the
+//     audit vocabulary is picked up here for free.
+//   - noop-locked passes DO NOT write a status record: the pass that is
+//     actually running (and holding the lock) will write its own record
+//     when it finishes, and a concurrent overwrite from a lock contender
+//     would race with it. Contenders exit silently.
+//   - The `agents/estate-sync/<paName>/` directory is created on first
+//     write. Failure to write fails silently — this is a status
+//     side-channel and must never block the sync exit code.
+//   - Callers wrap runSync via `runSyncWithStatus`, which reads the last
+//     line of runs.jsonl to derive the terminal record. This means the
+//     writer is layered ON TOP of runSync rather than braided into every
+//     one of its exit paths — the run.mjs surface stays untouched.
+//
+// Absence-of-work: a fresh file dated after `now - 6h` on every host is
+// the healthy signal; the reader flags anything older or with alertLevel
+// > 'ok'. The 6h window is chosen against the 30-minute cron cadence,
+// twelve missed ticks is loud enough to warrant a session-boot line.
+
+import { mkdir, readFile, writeFile, readdir } from 'node:fs/promises';
+import { hostname as osHostname } from 'node:os';
+import { join } from 'node:path';
+
+import { runSync } from './run.mjs';
+import { revParseSha } from './git.mjs';
+
+/**
+ * Audit statuses that count as a healthy pass. Everything else
+ * (`fail-*`, unknown vocab, missing status) maps to `failed` and the
+ * reader is expected to flag it. `noop-locked` never reaches the
+ * composer (see runSyncWithStatus), but is listed here for parity so a
+ * future direct caller lands in the same place.
+ */
+const OK_AUDIT_STATUSES = new Set([
+  'ok',
+  'noop-nothing-to-do',
+  'noop-locked',
+]);
+
+const ALERT_RANK = { ok: -1, warn: 0, error: 1, 'needs-human': 2 };
+
+/**
+ * Compose the tracked status record from an audit record plus context.
+ * Pure — no clock, no filesystem. Tested directly.
+ *
+ * @param {object} input
+ * @param {object} input.audit           audit record as written to runs.jsonl
+ * @param {string} input.paName          resolved paName (e.g. 'dave')
+ * @param {string} input.host            resolved hostname (os.hostname())
+ * @param {string|null} input.headBefore HEAD sha at start of pass (or null)
+ * @param {string|null} input.headAfter  HEAD sha at end of pass (or null)
+ * @param {number} [input.pendingCount]  count of self-heal pending entries
+ * @returns {{ host:string, paName:string, finishedAt:string, status:'ok'|'failed', alertLevel:'ok'|'warn'|'error'|'needs-human', attempts:number, lastError:(string|null), headBefore:(string|null), headAfter:(string|null), pending:number, auditStatus:string }}
+ */
+export function composeStatusRecord({
+  audit,
+  paName,
+  host,
+  headBefore = null,
+  headAfter = null,
+  pendingCount = 0,
+}) {
+  const auditStatus = typeof audit?.status === 'string' ? audit.status : 'unknown';
+  const status = OK_AUDIT_STATUSES.has(auditStatus) ? 'ok' : 'failed';
+  const alertLevel = deriveAlertLevel(audit, auditStatus);
+  const attempts = deriveAttempts(audit);
+  const lastError = deriveLastError(audit);
+  return {
+    host,
+    paName,
+    finishedAt: typeof audit?.ts === 'string' ? audit.ts : '',
+    status,
+    alertLevel,
+    attempts,
+    lastError,
+    headBefore: typeof headBefore === 'string' ? headBefore : null,
+    headAfter: typeof headAfter === 'string' ? headAfter : null,
+    pending: Number.isFinite(pendingCount) ? pendingCount : 0,
+    auditStatus,
+  };
+}
+
+function deriveAlertLevel(audit, auditStatus) {
+  // Prefer the highest-ranked alert level across queued self-heal
+  // entries when the audit carries them (needs-human > error > warn).
+  if (Array.isArray(audit?.queued) && audit.queued.length > 0) {
+    let best = 'warn';
+    for (const q of audit.queued) {
+      const lvl = typeof q?.alertLevel === 'string' ? q.alertLevel : 'warn';
+      if ((ALERT_RANK[lvl] ?? -1) > (ALERT_RANK[best] ?? -1)) best = lvl;
+    }
+    return best;
+  }
+  // Otherwise map from the status vocabulary.
+  switch (auditStatus) {
+    case 'fail-rebase-needs-human':
+      return 'needs-human';
+    case 'fail-rebase':
+    case 'fail-rebase-stuck':
+    case 'fail-push':
+    case 'fail-git':
+    case 'fail-cli-bootstrap':
+      return 'error';
+    case 'fail-rebase-queued':
+      return 'warn';
+    default:
+      return 'ok';
+  }
+}
+
+function deriveAttempts(audit) {
+  if (Array.isArray(audit?.queued) && audit.queued.length > 0) {
+    let max = 0;
+    for (const q of audit.queued) {
+      const n = typeof q?.attemptCount === 'number' ? q.attemptCount : 0;
+      if (n > max) max = n;
+    }
+    return max;
+  }
+  return 0;
+}
+
+function deriveLastError(audit) {
+  const reason = audit?.reason;
+  if (typeof reason !== 'string' || reason.length === 0) return null;
+  return reason.split(/\r?\n/)[0].slice(0, 200);
+}
+
+/**
+ * Write the status record to
+ * `<repoRoot>/agents/estate-sync/<paName>/<host>.json`. Parent dirs are
+ * created; the file is fully overwritten. Returns the path written.
+ * Failure to write is thrown to the caller — callers wrap in try/catch
+ * and never block on this.
+ *
+ * @param {{ repoRoot:string, paName:string, host:string, record:object }} opts
+ * @returns {Promise<string>}
+ */
+export async function writeStatusRecord({ repoRoot, paName, host, record }) {
+  const dir = join(repoRoot, 'agents', 'estate-sync', sanitiseSegment(paName));
+  await mkdir(dir, { recursive: true });
+  const path = join(dir, `${sanitiseSegment(host)}.json`);
+  await writeFile(path, JSON.stringify(record, null, 2) + '\n');
+  return path;
+}
+
+/**
+ * Read paName from preferences.json with an optional preferences.local.json
+ * overlay (overlay wins). Returns null on any failure — the status
+ * writer is a side-channel and a missing paName just means the record
+ * is skipped, not that estate-sync itself fails.
+ *
+ * @param {string} repoRoot
+ * @returns {Promise<string|null>}
+ */
+export async function readPaName(repoRoot) {
+  const basePath = join(repoRoot, 'operator/config/preferences.json');
+  const overlayPath = join(repoRoot, 'operator/config/preferences.local.json');
+  let base = {};
+  let overlay = {};
+  try { base = JSON.parse(await readFile(basePath, 'utf8')); } catch { /* ignore */ }
+  try { overlay = JSON.parse(await readFile(overlayPath, 'utf8')); } catch { /* ignore */ }
+  const value = overlay?.paName ?? base?.paName ?? null;
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+/**
+ * `os.hostname()` with the injection seam runSync already uses for
+ * registry-scope tests. Empty results fall back to `unknown-host`.
+ */
+export function resolveHost(hostnameFn) {
+  try {
+    const h = (hostnameFn || osHostname)();
+    return typeof h === 'string' && h.length > 0 ? h : 'unknown-host';
+  } catch {
+    return 'unknown-host';
+  }
+}
+
+/**
+ * Read the last non-empty line of runs.jsonl and parse it as JSON.
+ * Returns null if the file is missing, empty, or the last line does not
+ * parse. Callers only care about the terminal record for the pass they
+ * just ran; earlier entries are irrelevant here.
+ *
+ * @param {string} runsLog
+ * @returns {Promise<object|null>}
+ */
+export async function readLastAuditRecord(runsLog) {
+  let text;
+  try {
+    text = await readFile(runsLog, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+  const lines = text.split('\n').map((s) => s.trim()).filter((s) => s.length > 0);
+  if (lines.length === 0) return null;
+  try {
+    return JSON.parse(lines[lines.length - 1]);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Count entries in the self-heal pending queue directory. Returns 0 on
+ * missing dir. Directory entries starting with `.` (e.g. `.gitkeep`)
+ * are ignored, and sidecar `.json` files are counted alongside their
+ * data twins as a single pending — we count the DATA files only, i.e.
+ * entries whose name does not end in `.json`.
+ *
+ * @param {string} pendingDir
+ * @returns {Promise<number>}
+ */
+export async function countPending(pendingDir) {
+  let entries;
+  try {
+    entries = await readdir(pendingDir);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return 0;
+    return 0;
+  }
+  return entries.filter((n) => !n.startsWith('.') && !n.endsWith('.json')).length;
+}
+
+/**
+ * Wrap `runSync` so that after each real (non-dry-run) pass the terminal
+ * audit record is mirrored to a tracked per-host status file. Signature
+ * is a superset of runSync — every existing runSync caller keeps working
+ * unchanged when swapped for this wrapper.
+ *
+ * Injection seams (all test-only; production defaults from prefs/env):
+ *   - `paName`      : override the paName that would otherwise come from
+ *                     preferences.json (used by tests and by callers who
+ *                     already resolved it).
+ *   - `hostnameFn`  : function returning the host string (already an
+ *                     injection seam on runSync itself, for scope tests).
+ *   - `statusEnabled: false` disables the status write entirely (kept as
+ *                     a defensive off-switch; not user-facing).
+ *
+ * @param {object} opts  every field runSync accepts, plus `paName`, `statusEnabled`.
+ * @returns {Promise<number>}
+ */
+export async function runSyncWithStatus(opts) {
+  const {
+    repoRoot,
+    runsLog,
+    runner,
+    dryRun = false,
+    hostnameFn,
+    paName: paNameOverride,
+    statusEnabled = true,
+    stderr = process.stderr,
+  } = opts;
+
+  // Resolve paName + host early; if paName is unresolvable we skip the
+  // status write but still run the sync. Host is safe-defaulted.
+  const paName = statusEnabled
+    ? (paNameOverride || (repoRoot ? await readPaName(repoRoot) : null))
+    : null;
+  const host = resolveHost(hostnameFn);
+
+  // Capture HEAD BEFORE the pass — best-effort. A detached HEAD or an
+  // uninitialised repo yields null; the reader treats null as "unknown"
+  // and does not flag on it.
+  let headBefore = null;
+  if (paName && !dryRun && runner) {
+    headBefore = await safeHeadSha(runner, repoRoot);
+  }
+
+  const code = await runSync(opts);
+
+  // Skip status write for dry-run (nothing durable to report), for
+  // missing paName (nowhere to write), and for lock-contended passes
+  // (the pass holding the lock writes its own record; a contender would
+  // race).
+  if (!paName || dryRun) return code;
+
+  try {
+    const audit = await readLastAuditRecord(runsLog);
+    if (!audit) return code;
+    if (audit.status === 'noop-locked') return code;
+
+    const headAfter = await safeHeadSha(runner, repoRoot);
+    const pendingCount = await countPending(join(repoRoot, '.cache/estate-sync/pending'));
+    const record = composeStatusRecord({
+      audit,
+      paName,
+      host,
+      headBefore,
+      headAfter,
+      pendingCount,
+    });
+    await writeStatusRecord({ repoRoot, paName, host, record });
+  } catch (err) {
+    // Never block the sync exit code on a status-write failure. Log
+    // one line so the seam is visible in the cron output.
+    stderr.write(`[estate-sync] warning: failed to write synced status record: ${err && err.message ? err.message : err}\n`);
+  }
+
+  return code;
+}
+
+async function safeHeadSha(runner, repoRoot) {
+  try {
+    const res = await revParseSha(runner, { cwd: repoRoot, ref: 'HEAD' });
+    if (res && res.code === 0 && typeof res.sha === 'string' && res.sha.length > 0) {
+      return res.sha;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function sanitiseSegment(name) {
+  // File-system-safe path segment: keep alnum, dot, dash, underscore.
+  // Anything else collapses to `-`. Empty result falls back to
+  // `unknown`. Prevents a hostname or paName carrying a path separator
+  // from writing outside the intended directory.
+  const cleaned = String(name || '').replace(/[^A-Za-z0-9._-]/g, '-');
+  return cleaned.length > 0 ? cleaned : 'unknown';
+}

package/dist/engineering-pa-core/docs/commands/onboard.md

@@ -0,0 +1,119 @@
+---
+description: First-session onboarding walkthrough — verifies the install, offers optional setup (Atlassian, workspace, alias, profile intake), and marks each step complete.
+when_to_use: >-
+  Run on the operator's first session in a fresh scaffolded PA instance. Also
+  re-runnable any time later: every step is idempotent and reads the current
+  state from `.session/onboarding.json`, so `/onboard` picks up where it left off
+  and skips steps already marked done.
+allowed-tools: Bash, Read, Write, Edit
+argument-hint: (no arguments)
+context: inline
+---
+
+# /onboard — first-session walkthrough
+
+You are running the onboarding walkthrough for a freshly scaffolded PA instance.
+The scaffold has already run `pnpm install` and `pa status` at scaffold time, so
+the install is proven working. Your job is the second half: verify the runtime,
+offer the optional setup steps the guide deliberately left for you, and hand
+over. Every step below is idempotent. State lives in `.session/onboarding.json`
+so re-running `/onboard` picks up where it left off.
+
+## State file
+
+Read `.session/onboarding.json` first. Shape:
+
+```
+{
+  "version": 1,
+  "startedAt": "<iso>",
+  "steps": {
+    "verifyRuntime": "pending" | "done" | "skipped",
+    "verifyVersion": "pending" | "done" | "skipped",
+    "profileIntake": "pending" | "done" | "skipped",
+    "aliasOffer":    "pending" | "done" | "skipped",
+    "workspaceOffer":"pending" | "done" | "skipped",
+    "atlassianOffer":"pending" | "done" | "skipped"
+  },
+  "completedAt": null | "<iso>"
+}
+```
+
+If the file is missing, the scaffold did not seed it — flag that and stop.
+
+If `completedAt` is set, tell the operator onboarding is already complete and
+offer to re-run a specific step by name. Do not walk the whole flow again.
+
+## Flow
+
+Walk the pending steps in this order. After each, write the state file back
+with the step marked `done` or `skipped`. Keep exchanges short: one question,
+one answer, move on.
+
+### 1. verifyRuntime
+
+Run `pnpm exec pa environment` and read the resulting `.session/environment.json`.
+Report Node version, pnpm version, git version, and workspace state in one line.
+If Node is below 24 or pnpm below 9, name the gap and stop; the operator needs
+to upgrade before continuing.
+
+### 2. verifyVersion
+
+Run `pnpm exec pa status` and capture the installed package version. Compare
+against `npm view @stravica-ai/digital-operator-pa version`. On a match, mark
+done and move on. On a mismatch, print both versions and the recovery line
+(`pnpm install` inside the instance) — do not attempt the fix yourself.
+
+### 3. profileIntake
+
+Ask the operator four questions in one turn:
+
+1. Your name and how you prefer to be addressed?
+2. Your role (job title, or "solo", or a short description)?
+3. Communication style you want (formal, casual, direct, verbose)?
+4. Any topic areas the PA should be strong on from day one?
+
+Take the answers and write them into `operator/profile/profile.md`, overwriting
+the placeholder. Keep it a short human-readable paragraph plus a bulleted list
+of preferences. Do not invent fields the operator did not name.
+
+### 4. aliasOffer
+
+The colleague probably has not aliased the PA yet. Offer one line and let them
+decide whether to run it. The exact command is:
+
+```
+echo "alias <pa-name>='cd <target-dir> && pnpm exec pa session'" >> ~/.zshrc && source ~/.zshrc
+```
+
+Substitute `<pa-name>` from `operator/config/preferences.json` and
+`<target-dir>` from `process.cwd()`. If the operator says yes, print the exact
+line to run; do not run it for them (their shell rc is not our file to write).
+
+### 5. workspaceOffer
+
+Ask if they want the local workspace started now. On yes, run
+`pnpm exec pa workspace start` in the background and print the URL from
+`operator/config/preferences.json:workspacePort` (default 4200). On no, note
+that `pnpm exec pa workspace start` is the verb whenever they want it.
+
+### 6. atlassianOffer
+
+Ask if they use Jira or Confluence. On no, mark skipped. On yes, walk them
+through:
+
+```
+pnpm exec secrets set JIRA_DOMAIN <site>          # for <site>.atlassian.net
+pnpm exec secrets set JIRA_EMAIL   <email>
+pnpm exec secrets set JIRA_API_TOKEN <paste-token>  # id.atlassian.com/manage-profile/security/api-tokens
+```
+
+The vault self-initialises on the first `secrets set`. After the three sets,
+run `pnpm exec jira auth` and `pnpm exec confluence auth` and report the
+identity each returns.
+
+## Completion
+
+When every step is done or skipped, write `completedAt` and tell the operator
+onboarding is done. Give them one line: "You are ready. Ask me anything, or
+say `bring me up to speed` and I will run the standard session-boot briefing."

package/dist/engineering-pa-core/knowledge/platform-tooling/workspace-server.md

@@ -33,7 +33,7 @@ The workspace server hosts `viewer.html` — the PA's canonical surface for long
 
 ## Supervisor-aware lifecycle
 
-When the workspace is supervised by launchd (`~/Library/LaunchAgents/com.dave.workspace.plist`) or systemd (`~/.config/systemd/user/dave-workspace.service`), `stop` is refused and `restart` delegates to the supervisor. This is the in-place version-pickup path after `pnpm update @stravica-ai/digital-operator-pa`.
+When the workspace is supervised by launchd (`~/Library/LaunchAgents/com.<paName>.workspace.plist`) or systemd (`~/.config/systemd/user/<paName>-workspace.service`), `stop` is refused and `restart` delegates to the supervisor. This is the in-place version-pickup path after `pnpm update @stravica-ai/digital-operator-pa`. Unit labels follow the scheduler's `com.{agent}.{id}` convention with `id = workspace` and `agent` resolved from `paName` in `operator/config/preferences.json`; pre-0.1.44 installs are still recognised under the legacy `com.dave.workspace` / `dave-workspace.service` name until you run `install-daemon install --migrate` to rename.
 
 ## When to use the workspace
 

package/dist/engineering-pa-library-cli/README.md

@@ -27,6 +27,31 @@ deliberately not a shim for the pre-remote library sweep.
 - `library status [--json]`
   GETs `/status` from the service, plus `git rev-list HEAD..origin/main --count`
   per tier clone.
+- `library up-merge [--repo <owner/name>]... [--pr <number>] [--dry-run] [--once] [--verbose] [--json]`
+  Scheduled auto-merger for library up-path PRs. Scans configured library
+  repos for open PRs from branch `library-sync-up/<device>` and merges each
+  one whose diff is confined to the paths `<device>` owns per
+  `operator/registry/repos.json`. Anything else is a refusal: the PR is
+  left open with a one-time comment (idempotent via an HTML marker) and no
+  merge is ever attempted. Writes one JSONL line per PR per pass to
+  `library.upMerge.eventsLog` (default `.cache/library-up-merger/events.jsonl`).
+  Runs the same in SIMPLE and REMOTE mode (GitHub-side maintenance verb,
+  no ingest touch). Config in the `library.upMerge` stanza; see below.
+
+### Scope rule (verbatim)
+
+```
+A PR is eligible when both:
+  (1) its head branch matches "library-sync-up/<device>"
+  (2) every changed file's repo-relative path falls under a path <device>
+      owns for that library repo per operator/registry/repos.json:
+        for each mount M where M.upPath === true and M.upPathOwner === <device>:
+          allowed prefix = M.from + include, for each include in M.upPathInclude
+        a file matches when its path equals a prefix (single-file include)
+        or starts with prefix + "/" (directory include).
+Any file outside the device's allowed prefixes is a refusal - the PR is
+left open, a one-time comment is posted, and no merge is ever attempted.
+```
 
 ## Configuration
 
@@ -45,6 +70,40 @@ deliberately not a shim for the pre-remote library sweep.
 
 - `LIBRARY_PULL_CLONES_ROOT` env — overrides the pull-clones root at runtime.
 
+- `library.upMerge` stanza in preferences (used by `library up-merge` only):
+
+  ```json
+  {
+    "library": {
+      "upMerge": {
+        "repos": ["Stravica/stravica-library-wsd"],
+        "registryPath": "operator/registry/repos.json",
+        "eventsLog": ".cache/library-up-merger/events.jsonl",
+        "mergeMethod": "merge",
+        "branchPrefix": "library-sync-up/",
+        "deleteBranchOnMerge": true,
+        "ghBin": "gh"
+      }
+    }
+  }
+  ```
+
+  Every field has a safe default; `repos` defaults to `[]` (no repos scanned)
+  and can be overridden per invocation with `--repo <owner/name>` (repeatable).
+
+### Migrating from the HQ `library-up-merger` tool
+
+`library up-merge` is a behaviour-identical promotion of the HQ tool at
+`operator/extensions/tools/library-up-merger/`. The scheduled command
+changes from
+`node operator/extensions/tools/library-up-merger/bin/library-up-merger`
+to `pnpm exec library up-merge`. The scope rule, refusal marker, events
+log path, and default merge method are unchanged; the HQ tool's
+`config.json` maps 1:1 to the `library.upMerge` stanza above (`repos`,
+`registryPath`, `eventsLog`, `mergeMethod`, `branchPrefix`,
+`deleteBranchOnMerge`). Repoint the schedule at the new command and
+retire the HQ tool.
+
 Ingest authenticates by subkey alone (spec §3.4, main ruling 2026-08-20 option b);
 no install-key header is sent. The former `REMOTE_LIBRARY_INSTALL_KEY` env
 interim was removed in the same pass.

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

@@ -22,6 +22,7 @@ import { runGet } from './verbs/get.mjs';
 import { runSearch } from './verbs/search.mjs';
 import { runStatus } from './verbs/status.mjs';
 import { runRefreshClones } from './verbs/refresh-clones.mjs';
+import { runUpMerge } from './verbs/up-merge.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -52,13 +53,15 @@ Usage:
   library search <query> [--files-only]
   library status [--json]
   library refresh-clones [--json] [--timeout-ms <n>] [--tier <name>]...
+  library up-merge [--repo <owner/name>]... [--pr <number>] [--dry-run] [--once] [--verbose] [--json]
   library -h | --help
   library -v | --version
 
 Reads config from operator/config/preferences.json (+ preferences.local.json overlay).
 Verbs are only active in REMOTE mode. SIMPLE mode 'library status' prints a
 one-line mode summary and exits 0; every other verb exits 1 in SIMPLE mode
-with a clean not-applicable message.
+with a clean not-applicable message. 'library up-merge' is a GitHub-side
+maintenance verb and runs in both SIMPLE and REMOTE mode.
 
 --help and --version never touch config or the vault, so they always work
 from a directory with no operator config and no vault installed.
@@ -102,6 +105,18 @@ export async function main(argv, seams = {}) {
   }
 
   if (config.mode === 'simple') {
+    // `library up-merge` is a GitHub-side maintenance verb: it reads
+    // library.upMerge from preferences and hits gh, never the ingest
+    // service. It runs the same in SIMPLE and REMOTE mode.
+    if (verb === 'up-merge') {
+      const ctxUp = { config, log, err };
+      try {
+        return await runUpMerge({ ...ctxUp, args: parseUpMerge(rest) });
+      } catch (e) {
+        err(`[library up-merge] ${e.message ?? e}`);
+        return typeof e.exitCode === 'number' ? e.exitCode : 2;
+      }
+    }
     // `library status` is the one verb useful in SIMPLE mode too: a plain
     // one-line mode summary that tells the operator the CLI is installed
     // and the remote path is intentionally not wired. No vault touch,
@@ -141,6 +156,7 @@ export async function main(argv, seams = {}) {
       case 'search':   return await runSearch({ ...ctx, args: parseSearch(rest) });
       case 'status':   return await runStatus({ ...ctx, args: parseStatus(rest) });
       case 'refresh-clones': return await runRefreshClones({ ...ctx, args: parseRefreshClones(rest) });
+      case 'up-merge': return await runUpMerge({ ...ctx, args: parseUpMerge(rest) });
       default:
         err(`[library] unknown verb: ${verb}`);
         log(USAGE);
@@ -195,6 +211,30 @@ function parseStatus(argv) {
   });
   return { json: values.json };
 }
+function parseUpMerge(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    strict: true,
+    allowPositionals: false,
+    options: {
+      repo:      { type: 'string', multiple: true },
+      pr:        { type: 'string' },
+      'dry-run': { type: 'boolean', default: false },
+      once:      { type: 'boolean', default: false },
+      verbose:   { type: 'boolean', default: false },
+      json:      { type: 'boolean', default: false },
+    },
+  });
+  const pr = values.pr ? parseInt(values.pr, 10) : undefined;
+  return {
+    repos: values.repo,
+    pr,
+    dryRun: values['dry-run'],
+    once: values.once,
+    verbose: values.verbose,
+    json: values.json,
+  };
+}
 function parseRefreshClones(argv) {
   const { values } = parseArgs({
     args: argv,