@sbains2/lifeos 0.2.2 → 0.3.1

package/src/commands/schedule.js

@@ -0,0 +1,748 @@
+/**
+ * `lifeos schedule` — scheduled-agent runner.
+ *
+ * Generalizes a proven pattern: an OS-level scheduler (launchd on macOS, cron
+ * on Linux) fires a small shell job every N days/hours; the job runs your agent
+ * CLI non-interactively against a markdown prompt and captures the output as a
+ * local digest you read on your own time.
+ *
+ * Subcommands:
+ *   add <name>     --prompt <file> (--every 1d|2d|12h [--at HH:MM] | --cron "<expr>")
+ *                  [--runtime claude-code|codex] [--dry-run]
+ *   list
+ *   remove <name>
+ *
+ * Trust defaults (see docs/TRUST.md — non-negotiable):
+ * - Local-first: everything the job writes lands under <target>/.lifeos/schedule/.
+ * - Draft-only: scheduled prompts inherit draft-only rules; the runner never
+ *   sends anything — it writes local files the user reviews.
+ * - No silent system mutation: on Linux we PRINT the crontab line and exact
+ *   `crontab -e` guidance instead of editing the user's crontab. On macOS the
+ *   plist install is explicit, announced, and reversible via `remove`.
+ * - Validate-before-write: name, cadence, prompt file, and existing state are
+ *   all checked before any file is touched.
+ *
+ * Structure: all string generation (plist, cron line, job script) is pure and
+ * exported so tests never need launchctl or a real scheduler.
+ */
+
+import { execFileSync } from 'node:child_process';
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { homedir as osHomedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import { c } from '../utils/colors.js';
+
+// =====================================================================
+// Runtime adapters — the multi-runtime connector table.
+// Add future runtimes (cursor-agent, gemini, ...) as new entries; everything
+// downstream (job script, dry-run output, config fallback) reads this table.
+// =====================================================================
+
+export const RUNTIME_ADAPTERS = {
+  'claude-code': {
+    id: 'claude-code',
+    label: 'Claude Code',
+    bin: 'claude',
+    // `claude -p <prompt>` (alias --print) is Claude Code's non-interactive
+    // mode: runs the prompt, writes the result to stdout, exits.
+    args: (promptRef) => ['-p', promptRef],
+  },
+  codex: {
+    id: 'codex',
+    label: 'OpenAI Codex',
+    bin: 'codex',
+    // `codex exec <prompt>` is Codex CLI's non-interactive mode.
+    args: (promptRef) => ['exec', promptRef],
+  },
+};
+
+export const DEFAULT_RUNTIME = 'claude-code';
+
+/**
+ * Shell fragment that invokes a runtime with the prompt held in $PROMPT.
+ * Pure; used verbatim inside the generated job script.
+ */
+export function buildRuntimeShellCommand(runtimeId) {
+  const adapter = RUNTIME_ADAPTERS[runtimeId];
+  if (!adapter) return null;
+  return [adapter.bin, ...adapter.args('"$PROMPT"')].join(' ');
+}
+
+/**
+ * Resolve which runtime to use: explicit flag > lifeos.config.json
+ * (agent_runtime.provider or agent_runtime.primary) > claude-code.
+ * Unknown values from config fall back silently; unknown explicit flags
+ * return null so the command can error loudly.
+ */
+export function resolveRuntime(explicit, config) {
+  if (explicit) return RUNTIME_ADAPTERS[explicit] ? explicit : null;
+  const fromConfig = config?.agent_runtime?.provider ?? config?.agent_runtime?.primary;
+  if (fromConfig && RUNTIME_ADAPTERS[fromConfig]) return fromConfig;
+  return DEFAULT_RUNTIME;
+}
+
+// =====================================================================
+// Parsing — pure
+// =====================================================================
+
+/**
+ * Parse an --every interval like "1d", "2d", "12h".
+ * Returns { value, unit: 'd'|'h', seconds } or null when invalid.
+ */
+export function parseInterval(str) {
+  if (typeof str !== 'string') return null;
+  const m = /^(\d+)([dh])$/.exec(str.trim());
+  if (!m) return null;
+  const value = Number(m[1]);
+  if (value < 1) return null;
+  const unit = m[2];
+  return { value, unit, seconds: value * (unit === 'd' ? 86400 : 3600) };
+}
+
+export const DEFAULT_AT = '08:00';
+
+/**
+ * Parse an --at time like "08:00". Returns { hour, minute } or null.
+ */
+export function parseAt(str) {
+  if (typeof str !== 'string') return null;
+  const m = /^(\d{1,2}):(\d{2})$/.exec(str.trim());
+  if (!m) return null;
+  const hour = Number(m[1]);
+  const minute = Number(m[2]);
+  if (hour > 23 || minute > 59) return null;
+  return { hour, minute };
+}
+
+// Names become launchd labels and filenames — keep the charset boring.
+export function isValidScheduleName(name) {
+  return typeof name === 'string' && /^[a-z0-9][a-z0-9_-]{0,63}$/.test(name);
+}
+
+/**
+ * Map a 5-field cron expression to launchd StartCalendarInterval keys.
+ * launchd has no step/range/list syntax, so only plain numerics and `*`
+ * translate. Returns { ok, fields } or { ok: false, error }.
+ */
+export function cronToCalendarFields(expr) {
+  const parts = String(expr).trim().split(/\s+/);
+  if (parts.length !== 5) {
+    return { ok: false, error: 'cron expression must have 5 fields (minute hour day month weekday)' };
+  }
+  const keys = ['Minute', 'Hour', 'Day', 'Month', 'Weekday'];
+  const max = { Minute: 59, Hour: 23, Day: 31, Month: 12, Weekday: 7 };
+  const fields = {};
+  for (let i = 0; i < 5; i++) {
+    const p = parts[i];
+    if (p === '*') continue;
+    if (!/^\d+$/.test(p)) {
+      return {
+        ok: false,
+        error: `launchd can't express "${p}" (steps/ranges/lists) — use plain numbers, or use --every instead`,
+      };
+    }
+    const n = Number(p);
+    if (n > max[keys[i]]) {
+      return { ok: false, error: `cron field ${keys[i].toLowerCase()} out of range: ${p}` };
+    }
+    fields[keys[i]] = n;
+  }
+  if (Object.keys(fields).length === 0) {
+    return { ok: false, error: 'cron "* * * * *" (every minute) is not supported — use --every' };
+  }
+  return { ok: true, fields };
+}
+
+/**
+ * Derive a cron expression from an --every interval (+ optional --at).
+ * "*\/N" day-of-month steps drift at month boundaries; the generated job
+ * script self-gates on a last-run stamp, so an occasional extra fire is a
+ * no-op rather than a double run.
+ */
+export function cronExprFromEvery(interval, at) {
+  if (interval.unit === 'h') {
+    return `0 */${interval.value} * * *`;
+  }
+  const { hour, minute } = at ?? parseAt(DEFAULT_AT);
+  if (interval.value === 1) return `${minute} ${hour} * * *`;
+  return `${minute} ${hour} */${interval.value} * *`;
+}
+
+// =====================================================================
+// Artifact string generation — pure, fully unit-testable
+// =====================================================================
+
+function xmlEscape(s) {
+  return String(s)
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+}
+
+// POSIX single-quote escaping: close, escaped quote, reopen.
+function shQuote(s) {
+  return `'${String(s).replaceAll("'", `'\\''`)}'`;
+}
+
+/**
+ * Decide the launchd trigger for a schedule spec.
+ * - --cron → StartCalendarInterval mapped from the cron fields
+ * - --every Nh → StartInterval (seconds)
+ * - --every Nd → StartCalendarInterval at --at, daily; launchd can't express
+ *   multi-day cadence, so N>1 is enforced by the job script's last-run gate.
+ */
+export function launchdTrigger({ interval, at, cron }) {
+  if (cron) {
+    const mapped = cronToCalendarFields(cron);
+    if (!mapped.ok) return mapped;
+    return { ok: true, kind: 'calendar-fields', fields: mapped.fields };
+  }
+  if (interval.unit === 'h') return { ok: true, kind: 'interval', seconds: interval.seconds };
+  const time = at ?? parseAt(DEFAULT_AT);
+  return { ok: true, kind: 'calendar', hour: time.hour, minute: time.minute };
+}
+
+/**
+ * Generate the ~/Library/LaunchAgents plist as a string. Pure.
+ */
+export function buildLaunchdPlist({ name, jobScriptPath, trigger, stderrLogPath }) {
+  const label = `com.lifeos.${name}`;
+  let triggerXml;
+  if (trigger.kind === 'interval') {
+    triggerXml = [
+      '  <key>StartInterval</key>',
+      `  <integer>${trigger.seconds}</integer>`,
+    ].join('\n');
+  } else if (trigger.kind === 'calendar') {
+    triggerXml = [
+      '  <key>StartCalendarInterval</key>',
+      '  <dict>',
+      `    <key>Hour</key><integer>${trigger.hour}</integer>`,
+      `    <key>Minute</key><integer>${trigger.minute}</integer>`,
+      '  </dict>',
+    ].join('\n');
+  } else {
+    const rows = Object.entries(trigger.fields)
+      .map(([k, v]) => `    <key>${k}</key><integer>${v}</integer>`)
+      .join('\n');
+    triggerXml = ['  <key>StartCalendarInterval</key>', '  <dict>', rows, '  </dict>'].join('\n');
+  }
+  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>${xmlEscape(label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/sh</string>
+    <string>${xmlEscape(jobScriptPath)}</string>
+  </array>
+${triggerXml}
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(stderrLogPath)}</string>
+</dict>
+</plist>
+`;
+}
+
+/**
+ * Generate the crontab line for Linux. Pure. We never install this — trust
+ * default: no silent system mutation. The caller prints it with `crontab -e`
+ * guidance.
+ */
+export function buildCronLine({ interval, at, cron, jobScriptPath }) {
+  const expr = cron ? String(cron).trim() : cronExprFromEvery(interval, at);
+  return `${expr} /bin/sh ${shQuote(jobScriptPath)}`;
+}
+
+/**
+ * Generate the job shell script. Pure. The script:
+ *   1. cds into the target dir
+ *   2. (multi-day cadence only) gates on a last-run stamp
+ *   3. runs the runtime CLI non-interactively with the prompt file contents
+ *   4. appends stdout+stderr to .lifeos/schedule/logs/<name>.log
+ *   5. overwrites .lifeos/schedule/out/<name>-latest.md — the digest
+ */
+export function buildJobScript({ targetDir, promptPath, runtimeId, name, gateSeconds = null }) {
+  const runtimeCmd = buildRuntimeShellCommand(runtimeId);
+  if (!runtimeCmd) return null;
+
+  // launchd/cron can't express "every N days" natively — on macOS the plist
+  // fires DAILY, so the job itself must enforce the cadence: an --every Nd job
+  // must never run more often than every N days. We gate on a last-run stamp
+  // and require the FULL interval to have elapsed before running again (no
+  // undershoot — undershooting would let the job run early, breaking the
+  // cadence guarantee). The stamp is written before the run so a same-second
+  // re-fire can't double-run.
+  const gateBlock =
+    gateSeconds == null
+      ? ''
+      : `
+STAMP=".lifeos/schedule/state/${name}.last-run"
+NOW="$(date +%s)"
+if [ -f "$STAMP" ]; then
+  LAST="$(cat "$STAMP" 2>/dev/null)"
+  [ -n "$LAST" ] || LAST=0
+  if [ $((NOW - LAST)) -lt ${gateSeconds} ]; then
+    exit 0
+  fi
+fi
+printf '%s' "$NOW" > "$STAMP"
+`;
+
+  return `#!/bin/sh
+# Generated by \`lifeos schedule add ${name}\`. Safe to delete; recreate with the CLI.
+# Trust defaults: this job runs locally and never sends anything — it only
+# writes files under .lifeos/schedule/ for you to review.
+set -u
+
+cd ${shQuote(targetDir)} || exit 1
+mkdir -p .lifeos/schedule/logs .lifeos/schedule/out .lifeos/schedule/state
+${gateBlock}
+PROMPT="$(cat ${shQuote(promptPath)})" || exit 1
+STARTED="$(date '+%Y-%m-%d %H:%M:%S')"
+OUTPUT="$(${runtimeCmd} 2>&1)"
+STATUS=$?
+
+{
+  printf '\\n===== ${name} run %s (exit %s) =====\\n' "$STARTED" "$STATUS"
+  printf '%s\\n' "$OUTPUT"
+} >> ".lifeos/schedule/logs/${name}.log"
+
+printf '%s\\n' "$OUTPUT" > ".lifeos/schedule/out/${name}-latest.md"
+exit $STATUS
+`;
+}
+
+// =====================================================================
+// State — <targetDir>/.lifeos/schedule/schedules.json
+// =====================================================================
+
+export function schedulesPath(targetDir) {
+  return join(targetDir, '.lifeos', 'schedule', 'schedules.json');
+}
+
+/**
+ * Read schedule state. Returns { ok, data } or { ok: false, error } — a
+ * corrupt file is an error, never silently clobbered (validate-before-write).
+ */
+export function loadSchedules(targetDir) {
+  const p = schedulesPath(targetDir);
+  if (!existsSync(p)) return { ok: true, data: { version: 1, schedules: [] } };
+  try {
+    return { ok: true, data: JSON.parse(readFileSync(p, 'utf8')) };
+  } catch (err) {
+    return { ok: false, error: `${p} is not valid JSON (${err.message}) — fix or delete it, then retry` };
+  }
+}
+
+export function saveSchedules(targetDir, data) {
+  const p = schedulesPath(targetDir);
+  mkdirSync(join(targetDir, '.lifeos', 'schedule'), { recursive: true });
+  writeFileSync(p, JSON.stringify(data, null, 2) + '\n', 'utf8');
+}
+
+// =====================================================================
+// Planning — pure given (targetDir, opts); reads fs only to validate inputs
+// =====================================================================
+
+function readConfig(targetDir) {
+  const p = join(targetDir, 'lifeos.config.json');
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+  } catch {
+    return null; // malformed config never blocks scheduling; runtime just falls back
+  }
+}
+
+/**
+ * Validate inputs and compute every artifact for `add` without writing
+ * anything. Returns { ok, plan } or { ok: false, error, usage? }.
+ */
+export function planScheduleAdd(targetDir, opts) {
+  const { name, prompt, every, cron, at, runtime: runtimeFlag, platform, homedir } = opts;
+
+  if (!isValidScheduleName(name)) {
+    return {
+      ok: false,
+      usage: true,
+      error: `invalid name "${name ?? ''}" — use lowercase letters, digits, hyphens, underscores (e.g. "digest")`,
+    };
+  }
+  if (!prompt) {
+    return { ok: false, usage: true, error: 'missing --prompt <file> — the markdown prompt the agent runs' };
+  }
+  if (every && cron) {
+    return { ok: false, usage: true, error: '--every and --cron are mutually exclusive — pick one' };
+  }
+  if (!every && !cron) {
+    return { ok: false, usage: true, error: 'missing cadence — pass --every <interval> (e.g. 1d, 12h) or --cron "<expr>"' };
+  }
+
+  let interval = null;
+  let atTime = null;
+  if (every) {
+    interval = parseInterval(every);
+    if (!interval) {
+      return { ok: false, usage: true, error: `invalid --every "${every}" — use <n>d or <n>h (e.g. 1d, 2d, 12h)` };
+    }
+    if (at && interval.unit === 'h') {
+      return { ok: false, usage: true, error: '--at only applies to day-based intervals (--every 1d --at 08:00)' };
+    }
+    if (interval.unit === 'd') {
+      atTime = parseAt(at ?? DEFAULT_AT);
+      if (!atTime) {
+        return { ok: false, usage: true, error: `invalid --at "${at}" — use HH:MM (e.g. 08:00)` };
+      }
+    }
+  }
+  if (cron && at) {
+    return { ok: false, usage: true, error: '--at only applies with --every; encode the time in the cron expression' };
+  }
+
+  const promptPath = isAbsolute(prompt) ? prompt : resolve(targetDir, prompt);
+  if (!existsSync(promptPath)) {
+    return { ok: false, error: `prompt file not found: ${promptPath}` };
+  }
+
+  const runtimeId = resolveRuntime(runtimeFlag, readConfig(targetDir));
+  if (!runtimeId) {
+    const known = Object.keys(RUNTIME_ADAPTERS).join(', ');
+    return { ok: false, usage: true, error: `unknown --runtime "${runtimeFlag}" — supported: ${known}` };
+  }
+
+  if (platform !== 'darwin' && platform !== 'linux') {
+    return { ok: false, error: `unsupported platform "${platform}" — lifeos schedule supports macOS (launchd) and Linux (cron)` };
+  }
+
+  const jobScriptPath = join(targetDir, '.lifeos', 'schedule', 'jobs', `${name}.sh`);
+  const gateSeconds = interval && interval.unit === 'd' && interval.value > 1 ? interval.seconds : null;
+  const jobScript = buildJobScript({ targetDir, promptPath, runtimeId, name, gateSeconds });
+
+  const plan = {
+    name,
+    runtimeId,
+    promptPath,
+    interval,
+    at: atTime,
+    cron: cron ?? null,
+    platform,
+    jobScriptPath,
+    jobScript,
+    digestPath: join(targetDir, '.lifeos', 'schedule', 'out', `${name}-latest.md`),
+    logPath: join(targetDir, '.lifeos', 'schedule', 'logs', `${name}.log`),
+  };
+
+  if (platform === 'darwin') {
+    const trigger = launchdTrigger({ interval, at: atTime, cron });
+    if (!trigger.ok) return { ok: false, error: trigger.error };
+    plan.plistPath = join(homedir, 'Library', 'LaunchAgents', `com.lifeos.${name}.plist`);
+    plan.plist = buildLaunchdPlist({
+      name,
+      jobScriptPath,
+      trigger,
+      stderrLogPath: join(targetDir, '.lifeos', 'schedule', 'logs', `${name}.launchd.err.log`),
+    });
+  } else {
+    plan.cronLine = buildCronLine({ interval, at: atTime, cron, jobScriptPath });
+  }
+
+  return { ok: true, plan };
+}
+
+function cadenceLabel(entry) {
+  if (entry.cron) return `cron "${entry.cron}"`;
+  return entry.at ? `every ${entry.interval} at ${entry.at}` : `every ${entry.interval}`;
+}
+
+// =====================================================================
+// Command orchestrator
+// =====================================================================
+
+export const SCHEDULE_HELP = `lifeos schedule — run an agent prompt on a schedule, digest the output locally
+
+Usage:
+  lifeos schedule add <name> --prompt <file> (--every <interval> [--at HH:MM] | --cron "<expr>") [options]
+  lifeos schedule list
+  lifeos schedule remove <name>
+
+Add options:
+  --prompt <file>   Markdown prompt the agent runs (required)
+  --every <n>{d|h}  Cadence: 1d, 2d, 12h ... (mutually exclusive with --cron)
+  --at HH:MM        Time of day for day-based intervals (default 08:00)
+  --cron "<expr>"   5-field cron expression instead of --every
+  --runtime <id>    claude-code | codex (default: agent_runtime from
+                    lifeos.config.json, else claude-code)
+  --dry-run         Print the artifacts (job script + plist/cron line),
+                    install nothing
+
+Platform behavior:
+  macOS   installs ~/Library/LaunchAgents/com.lifeos.<name>.plist (launchctl load)
+  Linux   prints the crontab line + "crontab -e" guidance — your crontab is
+          never edited silently
+
+Trust defaults: scheduled prompts inherit draft-only rules. The runner never
+sends anything — it writes local files under .lifeos/schedule/ for you to review.
+
+Try the bundled digest prompt:
+  lifeos schedule add digest --prompt templates/prompts/weekly_digest.md --every 1d
+`;
+
+const VALUE_FLAGS = new Set(['--prompt', '--every', '--cron', '--at', '--runtime']);
+const BOOL_FLAGS = new Set(['--dry-run', '--help', '-h']);
+
+/**
+ * Minimal argv parser for the schedule surface. bin/lifeos.js's global parser
+ * treats flags as valueless; schedule needs value flags, so it parses its own
+ * raw argv slice.
+ */
+export function parseScheduleArgs(argv) {
+  const out = { positional: [], flags: {}, errors: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (VALUE_FLAGS.has(a)) {
+      const v = argv[i + 1];
+      if (v === undefined || v.startsWith('--')) out.errors.push(`${a} requires a value`);
+      else {
+        out.flags[a.slice(2)] = v;
+        i++;
+      }
+    } else if (BOOL_FLAGS.has(a)) {
+      out.flags[a === '-h' ? 'help' : a.slice(2)] = true;
+    } else if (a.startsWith('-')) {
+      out.errors.push(`unknown flag: ${a}`);
+    } else {
+      out.positional.push(a);
+    }
+  }
+  return out;
+}
+
+function defaultExec(cmd, args) {
+  execFileSync(cmd, args, { stdio: 'ignore' });
+}
+
+/**
+ * Entry point wired by bin/lifeos.js. argv is everything after the
+ * "schedule" token. deps are injectable for tests (never call launchctl in
+ * tests — pass a stub exec).
+ */
+export async function runSchedule(targetDir, argv = [], deps = {}) {
+  const {
+    platform = process.platform,
+    homedir = osHomedir(),
+    exec = defaultExec,
+    log = console.log,
+    logError = console.error,
+    now = () => new Date(),
+  } = deps;
+
+  const { positional, flags, errors } = parseScheduleArgs(argv);
+  const subcommand = positional[0];
+
+  if (flags.help || subcommand === 'help') {
+    log(SCHEDULE_HELP);
+    return 0;
+  }
+  if (errors.length > 0) {
+    for (const e of errors) logError(c.err(`✗ ${e}`));
+    return 2;
+  }
+
+  if (subcommand === 'add') {
+    return runAdd(targetDir, positional[1], flags, { platform, homedir, exec, log, logError, now });
+  }
+  if (subcommand === 'list') {
+    return runList(targetDir, { log, logError });
+  }
+  if (subcommand === 'remove') {
+    return runRemove(targetDir, positional[1], { platform, exec, log, logError });
+  }
+
+  logError(c.err(`✗ unknown subcommand: ${subcommand ?? '(none)'}`));
+  log('');
+  log(SCHEDULE_HELP);
+  return 2;
+}
+
+function runAdd(targetDir, name, flags, { platform, homedir, exec, log, logError, now }) {
+  const planned = planScheduleAdd(targetDir, {
+    name,
+    prompt: flags.prompt,
+    every: flags.every,
+    cron: flags.cron,
+    at: flags.at,
+    runtime: flags.runtime,
+    platform,
+    homedir,
+  });
+  if (!planned.ok) {
+    logError(c.err(`✗ ${planned.error}`));
+    if (planned.usage) logError(c.dim('  see: lifeos schedule --help'));
+    return planned.usage ? 2 : 1;
+  }
+  const plan = planned.plan;
+
+  if (flags['dry-run']) {
+    log('');
+    log(c.bold('lifeos schedule add --dry-run') + c.dim(' — would create (installing nothing):'));
+    log('');
+    log(c.cyan(`  job script → ${plan.jobScriptPath}`));
+    log(indent(plan.jobScript));
+    if (platform === 'darwin') {
+      log(c.cyan(`  launchd plist → ${plan.plistPath} (then: launchctl load)`));
+      log(indent(plan.plist));
+    } else {
+      log(c.cyan('  crontab line (printed, never installed for you):'));
+      log(indent(plan.cronLine));
+    }
+    log(c.dim(`  state entry → ${schedulesPath(targetDir)}`));
+    log(c.dim(`  digest lands at ${plan.digestPath}`));
+    log('');
+    return 0;
+  }
+
+  // Validate-before-write: state must be readable and the name free before
+  // anything is created.
+  const state = loadSchedules(targetDir);
+  if (!state.ok) {
+    logError(c.err(`✗ ${state.error}`));
+    return 1;
+  }
+  if (state.data.schedules.some((s) => s.name === plan.name)) {
+    logError(c.err(`✗ a schedule named "${plan.name}" already exists — remove it first: lifeos schedule remove ${plan.name}`));
+    return 1;
+  }
+
+  mkdirSync(join(targetDir, '.lifeos', 'schedule', 'jobs'), { recursive: true });
+  mkdirSync(join(targetDir, '.lifeos', 'schedule', 'logs'), { recursive: true });
+  mkdirSync(join(targetDir, '.lifeos', 'schedule', 'out'), { recursive: true });
+  writeFileSync(plan.jobScriptPath, plan.jobScript, 'utf8');
+  chmodSync(plan.jobScriptPath, 0o755);
+
+  if (platform === 'darwin') {
+    mkdirSync(join(homedir, 'Library', 'LaunchAgents'), { recursive: true });
+    writeFileSync(plan.plistPath, plan.plist, 'utf8');
+    // Unload first in case a stale job holds the label; load errors are real.
+    try {
+      exec('launchctl', ['unload', plan.plistPath]);
+    } catch {
+      /* not loaded — fine */
+    }
+    try {
+      exec('launchctl', ['load', plan.plistPath]);
+    } catch (err) {
+      logError(c.err(`✗ launchctl load failed: ${err.message}`));
+      logError(c.dim(`  the plist is written at ${plan.plistPath} — retry with: launchctl load ${plan.plistPath}`));
+      return 1;
+    }
+  }
+
+  state.data.schedules.push({
+    name: plan.name,
+    prompt: plan.promptPath,
+    interval: plan.interval ? `${plan.interval.value}${plan.interval.unit}` : null,
+    at: plan.at ? `${String(plan.at.hour).padStart(2, '0')}:${String(plan.at.minute).padStart(2, '0')}` : null,
+    cron: plan.cron,
+    runtime: plan.runtimeId,
+    platform,
+    job_script: plan.jobScriptPath,
+    plist: plan.plistPath ?? null,
+    created: now().toISOString(),
+  });
+  saveSchedules(targetDir, state.data);
+
+  log('');
+  log(c.bold(c.ok(`✓ schedule "${plan.name}" added`)) + c.dim(` (${RUNTIME_ADAPTERS[plan.runtimeId].label})`));
+  if (platform === 'darwin') {
+    log(c.dim(`  launchd job installed: ${plan.plistPath}`));
+  } else {
+    log('');
+    log(c.warn('  Linux: your crontab is never edited silently. Install the job yourself:'));
+    log(`    1. run ${c.cyan('crontab -e')}`);
+    log('    2. add this line:');
+    log(`       ${c.cyan(plan.cronLine)}`);
+  }
+  log(c.dim(`  digest:  ${plan.digestPath}`));
+  log(c.dim(`  log:     ${plan.logPath}`));
+  log('');
+  log(c.dim('  Trust defaults: scheduled prompts inherit draft-only rules. This runner'));
+  log(c.dim('  never sends anything — it writes local files you review.'));
+  log('');
+  return 0;
+}
+
+function runList(targetDir, { log, logError }) {
+  const state = loadSchedules(targetDir);
+  if (!state.ok) {
+    logError(c.err(`✗ ${state.error}`));
+    return 1;
+  }
+  log('');
+  log(c.bold('lifeos schedule list'));
+  log('');
+  if (state.data.schedules.length === 0) {
+    log(c.dim('  no schedules installed. Try:'));
+    log(c.dim('    lifeos schedule add digest --prompt templates/prompts/weekly_digest.md --every 1d'));
+    log('');
+    return 0;
+  }
+  for (const s of state.data.schedules) {
+    log(`  ${c.check} ${c.bold(s.name)} ${c.dim(`— ${cadenceLabel(s)}, ${s.runtime}`)}`);
+    log(c.dim(`     prompt:  ${s.prompt}`));
+    log(c.dim(`     digest:  ${join(targetDir, '.lifeos', 'schedule', 'out', `${s.name}-latest.md`)}`));
+    log(c.dim(`     created: ${s.created}`));
+  }
+  log('');
+  return 0;
+}
+
+function runRemove(targetDir, name, { platform, exec, log, logError }) {
+  const state = loadSchedules(targetDir);
+  if (!state.ok) {
+    logError(c.err(`✗ ${state.error}`));
+    return 1;
+  }
+  const entry = state.data.schedules.find((s) => s.name === name);
+  if (!entry) {
+    logError(c.err(`✗ no schedule named "${name ?? ''}" — see: lifeos schedule list`));
+    return 1;
+  }
+
+  if (entry.plist) {
+    try {
+      exec('launchctl', ['unload', entry.plist]);
+    } catch {
+      /* already unloaded — still remove the plist */
+    }
+    rmSync(entry.plist, { force: true });
+  }
+  if (entry.job_script) rmSync(entry.job_script, { force: true });
+  state.data.schedules = state.data.schedules.filter((s) => s.name !== name);
+  saveSchedules(targetDir, state.data);
+
+  log('');
+  log(c.bold(c.ok(`✓ schedule "${name}" removed`)));
+  if (platform === 'linux' || (!entry.plist && entry.platform === 'linux')) {
+    log(c.warn(`  reminder: remove the matching line from your crontab (${c.cyan('crontab -e')}) — it was never installed by lifeos, so it's only there if you added it.`));
+  }
+  log(c.dim(`  past digests/logs under .lifeos/schedule/ are kept — delete them yourself if unwanted.`));
+  log('');
+  return 0;
+}
+
+function indent(block) {
+  return block
+    .split('\n')
+    .map((l) => (l.length > 0 ? `    ${l}` : l))
+    .join('\n');
+}