@stravica-ai/digital-operator-pa 0.1.0

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

@@ -0,0 +1,854 @@
+#!/usr/bin/env node
+/**
+ * install.mjs -- Install a Dave schedule definition using the specified backend
+ *
+ * Usage: node node_modules/@stravica-ai/engineering-pa-core/src/scheduler/install.mjs <schedule.json> <backend>
+ *
+ * Reads a schedule JSON file and installs it using the specified backend
+ * (cron, launchd, systemd, schtasks). The schedule field uses cron syntax
+ * (minute hour day month weekday). This script translates to the native
+ * format for each backend.
+ */
+
+import {
+  readFileSync, writeFileSync, mkdirSync, chmodSync, realpathSync,
+  existsSync, statSync, readdirSync,
+} from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { homedir, hostname } from 'node:os';
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import { hostMatches } from './host.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/** Default agent id used when a schedule does not declare one. Backward-compat anchor. */
+export const DEFAULT_AGENT = 'dave';
+
+/**
+ * Compute the launchd label prefix for an agent. Centralised so install,
+ * remove, and list all agree on the naming scheme. Defaults to the
+ * pre-existing `com.dave.` behaviour when no agent is given.
+ * @param {string|undefined} agent
+ * @returns {string}
+ */
+export function launchdLabelPrefix(agent) {
+  return `com.${agent || DEFAULT_AGENT}.`;
+}
+
+/**
+ * Resolve the full launchd label for a schedule. Agent-derived: reads
+ * `sched.agent` (optional field on the schedule JSON), falling back to
+ * DEFAULT_AGENT so existing schedule files with no `agent` field keep
+ * producing exactly `com.dave.<id>`, unchanged from pre-feature behaviour.
+ * @param {object} sched
+ * @returns {string}
+ */
+export function resolveLaunchdLabel(sched) {
+  return `${launchdLabelPrefix(sched.agent)}${sched.id}`;
+}
+
+/**
+ * Parse a cron expression into its five fields.
+ * @param {string} expr - Cron expression (minute hour dom month dow)
+ * @returns {{ minute: string, hour: string, dom: string, month: string, dow: string }}
+ */
+function parseCron(expr) {
+  const parts = expr.trim().split(/\s+/);
+  if (parts.length < 5) {
+    throw new Error(`Invalid cron expression (need 5 fields): ${expr}`);
+  }
+  return {
+    minute: parts[0],
+    hour: parts[1],
+    dom: parts[2],
+    month: parts[3],
+    dow: parts[4],
+  };
+}
+
+/**
+ * Read and parse a schedule JSON file.
+ * @param {string} filePath
+ * @returns {object}
+ */
+function readSchedule(filePath) {
+  const raw = readFileSync(filePath, 'utf8');
+  return JSON.parse(raw);
+}
+
+/**
+ * Compute the resolved DAVE_ROOT for the current install.
+ * @returns {string}
+ */
+function computeDaveRoot() {
+  return process.env.DAVE_ROOT || resolve(__dirname, '..', '..', '..');
+}
+
+/**
+ * Resolve the DAVE_ROOT variable and working directory.
+ * @param {string|undefined} workDir
+ * @returns {string}
+ */
+function resolveWorkDir(workDir) {
+  const daveRoot = computeDaveRoot();
+  if (!workDir) return daveRoot;
+  return workDir.replace(/\$\{DAVE_ROOT\}/g, daveRoot);
+}
+
+/**
+ * Expand ${DAVE_ROOT}, ${HOME}, ${USER} inside a string value.
+ * Unknown ${...} tokens are left as-is (so users can reference
+ * environment variables that exist at execution time on the target backend).
+ * @param {string} value
+ * @returns {string}
+ */
+function substituteVars(value) {
+  if (typeof value !== 'string') return value;
+  const daveRoot = computeDaveRoot();
+  const home = homedir();
+  const user = process.env.USER || process.env.USERNAME || '';
+  return value
+    .replace(/\$\{DAVE_ROOT\}/g, daveRoot)
+    .replace(/\$\{HOME\}/g, home)
+    .replace(/\$\{USER\}/g, user);
+}
+
+/**
+ * Resolve the environment map on a schedule, performing variable substitution
+ * on all values. Returns an empty object if no environment is set.
+ * @param {object} sched
+ * @returns {Record<string,string>}
+ */
+function resolveEnvironment(sched) {
+  const env = sched.environment || {};
+  const out = {};
+  for (const [k, v] of Object.entries(env)) {
+    out[k] = substituteVars(String(v));
+  }
+  return out;
+}
+
+/**
+ * Validate a RESOLVED (post-substitution) working directory before it is
+ * baked into an installed schedule. Three refusals, all exit-2 (never a
+ * silent empty/wrong path):
+ *
+ *   (a) any `${...}` token still present -> an unresolvable variable
+ *       (unknown template var, or a var that substituted to an empty
+ *       string leaving a dangling `${}`-shaped remainder is caught by the
+ *       same regex — "silently empty" never reaches the backend).
+ *   (b) the resolved path has a `node_modules` path segment -> the
+ *       versioned-dist-path trap: DAVE_ROOT unset falls back to
+ *       `resolve(__dirname, '..','..','..')`, which under an INSTALLED
+ *       package resolves inside `node_modules/.pnpm/@stravica-ai+digital-operator-pa@X.Y.Z/...`
+ *       — a version-pinned store path that silently breaks on the next
+ *       upgrade. Proven live (w-2026-07-15-003).
+ *   (c) the resolved path does not exist, or exists but is not a
+ *       directory.
+ *
+ * @param {string} resolved
+ * @throws {Error & { exitCode: 2 }}
+ */
+export function validateWorkDir(resolved) {
+  if (/\$\{[^}]*\}/.test(resolved)) {
+    const e = new Error(
+      `workingDirectory resolves to "${resolved}", which still contains an unresolved `
+      + 'variable — refusing to install with a partially-substituted path. '
+      + 'Known vars: ${DAVE_ROOT}, ${HOME}, ${USER}.',
+    );
+    e.exitCode = 2;
+    throw e;
+  }
+  const segments = resolved.split(/[\\/]/);
+  if (segments.includes('node_modules')) {
+    const e = new Error(
+      `workingDirectory resolves to "${resolved}", which is under a node_modules directory — `
+      + 'this is almost always the versioned-dist-path trap (DAVE_ROOT unset, falling back to '
+      + 'the installed package\'s own directory, which is version-pinned and breaks on the next '
+      + 'upgrade). Set DAVE_ROOT explicitly, or set workingDirectory to the real operator repo root.',
+    );
+    e.exitCode = 2;
+    throw e;
+  }
+  let stat;
+  try {
+    stat = statSync(resolved);
+  } catch {
+    const e = new Error(`workingDirectory "${resolved}" does not exist.`);
+    e.exitCode = 2;
+    throw e;
+  }
+  if (!stat.isDirectory()) {
+    const e = new Error(`workingDirectory "${resolved}" exists but is not a directory.`);
+    e.exitCode = 2;
+    throw e;
+  }
+}
+
+/**
+ * Host-enforcement decision for `scheduler install`. A schedule with a
+ * `host` field declaring a machine other than the current one refuses to
+ * install here unless `forceHost` overrides it (still with a warning — the
+ * override is for deliberate cross-provisioning, not silent mismatch).
+ * A schedule with NO `host` field at all is a warning-only pass — host
+ * data backfill onto existing schedule files is estate-side, out of this
+ * package's scope.
+ *
+ * @param {object} sched
+ * @param {object} [opts]
+ * @param {string} [opts.currentHost] - defaults to the real os.hostname()
+ * @param {boolean} [opts.forceHost]
+ * @returns {{ ok: boolean, warning?: string, reason?: string }}
+ */
+export function evaluateHostGate(sched, { currentHost = hostname(), forceHost = false } = {}) {
+  if (!sched.host) {
+    return {
+      ok: true,
+      warning: `schedule "${sched.id}" has no "host" field — installing without host verification `
+        + '(host data backfill onto existing schedule files is estate-side).',
+    };
+  }
+  if (hostMatches(sched.host, currentHost)) {
+    return { ok: true };
+  }
+  if (forceHost) {
+    return {
+      ok: true,
+      warning: `schedule "${sched.id}" declares host "${sched.host}" but this machine is `
+        + `"${currentHost}" — proceeding anyway due to --force-host.`,
+    };
+  }
+  return {
+    ok: false,
+    reason: `schedule "${sched.id}" declares host "${sched.host}" but this machine is `
+      + `"${currentHost}" — refusing to install here. Pass --force-host to override.`,
+  };
+}
+
+/**
+ * Refuse when another schedule file in the same schedules directory
+ * resolves to the same task id (and therefore the same backend tag —
+ * `dave-<id>` for cron, `com.<agent>.<id>` for launchd, etc.). Two
+ * different files sharing an id is exactly the namespace-clobber class
+ * (`namespace-clobber-flat-shared-dirs`): whichever installs last silently
+ * owns the backend entry, and the other file's association is lost with
+ * no error anywhere.
+ *
+ * Malformed sibling files are skipped (not this tool's job to validate
+ * every other file in the directory) rather than aborting the whole
+ * install over an unrelated broken file.
+ *
+ * @param {string} scheduleFile
+ * @param {object} sched
+ * @param {object} [opts]
+ * @param {string} [opts.schedulesDir] - defaults to dirname(scheduleFile)
+ * @throws {Error & { exitCode: 2 }}
+ */
+export function checkNameCollision(scheduleFile, sched, opts = {}) {
+  const schedulesDir = opts.schedulesDir ?? dirname(resolve(scheduleFile));
+  const selfAbs = resolve(scheduleFile);
+  let entries;
+  try {
+    entries = readdirSync(schedulesDir);
+  } catch {
+    return;
+  }
+  for (const f of entries) {
+    if (!f.endsWith('.json')) continue;
+    const candidate = join(schedulesDir, f);
+    if (resolve(candidate) === selfAbs) continue;
+    let other;
+    try {
+      other = JSON.parse(readFileSync(candidate, 'utf8'));
+    } catch {
+      continue;
+    }
+    if (other && other.id === sched.id) {
+      const e = new Error(
+        `schedule id "${sched.id}" collides with ${candidate} — two different schedule files `
+        + `resolve to the same task id/tag ("dave-${sched.id}"). Rename one of the ids before installing.`,
+      );
+      e.exitCode = 2;
+      throw e;
+    }
+  }
+}
+
+/**
+ * XML-escape a string for safe embedding in plist values.
+ * @param {string} s
+ */
+function xmlEscape(s) {
+  return String(s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+// ── Backend: cron ────────────────────────────────────────────────────
+
+/**
+ * Detect whether an nvm installation exists at the target's
+ * `$HOME/.nvm/nvm.sh` — tested AT INSTALL TIME against the real
+ * filesystem (not assumed). When present, the generated cron line sources
+ * it before running the command, so `pnpm`/`node` resolve exactly the way
+ * they do in an interactive nvm-managed shell. Proven necessary
+ * (w-2026-07-15-003): cron's own minimal environment has no nvm wrapper,
+ * so `pnpm` is otherwise invisible.
+ * @param {string} [homeDir]
+ * @returns {boolean}
+ */
+export function detectNvm(homeDir = homedir()) {
+  return existsSync(join(homeDir, '.nvm', 'nvm.sh'));
+}
+
+/**
+ * Default per-run log path for a schedule's cron entry, matching the
+ * real house pattern (`/tmp/dave-knowledge-eval-daily.log` for
+ * agent=dave, id=knowledge-eval-daily).
+ * @param {object} sched
+ * @returns {string}
+ */
+export function defaultCronLogPath(sched) {
+  return `/tmp/${sched.agent || DEFAULT_AGENT}-${sched.id}.log`;
+}
+
+/**
+ * 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.
+ *
+ * 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`):
+ *
+ *   [. $HOME/.nvm/nvm.sh && ]<export VAR='val'; >*cd <workDir> && <command> >> <logPath> 2>&1
+ *
+ * Env vars are emitted as `export VAR='val';` statements (not bare
+ * `VAR='val' cd ...` prefix-assignment, which in POSIX shell only scopes
+ * to the single following simple command — `cd` — and therefore never
+ * actually reaches `command` after the `&&`). `export` persists them for
+ * the rest of the script, which is what a schedule author setting
+ * `environment` actually wants.
+ *
+ * @param {object} sched
+ * @param {string} workDir
+ * @param {Record<string,string>} env
+ * @param {object} [opts]
+ * @param {boolean} [opts.hasNvm]
+ * @param {string} [opts.logPath]
+ * @returns {{ inner: string, wrapped: string }}
+ */
+export function buildCronCommand(sched, workDir, env, opts = {}) {
+  const hasNvm = !!opts.hasNvm;
+  const logPath = opts.logPath || defaultCronLogPath(sched);
+  const preamble = hasNvm ? '. $HOME/.nvm/nvm.sh && ' : '';
+  const exportStmts = Object.entries(env)
+    .map(([k, v]) => `export ${k}='${String(v).replace(/'/g, `'\\''`)}'; `)
+    .join('');
+  const inner = `${preamble}${exportStmts}cd ${workDir} && ${sched.command} >> ${logPath} 2>&1`;
+  const wrapped = `bash -c "${inner.replace(/"/g, '\\"')}"`;
+  return { inner, wrapped };
+}
+
+/**
+ * Build the full cron line for a schedule (schedule expression + wrapped
+ * command + trailing tag comment).
+ * @param {object} sched
+ * @param {string} workDir
+ * @param {Record<string,string>} env
+ * @param {object} [opts] - see buildCronCommand
+ * @returns {string}
+ */
+export function buildCronLine(sched, workDir, env, opts = {}) {
+  const tag = `dave-${sched.id}`;
+  const { wrapped } = buildCronCommand(sched, workDir, env, opts);
+  return `${sched.schedule} ${wrapped} # ${tag}`;
+}
+
+function installCron(sched, workDir) {
+  const env = resolveEnvironment(sched);
+  const tag = `# dave-${sched.id}`;
+  const hasNvm = detectNvm();
+  const entry = buildCronLine(sched, workDir, env, { hasNvm });
+
+  let existing = '';
+  try {
+    existing = execSync('crontab -l 2>/dev/null', { encoding: 'utf8' });
+  } catch {
+    // no crontab yet
+  }
+
+  // Remove any existing entry for this schedule
+  const filtered = existing
+    .split('\n')
+    .filter(line => !line.includes(tag))
+    .join('\n')
+    .replace(/^\n+|\n+$/g, '');
+
+  const newCrontab = filtered ? `${filtered}\n${entry}\n` : `${entry}\n`;
+  execSync('crontab -', { input: newCrontab, encoding: 'utf8' });
+
+  console.log(`Installed cron schedule: dave-${sched.id}`);
+  console.log(`  ${sched.schedule} -- ${sched.description || ''}`);
+
+  return { tag: `dave-${sched.id}` };
+}
+
+// ── Backend: launchd ─────────────────────────────────────────────────
+
+/**
+ * Merge explicit environment with launchd defaults. Explicit values win.
+ * Defaults: PATH (current process PATH), HOME (os.homedir()),
+ * DAVE_ROOT (resolved). These guard against launchd's minimal agent
+ * environment (/usr/bin:/bin:/usr/sbin:/sbin, no HOME) which silently
+ * breaks anything installed via Homebrew.
+ * @param {Record<string,string>} explicitEnv
+ * @returns {Record<string,string>}
+ */
+export function withLaunchdDefaults(explicitEnv) {
+  const defaults = {
+    PATH: process.env.PATH || '/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin',
+    HOME: homedir(),
+    DAVE_ROOT: computeDaveRoot(),
+  };
+  return { ...defaults, ...explicitEnv };
+}
+
+/**
+ * Build the EnvironmentVariables <dict> block (indented 2 spaces, matching
+ * the surrounding plist indentation). Returns an empty string when env is
+ * empty so the block is omitted entirely.
+ * @param {Record<string,string>} env
+ * @returns {string}
+ */
+function buildLaunchdEnvBlock(env) {
+  const entries = Object.entries(env);
+  if (entries.length === 0) return '';
+  const inner = entries
+    .map(([k, v]) => `    <key>${xmlEscape(k)}</key>\n    <string>${xmlEscape(v)}</string>`)
+    .join('\n');
+  return `  <key>EnvironmentVariables</key>\n  <dict>\n${inner}\n  </dict>\n`;
+}
+
+/**
+ * Expand a single cron field into either "wildcard" (no constraint — the
+ * launchd key is omitted, same as historical behaviour) or a sorted,
+ * deduped list of concrete integer values. Handles plain values, comma
+ * lists, ranges (`a-b`), stepped ranges (`a-b` over `n`), and step-wildcards
+ * (star over `n`) — the step-wildcard form is what BUG 4 could not express
+ * at all (launchd has no native step syntax; it needs the concrete value set).
+ * @param {string} field - Raw cron field text (e.g. a bare star, a stepped star, '3,6,9', '1-5')
+ * @param {number} min
+ * @param {number} max
+ * @returns {{ kind: 'wildcard' } | { kind: 'values', values: number[] }}
+ */
+export function expandCronField(field, min, max) {
+  if (field === '*') return { kind: 'wildcard' };
+
+  const values = new Set();
+  for (const token of field.split(',')) {
+    const stepWildcard = token.match(/^\*\/(\d+)$/);
+    const stepRange = token.match(/^(\d+)-(\d+)\/(\d+)$/);
+    const plainRange = token.match(/^(\d+)-(\d+)$/);
+    const single = token.match(/^(\d+)$/);
+
+    if (stepWildcard) {
+      const step = Number(stepWildcard[1]);
+      if (step <= 0) throw new Error(`Invalid cron step (must be > 0): "${token}"`);
+      for (let v = min; v <= max; v += step) values.add(v);
+    } else if (stepRange) {
+      const a = Number(stepRange[1]);
+      const b = Number(stepRange[2]);
+      const step = Number(stepRange[3]);
+      if (step <= 0) throw new Error(`Invalid cron step (must be > 0): "${token}"`);
+      for (let v = a; v <= b; v += step) values.add(v);
+    } else if (plainRange) {
+      const a = Number(plainRange[1]);
+      const b = Number(plainRange[2]);
+      for (let v = a; v <= b; v++) values.add(v);
+    } else if (single) {
+      values.add(Number(single[1]));
+    } else {
+      throw new Error(`Unsupported cron field token for launchd translation: "${token}"`);
+    }
+  }
+
+  return { kind: 'values', values: [...values].sort((a, b) => a - b) };
+}
+
+const CRON_FIELD_SPECS = [
+  { key: 'Minute', field: 'minute', min: 0, max: 59 },
+  { key: 'Hour', field: 'hour', min: 0, max: 23 },
+  { key: 'Day', field: 'dom', min: 1, max: 31 },
+  { key: 'Month', field: 'month', min: 1, max: 12 },
+  { key: 'Weekday', field: 'dow', min: 0, max: 7 },
+];
+
+// Sanity cap on the StartCalendarInterval array launchd will accept. A
+// pathological step (e.g. every minute across an unconstrained day/month)
+// would otherwise silently generate thousands of dict entries.
+const MAX_CALENDAR_COMBINATIONS = 366;
+
+/**
+ * Build the StartCalendarInterval block (BUG 4 fix). launchd has no cron
+ * step syntax — a stepped field (or a list/range) must be expressed as
+ * multiple concrete StartCalendarInterval dicts, one per combination of
+ * the non-wildcard fields' expanded values (cartesian product), inside an
+ * <array>. Schedules where every field is a plain single value or a
+ * wildcard collapse to exactly the old single <dict> shape, so existing
+ * plain-cron installs are byte-for-byte unaffected.
+ * @param {object} cron
+ * @returns {string}
+ */
+export function buildStartCalendarIntervalBlock(cron) {
+  const expanded = CRON_FIELD_SPECS
+    .map((spec) => ({ key: spec.key, expansion: expandCronField(cron[spec.field], spec.min, spec.max) }))
+    .filter((e) => e.expansion.kind !== 'wildcard');
+
+  let combos = [[]];
+  for (const { key, expansion } of expanded) {
+    const next = [];
+    for (const combo of combos) {
+      for (const value of expansion.values) {
+        next.push([...combo, { key, value }]);
+      }
+    }
+    combos = next;
+    if (combos.length > MAX_CALENDAR_COMBINATIONS) {
+      throw new Error(
+        `Cron expression expands to more than ${MAX_CALENDAR_COMBINATIONS} launchd StartCalendarInterval entries — too fine-grained to express as a step schedule on launchd. Narrow the schedule or use the cron/systemd backend instead.`
+      );
+    }
+  }
+
+  const dictFor = (combo) => {
+    const inner = combo.map(({ key, value }) => `    <key>${key}</key>\n    <integer>${value}</integer>`).join('\n');
+    return `  <dict>\n${inner}\n  </dict>`;
+  };
+
+  if (combos.length <= 1) {
+    const combo = combos[0] || [];
+    const inner = combo.map(({ key, value }) => `    <key>${key}</key>\n    <integer>${value}</integer>`).join('\n');
+    return `  <key>StartCalendarInterval</key>\n  <dict>\n${inner}\n  </dict>\n`;
+  }
+
+  const dicts = combos.map(dictFor).join('\n');
+  return `  <key>StartCalendarInterval</key>\n  <array>\n${dicts}\n  </array>\n`;
+}
+
+/**
+ * Generate the full plist content for a schedule. Pure function — safe to
+ * call in tests. Always emits an EnvironmentVariables block on launchd
+ * (auto-injected defaults when the schedule has no explicit environment).
+ * The launchd Label is agent-derived (`com.<sched.agent||'dave'>.<id>`) —
+ * see resolveLaunchdLabel.
+ * @param {object} sched
+ * @param {string} workDir
+ * @param {object} cron
+ * @returns {string}
+ */
+export function buildLaunchdPlist(sched, workDir, cron) {
+  const label = resolveLaunchdLabel(sched);
+  const calendarBlock = buildStartCalendarIntervalBlock(cron);
+
+  const cmdParts = sched.command.split(/\s+/);
+  const programArgs = cmdParts.map(p => `    <string>${xmlEscape(p)}</string>`).join('\n');
+
+  const mergedEnv = withLaunchdDefaults(resolveEnvironment(sched));
+  const envBlock = buildLaunchdEnvBlock(mergedEnv);
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${label}</string>
+  <key>ProgramArguments</key>
+  <array>
+${programArgs}
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${xmlEscape(workDir)}</string>
+${envBlock}${calendarBlock}  <key>StandardOutPath</key>
+  <string>/tmp/dave-${sched.id}-stdout.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/dave-${sched.id}-stderr.log</string>
+  <key>RunAtLoad</key>
+  <false/>
+</dict>
+</plist>
+`;
+}
+
+function installLaunchd(sched, workDir, cron) {
+  const label = resolveLaunchdLabel(sched);
+  const plistDir = join(homedir(), 'Library', 'LaunchAgents');
+  const plistPath = join(plistDir, `${label}.plist`);
+
+  mkdirSync(plistDir, { recursive: true });
+  const plist = buildLaunchdPlist(sched, workDir, cron);
+  writeFileSync(plistPath, plist, 'utf8');
+
+  // Unload if already loaded, then load
+  const uid = execSync('id -u', { encoding: 'utf8' }).trim();
+  try { execSync(`launchctl bootout gui/${uid}/${label}`, { stdio: 'pipe' }); } catch { /* not loaded */ }
+  execSync(`launchctl bootstrap gui/${uid} ${plistPath}`);
+
+  console.log(`Installed launchd schedule: ${label}`);
+  console.log(`  Plist: ${plistPath}`);
+  console.log(`  ${sched.schedule} -- ${sched.description || ''}`);
+
+  return { label, plistPath };
+}
+
+// ── Backend: systemd ─────────────────────────────────────────────────
+
+/**
+ * Build the .service unit contents.
+ * @param {object} sched
+ * @param {string} workDir
+ * @param {Record<string,string>} env
+ * @returns {string}
+ */
+export function buildSystemdService(sched, workDir, env) {
+  const description = sched.description || `Dave scheduled task: ${sched.id}`;
+  const envLines = Object.entries(env)
+    .map(([k, v]) => `Environment=${k}=${v}`)
+    .join('\n');
+  const envBlock = envLines ? `${envLines}\n` : '';
+  return `[Unit]
+Description=${description}
+
+[Service]
+Type=oneshot
+WorkingDirectory=${workDir}
+${envBlock}ExecStart=/usr/bin/env bash -c '${sched.command.replace(/'/g, `'\\''`)}'
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+/**
+ * Build the .timer unit contents.
+ * @param {object} sched
+ * @param {object} cron
+ * @returns {string}
+ */
+export function buildSystemdTimer(sched, cron) {
+  const description = sched.description || `Dave scheduled task: ${sched.id}`;
+  const dowNames = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+  const dowPart = cron.dow !== '*' ? (dowNames[Number(cron.dow)] || '*') : '';
+  let onCalendar = `*-${cron.month}-${cron.dom} ${cron.hour}:${cron.minute}:00`;
+  if (dowPart) onCalendar = `${dowPart} ${onCalendar}`;
+  return `[Unit]
+Description=Timer for ${description}
+
+[Timer]
+OnCalendar=${onCalendar}
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+`;
+}
+
+function installSystemd(sched, workDir, cron) {
+  const unitName = `dave-${sched.id}`;
+  const unitDir = join(homedir(), '.config', 'systemd', 'user');
+  mkdirSync(unitDir, { recursive: true });
+
+  const env = resolveEnvironment(sched);
+  const service = buildSystemdService(sched, workDir, env);
+  const timer = buildSystemdTimer(sched, cron);
+  writeFileSync(join(unitDir, `${unitName}.service`), service, 'utf8');
+  writeFileSync(join(unitDir, `${unitName}.timer`), timer, 'utf8');
+
+  execSync('systemctl --user daemon-reload');
+  execSync(`systemctl --user enable --now ${unitName}.timer`);
+
+  const description = sched.description || `Dave scheduled task: ${sched.id}`;
+  console.log(`Installed systemd schedule: ${unitName}`);
+  console.log(`  Service: ${join(unitDir, unitName + '.service')}`);
+  console.log(`  Timer:   ${join(unitDir, unitName + '.timer')}`);
+  console.log(`  ${sched.schedule} -- ${description}`);
+
+  return { unitName };
+}
+
+// ── Backend: schtasks (Windows) ──────────────────────────────────────
+
+/**
+ * Build the cmd.exe wrapper string used as the /TR argument to schtasks.
+ *
+ * schtasks has no native env-var support, so env vars are emitted as
+ * `set VAR=val &&` pairs before `cd /d workDir && command`. Callers
+ * that need stable cross-process env should instead write a .cmd wrapper
+ * to disk and point schtasks at it — we keep the inline form for
+ * parity with the other backends on simple schedules.
+ * @param {object} sched
+ * @param {string} workDir
+ * @param {Record<string,string>} env
+ * @returns {string}
+ */
+export function buildSchtasksCommand(sched, workDir, env) {
+  const envPrefix = Object.entries(env)
+    .map(([k, v]) => `set "${k}=${String(v).replace(/"/g, '""')}" &&`)
+    .join(' ');
+  const inner = envPrefix
+    ? `${envPrefix} cd /d ${workDir} && ${sched.command}`
+    : `cd /d ${workDir} && ${sched.command}`;
+  return `cmd /c "${inner}"`;
+}
+
+function installSchtasks(sched, workDir, cron) {
+  const taskName = `dave-${sched.id}`;
+  const env = resolveEnvironment(sched);
+
+  const fmtHour = cron.hour === '*' ? '00' : cron.hour.padStart(2, '0');
+  const fmtMin = cron.minute === '*' ? '00' : cron.minute.padStart(2, '0');
+  const startTime = `${fmtHour}:${fmtMin}`;
+
+  let scType = 'DAILY';
+  let scModifier = '';
+  const dowNames = ['SUN', 'MON', 'TUE', 'WED', 'THU', 'FRI', 'SAT'];
+
+  if (cron.dom === '*' && cron.month === '*' && cron.dow === '*') {
+    scType = 'DAILY';
+  } else if (cron.dow !== '*') {
+    scType = 'WEEKLY';
+    scModifier = `/D ${dowNames[Number(cron.dow)] || 'MON'}`;
+  } else if (cron.dom !== '*') {
+    scType = 'MONTHLY';
+    scModifier = `/D ${cron.dom}`;
+  }
+
+  try {
+    execSync(`schtasks.exe /Delete /TN "${taskName}" /F`, { stdio: 'pipe' });
+  } catch { /* not found */ }
+
+  const tr = buildSchtasksCommand(sched, workDir, env);
+  let cmd = `schtasks.exe /Create /TN "${taskName}" /TR "${tr}" /SC ${scType} /ST ${startTime}`;
+  if (scModifier) cmd += ` ${scModifier}`;
+
+  execSync(cmd);
+
+  console.log(`Installed schtasks schedule: ${taskName}`);
+  console.log(`  ${sched.schedule} -- ${sched.description || ''}`);
+
+  return { taskName };
+}
+
+// ── Main ─────────────────────────────────────────────────────────────
+
+/**
+ * Install a schedule definition using the specified backend.
+ *
+ * BUG 2 fix: this used to fall off the end of the function with no return
+ * statement, so every caller checking a result's `.ok` field (the CLI
+ * wrapper included) was reading `undefined.ok`. Every path now returns a
+ * result object; callers can rely on `.ok` being present.
+ * @param {string} scheduleFile - Path to the schedule JSON file
+ * @param {string} backend - Backend name (cron, launchd, systemd, schtasks)
+ * @param {object} [opts]
+ * @param {boolean} [opts.forceHost] - override a foreign-host refusal (with a warning)
+ * @param {string} [opts.schedulesDir] - collision-check dir; defaults to dirname(scheduleFile)
+ * @param {string} [opts.currentHost] - test-only override for the host-gate check
+ * @returns {{ ok: boolean, id: string, backend: string, skipped?: boolean, reason?: string, warnings?: string[] }}
+ */
+export function install(scheduleFile, backend, opts = {}) {
+  const sched = readSchedule(scheduleFile);
+
+  if (!sched.id || !sched.schedule || !sched.command) {
+    throw new Error('Schedule file must have id, schedule, and command fields');
+  }
+
+  const warnings = [];
+
+  // Name-collision check — refuse before touching any backend if another
+  // schedule file in the same directory resolves to the same task id.
+  checkNameCollision(scheduleFile, sched, { schedulesDir: opts.schedulesDir });
+
+  // Host-enforcement gate — refuse (exit 2) a schedule declaring a foreign
+  // host unless --force-host overrides it. Missing `host` field is a
+  // warning, not a refusal (data backfill is estate-side).
+  const hostGate = evaluateHostGate(sched, { currentHost: opts.currentHost, forceHost: opts.forceHost });
+  if (!hostGate.ok) {
+    const e = new Error(hostGate.reason);
+    e.exitCode = 2;
+    throw e;
+  }
+  if (hostGate.warning) {
+    console.warn(`Warning: ${hostGate.warning}`);
+    warnings.push(hostGate.warning);
+  }
+
+  if (sched.enabled === false) {
+    console.log(`Schedule '${sched.id}' is disabled. Set enabled=true to install.`);
+    return { ok: true, id: sched.id, backend, skipped: true, reason: 'disabled', ...(warnings.length ? { warnings } : {}) };
+  }
+
+  const workDir = resolveWorkDir(sched.workingDirectory);
+  validateWorkDir(workDir);
+  const cron = parseCron(sched.schedule);
+
+  let detail;
+  switch (backend) {
+    case 'cron':     detail = installCron(sched, workDir); break;
+    case 'launchd':  detail = installLaunchd(sched, workDir, cron); break;
+    case 'systemd':  detail = installSystemd(sched, workDir, cron); break;
+    case 'schtasks': detail = installSchtasks(sched, workDir, cron); break;
+    default:
+      throw new Error(`Unknown backend: ${backend}. Supported: cron, launchd, systemd, schtasks`);
+  }
+
+  return { ok: true, id: sched.id, backend, ...detail, ...(warnings.length ? { warnings } : {}) };
+}
+
+// Exported for tests — pure helpers.
+export { parseCron, resolveWorkDir, resolveEnvironment, substituteVars };
+
+// ── CLI entry point ──────────────────────────────────────────────────
+//
+// BUG 3 fix: the previous check compared the realpath-resolved
+// import.meta.url against the raw (possibly symlinked) process.argv[1] via
+// String#endsWith. Under pnpm, a direct invocation's argv[1] is frequently
+// a symlink (workspace link or .pnpm store link) while import.meta.url is
+// always the fully-resolved real path, so the comparison silently failed
+// and this entrypoint became a no-op that still exited 0. Fix: realpath
+// BOTH sides before comparing (matches the pattern already proven correct
+// in packages/workspace/src/server.mjs and install-daemon.mjs).
+
+function isDirectlyInvoked() {
+  if (!process.argv[1]) return false;
+  try {
+    return fileURLToPath(import.meta.url) === realpathSync(resolve(process.argv[1]));
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectlyInvoked()) {
+  const args = process.argv.slice(2);
+  if (args.length < 2) {
+    console.error('Usage: node install.mjs <schedule.json> <backend>');
+    console.error('Backends: cron, launchd, systemd, schtasks');
+    process.exit(1);
+  }
+  try {
+    install(args[0], args[1]);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+}