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

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

@@ -108,10 +108,12 @@ 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.
 
+**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.
+
 ### Verify your schedule before walking away
 
 After installing a schedule, run `verify.mjs` to confirm the command actually launches under the installed env. The verify deliberately uses the same env-derivation logic as the installer, so it catches the env-mismatch class of bugs (narrow PATH, missing HOME, etc.) before the job's first scheduled fire; instead of finding out two weeks later from a stale audit log.

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,8 @@ 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}`;
 }
 
 function installCron(sched, workDir) {

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

@@ -36,6 +36,7 @@ import {
   resolveEnvironment,
   withLaunchdDefaults,
   buildCronCommand,
+  unescapeCronPercent,
   detectNvm,
   schedAgent,
 } from './install.mjs';
@@ -250,8 +251,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 —
@@ -269,7 +274,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>, workDir: string, run: object, argv: string[] | null }>}
  */
 export async function verify(scheduleFile, opts = {}) {
   const sched = readSchedule(scheduleFile);
@@ -287,12 +292,14 @@ export async function verify(scheduleFile, opts = {}) {
   const env = computeBackendEnv(sched, backend);
 
   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 +320,7 @@ export async function verify(scheduleFile, opts = {}) {
     exitCode = 2;
   }
 
-  return { result, exitCode, sched, backend, env, workDir, run };
+  return { result, exitCode, sched, backend, env, workDir, run, argv };
 }
 
 // ── CLI entry point ──────────────────────────────────────────────────

package/package.json

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