@stravica-ai/digital-operator-pa 0.1.61 → 0.1.63

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

@@ -108,9 +108,11 @@ The failure mode is silent: launchd records exit code 78 (`EX_CONFIG`), the Stan
 
 Proven live (w-2026-07-15-003, verified with `env -i`): cron's crond process provides a small fixed environment (`SHELL`, a narrow system `PATH`; `/usr/bin:/bin`; `HOME`, `LOGNAME`/`USER`), NOT a login shell's env. A schedule whose `command` relies on `pnpm`/`node` being on PATH via nvm silently fails to spawn once actually installed, even if it "worked" when tested from an interactive terminal.
 
-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).
+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 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
 
@@ -154,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/scheduler/install.mjs

@@ -371,16 +371,24 @@ export function defaultCronLogPath(sched) {
 
 /**
  * Build the INNER shell script a cron entry (or a `scheduler verify` run
- * simulating one) actually executes, plus the `bash -c "<inner>"`
- * wrapper string. Kept separate from the inner content so `verify` can
- * run the exact same inner script via `spawn('bash', ['-c', inner], ...)`
- * — an argv array, never a re-parsed/re-split string — while `install`
- * embeds the wrapper form into the crontab line.
+ * simulating one) actually executes, the `bash -c '<inner>'` wrapper
+ * string, and the crontab command field (the wrapper with every `%`
+ * escaped as `\%`).
  *
- * Shape (matches the real house pattern, e.g.
- * `bash -c ". $HOME/.nvm/nvm.sh && cd /home/thefoot/dave-v2 && pnpm exec
- * pa knowledge eval --format line >> /tmp/dave-knowledge-eval-daily.log
- * 2>&1" # dave-knowledge-eval-daily`):
+ * The wrapper is single-quoted, embedded single quotes rendered as
+ * `'\''`, exactly like the systemd backend's ExecStart. cron hands the
+ * command field to `/bin/sh -c`; inside the old double-quoted form sh
+ * expanded every `$(...)`, `$N` and `${VAR}` in the cron user's HOME
+ * before bash ever ran (smarthome01 workspace-refresh, w-2026-10-17-dave-006).
+ * Single quotes hand the inner script to bash untouched.
+ *
+ * cron turns an unescaped `%` into a newline and feeds the rest of the
+ * line to stdin, so `cronField` escapes every `%` as `\%`; cron strips
+ * the backslash before sh sees the line. `wrapped` is the string sh
+ * receives after that unescaping, which is what `verify` runs.
+ *
+ * Shape: `bash -c '{ date -u; [. $HOME/.nvm/nvm.sh && ]cd <workDir> &&
+ * <command>; } >> <log> 2>&1'`:
  *
  *   [. $HOME/.nvm/nvm.sh && ]<export VAR='val'; >*cd <workDir> && <command> >> <logPath> 2>&1
  *
@@ -397,7 +405,7 @@ export function defaultCronLogPath(sched) {
  * @param {object} [opts]
  * @param {boolean} [opts.hasNvm]
  * @param {string} [opts.logPath]
- * @returns {{ inner: string, wrapped: string }}
+ * @returns {{ inner: string, wrapped: string, cronField: string }}
  */
 /**
  * When the schedule's argv[0] is a bare `node`, swap in the absolute
@@ -444,14 +452,31 @@ export function buildCronCommand(sched, workDir, env, opts = {}) {
   // file empty — the exact silent-failure class w-2026-09-13-dave-030 tracks
   // (smarthome01 crons fired but never wrote a log line, 2026-09-09 -> 13).
   // A leading `date -u` inside the group prints an ISO timestamp so a run
-  // that dies mid-chain still leaves dated evidence. No `$()` — cron passes
-  // the crontab line through /bin/sh -c '...' which parses the double-quoted
-  // bash-c argument and would eagerly expand $(...) at dispatch time, not
-  // at run time.
+  // that dies mid-chain still leaves dated evidence.
   const chain = `date -u; ${preamble}${exportStmts}cd ${workDir} && ${resolvedCommand}`;
   const inner = `{ ${chain}; } >> ${logPath} 2>&1`;
-  const wrapped = `bash -c "${inner.replace(/"/g, '\\"')}"`;
-  return { inner, wrapped };
+  const wrapped = `bash -c '${inner.replace(/'/g, `'\\''`)}'`;
+  return { inner, wrapped, cronField: escapeCronPercent(wrapped) };
+}
+
+/**
+ * Escape every `%` as `\%` for a crontab command field. cron otherwise
+ * treats `%` as a newline and sends the remainder to the command's stdin.
+ * @param {string} s
+ * @returns {string}
+ */
+export function escapeCronPercent(s) {
+  return s.replace(/%/g, '\\%');
+}
+
+/**
+ * Undo cron's own `\%` unescaping, yielding the string cron passes to
+ * `/bin/sh -c`. Inverse of escapeCronPercent.
+ * @param {string} s
+ * @returns {string}
+ */
+export function unescapeCronPercent(s) {
+  return s.replace(/\\%/g, '%');
 }
 
 /**
@@ -465,8 +490,46 @@ export function buildCronCommand(sched, workDir, env, opts = {}) {
  */
 export function buildCronLine(sched, workDir, env, opts = {}) {
   const tag = `${schedAgent(sched)}-${sched.id}`;
-  const { wrapped } = buildCronCommand(sched, workDir, env, opts);
-  return `${sched.schedule} ${wrapped} # ${tag}`;
+  const { cronField } = buildCronCommand(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) {
@@ -483,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, '');
 
@@ -818,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
@@ -837,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';
@@ -36,6 +36,7 @@ import {
   resolveEnvironment,
   withLaunchdDefaults,
   buildCronCommand,
+  unescapeCronPercent,
   detectNvm,
   schedAgent,
 } from './install.mjs';
@@ -67,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.
  *
@@ -87,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
@@ -97,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
@@ -250,8 +303,12 @@ export function runVerifyArgv(bin, args, workDir, env, timeoutMs) {
  * For backend === 'cron', this does NOT run `sched.command` directly — it
  * builds the exact GENERATED inner cron script (via install.mjs's
  * `buildCronCommand`, the same function `scheduler install` uses to write
- * the actual crontab line) and runs THAT via `bash -c` with an exact argv
- * array (never a re-split string). This is the "verification is honest
+ * the actual crontab line) and runs it the way cron does: the crontab
+ * command field (`bash -c '...'`, `%` escaped as `\%`) has cron's own
+ * `\%` unescaping undone and is handed to `/bin/sh -c` as one argv
+ * element, from the working directory. Running the inner script under
+ * bash directly would skip the sh pass that cron performs, so quoting or
+ * `%` defects in the wrapper could never show (w-2026-10-17-dave-006). This is the "verification is honest
  * about cron reality" fix: verifying `sched.command` alone, under an env
  * that inherits the verifying process's PATH, never exercised the nvm
  * preamble or the minimal-PATH reality a real cron invocation faces —
@@ -261,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
@@ -269,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 }>}
+ * @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);
@@ -281,18 +340,20 @@ 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;
   if (backend === 'cron') {
     const explicit = resolveEnvironment(sched);
     const hasNvm = opts.hasNvm ?? detectNvm();
     const logPath = opts.cronLogPath ?? `/tmp/${schedAgent(sched)}-${sched.id}-verify.log`;
-    const { inner } = buildCronCommand(sched, workDir, explicit, { hasNvm, logPath });
-    run = await runVerifyArgv('bash', ['-c', inner], workDir, env, timeoutMs);
+    const { cronField } = buildCronCommand(sched, workDir, explicit, { hasNvm, logPath });
+    argv = ['/bin/sh', '-c', unescapeCronPercent(cronField)];
+    run = await runVerifyArgv(argv[0], argv.slice(1), workDir, env, timeoutMs);
   } else {
     run = await runVerify(sched.command, workDir, env, timeoutMs);
   }
@@ -313,7 +374,7 @@ export async function verify(scheduleFile, opts = {}) {
     exitCode = 2;
   }
 
-  return { result, exitCode, sched, backend, env, workDir, run };
+  return { result, exitCode, sched, backend, env, path: env.PATH ?? null, workDir, run, argv };
 }
 
 // ── CLI entry point ──────────────────────────────────────────────────
@@ -332,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:
@@ -368,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/package.json

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