@stravica-ai/digital-operator-pa 0.1.62 → 0.1.64

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

@@ -137,11 +137,13 @@ roots, else the clone's own. For every mount whose `to` lies under
 `operator/knowledge/writing/`. The legacy `<clone>/operator/knowledge/`
 form is still read during the path migration. On a colliding id the home
 copy wins, then the mapped copy (higher registry `precedence` first), then
-the legacy copy. Within one clone that holds both forms of an id, the
-legacy copy wins over the mapped one until the migration removes it: every
-writer has written the legacy form since the 2026-08-21 cutover, so it is
-the newer copy. A clone with no registry entry is read in the legacy form
-only.
+the legacy copy. Within one clone that holds both forms of an id, the copy
+whose last commit in that clone is newer wins (`git log -1 --format=%ct`,
+read only on such a collision), until the migration removes the legacy
+copies. On a tie, or when either time is unavailable (the clone is not a
+git repo, the file is untracked, git fails), the legacy copy wins. Commit
+times, not file mtimes, because a clone's mtimes are checkout times. A
+clone with no registry entry is read in the legacy form only.
 
 Global flag: `--format <table|json|mermaid>` (default: `table`). The
 `json` shape is stable-by-convention — `{ "verb": "<name>", ... }` —

package/dist/engineering-pa-cli/src/launch/README.md

@@ -82,6 +82,8 @@ The runner spawns the command **directly** — no shell, no expansion, no operat
 
 If the command contains `'` or `"`, `task-loader` rejects it at load time with exit code 2 (a `--dry-run` also fails). This is a deliberate guard: silently splitting `bash -c "a && b"` on whitespace shreds it to `spawn('bash', ['-c', '"a', '&&', 'b"'])`, bash exits 2 with `unexpected EOF`, and cron mails the operator every interval until someone notices.
 
+Shell operators are refused the same way, at load time and in the runner: a command with `;`, `&&`, `||`, `|`, `>`, `<`, `$(`, a backtick or `&` exits 2 with a message naming the schedule id and the offending token. Without a shell the operator would reach the program as a literal argument (`pnpm exec estate-sync run; node ...` handed estate-sync the subcommand `run;`).
+
 If you need shell features, you have two options:
 
 1. **Wrap the work in a script file** and put the script path in `command`: `command: "/path/to/wrapper.sh"`. The runner spawns the script; the script does whatever it likes.

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

@@ -43,6 +43,7 @@ function resolveWorkdir(workdir, repoRoot) {
  * expressions. The string is split on whitespace and passed to spawn()
  * WITHOUT a shell — no quoting, globbing, expansion, or operators are
  * honoured. Any single (') or double (") quote character in the command
+ * or shell operator (; && || | > < $( ` &)
  * is a configuration error: rejected via assertNoShellQuoting with
  * exitCode 2 (task-loader also asserts this at load time so --dry-run
  * catches it; the check here is the chokepoint guarantee for any caller
@@ -58,8 +59,8 @@ function resolveWorkdir(workdir, repoRoot) {
  * @returns {{ bin: string, args: string[] }}
  * @throws  {Error & { exitCode: 2 }} on quoted or empty commands
  */
-function parseCommand(command) {
-  assertNoShellQuoting(command);
+function parseCommand(command, scheduleId) {
+  assertNoShellQuoting(command, scheduleId);
   const parts = command.trim().split(/\s+/);
   if (!parts[0]) {
     const e = new Error('command is empty');
@@ -70,7 +71,7 @@ function parseCommand(command) {
 }
 
 async function defaultSpawner(plan) {
-  const { bin, args } = parseCommand(plan.task.command);
+  const { bin, args } = parseCommand(plan.task.command, plan.task.id);
   const cwd = resolveWorkdir(plan.task.workingDirectory, plan.repoRoot);
   return new Promise((resolve, reject) => {
     const child = spawn(bin, args, { cwd, stdio: 'inherit' });

package/dist/engineering-pa-cli/src/launch/task-loader.mjs

@@ -16,11 +16,17 @@ const REQUIRED_FIELDS = ['id', 'command'];
  * re-asserted by runner.parseCommand as a chokepoint guarantee for
  * programmatic callers.
  *
+ * Shell operators (`;`, `&&`, `||`, `|`, `>`, `<`, `$(`, backticks, `&`)
+ * are refused for the same reason: without a shell they reach the program
+ * as literal args (`pnpm exec estate-sync run; node ...` handed
+ * estate-sync the subcommand `run;` and failed 34 runs in a row).
+ *
  * @param {string} command
+ * @param {string} [scheduleId]  named in the operator refusal message
  * @throws {Error & { exitCode: 2 }} if command is not a non-empty string,
- *   or contains a single (') or double (") quote character
+ *   or contains a single (') or double (") quote character, or a shell operator
  */
-export function assertNoShellQuoting(command) {
+export function assertNoShellQuoting(command, scheduleId) {
   if (typeof command !== 'string') {
     const e = new Error('command must be a string');
     e.exitCode = 2;
@@ -38,6 +44,34 @@ export function assertNoShellQuoting(command) {
     e.exitCode = 2;
     throw e;
   }
+  const op = findShellOperator(command);
+  if (op) {
+    const where = scheduleId ? `schedule "${scheduleId}"` : 'task command';
+    const e = new Error(
+      `${where} contains shell operator ${JSON.stringify(op.operator)} in token ` +
+      `${JSON.stringify(op.token)}: launch runs commands without a shell, so the operator ` +
+      'would reach the program as a literal argument. Wrap the chain in a script file ' +
+      'and invoke the script, or split it into separate schedules.'
+    );
+    e.exitCode = 2;
+    throw e;
+  }
+}
+
+// Multi-char operators first so `&&` is reported as `&&`, not `&`.
+const SHELL_OPERATORS = ['$(', '&&', '||', ';', '|', '>', '<', '`', '&'];
+
+/**
+ * @param {string} command
+ * @returns {{ operator: string, token: string } | null}
+ */
+export function findShellOperator(command) {
+  for (const token of command.trim().split(/\s+/)) {
+    for (const operator of SHELL_OPERATORS) {
+      if (token.includes(operator)) return { operator, token };
+    }
+  }
+  return null;
 }
 
 export async function loadTask(repoRoot, taskId) {
@@ -74,7 +108,7 @@ export async function loadTask(repoRoot, taskId) {
   }
 
   try {
-    assertNoShellQuoting(data.command);
+    assertNoShellQuoting(data.command, data.id ?? taskId);
   } catch (err) {
     const e = new Error(`task "${taskId}": ${err.message}`);
     e.exitCode = err.exitCode ?? 2;

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

@@ -16,6 +16,7 @@ import { resolve } from 'node:path';
 // rewrites this string to a relative path inside the single-bundled
 // tarball.
 import { detect, install, list, remove, verify } from '../../../engineering-pa-core/src/scheduler/index.mjs';
+import { parseTimeoutSeconds } from '../../../engineering-pa-core/src/scheduler/verify.mjs';
 
 const USAGE = `scheduler — operator-facing scheduling primitives
 
@@ -32,7 +33,9 @@ Usage:
                                          field wins (OS-native detect is the fallback).
                                          The label form the list verb prints as a
                                          secondary line is accepted here directly.
-  scheduler verify <schedule.json>      Verify a schedule fires correctly
+  scheduler verify <schedule.json> [--backend N] [--timeout <seconds>]
+                                         Verify a schedule fires correctly.
+                                         --timeout is in seconds (default 120).
   scheduler -h, --help                  Show this help
 
 Schedule files live at <repoRoot>/schedules/<id>.json. The canonical
@@ -189,7 +192,14 @@ export async function run(argv) {
         const schedulePath = resolve(positionals[0]);
         const opts = {};
         if (values.backend) opts.backend = values.backend;
-        if (values.timeout) opts.timeoutMs = parseInt(values.timeout, 10);
+        if (values.timeout !== undefined) {
+          const ms = parseTimeoutSeconds(values.timeout);
+          if (ms === null) {
+            process.stderr.write(`[scheduler] verify: --timeout requires a positive number of seconds, got: ${values.timeout}\n`);
+            return 1;
+          }
+          opts.timeoutMs = ms;
+        }
         const result = await verify(schedulePath, opts);
         process.stdout.write(JSON.stringify(result, null, 2) + '\n');
         return result.exitCode ?? (result.ok ? 0 : 2);

package/dist/engineering-pa-core/docs/tools/scheduler.md

@@ -110,9 +110,9 @@ Proven live (w-2026-07-15-003, verified with `env -i`): cron's crond process pro
 
 The generated cron line handles this for you automatically: `scheduler install` detects `$HOME/.nvm/nvm.sh` on the target AT INSTALL TIME and, if present, sources it inside the rendered chain. The generated cron line is `bash -c '{ date -u; . $HOME/.nvm/nvm.sh && cd <workDir> && <command>; } >> /tmp/<agent>-<id>.log 2>&1'`; the `{ ...; }` braces are load-bearing: without them the `>> log 2>&1` binds only to `<command>` and any earlier link failing (nvm-source, cd) sends its stderr to cron mail, which hosts with no MTA silently discard (w-2026-09-13-dave-042; 0.1.39 fix, smarthome01 crons fired but wrote no log 2026-09-09 -> 13). The leading `date -u` prints an ISO timestamp so a run that dies mid-chain still leaves dated evidence. If no nvm install is found, the preamble is simply omitted; nothing to do for schedules that only need system binaries. `environment.*` values are emitted as `export VAR='val';` statements ahead of the command (not a bare `VAR='val' cd ...` prefix, which in POSIX shell only scopes to the `cd` builtin and never actually reaches the command after `&&`; a real, silent bug the old generator had).
 
-`scheduler verify` now runs this EXACT generated line (not a bare `sched.command`), under cron's actual minimal environment; never the verifying shell's `process.env`. This is deliberate: the old verify path inherited the operator's full login-shell env, which reliably masked this whole bug class. If `verify` reports `ok` today, that's an honest signal the schedule will actually fire under real cron.
+`scheduler verify` now runs this EXACT generated line (not a bare `sched.command`), under cron's actual minimal environment; never the verifying shell's `process.env`. This is deliberate: the old verify path inherited the operator's full login-shell env, which reliably masked this whole bug class. If `verify` reports `ok` today, that's an honest signal the schedule will actually fire under real cron. The cron verify PATH is cron's base `/usr/bin:/bin`, then `/usr/local/bin`, then the PATH entries of `/etc/environment` when that file exists, because Debian cron reads `/etc/environment` through pam_env (w-2026-10-17-dave-007). A `PATH` in the schedule's own `environment` still replaces it. The result JSON carries the PATH used as `path`.
 
-**Quoting and `%` (w-2026-10-17-dave-006, 0.1.62).** cron hands the command field to `/bin/sh -c`, so the `bash -c` wrapper is single-quoted, with any single quote inside rendered as `'\''` (the same rule the systemd backend uses for `ExecStart`). sh therefore passes the inner script to bash untouched and every `$(...)`, `$1` and `${VAR}` is expanded by bash after the `cd`, not by sh in the cron user's HOME. The old double-quoted wrapper let sh expand them first (smarthome01 workspace-refresh failed 162 of 162 runs with `fatal: ambiguous argument 'origin/'`). cron also turns an unescaped `%` into a newline and feeds the rest of the line to stdin, so every `%` in the rendered line is written as `\%`; cron strips the backslash before sh sees it. `scheduler verify` on the cron backend runs the rendered command the way cron does: it takes the full `bash -c '...'` string, undoes the `\%` escaping, and executes it through `/bin/sh -c` from the working directory, so a quoting or `%` defect shows up in verify. Write schedule `command` strings exactly as you would type them into bash in the working directory: no `\$` or `\%` workarounds. Lines installed by 0.1.61 or earlier keep the double-quoted form until the schedule is re-installed; `list`, `remove` and `install` match both forms by the trailing `# <agent>-<id>` tag. The systemd backend does not escape `%` in `ExecStart`, so systemd still reads `%` as a unit specifier there.
+**Quoting and `%` (w-2026-10-17-dave-006, 0.1.62).** cron hands the command field to `/bin/sh -c`, so the `bash -c` wrapper is single-quoted, with any single quote inside rendered as `'\''` (the same rule the systemd backend uses for `ExecStart`). sh therefore passes the inner script to bash untouched and every `$(...)`, `$1` and `${VAR}` is expanded by bash after the `cd`, not by sh in the cron user's HOME. The old double-quoted wrapper let sh expand them first (smarthome01 workspace-refresh failed 162 of 162 runs with `fatal: ambiguous argument 'origin/'`). cron also turns an unescaped `%` into a newline and feeds the rest of the line to stdin, so every `%` in the rendered line is written as `\%`; cron strips the backslash before sh sees it. `scheduler verify` on the cron backend runs the rendered command the way cron does: it takes the full `bash -c '...'` string, undoes the `\%` escaping, and executes it through `/bin/sh -c` from the working directory, so a quoting or `%` defect shows up in verify. Write schedule `command` strings exactly as you would type them into bash in the working directory: no `\$` or `\%` workarounds. Lines installed by 0.1.61 or earlier keep the double-quoted form until the schedule is re-installed; `list`, `remove` and `install` match both forms by the trailing `# <agent>-<id>` tag. The tag must end the line (w-2026-10-17-dave-007), so an id that is a prefix of another (`dave-foo` against `dave-foo-bar`) matches only its own line. When a schedule's `agent` field changes, `install` also removes the line with the same id under the old agent prefix and prints one line naming both tags. The systemd backend escapes `%` as `%%` and `$` as `$$` in `ExecStart` (w-2026-10-17-dave-007), because systemd resolves `%` specifiers and expands `$VAR` and `${VAR}` itself, inside single quotes too, before bash sees the command; bash then receives the command exactly as written.
 
 ### Verify your schedule before walking away
 
@@ -156,7 +156,7 @@ After installing, run the schedule's command once under the same environment the
 node core/tools/scheduler/verify.mjs schedules/my-task.json launchd
 ```
 
-If the backend is omitted, verify auto-detects (the same way `detect.mjs` does). Default timeout is 30 seconds; override with `--timeout`:
+If the backend is omitted, verify auto-detects (the same way `detect.mjs` does). Default timeout is 120 seconds; override with `--timeout`, which is in seconds on both `pa scheduler verify` and `verify.mjs` (w-2026-10-17-dave-007; the `pa` CLI used to read it as milliseconds):
 
 ```bash
 node core/tools/scheduler/verify.mjs schedules/long-job.json launchd --timeout 60

package/dist/engineering-pa-core/src/knowledge/retrieval/links.mjs

@@ -33,6 +33,7 @@
 // nowhere does not describe the estate — it inflates it, and every orphan
 // statistic computed over it is wrong in both directions.
 
+import { execFileSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { readdir } from 'node:fs/promises';
 import { join, normalize, posix, relative } from 'node:path';
@@ -66,8 +67,9 @@ export const KNOWLEDGE_SCAN_DIRS = ['operator/knowledge', 'core/knowledge'];
 // composes at `operator/knowledge/` (or `operator/knowledge/wsd/`, and
 // `<clone>/voice/` at `operator/knowledge/writing/`) exactly as the registry
 // says. Across clones a mapped copy beats a legacy one; within one clone the
-// legacy `<clone>/operator/knowledge/` copy beats the mapped copy during the
-// migration bridge (`legacySupersedes`); home still beats both. See
+// copy with the newer last commit wins during the migration bridge, the
+// legacy `<clone>/operator/knowledge/` copy on a tie or when a commit time is
+// unavailable (`legacySupersedes`); home still beats both. See
 // `scanSourcesFor` and mounts.mjs.
 export const EXTRA_SCAN_ROOTS_ENV = 'LIBRARY_KNOWLEDGE_EXTRA_ROOTS';
 
@@ -193,9 +195,10 @@ export function scanDirsFor(root) {
  *      exactly the ids this function produced before mounts were read.
  *
  * So the home copy beats both forms, and a mapped copy beats another clone's
- * legacy copy of the same id. Within ONE clone the legacy copy beats the
- * mapped one; the order cannot say that, so the collision step applies it
- * (`legacySupersedes`, `collectScannedFiles`). A clone with no registry entry
+ * legacy copy of the same id. Within ONE clone the copy whose last commit
+ * is newer wins (legacy on a tie or an unavailable time); the order cannot
+ * say that, so the collision step applies it (`legacySupersedes`,
+ * `collectScannedFiles`). A clone with no registry entry
  * contributes its legacy form only.
  *
  * @param {string} root the home workspace root
@@ -258,35 +261,92 @@ export function scanIdFor(scan, abs) {
 }
 
 // slice 3 removes: the within-tier bridge rule. The scan order cannot carry
-// it, because "legacy first within a clone" and "mapped first across clones"
-// are not one order: with copies in A legacy, A mapped and B mapped (A of
-// higher precedence) the two rules cycle. So the order picks the winning
-// TIER (first occurrence: home, mapped by precedence, legacy), and this rule
-// then swaps a mapped winner for the same clone's legacy copy. Every writer
-// wrote the legacy form after the 2026-08-21 cutover, so where one clone
-// holds both, the legacy copy is the newer (all 25 hq merge rows).
+// it, because "one form first within a clone" and "mapped first across
+// clones" are not one order: with copies in A legacy, A mapped and B mapped
+// (A of higher precedence) the two rules cycle. So the order picks the
+// winning TIER (first occurrence: home, mapped by precedence, legacy), and
+// this rule then decides between that clone's own two copies: the copy whose
+// last commit in the clone is newer wins. On a tie, or when either commit
+// time is unavailable (not a git clone, untracked file, git error), the
+// legacy copy wins, which was the slice 1 rule: every writer took the legacy
+// form between the 2026-08-21 cutover and slice 2, which moved the writers
+// to the mounted form. Commit times, not mtimes: a clone's mtimes are
+// checkout times, while commit times are the same on every host.
+
+/**
+ * Unix seconds of the last commit that touched `abs` in the clone at
+ * `root`, or null when there is none to read: `root` is not a git clone,
+ * the file is untracked, or git fails.
+ *
+ * @param {string} root clone root
+ * @param {string} abs absolute path of a file under `root`
+ * @returns {number|null}
+ */
+export function lastCommitTime(root, abs) {
+  // `git -C` would climb into an enclosing repo; only the clone's own
+  // history counts.
+  if (!existsSync(join(root, '.git'))) return null;
+  try {
+    const out = execFileSync(
+      'git',
+      ['-C', root, 'log', '-1', '--format=%ct', '--', toPosix(relative(root, abs))],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+    ).trim();
+    return /^\d+$/.test(out) ? Number(out) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * `lastCommitTime` memoised per path, for the life of one scan.
+ *
+ * @returns {(root: string, abs: string) => number|null}
+ */
+export function memoCommitTime(lookup = lastCommitTime) {
+  const memo = new Map();
+  return (root, abs) => {
+    if (!memo.has(abs)) memo.set(abs, lookup(root, abs));
+    return memo.get(abs);
+  };
+}
+
 /**
  * True when `candidate` (met later in scan order) should replace `winner`,
- * the scan that first claimed the same id.
+ * the scan that first claimed the same id. Only a clone's legacy copy can
+ * replace that same clone's mapped copy, and it does unless the mapped copy's
+ * last commit is strictly newer. Commit times are read only here, so only on
+ * a within-clone collision.
  *
  * @param {ReturnType<typeof scanSourcesFor>[number]} winner
+ * @param {string} winnerAbs the file `winner` holds for the id
  * @param {ReturnType<typeof scanSourcesFor>[number]} candidate
+ * @param {string} candidateAbs the file `candidate` holds for the id
+ * @param {(root: string, abs: string) => number|null} commitTime
  */
-export function legacySupersedes(winner, candidate) {
-  return winner.form === 'mapped' && candidate.form === 'legacy'
-    && winner.sourceRoot === candidate.sourceRoot;
+export function legacySupersedes(winner, winnerAbs, candidate, candidateAbs, commitTime) {
+  if (winner.form !== 'mapped' || candidate.form !== 'legacy'
+    || winner.sourceRoot !== candidate.sourceRoot) return false;
+  const mappedAt = commitTime(winner.sourceRoot, winnerAbs);
+  const legacyAt = commitTime(candidate.sourceRoot, candidateAbs);
+  if (mappedAt === null || legacyAt === null) return true;
+  return legacyAt >= mappedAt;
 }
 
 /**
  * Walk every scan and keep one file per workspace id: the first occurrence,
- * except that a clone's legacy copy replaces that clone's mapped copy
+ * except that within one clone the copy with the newer last commit wins
  * (`legacySupersedes`). A replaced entry keeps its position, so the entry
  * order is still scan order of first occurrence.
  *
  * @param {ReturnType<typeof scanSourcesFor>} scans
+ * @param {object} [opts]
+ * @param {(root: string, abs: string) => number|null} [opts.commitTime]
+ *   override the memoised git lookup (tests, timing)
  * @returns {Promise<{ abs: string, id: string, scan: object }[]>}
  */
-export async function collectScannedFiles(scans) {
+export async function collectScannedFiles(scans, opts = {}) {
+  const commitTime = opts.commitTime ?? memoCommitTime();
   const entries = [];
   const byId = new Map();
   for (const scan of scans) {
@@ -297,7 +357,7 @@ export async function collectScannedFiles(scans) {
         const entry = { abs, id, scan };
         byId.set(id, entry);
         entries.push(entry);
-      } else if (legacySupersedes(existing.scan, scan)) {
+      } else if (legacySupersedes(existing.scan, existing.abs, scan, abs, commitTime)) {
         existing.abs = abs;
         existing.scan = scan;
       }
@@ -308,14 +368,18 @@ export async function collectScannedFiles(scans) {
 
 /**
  * The on-disk file that backs a workspace id, under the same precedence the
- * builders apply (including `legacySupersedes`), or null. Lets body readers (`pa knowledge search --full`)
- * open the copy the graph actually indexed.
+ * builders apply (including `legacySupersedes`), or null. Lets body readers
+ * (`pa knowledge search --full`) open the copy the graph actually indexed.
  *
  * @param {ReturnType<typeof scanSourcesFor>} scans
  * @param {string} id
+ * @param {object} [opts]
+ * @param {(root: string, abs: string) => number|null} [opts.commitTime]
+ *   override the memoised git lookup (tests, timing)
  * @returns {string|null}
  */
-export function locateScannedFile(scans, id) {
+export function locateScannedFile(scans, id, opts = {}) {
+  const commitTime = opts.commitTime ?? memoCommitTime();
   const posixId = toPosix(id);
   const fileIn = (scan) => {
     if (!posixId.startsWith(scan.idPrefix)) return null;
@@ -328,9 +392,9 @@ export function locateScannedFile(scans, id) {
     const found = fileIn(scan);
     if (!found) continue;
     for (const later of scans.slice(i + 1)) {
-      if (!legacySupersedes(scan, later)) continue;
+      if (later.form !== 'legacy' || later.sourceRoot !== scan.sourceRoot) continue;
       const legacy = fileIn(later);
-      if (legacy) return legacy;
+      if (legacy && legacySupersedes(scan, found, later, legacy, commitTime)) return legacy;
     }
     return found;
   }

package/dist/engineering-pa-core/src/knowledge/retrieval/mount-map.mjs

@@ -0,0 +1,169 @@
+// Vendored from Stravica/remote-library, src/mounts/mount-map.ts, compiled at 2add6c77a58664981771e71e0cdf0db8def64f66.
+// Do not edit here; change the source and re-vendor.
+// Same fixture in both repos (test/knowledge/fixtures/mount-map-cases.json) proves it is one map.
+// Shared mount map (w-2026-10-16-dave-019, library-sync slice 2).
+//
+// One answer, used by every writer and gate, to "which tier path does a
+// registry mount read for this workspace path, and back". The registry is
+// `registry/repos.json` from the company tier: `repos.<repoKey>.mounts[]`,
+// each `{ from, to }` where `from` is the path inside the tier repo and `to`
+// is the workspace path it composes at.
+//
+// PURE by contract: this file has no imports at all (not even node:path) and
+// works on POSIX path strings only, so its compiled `dist/mounts/mount-map.js`
+// can be vendored unchanged into other repos. Keep it that way.
+export const KNOWLEDGE_TO_PREFIX = "operator/knowledge/";
+function stripDotSlash(p) {
+    let out = p;
+    while (out.startsWith("./"))
+        out = out.slice(2);
+    return out;
+}
+function hasUnsafeSegment(p) {
+    return p.split("/").some((seg) => seg === "..");
+}
+// Normalise a mount side to `a/b/` form. Null when it cannot be a safe
+// relative directory (empty, absolute, or holding a `..` segment).
+function normaliseMountSide(raw) {
+    if (typeof raw !== "string")
+        return null;
+    let p = stripDotSlash(raw.trim());
+    if (p === "" || p.startsWith("/") || p.includes("\\"))
+        return null;
+    if (hasUnsafeSegment(p))
+        return null;
+    if (!p.endsWith("/"))
+        p += "/";
+    return p;
+}
+// Normalise an input file path. Null when it is not a safe relative file
+// path: empty, absolute, a directory (trailing `/`), or holding an empty,
+// `.` or `..` segment.
+function normaliseFilePath(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const p = stripDotSlash(raw);
+    if (p === "" || p.startsWith("/") || p.endsWith("/") || p.includes("\\"))
+        return null;
+    if (p.includes("\0"))
+        return null;
+    for (const seg of p.split("/")) {
+        if (seg === "" || seg === "." || seg === "..")
+            return null;
+    }
+    return p;
+}
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+// Longest-prefix mount for `path` on the given side, with the remainder.
+function longestMatch(mounts, path, side) {
+    let best = null;
+    for (const m of mounts) {
+        if (!path.startsWith(m[side]))
+            continue;
+        if (best === null || m[side].length > best[side].length)
+            best = m;
+    }
+    if (best === null)
+        return null;
+    const rest = path.slice(best[side].length);
+    if (rest === "")
+        return null;
+    return { mount: best, rest };
+}
+export function createMountMap(registry, opts) {
+    const toPrefix = opts?.toPrefix ?? KNOWLEDGE_TO_PREFIX;
+    const byRepo = new Map();
+    const repoEntries = isObject(registry) && isObject(registry.repos) ? registry.repos : {};
+    for (const [repoKey, entry] of Object.entries(repoEntries)) {
+        const kept = [];
+        const rawMounts = isObject(entry) && Array.isArray(entry.mounts) ? entry.mounts : [];
+        for (const raw of rawMounts) {
+            if (!isObject(raw))
+                continue;
+            const from = normaliseMountSide(raw.from);
+            const to = normaliseMountSide(raw.to);
+            if (from === null || to === null)
+                continue;
+            if (!to.startsWith(toPrefix))
+                continue;
+            kept.push({ from, to });
+        }
+        byRepo.set(repoKey, kept);
+    }
+    const mountsFor = (repo) => (byRepo.get(repo) ?? []).map((m) => ({ from: m.from, to: m.to }));
+    const toLibraryPath = (repo, workspacePath) => {
+        const p = normaliseFilePath(workspacePath);
+        if (p === null)
+            return null;
+        const hit = longestMatch(byRepo.get(repo) ?? [], p, "to");
+        return hit === null ? null : hit.mount.from + hit.rest;
+    };
+    const toWorkspacePath = (repo, libraryPath) => {
+        const p = normaliseFilePath(libraryPath);
+        if (p === null)
+            return null;
+        const hit = longestMatch(byRepo.get(repo) ?? [], p, "from");
+        return hit === null ? null : hit.mount.to + hit.rest;
+    };
+    const resolveRepoKey = (tier) => {
+        if (typeof tier !== "string" || tier === "")
+            return null;
+        if (byRepo.has(tier))
+            return tier;
+        const suffix = `-${tier}`;
+        const hits = [...byRepo.keys()].filter((k) => k.endsWith(suffix));
+        return hits.length === 1 ? hits[0] : null;
+    };
+    return {
+        repos: () => [...byRepo.keys()],
+        mountsFor,
+        toLibraryPath,
+        toWorkspacePath,
+        isReadable: (repo, libraryPath) => toWorkspacePath(repo, libraryPath) !== null,
+        resolveRepoKey,
+    };
+}
+export function resolveWrite(map, workspacePath, assertedTier) {
+    const triedFor = (repo) => map.mountsFor(repo).map((m) => ({ repo, from: m.from, to: m.to }));
+    if (assertedTier !== undefined && assertedTier !== "") {
+        const repo = map.resolveRepoKey(assertedTier);
+        if (repo === null)
+            return { ok: false, reason: "unknown-tier", tried: [] };
+        const libraryPath = map.toLibraryPath(repo, workspacePath);
+        if (libraryPath === null)
+            return { ok: false, reason: "unmapped", tried: triedFor(repo) };
+        return { ok: true, repo, libraryPath };
+    }
+    const p = normaliseFilePath(workspacePath);
+    const candidates = [];
+    const tried = [];
+    for (const repo of map.repos()) {
+        tried.push(...triedFor(repo));
+        if (p === null)
+            continue;
+        const libraryPath = map.toLibraryPath(repo, p);
+        if (libraryPath === null)
+            continue;
+        const mount = map
+            .mountsFor(repo)
+            .filter((m) => p.startsWith(m.to))
+            .reduce((a, b) => (b.to.length > a.to.length ? b : a));
+        candidates.push({ repo, mount, libraryPath });
+    }
+    if (candidates.length === 0)
+        return { ok: false, reason: "unmapped", tried };
+    const longest = Math.max(...candidates.map((c) => c.mount.to.length));
+    const best = candidates.filter((c) => c.mount.to.length === longest);
+    if (best.length === 1)
+        return { ok: true, repo: best[0].repo, libraryPath: best[0].libraryPath };
+    const paths = new Set(best.map((c) => c.libraryPath));
+    if (paths.size === 1)
+        return { ok: true, repo: null, libraryPath: best[0].libraryPath };
+    return {
+        ok: false,
+        reason: "ambiguous",
+        tried: best.map((c) => ({ repo: c.repo, from: c.mount.from, to: c.mount.to })),
+    };
+}

package/dist/engineering-pa-core/src/knowledge/retrieval/mounts.mjs

@@ -22,6 +22,9 @@
 //      `registry/`, the registry source of truth);
 //   2. else the clone's own `registry/repos.json`;
 //   3. else no registry: the clone is scanned in the legacy form only.
+//
+// `loadWriteRegistry` gives `library put` its registry by the same company
+// rule, falling back to the workspace copy (slice 2).
 
 import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
@@ -147,15 +150,7 @@ function mountsRegistry(entry) {
 export function resolveTierMounts(extraRoots, { remoteOf = gitRemoteOf } = {}) {
   const own = new Map();
   for (const root of extraRoots) own.set(root, readRegistry(root));
-
-  // The company clone is the registry's own source: its entry mounts
-  // `registry/`. Prefer its copy over each clone's (possibly drifted) one.
-  let company = null;
-  for (const root of extraRoots) {
-    const registry = own.get(root);
-    const self = resolveRepoEntry(registry, root, { remoteOf });
-    if (self && mountsRegistry(self.entry)) { company = registry; break; }
-  }
+  const company = findCompanyRegistry(extraRoots, { remoteOf, read: (root) => own.get(root) })?.registry ?? null;
 
   return extraRoots.map((root) => {
     let hit = null;
@@ -182,3 +177,61 @@ export function resolveTierMounts(extraRoots, { remoteOf = gitRemoteOf } = {}) {
     };
   });
 }
+
+/**
+ * The company clone among `roots`: the clone whose own registry entry mounts
+ * `registry/`, the registry's source of truth. Its copy is preferred over
+ * every other (possibly drifted) one.
+ *
+ * @param {string[]} roots
+ * @param {object} [opts]
+ * @param {(root: string) => string|null} [opts.remoteOf]
+ * @param {(root: string) => object|null} [opts.read] registry reader seam
+ * @returns {{ root: string, registry: object } | null}
+ */
+export function findCompanyRegistry(roots, { remoteOf = gitRemoteOf, read = readRegistry } = {}) {
+  for (const root of roots) {
+    const registry = read(root);
+    const self = resolveRepoEntry(registry, root, { remoteOf });
+    if (self && mountsRegistry(self.entry)) return { root, registry };
+  }
+  return null;
+}
+
+/**
+ * The registry `library put` maps knowledge paths through
+ * (w-2026-10-16-dave-019, slice 2). Source order:
+ *   1. the company clone among the extra roots (LIBRARY_KNOWLEDGE_EXTRA_ROOTS);
+ *   2. else the workspace copy, `<repoRoot>/operator/registry/repos.json`;
+ *   3. else none.
+ * `looked` names every place tried, so a refusal can print it.
+ *
+ * @param {object} opts
+ * @param {string[]} opts.extraRoots
+ * @param {string} opts.repoRoot
+ * @param {(root: string) => string|null} [opts.remoteOf]
+ * @returns {{ registry: object|null, source: 'company'|'workspace'|null, path: string|null, looked: string[] }}
+ */
+export function loadWriteRegistry({ extraRoots, repoRoot, remoteOf = gitRemoteOf }) {
+  const looked = [];
+  if (extraRoots.length) {
+    looked.push(`company clone among ${extraRoots.length} extra root(s) (${extraRoots.join(':')})`);
+    const company = findCompanyRegistry(extraRoots, { remoteOf });
+    if (company) {
+      return {
+        registry: company.registry,
+        source: 'company',
+        path: join(company.root, ...REGISTRY_RELATIVE_PATH.split('/')),
+        looked,
+      };
+    }
+  } else {
+    looked.push('company clone (LIBRARY_KNOWLEDGE_EXTRA_ROOTS unset)');
+  }
+  const operatorDir = join(repoRoot, 'operator');
+  const workspacePath = join(operatorDir, ...REGISTRY_RELATIVE_PATH.split('/'));
+  looked.push(workspacePath);
+  const workspace = readRegistry(operatorDir);
+  if (workspace) return { registry: workspace, source: 'workspace', path: workspacePath, looked };
+  return { registry: null, source: null, path: null, looked };
+}

package/dist/engineering-pa-core/src/scheduler/install.mjs

@@ -494,6 +494,44 @@ export function buildCronLine(sched, workDir, env, opts = {}) {
   return `${sched.schedule} ${cronField} # ${tag}`;
 }
 
+/**
+ * True when a crontab line carries `tag` (`# <agent>-<id>`) as its trailing
+ * comment. Anchored to the end of the line so `# dave-foo` does not also
+ * match `# dave-foo-bar` (w-2026-10-17-dave-007 item 2).
+ * @param {string} line
+ * @param {string} tag
+ * @returns {boolean}
+ */
+export function cronLineHasTag(line, tag) {
+  return line.trimEnd().endsWith(tag);
+}
+
+/**
+ * True when a crontab line ends in any `# <agent>-<suffix>` tag for `agent`.
+ * @param {string} line
+ * @param {string} agent
+ * @returns {boolean}
+ */
+export function cronLineHasAgentTag(line, agent) {
+  return /# (\S+)$/.exec(line.trimEnd())?.[1].startsWith(`${agent}-`) ?? false;
+}
+
+/**
+ * The tag of a crontab line installed for the same schedule id under a
+ * different agent (`# sam-<id>` when installing `# dave-<id>`), or null.
+ * The other agent prefix must be a single hyphen-free word so `# dave-foo-bar`
+ * is never read as agent `dave-foo` with id `bar` (w-2026-10-17-dave-007 item 5).
+ * @param {string} line
+ * @param {string} agent
+ * @param {string} id
+ * @returns {string | null}
+ */
+export function otherAgentCronTag(line, agent, id) {
+  const m = /# ([A-Za-z0-9_]+)-(\S+)$/.exec(line.trimEnd());
+  if (!m || m[2] !== id || m[1] === agent) return null;
+  return `${m[1]}-${m[2]}`;
+}
+
 function installCron(sched, workDir) {
   const agent = schedAgent(sched);
   const env = resolveEnvironment(sched);
@@ -508,10 +546,17 @@ function installCron(sched, workDir) {
     // no crontab yet
   }
 
-  // Remove any existing entry for this schedule
+  // Remove any existing entry for this schedule, including one left under
+  // another agent prefix when the schedule's `agent` field changed.
   const filtered = existing
     .split('\n')
-    .filter(line => !line.includes(tag))
+    .filter((line) => {
+      if (cronLineHasTag(line, tag)) return false;
+      const other = otherAgentCronTag(line, agent, sched.id);
+      if (!other) return true;
+      console.log(`Removed cron line tagged ${other}; replaced by ${agent}-${sched.id} (agent changed)`);
+      return false;
+    })
     .join('\n')
     .replace(/^\n+|\n+$/g, '');
 
@@ -843,6 +888,23 @@ function installLaunchd(sched, workDir, cron) {
 
 // ── Backend: systemd ─────────────────────────────────────────────────
 
+/**
+ * Escape a command for systemd's ExecStart parser. systemd resolves `%`
+ * specifiers when the unit is loaded and expands `$VAR` / `${VAR}` itself,
+ * inside single quotes too, before bash ever sees the line. `%%` is a
+ * literal percent and `$$` a literal dollar (systemd.unit(5) Specifiers,
+ * systemd.service(5) Command lines). The single quote is escaped for the
+ * `bash -c '...'` wrapper.
+ * @param {string} command
+ * @returns {string}
+ */
+export function escapeSystemdExecCommand(command) {
+  return command
+    .replace(/%/g, '%%')
+    .replace(/\$/g, '$$$$')
+    .replace(/'/g, `'\\''`);
+}
+
 /**
  * Build the .service unit contents.
  * @param {object} sched
@@ -862,7 +924,7 @@ Description=${description}
 [Service]
 Type=oneshot
 WorkingDirectory=${workDir}
-${envBlock}ExecStart=/usr/bin/env bash -c '${sched.command.replace(/'/g, `'\\''`)}'
+${envBlock}ExecStart=/usr/bin/env bash -c '${escapeSystemdExecCommand(sched.command)}'
 
 [Install]
 WantedBy=default.target

package/dist/engineering-pa-core/src/scheduler/list.mjs

@@ -24,7 +24,7 @@ import { resolveHome } from '../home/resolve.mjs';
 import { execSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { detect } from './detect.mjs';
-import { launchdLabelPrefix } from './install.mjs';
+import { launchdLabelPrefix, cronLineHasAgentTag } from './install.mjs';
 import { resolveAgent } from './resolve-agent.mjs';
 
 /**
@@ -70,12 +70,10 @@ export function list(backend, opts = {}) {
 function listCron(agent) {
   const lines = [`${headerName(agent)} schedules (cron):`, '─'.repeat(37)];
   let found = false;
-  const tag = `# ${agent}-`;
-
   try {
     const crontab = execSync('crontab -l 2>/dev/null', { encoding: 'utf8' });
     for (const line of crontab.split('\n')) {
-      if (line.includes(tag)) {
+      if (cronLineHasAgentTag(line, agent)) {
         lines.push(`  ${line}`);
         found = true;
       }

package/dist/engineering-pa-core/src/scheduler/remove.mjs

@@ -23,7 +23,7 @@ import { join, resolve, dirname } from 'node:path';
 import { resolveHome } from '../home/resolve.mjs';
 import { execSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { launchdLabelPrefix } from './install.mjs';
+import { launchdLabelPrefix, cronLineHasTag } from './install.mjs';
 import { findRepoRootSync, walkUpForMarker } from '../instance-root/find.mjs';
 import { resolveAgent } from './resolve-agent.mjs';
 import { detect } from './detect.mjs';
@@ -44,7 +44,7 @@ function removeCron(schedId, agent) {
   }
 
   const lines = existing.split('\n');
-  const filtered = lines.filter(line => !line.includes(tag)).join('\n').replace(/^\n+|\n+$/g, '');
+  const filtered = lines.filter(line => !cronLineHasTag(line, tag)).join('\n').replace(/^\n+|\n+$/g, '');
 
   if (filtered === existing.replace(/^\n+|\n+$/g, '')) {
     console.log(`No cron entry found for ${agent}-${schedId}`);

package/dist/engineering-pa-core/src/scheduler/verify.mjs

@@ -11,7 +11,7 @@
  *
  * The verify deliberately does not require the schedule to be installed already —
  * it derives the env the same way install.mjs does and runs the command once. A
- * timeout (default 30s) bounds the run; verify is meant for "does this schedule
+ * timeout (default 120s) bounds the run; verify is meant for "does this schedule
  * even start?" not "does it complete its full work?".
  *
  * Backend defaults to the auto-detected backend for the host (launchd on macOS,
@@ -25,7 +25,7 @@
  *   4  timeout                — command did not finish within the timeout
  */
 
-import { readFileSync, realpathSync } from 'node:fs';
+import { readFileSync, realpathSync, existsSync } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { resolve, dirname, join } from 'node:path';
 import { resolveHome } from '../home/resolve.mjs';
@@ -68,6 +68,54 @@ export function minimalCronEnv({ home = resolveHome(), user = process.env.USER |
   };
 }
 
+/** Default `scheduler verify --timeout`, in seconds (both CLI paths). */
+export const DEFAULT_VERIFY_TIMEOUT_SECONDS = 120;
+
+/**
+ * Parse a `--timeout` value given in seconds into milliseconds. Both the
+ * `pa scheduler verify` CLI and this module's own CLI read seconds
+ * (w-2026-10-17-dave-007 item 3).
+ * @param {string | number} value
+ * @returns {number | null} milliseconds, or null when not a positive number
+ */
+export function parseTimeoutSeconds(value) {
+  const n = Number(value);
+  if (value === '' || value == null || !Number.isFinite(n) || n <= 0) return null;
+  return Math.round(n * 1000);
+}
+
+/**
+ * Read the PATH entries from an `/etc/environment`-format file (pam_env
+ * hands this to cron jobs on Debian). Returns [] when the file is absent
+ * or carries no PATH line.
+ * @param {string} file
+ * @returns {string[]}
+ */
+export function readEtcEnvironmentPath(file) {
+  if (!existsSync(file)) return [];
+  let pathValue = null;
+  for (const raw of readFileSync(file, 'utf8').split('\n')) {
+    const m = /^\s*(?:export\s+)?PATH\s*=\s*(.*?)\s*$/.exec(raw);
+    if (m) pathValue = m[1].replace(/^(["'])(.*)\1$/, '$2');
+  }
+  return pathValue ? pathValue.split(':').filter(Boolean) : [];
+}
+
+/**
+ * The PATH verify uses for the cron backend: cron's minimal base, then
+ * `/usr/local/bin`, then the PATH entries of `/etc/environment` when it
+ * exists, without duplicates (w-2026-10-17-dave-007 item 4). Real cron on
+ * Debian gets `/etc/environment` through pam_env, so the bare base alone
+ * was stricter than the runtime.
+ * @param {string} basePath
+ * @param {string} [etcEnvironmentFile]
+ * @returns {string}
+ */
+export function composeCronVerifyPath(basePath, etcEnvironmentFile = '/etc/environment') {
+  const entries = [...basePath.split(':'), '/usr/local/bin', ...readEtcEnvironmentPath(etcEnvironmentFile)];
+  return [...new Set(entries.filter(Boolean))].join(':');
+}
+
 /**
  * Compute the env the named backend would install for this schedule.
  *
@@ -88,9 +136,11 @@ export function minimalCronEnv({ home = resolveHome(), user = process.env.USER |
  *
  * @param {object} sched
  * @param {string} backend
+ * @param {object} [opts]
+ * @param {string} [opts.etcEnvironmentFile] - cron only; defaults to /etc/environment
  * @returns {Record<string,string>}
  */
-export function computeBackendEnv(sched, backend) {
+export function computeBackendEnv(sched, backend, opts = {}) {
   const explicit = resolveEnvironment(sched);
   if (backend === 'launchd') {
     // launchd builds the agent env from EnvironmentVariables alone. Verify
@@ -98,7 +148,9 @@ export function computeBackendEnv(sched, backend) {
     return withLaunchdDefaults(explicit);
   }
   if (backend === 'cron') {
-    return { ...minimalCronEnv(), ...explicit };
+    const base = minimalCronEnv();
+    base.PATH = composeCronVerifyPath(base.PATH, opts.etcEnvironmentFile);
+    return { ...base, ...explicit };
   }
   // systemd/schtasks: "parent env then explicit overrides". Replicate by
   // layering explicit over process.env, dropping any keys the parent has
@@ -266,7 +318,9 @@ export function runVerifyArgv(bin, args, workDir, env, timeoutMs) {
  * @param {string} scheduleFile - Path to the schedule JSON
  * @param {object} [opts]
  * @param {string} [opts.backend] - Override backend (default: auto-detect)
- * @param {number} [opts.timeoutMs] - Timeout in ms (default: 30000)
+ * @param {number} [opts.timeoutMs] - Timeout in ms (default: 120000)
+ * @param {string} [opts.etcEnvironmentFile] - Test-only override for the
+ *   cron backend's `/etc/environment` path.
  * @param {boolean} [opts.hasNvm] - Test-only override; defaults to a real
  *   filesystem check of $HOME/.nvm/nvm.sh, matching install-time detection.
  * @param {string} [opts.cronLogPath] - Test-only override for the cron
@@ -274,7 +328,7 @@ export function runVerifyArgv(bin, args, workDir, env, timeoutMs) {
  *   `/tmp/<agent>-<id>-verify.log` — distinct from the INSTALLED
  *   schedule's own `/tmp/<agent>-<id>.log`, so a verify run never
  *   clobbers/interleaves with real cron output).
- * @returns {Promise<{ result: 'ok' | 'fail-exit' | 'fail-spawn' | 'fail-timeout', exitCode: number, sched: object, backend: string, env: Record<string,string>, workDir: string, run: object, argv: string[] | null }>}
+ * @returns {Promise<{ result: 'ok' | 'fail-exit' | 'fail-spawn' | 'fail-timeout', exitCode: number, sched: object, backend: string, env: Record<string,string>, path: string | null, workDir: string, run: object, argv: string[] | null }>}
  */
 export async function verify(scheduleFile, opts = {}) {
   const sched = readSchedule(scheduleFile);
@@ -286,10 +340,10 @@ export async function verify(scheduleFile, opts = {}) {
   }
 
   const backend = opts.backend || sched.backend || detectDefaultBackend();
-  const timeoutMs = opts.timeoutMs ?? 30000;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_VERIFY_TIMEOUT_SECONDS * 1000;
 
   const workDir = resolveWorkDir(sched.workingDirectory);
-  const env = computeBackendEnv(sched, backend);
+  const env = computeBackendEnv(sched, backend, { etcEnvironmentFile: opts.etcEnvironmentFile });
 
   let run;
   let argv = null;
@@ -320,7 +374,7 @@ export async function verify(scheduleFile, opts = {}) {
     exitCode = 2;
   }
 
-  return { result, exitCode, sched, backend, env, workDir, run, argv };
+  return { result, exitCode, sched, backend, env, path: env.PATH ?? null, workDir, run, argv };
 }
 
 // ── CLI entry point ──────────────────────────────────────────────────
@@ -339,7 +393,7 @@ Arguments:
                       systemd, schtasks). Defaults to auto-detected backend.
 
 Flags:
-  --timeout <seconds> Kill the verify run after this many seconds (default: 30).
+  --timeout <seconds> Kill the verify run after this many seconds (default: 120).
   -h, --help          Print this message and exit 0.
 
 Exit codes:
@@ -375,7 +429,7 @@ if (isDirectlyInvoked()) {
   // Parse: positional <schedule.json>, optional positional <backend>, optional --timeout N.
   let scheduleFile = null;
   let backend = null;
-  let timeoutSeconds = 30;
+  let timeoutSeconds = DEFAULT_VERIFY_TIMEOUT_SECONDS;
 
   for (let i = 0; i < args.length; i++) {
     const a = args[i];

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

@@ -14,27 +14,54 @@ pre-remote library sweep.
 
 ## Verbs
 
-- `library put <path> [--kind <kind>] [--tier auto|<tier>]`
+- `library put <path> [--kind <kind>] [--tier auto|<tier>] [--verbatim-path]`
   Streams a single event to `POST /events`.
   **`--kind` is required** for any path outside `agents/*/staging/`; those
   staging paths default to `knowledge.observation.staged` via path inference.
-  A canonical doc write is `library put <absolute path> --kind knowledge.doc.upsert`.
+  A canonical doc write is `library put <path> --kind knowledge.doc.upsert`.
   Known kinds (ingest will 422 anything else): `knowledge.observation.staged`,
   `knowledge.doc.upsert`, `knowledge.doc.delete`, `profile.upsert`,
   `profile.slice.upsert`, `preferences.upsert`, `role.output`,
   `system.correction`, `synthesis.upsert`, `synthesis.merge`,
   `synthesis.retire`, `system.seed`.
-  **Path resolution.** The `<path>` argument is read as given (cwd-relative or
-  absolute); the repo-relative payload path is derived only when the input is
-  absolute. A relative path run from `agents/dave/` therefore encodes a
-  payload path relative to `agents/dave/`, which also misses the
-  `agents/*/staging/` kind-inference regex. Safe form: pass an absolute path,
-  or run from the repo root.
+  **Path resolution.** `<path>` is resolved against the current directory, so
+  a relative path from any cwd and an absolute path encode the same
+  repo-relative path. From the repo root this is byte-identical to the old
+  "as given" encoding.
+  **Knowledge docs go to the tier path a mount reads.** For
+  `knowledge.doc.upsert` and `knowledge.doc.delete` the workspace path
+  (`operator/knowledge/...`) is mapped through the registry knowledge mounts
+  (`repos.<repo>.mounts[]` with `to` under `operator/knowledge/`) by the
+  shared mount map vendored from remote-library
+  (`packages/core/src/knowledge/retrieval/mount-map.mjs`). The longest
+  matching mount `to` wins:
+  | Workspace path | Sent as | Tier |
+  |---|---|---|
+  | `operator/knowledge/engineering/x.md` | `knowledge/engineering/x.md` | `auto` (hq and company agree) |
+  | `operator/knowledge/wsd/memory/y.md` | `knowledge/memory/y.md` | `stravica-library-wsd` |
+  | `operator/knowledge/writing/z.md` | `voice/z.md` | `stravica-operator-barry` |
+  A unique tier is stamped exactly as an explicit `--tier` is (envelope `tier`
+  and `payload.source`); `provenance.sourcePath` keeps the workspace path.
+  With an explicit `--tier` (registry key or short name such as `hq`), only
+  that tier's mounts are tried, and the registry key is stamped. Put refuses
+  with exit 2 and one line naming the mounts tried when no knowledge mount
+  reads the path, when the candidate tiers disagree, when `--tier` names an
+  unknown tier or one that cannot read the path, or when no registry is found.
+  The ingest refuses the same shape with 422 `unmapped-path`.
+  Paths the profile tier map owns (`operator/profile/**`) keep their profile
+  routing and are sent unmapped.
+  **Registry source.** The company clone among `LIBRARY_KNOWLEDGE_EXTRA_ROOTS`
+  (the clone whose own registry entry mounts `registry/`), else the workspace
+  copy `<repoRoot>/operator/registry/repos.json`, else none (refuse).
   `--tier auto` sends the spec §2.3 sentinel; the server's routing engine
   resolves the actual tier. An explicit `--tier <repo>` also stamps
   `payload.source = <repo>` on the kinds whose ingest schema accepts it
   (`knowledge.doc.upsert`, `knowledge.doc.delete`, `profile.upsert`,
   `profile.slice.upsert`).
+  `--verbatim-path` (slice 3 removes) sends a `knowledge.doc.delete` at the
+  workspace path unmapped, to delete the legacy `operator/knowledge/...`
+  copies. It needs `--kind knowledge.doc.delete` and an explicit `--tier`;
+  any other use is a usage error (exit 1).
 
 - `library flush`
   Sweeps `<repoRoot>/agents/<paName>/staging/*` and streams one event per file.

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

@@ -78,7 +78,7 @@ help ('library put --help' etc.) is served the same way.
  * useful at the point of friction, not a prose essay.
  */
 const VERB_USAGE = {
-  put: `library put <path> [--kind <kind>] [--tier auto|<tier>]
+  put: `library put <path> [--kind <kind>] [--tier auto|<tier>] [--verbatim-path]
 
   Streams a single event to POST /events (REMOTE mode only).
 
@@ -91,12 +91,23 @@ const VERB_USAGE = {
                   synthesis.upsert, synthesis.merge, synthesis.retire,
                   system.seed.
   --tier <name>   'auto' (default) lets the server route; an explicit tier
-                  (repo name) stamps payload.source for routing-rule kinds.
+                  (repo name, or a short name such as 'hq') stamps
+                  payload.source for routing-rule kinds.
+  --verbatim-path With --kind knowledge.doc.delete and an explicit --tier
+                  only: send the workspace path unmapped, to delete a legacy
+                  operator/knowledge/... copy (slice 3 removes).
 
-  Path resolution: the argument is read as given (cwd-relative or absolute);
-  the repo-relative payload path is derived only when the input is absolute.
-  Run from the repo root with a relative path, or always pass an absolute
-  path, to keep the staging-inference and payload path in agreement.
+  Path resolution: <path> is resolved against the current directory, so the
+  payload path is repo-relative from any cwd.
+
+  Knowledge docs (knowledge.doc.upsert, knowledge.doc.delete) are sent at the
+  tier path a registry knowledge mount reads, for example
+  operator/knowledge/x.md -> knowledge/x.md (tier auto),
+  operator/knowledge/wsd/x.md -> knowledge/x.md (stravica-library-wsd),
+  operator/knowledge/writing/x.md -> voice/x.md (stravica-operator-barry).
+  No mount reads the path, the tiers disagree, or no registry: exit 2 with
+  the mounts tried. Registry: the company clone among
+  LIBRARY_KNOWLEDGE_EXTRA_ROOTS, else operator/registry/repos.json.
 `,
   flush: `library flush
 
@@ -276,9 +287,16 @@ function parsePut(argv) {
     options: {
       kind: { type: 'string' },
       tier: { type: 'string', default: 'auto' },
+      // slice 3 removes: deletes the legacy operator/knowledge/... copies.
+      'verbatim-path': { type: 'boolean', default: false },
     },
   });
-  return { path: positionals[0], kind: values.kind, tier: values.tier };
+  return {
+    path: positionals[0],
+    kind: values.kind,
+    tier: values.tier,
+    verbatimPath: values['verbatim-path'],
+  };
 }
 function parseFlush(argv) {
   parseArgs({ args: argv, strict: true, allowPositionals: true, options: {} });

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

@@ -143,6 +143,12 @@ export function guessKindFromPath(sourcePath) {
  *   `--tier` is asserted explicitly (not the `auto` sentinel), the tier
  *   value is used as the source stamp for these kinds automatically, so
  *   callers rarely pass this directly.
+ * @param {string} [args.payloadPath]  the tier path to send as
+ *   `payload.path` when it differs from the repo-relative source path
+ *   (`library put` maps knowledge docs through the registry mounts,
+ *   w-2026-10-16-dave-019 slice 2). `provenance.sourcePath` keeps the
+ *   repo-relative source path. Absent: `payload.path` is the source path,
+ *   unchanged.
  * @param {() => Date} [args.clock]  test seam
  * @returns {object} EventInput ready for POST /events
  */
@@ -155,6 +161,7 @@ export function buildEnvelope({
   tier = 'auto',
   sourceKind = 'manual',
   source,
+  payloadPath,
   clock = () => new Date(),
 }) {
   // Repo-relative resolution + refusal for anything that would encode as
@@ -173,6 +180,10 @@ export function buildEnvelope({
   if (relPath !== undefined) {
     assertRepoRelativeSafe(relPath, sourcePath, repoRoot);
   }
+  if (payloadPath !== undefined) {
+    assertRepoRelativeSafe(payloadPath, sourcePath, repoRoot);
+  }
+  const wirePath = payloadPath ?? relPath;
 
   const resolvedKind = kind ?? guessKindFromPath(relPath ?? sourcePath ?? '') ?? null;
   if (!resolvedKind) {
@@ -218,7 +229,7 @@ export function buildEnvelope({
   let payload;
   if (resolvedKind === 'knowledge.doc.delete') {
     payload = {
-      path: relPath ?? null,
+      path: wirePath ?? null,
       ...(stampSource ? { source: effectiveSource } : {}),
     };
   } else if (resolvedKind === 'profile.slice.upsert') {
@@ -249,7 +260,7 @@ export function buildEnvelope({
   } else if (KINDS_ACCEPTING_SOURCE.has(resolvedKind)) {
     // knowledge.doc.upsert, profile.upsert.
     payload = {
-      path: relPath ?? null,
+      path: wirePath ?? null,
       content,
       ...(stampSource ? { source: effectiveSource } : {}),
     };
@@ -257,7 +268,7 @@ export function buildEnvelope({
     // Every other kind keeps the pre-cure {path, content} shape
     // byte-identical.
     payload = {
-      path: relPath ?? null,
+      path: wirePath ?? null,
       content,
     };
   }

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

@@ -1,40 +1,72 @@
-// verbs/put.mjs — `library put <path> [--kind ...] [--tier auto|<tier>]`
+// verbs/put.mjs: `library put <path> [--kind ...] [--tier auto|<tier>] [--verbatim-path]`
 //
 // Streams a single event to POST /events. Reads the file's UTF-8 contents,
 // builds an envelope (spec §3.1), and posts with retries via http.mjs.
 // A `deduped` server response counts as SUCCESS (spec §4.2: retrying a
 // timed-out send must see success).
+//
+// Knowledge docs (`knowledge.doc.upsert`, `knowledge.doc.delete`) are sent at
+// the TIER path a registry mount reads, never at the workspace path
+// (w-2026-10-16-dave-019, slice 2). The input resolves against cwd to a
+// repo-relative workspace path, the shared mount map (vendored from
+// remote-library) maps it, and put refuses with exit 2 when no knowledge
+// mount reads it. The ingest refuses the same shape with 422 `unmapped-path`.
 
 import { readFile } from 'node:fs/promises';
-import { basename } from 'node:path';
+import { basename, isAbsolute, relative, resolve, sep } from 'node:path';
+
+import { resolveExtraScanRoots } from '../../../engineering-pa-core/src/knowledge/retrieval/links.mjs';
+import { loadWriteRegistry } from '../../../engineering-pa-core/src/knowledge/retrieval/mounts.mjs';
+import { createMountMap, resolveWrite } from '../../../engineering-pa-core/src/knowledge/retrieval/mount-map.mjs';
 
-import { buildEnvelope, subkeyIdFromRemoteKey } from '../envelope.mjs';
+import { buildEnvelope, guessKindFromPath, subkeyIdFromRemoteKey } from '../envelope.mjs';
 import { postEvents } from '../http.mjs';
 import { parseIngestAck } from '../ack.mjs';
 import { assertTierMatchesPath, deriveTierFromPath } from '../tier-map.mjs';
 
+/** Kinds whose payload path must be one a registry knowledge mount reads. */
+export const MAPPED_KINDS = new Set(['knowledge.doc.upsert', 'knowledge.doc.delete']);
+
 /**
  * @param {object} ctx
  * @param {object} ctx.config   from loadLibraryConfig (mode/remoteEndpoint/remoteKey/preferences)
- * @param {object} ctx.args     { path, kind?, tier? }
+ * @param {object} ctx.args     { path, kind?, tier?, verbatimPath? }
  * @param {typeof fetch} [ctx.fetchImpl]
  * @param {(...m:unknown[])=>void} [ctx.log]
+ * @param {string} [ctx.cwd]    test seam; defaults to process.cwd()
+ * @param {() => { registry: object|null, looked: string[] }} [ctx.loadRegistry]
+ *   test seam for the mount registry; defaults to loadWriteRegistry over
+ *   LIBRARY_KNOWLEDGE_EXTRA_ROOTS and the workspace copy
  * @returns {Promise<number>}   exit code
  */
-export async function runPut({ config, args, fetchImpl, log = defaultLog }) {
-  const { path, kind, tier = 'auto' } = args;
+export async function runPut({ config, args, fetchImpl, log = defaultLog, cwd = process.cwd(), loadRegistry }) {
+  const { path, kind, tier = 'auto', verbatimPath = false } = args;
   if (!path) {
-    log('usage: library put <path> [--kind <kind>] [--tier auto|<tier>]');
+    log('usage: library put <path> [--kind <kind>] [--tier auto|<tier>] [--verbatim-path]');
+    return 1;
+  }
+
+  // `--verbatim-path` (slice 3 removes): send a delete at the workspace path
+  // unmapped, so slice 3 can delete the legacy `operator/knowledge/...`
+  // copies. Deletes only, and only with an explicit tier.
+  if (verbatimPath && (kind !== 'knowledge.doc.delete' || tier === 'auto')) {
+    log('usage: --verbatim-path is valid only with --kind knowledge.doc.delete and an explicit --tier <tier>');
     return 1;
   }
 
+  // Every kind resolves the input against cwd, so the payload path is
+  // repo-relative whether the caller passed a repo-root-relative path, a
+  // path relative to some other cwd, or an absolute path. From the repo
+  // root this encodes byte-identically to the old "as given" behaviour.
+  const absPath = resolve(cwd, path);
+
   // Refuse a caller-forced tier that disagrees with the path-derived
   // default (w-2026-09-03-dave-017). `auto` never triggers the refusal
   // (auto means "let derivation choose"); an explicit tier does. The
   // refusal is a clean exit 2 with a single-line reason so an operator
   // sees why the CLI declined to encode the event rather than silently
   // stamping the wrong tier.
-  const tierRefusal = assertTierMatchesPath(path, config.repoRoot, tier);
+  const tierRefusal = assertTierMatchesPath(absPath, config.repoRoot, tier);
   if (tierRefusal) {
     log(`[library put] refused: ${tierRefusal}`);
     return 2;
@@ -43,9 +75,37 @@ export async function runPut({ config, args, fetchImpl, log = defaultLog }) {
   // When `--tier` is absent the CLI derives it from the path map. Paths
   // outside the map keep today's `auto` sentinel so unrelated payload
   // kinds still content-route the way they always did.
-  const derivedTier = tier === 'auto'
-    ? (deriveTierFromPath(path, config.repoRoot) ?? 'auto')
-    : tier;
+  const mapTier = deriveTierFromPath(absPath, config.repoRoot);
+  let derivedTier = tier === 'auto' ? (mapTier ?? 'auto') : tier;
+
+  // Knowledge docs go to the tier path a registry mount reads. Paths the
+  // profile tier map owns (operator/profile/**) keep their profile routing
+  // and path unchanged; profile routing is out of scope for slice 2. A path
+  // outside the repo skips mapping so buildEnvelope refuses it as before.
+  const workspacePath = relative(config.repoRoot, absPath).split(sep).join('/');
+  const insideRepo = workspacePath !== '' && !workspacePath.startsWith('../') && !isAbsolute(workspacePath);
+  const effectiveKind = kind ?? guessKindFromPath(workspacePath);
+  let payloadPath;
+  if (MAPPED_KINDS.has(effectiveKind) && insideRepo && !mapTier && !verbatimPath) {
+    const loaded = (loadRegistry ?? (() => loadWriteRegistry({
+      extraRoots: resolveExtraScanRoots(process.env),
+      repoRoot: config.repoRoot,
+    })))();
+    if (!loaded?.registry) {
+      log(`[library put] refused: no mount registry (looked in: ${(loaded?.looked ?? []).join(', ')})`);
+      return 2;
+    }
+    const asserted = tier === 'auto' ? undefined : tier;
+    const res = resolveWrite(createMountMap(loaded.registry), workspacePath, asserted);
+    if (!res.ok) {
+      log(`[library put] refused: ${describeRefusal(res, workspacePath, asserted)}`);
+      return 2;
+    }
+    payloadPath = res.libraryPath;
+    // A unique tier stamps itself exactly as an explicit --tier does; agreeing
+    // tiers (hq and company both read `knowledge/`) leave the server to route.
+    derivedTier = res.repo ?? 'auto';
+  }
 
   // Delete events carry no content by spec (§3.1 payload schema); the
   // operator can and typically will have removed the file locally before
@@ -54,17 +114,18 @@ export async function runPut({ config, args, fetchImpl, log = defaultLog }) {
   // delete. Every other kind still reads the file to populate
   // payload.content. Fix Wave E (w-2026-08-24-dave-029) partner cure to
   // the envelope kind-aware branch.
-  const content = kind === 'knowledge.doc.delete' ? undefined : await readFile(path, 'utf8');
+  const content = kind === 'knowledge.doc.delete' ? undefined : await readFile(absPath, 'utf8');
 
   const producer = producerFromPreferences(config);
   const envelope = buildEnvelope({
     repoRoot: config.repoRoot,
-    sourcePath: path,
+    sourcePath: absPath,
     content,
     producer,
     kind,
     tier: derivedTier,
     sourceKind: 'manual',
+    ...(payloadPath !== undefined ? { payloadPath } : {}),
   });
 
   const res = await postEvents({
@@ -77,13 +138,35 @@ export async function runPut({ config, args, fetchImpl, log = defaultLog }) {
   // RB-5 fix (2026-08-20 rehearsal). See ack.mjs for the wire contract.
   const ack = parseIngestAck(res);
   if (ack.kind === 'accepted' || ack.kind === 'deduped') {
-    log(`[library put] ${ack.kind} ${basename(path)} -> ${ack.eventId} (tier: ${derivedTier})`);
+    const pathNote = payloadPath !== undefined ? `, path: ${payloadPath}` : '';
+    log(`[library put] ${ack.kind} ${basename(path)} -> ${ack.eventId} (tier: ${derivedTier}${pathNote})`);
     return 0;
   }
   log(`[library put] rejected ${basename(path)}: ${ack.reason}`);
   return 2;
 }
 
+/**
+ * One-line reason for a failed resolveWrite, naming the mounts tried.
+ *
+ * @param {{ reason: string, tried: { repo: string, from: string, to: string }[] }} res
+ * @param {string} workspacePath
+ * @param {string|undefined} asserted
+ */
+export function describeRefusal(res, workspacePath, asserted) {
+  const tried = res.tried.length
+    ? res.tried.map((t) => `${t.repo} ${t.to} -> ${t.from}`).join(', ')
+    : 'no knowledge mounts';
+  if (res.reason === 'unknown-tier') {
+    return `${workspacePath}: tier ${asserted} is not in the mount registry`;
+  }
+  if (res.reason === 'ambiguous') {
+    return `${workspacePath} is read by knowledge mounts of several tiers that disagree on the tier path; ` +
+      `pass --tier to choose; tried: ${tried}`;
+  }
+  return `${workspacePath} is read by no knowledge mount of ${asserted ?? 'any tier'}; tried: ${tried}`;
+}
+
 export function producerFromPreferences(config) {
   const paName = config.preferences?.paName;
   const operator = (config.preferences?.operator?.name ?? '').toString().toLowerCase() || 'unknown';

package/package.json

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