@awebai/oats 0.22.10 → 0.22.14

package/docs/release-notes/v0.22.13.md

@@ -0,0 +1,44 @@
+# OATS v0.22.13
+
+Terminal essentials for the Desktop and one kernel operation behind them:
+attachments reach the agent as a path, never as typed input.
+
+## Attachments (kernel)
+
+`oats session upload --file <local> --home <abs>` copies a file into the
+instance home's private `.oats-attachments/` directory (0700, file 0600,
+`name-2` when the name is taken) and answers `{path, bytes, sha256}`. With
+`--server <id> --instance <name>` (or `--home`), the same saved route as
+`session attach` is resolved, the remote must advertise the new
+`session-upload` feature, and the bytes travel on ssh stdin into
+`oats session receive --home <abs> --name <file>` on the execution host,
+which reads stdin event-driven, enforces the 64 MiB kernel bound before
+writing anything, allocates the destination exclusively so simultaneous
+uploads never overwrite each other, refuses a symlinked or redirected
+attachments directory, and reports the path only after the bytes are
+synced. The local side refuses the answer unless size and sha256 equal the
+local file's. Each side buffers the whole file up to the bound; a remote
+file is never a local path over SSH. Upload never sends terminal input.
+`oats version --json` lists `session-upload` in `remote` and `features`.
+The CLI's temporary tmux viewer session hides its status line; the agents'
+session and the operator's tmux settings are untouched.
+
+## Desktop
+
+Drop files or paste clipboard images onto an agent terminal: the paths are
+inserted into the draft with bracketed paste and no Enter, local files in
+place, clipboard images saved privately under the app's data directory, and
+remote terminals uploaded through the installed CLI first (both CLIs must
+advertise `session-upload`; a failed transfer leaves the draft unchanged and
+never inserts a local path). Up to 16 files and 25 MB per drop. The viewer's
+tmux status bar is hidden. Ctrl+Tab stays tab navigation inside terminals
+on macOS while other Ctrl chords stay with the program. An already-open
+terminal fills an empty split without a second attach; separators resize by
+pointer or keyboard. Guide: docs/desktop.md, "Attach files and screenshots".
+
+## Design
+
+docs/design/2026-09-07-architecture-reassessment.md records the direction:
+keep the package and capability-layer machinery, fix the places where the
+CLI and GUI bypass it, one session contract with both tmux and Herdr
+adapters until Herdr is qualified, and the Desktop correction sequence.

package/docs/release-notes/v0.22.14.md

@@ -0,0 +1,48 @@
+# OATS v0.22.14
+
+The same reviewed content as the unpublished v0.22.13 tag, whose hosted
+run failed in one Desktop test pin before anything was published; the
+test now checks the behaviour instead of the source text.
+
+Terminal essentials for the Desktop and one kernel operation behind them:
+attachments reach the agent as a path, never as typed input.
+
+## Attachments (kernel)
+
+`oats session upload --file <local> --home <abs>` copies a file into the
+instance home's private `.oats-attachments/` directory (0700, file 0600,
+`name-2` when the name is taken) and answers `{path, bytes, sha256}`. With
+`--server <id> --instance <name>` (or `--home`), the same saved route as
+`session attach` is resolved, the remote must advertise the new
+`session-upload` feature, and the bytes travel on ssh stdin into
+`oats session receive --home <abs> --name <file>` on the execution host,
+which reads stdin event-driven, enforces the 64 MiB kernel bound before
+writing anything, allocates the destination exclusively so simultaneous
+uploads never overwrite each other, refuses a symlinked or redirected
+attachments directory, and reports the path only after the bytes are
+synced. The local side refuses the answer unless size and sha256 equal the
+local file's. Each side buffers the whole file up to the bound; a remote
+file is never a local path over SSH. Upload never sends terminal input.
+`oats version --json` lists `session-upload` in `remote` and `features`.
+The CLI's temporary tmux viewer session hides its status line; the agents'
+session and the operator's tmux settings are untouched.
+
+## Desktop
+
+Drop files or paste clipboard images onto an agent terminal: the paths are
+inserted into the draft with bracketed paste and no Enter, local files in
+place, clipboard images saved privately under the app's data directory, and
+remote terminals uploaded through the installed CLI first (both CLIs must
+advertise `session-upload`; a failed transfer leaves the draft unchanged and
+never inserts a local path). Up to 16 files and 25 MB per drop. The viewer's
+tmux status bar is hidden. Ctrl+Tab stays tab navigation inside terminals
+on macOS while other Ctrl chords stay with the program. An already-open
+terminal fills an empty split without a second attach; separators resize by
+pointer or keyboard. Guide: docs/desktop.md, "Attach files and screenshots".
+
+## Design
+
+docs/design/2026-09-07-architecture-reassessment.md records the direction:
+keep the package and capability-layer machinery, fix the places where the
+CLI and GUI bypass it, one session contract with both tmux and Herdr
+adapters until Herdr is qualified, and the Desktop correction sequence.

package/docs/schedules.md

@@ -0,0 +1,143 @@
+# Schedules
+
+A schedule launches an agent, runs an oats command, or wakes an existing
+instance on a cron. Definitions belong to a scope, the team workspace (the
+config level that declares the team, else the outermost `oats-config.yaml`
+level), and are committable; every `oats schedule` command run anywhere
+inside that scope, including from an instance home, reads and writes the
+same file. Execution belongs to the host that holds the scope, so a
+schedule on a registered server keeps running while your laptop sleeps.
+
+There is no daemon. One host timer (a launchd user agent on macOS, a systemd
+user timer on Linux) runs `oats schedule tick --host` once a minute; the tick
+is a short-lived process that evaluates only the current minute, launches
+what is due through the same `spawn`, `session start` and `session input`
+paths you use by hand, records what it observed, and exits. Minutes missed
+while the machine slept are skipped, never replayed. There are no retries
+and no queue.
+
+## Files
+
+- `<workspace>/oats-schedules.json` — the definitions (`{version: 1, jobs:
+  {<id>: ...}}`). Commit it if you want the schedule shared with the team.
+- `<workspace>/.agents/schedules/state.json` — last attempted minute and
+  last run per job (gitignored), plus one lock directory per running job.
+- `~/.oats/schedules/registry.json` — the host registry: which scopes the
+  host ticks, `maxConcurrent` (default 1) and the tick interval. One host
+  lock serializes ticks, run-now, reconcile and remove; it is never reclaimed
+  by another process: a lock whose owner is unreadable or gone is reported
+  with the directory to remove, and the holder removes its own lock on exit
+  and on SIGINT/SIGTERM. Definition edits take a short per-scope lock.
+
+## Kinds
+
+- **spawn** `{id, enabled, cron, tz, kind: "spawn", agent, agentsRoot?,
+  repo?, backend?, purpose?, task, runtime?, model?, yolo?, wake?}` — every
+  due minute launches one disposable instance of `agent` with the same
+  options `oats spawn` takes. `agentsRoot` names the exact agents root that
+  holds the soul (it must lie inside the workspace and defaults to the
+  workspace's own root); it is what tells same-named souls in different
+  member repositories apart. `repo` is the work repository, as `--repo`. The task gets a trailing schedule block naming the job and the
+  minute and ending with `oats retire --self`. An optional `wake` object
+  (`{cron, tz, message}`) attaches a wake schedule to each launched instance;
+  nothing is attached unless you ask.
+- **command** `{id, enabled, cron, tz, kind: "command", cwd, argv}` — runs
+  an oats-only argv (`argv[0]` is `oats`, no shell) in `cwd`, which must be
+  inside the workspace. The runner parses the command's envelope and tracks
+  any instance it names, so `["oats", "okf", "harvest"]` run in a source
+  instance's home is followed until the harvester it spawned is gone.
+  Command return is not task completion.
+- **wake** `{id, enabled, cron, tz, kind: "wake", home, message}` — every
+  due minute inspects the instance at `home` through its session receipts.
+  Running: `message` is delivered once with `session input`. Not running
+  (absent, dead pane or fallback shell): the same home is started with
+  `session start` and the message becomes the job's one pending delivery,
+  completed on a later tick, any tick, as soon as the session is active; the
+  home is started again only at due minutes, never every minute, so a
+  harness that keeps exiting is not restarted in a loop. A job holds at most
+  one pending delivery: a due minute while one is pending adds nothing.
+  Unobservable or still starting: skipped with the reason, delivery kept
+  pending. Whether a running harness is busy cannot be seen from the
+  terminal: delivery is terminal input (bracketed paste plus Enter), never an
+  interrupt, never Ctrl-C, never into a stopped or starting shell. Word wake
+  messages so that receiving one again is harmless.
+
+`cron` has five fields (minute hour day month weekday) and `tz` is a
+required IANA zone; both are evaluated by the croner library. `--wake-every
+N` at spawn time means `*/N * * * *`: every 7 fires at :00, :07, ... :56 and
+then :00 again, so 1, 5, 10, 15 and 30 give an even cadence.
+
+## Commands
+
+```sh
+oats schedule add <id> --file spec.json --dir <workspace> --json
+oats schedule update <id> --file spec.json
+oats schedule list | show <id> | enable <id> | disable <id> | remove <id>
+oats schedule run <id>            # now, under the same lock and bound
+oats schedule tick --dry-run      # what would run this minute, launching nothing
+oats schedule reconcile <id> [--clear]   # resolve an attempt whose result was never recorded
+oats schedule host install        # register this scope and install the ONE host timer (idempotent while active)
+oats schedule host status | uninstall
+oats spawn <agent> ... --wake-every 15 --wake-message "Anything new?"   # or --wake-file spec.json
+```
+
+Every subcommand takes `--server <id>` instead of `--dir`: it then runs on
+that host, in its registered workspace, because schedules are host-owned.
+
+`list --json` answers `{schedules: [{id, ...definition, nextRun, lastRun,
+running}], scheduler: {installed, active, lastTick, maxConcurrent, ...}}`.
+`active` is what the OS reports about the timer, not whether a file exists.
+
+## What a run reports
+
+`launched` (spawn or command returned), `active` (the instance is running;
+a home whose retirement is pending still counts, its runtime may be alive),
+`ended` (its home is gone), `stopped` (home present, nothing running: needs
+attention, never removed for you), `launch-failed`, `unknown`, and for wake
+jobs `delivered`, `started` or `skipped`. The kernel never claims a task
+succeeded.
+
+`unknown` means the launch's side effects are unconfirmed: a command timed
+out or answered no envelope, an envelope named an instance the roster
+cannot place, or an attempt was never recorded. The job keeps its slot and
+is skipped until `oats schedule reconcile <id>`. Reconcile adopts only an
+attributable receipt: a spawn job's instance is named deterministically for
+its minute, a command job's only by the instance its answer named. Nothing
+is inferred from file times. A command whose answer named nothing stays
+unknown; check the roster and the host by hand, then
+`oats schedule reconcile <id> --clear` records launch-failed and frees the
+slot (or `remove --force` forgets the job).
+
+A wake job that starts a stopped home holds a launch slot while that
+runtime is starting, active, retiring or unobservable, and releases it when
+the runtime is proven stopped (the session start receipt's exit marker for
+that launch, or a home that no longer has a session) or the home is gone.
+A persistent home that outlives its process does not keep a slot. Delivering
+a message to a home that is already running takes no slot. The host tick
+observes every registered scope first, then admits due jobs in one
+host-wide order, least recently launched first (only an actual runtime
+launch counts; a skipped or pending job keeps its place at the front), so
+one frequent job in one scope cannot keep the only slot forever. An invalid
+or malformed definition is reported on that job and the rest of the tick
+continues.
+
+`disable` never stops anything. `update` never touches a running instance,
+and while a job holds a slot or has an unresolved attempt what its run is
+tracked or reconciled by (kind, agent, agentsRoot, repo, purpose, home, cwd,
+argv) cannot change; cron, tz, task, message, runtime, model and enabled
+can. A cold wake persists its slot before the session start runs and keeps
+it on any start exception, whatever its code (the kernel can refuse while
+recording, after the session exists); the next observation releases it once
+the runtime is proven stopped or absent, one tick at worst.
+`remove` refuses while the job's instance is still tracked (`--force`
+forgets the job without stopping anything). Retiring an instance removes the
+wake jobs bound to its home; a wake whose home is gone otherwise stays
+listed with its skipped reason.
+
+## Wake at spawn
+
+`oats spawn ... --wake-file <private JSON {cron, tz, message, enabled}>`
+saves a wake job `wake-<instance>` bound to the new home after the spawn
+succeeded. If the spawn succeeds but the save fails, the spawn result still
+carries the full instance receipt, plus `wakeScheduleError` and a warning;
+the instance is neither hidden nor spawned again.

package/lib/attachments.mjs

@@ -0,0 +1,164 @@
+/** Instance attachments: bytes a viewer drops or pastes for an agent, kept as
+ *  private files INSIDE the instance home so the agent can read them by path.
+ *  Upload never touches the terminal; the caller pastes the returned path.
+ *  Remote uploads stream through the same ssh transport as every routed
+ *  command, into `oats session receive` on the execution host. */
+import { createHash } from "node:crypto";
+import { closeSync, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readSync, rmSync, statSync, writeSync, realpathSync } from "node:fs";
+import { basename, extname, isAbsolute, join, resolve, sep } from "node:path";
+import { checkRemote, resolveRoute, runRemote, serverError } from "./servers.mjs";
+
+export const ATTACHMENTS_DIRNAME = ".oats-attachments";
+/** Kernel bound per file; a GUI imposes its own stricter interaction bound. */
+export const MAX_ATTACHMENT_BYTES = 64 * 1024 * 1024;
+/** The kernel version whose probe first advertises session-upload. */
+export const SESSION_UPLOAD_REMOTE_VERSION = "0.22.13";
+
+const err = (code, message, extra) => Object.assign(new Error(message), { code, ...(extra || {}) });
+
+/** A file name as it will exist in the attachments directory: one path
+ *  segment, printable, never a dot name, at most 200 bytes. */
+export function attachmentName(name) {
+  if (typeof name !== "string" || !name.trim()) throw err("E_BAD_ARGS", "attachment name must be a non-empty file name");
+  if (name.includes("/") || name.includes("\\") || name.includes("\0")) throw err("E_BAD_ARGS", "attachment name must be a single path segment without slashes or NUL");
+  if (/[\x00-\x1f\x7f]/.test(name)) throw err("E_BAD_ARGS", "attachment name must not contain control characters");
+  if (name === "." || name === "..") throw err("E_BAD_ARGS", "attachment name may not be a dot name");
+  // Deliberate: a name starting with a dash would read as an option on the
+  // remote command line; the caller renames the file (screenshots never
+  // start with one).
+  if (name.startsWith("-")) throw err("E_BAD_ARGS", `attachment name ${JSON.stringify(name)} starts with a dash; rename the file before attaching it`);
+  if (Buffer.byteLength(name) > 200) throw err("E_BAD_ARGS", "attachment name is longer than 200 bytes");
+  return name;
+}
+
+export function sha256Hex(bytes) { return createHash("sha256").update(bytes).digest("hex"); }
+
+/** Read a REGULAR file descriptor to its end, refusing once more than
+ *  `maxBytes` arrive. Regular files never answer EAGAIN; pipes must use
+ *  readStreamBounded, which waits for data instead of spinning. */
+export function readBounded(fd, maxBytes = MAX_ATTACHMENT_BYTES) {
+  const chunks = [];
+  let total = 0;
+  const buf = Buffer.allocUnsafe(1024 * 1024);
+  for (;;) {
+    const n = readSync(fd, buf, 0, buf.length, null);
+    if (n === 0) break;
+    total += n;
+    if (total > maxBytes) throw err("E_UPLOAD_TOO_LARGE", `attachment exceeds the kernel bound of ${maxBytes} bytes`);
+    chunks.push(Buffer.from(buf.subarray(0, n)));
+  }
+  return Buffer.concat(chunks, total);
+}
+
+/** Collect a readable stream (stdin from ssh) into memory, bounded: the
+ *  read is event-driven, so a slow or stalled sender costs no CPU, and the
+ *  bound is checked as chunks arrive, before anything is written. The whole
+ *  file is buffered on both sides (up to the bound); this is not end-to-end
+ *  streaming. */
+export async function readStreamBounded(stream, maxBytes = MAX_ATTACHMENT_BYTES) {
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of stream) {
+    const b = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    total += b.length;
+    if (total > maxBytes) { stream.destroy?.(); throw err("E_UPLOAD_TOO_LARGE", `attachment exceeds the kernel bound of ${maxBytes} bytes`); }
+    chunks.push(b);
+  }
+  return Buffer.concat(chunks, total);
+}
+
+function instanceHomeOf(home) {
+  if (typeof home !== "string" || !isAbsolute(home)) throw err("E_BAD_ARGS", "attachments need an absolute instance home");
+  if (!existsSync(join(home, "instance.json"))) throw err("E_SESSION_UNKNOWN", `${home} is not an OATS instance home (no instance.json); nothing was written`);
+  return realpathSync(home);
+}
+
+/** The attachments directory must be a real directory inside the home: a
+ *  symlink planted there (or a file) must not turn a receive into a write
+ *  somewhere else. Created 0700 when absent. */
+function attachmentsDir(realHome) {
+  const dir = join(realHome, ATTACHMENTS_DIRNAME);
+  let st;
+  try { st = lstatSync(dir); }
+  catch (e) {
+    if (e.code !== "ENOENT") throw e;
+    // Two first uploads may both see ENOENT: the loser's mkdir answers
+    // EEXIST and it validates what the winner (or a planted entry) put there.
+    try { mkdirSync(dir, { mode: 0o700 }); } catch (m) { if (m.code !== "EEXIST") throw m; }
+    st = lstatSync(dir);
+  }
+  if (st.isSymbolicLink() || !st.isDirectory()) throw err("E_UPLOAD_FAILED", `${dir} is not a real directory inside the instance home; nothing was written`);
+  const real = realpathSync(dir);
+  if (real !== dir && !real.startsWith(realHome + sep)) throw err("E_UPLOAD_FAILED", `${dir} resolves outside the instance home; nothing was written`);
+  return dir;
+}
+
+/** Store `bytes` as a private file under <home>/.oats-attachments/<name>,
+ *  taking name-2, name-3 ... when the name is taken. The destination is
+ *  allocated exclusively (O_CREAT|O_EXCL, 0600): two simultaneous uploads
+ *  of the same name get two files and neither clobbers the other, and a
+ *  symlink planted under a candidate name is skipped, never followed. The
+ *  path is reported only after the bytes are written and synced. */
+export function receiveAttachment(home, name, bytes, { maxBytes = MAX_ATTACHMENT_BYTES } = {}) {
+  const realHome = instanceHomeOf(home);
+  const safe = attachmentName(name);
+  if (!Buffer.isBuffer(bytes)) throw err("E_BAD_ARGS", "attachment bytes must be a Buffer");
+  if (bytes.length > maxBytes) throw err("E_UPLOAD_TOO_LARGE", `attachment exceeds the kernel bound of ${maxBytes} bytes`);
+  const dir = attachmentsDir(realHome);
+  const ext = extname(safe), stem = safe.slice(0, safe.length - ext.length);
+  for (let i = 1; i <= 10000; i++) {
+    const path = i === 1 ? join(dir, safe) : join(dir, `${stem}-${i}${ext}`);
+    let fd;
+    try { fd = openSync(path, "wx", 0o600); }
+    catch (e) { if (e.code === "EEXIST") continue; throw e; }
+    try {
+      let off = 0;
+      while (off < bytes.length) off += writeSync(fd, bytes, off, bytes.length - off);
+      fsyncSync(fd);
+    } catch (e) { closeSync(fd); rmSync(path, { force: true }); throw e; }
+    closeSync(fd);
+    return { path, bytes: bytes.length, sha256: sha256Hex(bytes) };
+  }
+  throw err("E_UPLOAD_FAILED", `no free name for ${safe} under ${dir}`);
+}
+
+function readLocalFile(file, maxBytes) {
+  if (typeof file !== "string" || !file) throw err("E_BAD_ARGS", "--file needs a path");
+  const abs = resolve(file);
+  let st;
+  try { st = statSync(abs); } catch { throw err("E_BAD_ARGS", `no such file: ${abs}`); }
+  if (!st.isFile()) throw err("E_BAD_ARGS", `${abs} is not a regular file`);
+  if (st.size > maxBytes) throw err("E_UPLOAD_TOO_LARGE", `${abs} is ${st.size} bytes; the kernel bound is ${maxBytes}`);
+  const fd = openSync(abs, "r");
+  try { if (fstatSync(fd).size !== st.size) throw err("E_UPLOAD_FAILED", `${abs} changed while being read`); return { abs, bytes: readBounded(fd, maxBytes) }; }
+  finally { closeSync(fd); }
+}
+
+/** Upload a local file into an instance's attachments: locally by home, or
+ *  on the execution host of a registered server through its saved route
+ *  (the same resolution as session attach). The remote answer's sha256 and
+ *  size must equal the local file's before the path is reported. */
+export function uploadAttachment({ file, home, server, instance }, io = {}) {
+  const maxBytes = io.maxBytes || MAX_ATTACHMENT_BYTES;
+  const { abs, bytes } = readLocalFile(file, maxBytes);
+  const name = basename(abs);
+  const sha256 = sha256Hex(bytes);
+  if (!server) {
+    if (!home) throw err("E_BAD_ARGS", "session upload needs --home </absolute/instance> or --server <id> with --instance <name> or --home");
+    return { ...receiveAttachment(home, name, bytes, { maxBytes }), name, home: realpathSync(home), source: abs };
+  }
+  const route = resolveRoute(server, { instance, home }, "session upload");
+  const remote = checkRemote(route.target, io);
+  // Both lists must carry the token; a probe without the arrays is an old kernel.
+  const advertises = (list) => Array.isArray(list) && list.includes("session-upload");
+  if (!advertises(remote.remote) || !advertises(remote.features)) {
+    throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${route.target.sshHost} does not advertise session-upload (kernels from ${SESSION_UPLOAD_REMOTE_VERSION} do); upgrade it there; nothing was sent`);
+  }
+  const { envelope, stderr } = runRemote(route.target, ["session", "receive", "--home", route.home, "--name", name, "--json"], { ...io, input: bytes, timeoutMs: io.timeoutMs || 600000 });
+  if (!envelope.ok) throw serverError(envelope.error?.code || "E_UPLOAD_FAILED", `${server}: ${envelope.error?.message || "receive failed"}`);
+  const r = envelope.result || {};
+  if (r.sha256 !== sha256 || r.bytes !== bytes.length || typeof r.path !== "string" || !r.path.startsWith("/")) {
+    throw serverError("E_UPLOAD_FAILED", `${server} stored ${r.bytes ?? "?"} bytes with sha256 ${r.sha256 ?? "?"} at ${r.path || "?"}, but the local file is ${bytes.length} bytes with sha256 ${sha256}; the remote file is left for inspection`);
+  }
+  return { path: r.path, bytes: r.bytes, sha256: r.sha256, name, home: route.home, server, instance: instance || route.snapshot?.instance, source: abs, ...(stderr?.trim() ? { stderr: stderr.trim() } : {}) };
+}

package/lib/schedule-host.mjs

@@ -0,0 +1,150 @@
+/** The ONE host timer that runs `oats schedule tick --host` once a minute:
+ *  a launchd user agent on macOS, a systemd user timer on Linux. Nothing is
+ *  installed unless `oats schedule host install` is run explicitly, and
+ *  status reports what the OS says is loaded, never what a file implies. */
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, platform, userInfo } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { hostScheduleDir, scheduleError } from "./schedule.mjs";
+
+export const LAUNCHD_LABEL = "ai.oats.schedule-tick";
+export const SYSTEMD_UNIT = "oats-schedule-tick";
+const OATS_BIN = join(dirname(fileURLToPath(import.meta.url)), "..", "bin", "oats.mjs");
+
+function escapeXml(s) { return String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;"); }
+
+/** launchd and systemd start units with a short PATH that has no Homebrew
+ *  tmux and no installed harness. The unit therefore carries an explicit
+ *  PATH: the installer's own PATH (the operator's tool environment) plus
+ *  the node running the installer and the usual prefixes. */
+export function hostPath({ node = process.execPath, envPath = process.env.PATH || "" } = {}) {
+  const seen = new Set();
+  const out = [];
+  for (const p of [dirname(node), ...envPath.split(":"), "/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin"]) {
+    if (p && !seen.has(p)) { seen.add(p); out.push(p); }
+  }
+  return out.join(":");
+}
+
+export function renderLaunchdPlist({ node = process.execPath, oatsBin = OATS_BIN, logDir = join(hostScheduleDir(), "log"), intervalSec = 60, oatsHomeDir = process.env.OATS_HOME_DIR, path = hostPath({ node }) } = {}) {
+  const env = `\n  <key>EnvironmentVariables</key>\n  <dict>\n    <key>PATH</key><string>${escapeXml(path)}</string>${oatsHomeDir ? `\n    <key>OATS_HOME_DIR</key><string>${escapeXml(oatsHomeDir)}</string>` : ""}\n  </dict>`;
+  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>${LAUNCHD_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${escapeXml(node)}</string>
+    <string>${escapeXml(oatsBin)}</string>
+    <string>schedule</string>
+    <string>tick</string>
+    <string>--host</string>
+    <string>--json</string>
+  </array>
+  <key>StartInterval</key><integer>${intervalSec}</integer>
+  <key>RunAtLoad</key><false/>
+  <key>ProcessType</key><string>Background</string>
+  <key>StandardOutPath</key><string>${escapeXml(join(logDir, "tick.log"))}</string>
+  <key>StandardErrorPath</key><string>${escapeXml(join(logDir, "tick.err"))}</string>${env}
+</dict>
+</plist>
+`;
+}
+/** systemd unit values: `%` is a specifier escape (`%%`), and a quoted
+ *  string protects spaces; backslashes and double quotes are escaped. */
+export function systemdQuote(value) {
+  return `"${String(value).replace(/%/g, "%%").replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+export function renderSystemdUnits({ node = process.execPath, oatsBin = OATS_BIN, intervalSec = 60, oatsHomeDir = process.env.OATS_HOME_DIR, path = hostPath({ node }) } = {}) {
+  const env = `Environment=${systemdQuote(`PATH=${path}`)}\n${oatsHomeDir ? `Environment=${systemdQuote(`OATS_HOME_DIR=${oatsHomeDir}`)}\n` : ""}`;
+  return {
+    service: `[Unit]\nDescription=OATS schedule tick\n\n[Service]\nType=oneshot\n${env}ExecStart=${systemdQuote(node)} ${systemdQuote(oatsBin)} schedule tick --host --json\n`,
+    timer: `[Unit]\nDescription=OATS schedule tick every ${intervalSec}s\n\n[Timer]\nOnBootSec=${intervalSec}\nOnUnitActiveSec=${intervalSec}\nAccuracySec=5\nUnit=${SYSTEMD_UNIT}.service\n\n[Install]\nWantedBy=timers.target\n`,
+  };
+}
+
+/** `unitDir` overrides the OS location (tests never touch a live timer's files). */
+export function hostUnitPaths(os = platform(), { unitDir } = {}) {
+  if (os === "darwin") return { kind: "launchd", plist: join(unitDir || join(homedir(), "Library", "LaunchAgents"), `${LAUNCHD_LABEL}.plist`) };
+  if (os === "linux") { const dir = unitDir || join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "systemd", "user"); return { kind: "systemd", service: join(dir, `${SYSTEMD_UNIT}.service`), timer: join(dir, `${SYSTEMD_UNIT}.timer`) }; }
+  return { kind: "unsupported" };
+}
+
+function run(exec, argv) {
+  try { return { ok: true, out: (exec || execFileSync)(argv[0], argv.slice(1), { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 20000 }) }; }
+  catch (e) { return { ok: false, out: String(e.stdout || ""), err: String(e.stderr || e.message || "").trim() }; }
+}
+
+/** installed = the unit file exists; active = the OS reports it loaded/active. */
+export function hostUnitStatus({ exec, os = platform(), unitDir } = {}) {
+  const p = hostUnitPaths(os, { unitDir });
+  if (p.kind === "launchd") {
+    const installed = existsSync(p.plist);
+    const r = run(exec, ["launchctl", "print", `gui/${userInfo().uid}/${LAUNCHD_LABEL}`]);
+    return { kind: p.kind, unit: p.plist, installed, active: r.ok };
+  }
+  if (p.kind === "systemd") {
+    const installed = existsSync(p.timer) && existsSync(p.service);
+    const r = run(exec, ["systemctl", "--user", "is-active", `${SYSTEMD_UNIT}.timer`]);
+    return { kind: p.kind, unit: p.timer, installed, active: r.ok && r.out.trim() === "active" };
+  }
+  return { kind: "unsupported", installed: false, active: false };
+}
+
+export function installHostUnit({ exec, os = platform(), intervalSec = 60, unitDir } = {}) {
+  const p = hostUnitPaths(os, { unitDir });
+  mkdirSync(join(hostScheduleDir(), "log"), { recursive: true });
+  if (p.kind === "launchd") {
+    mkdirSync(dirname(p.plist), { recursive: true });
+    const status = hostUnitStatus({ exec, os, unitDir });
+    const rendered = renderLaunchdPlist({ intervalSec });
+    // Idempotent: registering another scope while the same timer is active
+    // must not unload an in-flight tick just to rewrite identical bytes.
+    if (status.active && existsSync(p.plist) && readFileSync(p.plist, "utf8") === rendered) return status;
+    if (status.active) { const r = run(exec, ["launchctl", "bootout", `gui/${userInfo().uid}/${LAUNCHD_LABEL}`]); if (!r.ok) throw scheduleError("E_SCHEDULE_HOST", `launchctl bootout failed before reinstall: ${r.err}`); }
+    writeFileSync(p.plist, rendered);
+    const r = run(exec, ["launchctl", "bootstrap", `gui/${userInfo().uid}`, p.plist]);
+    if (!r.ok) throw scheduleError("E_SCHEDULE_HOST", `launchctl bootstrap failed: ${r.err}`);
+    return hostUnitStatus({ exec, os, unitDir });
+  }
+  if (p.kind === "systemd") {
+    mkdirSync(dirname(p.timer), { recursive: true });
+    const units = renderSystemdUnits({ intervalSec });
+    const status = hostUnitStatus({ exec, os, unitDir });
+    if (status.active && existsSync(p.service) && existsSync(p.timer) && readFileSync(p.service, "utf8") === units.service && readFileSync(p.timer, "utf8") === units.timer) return status;
+    writeFileSync(p.service, units.service); writeFileSync(p.timer, units.timer);
+    for (const argv of [["systemctl", "--user", "daemon-reload"], ["systemctl", "--user", "enable", "--now", `${SYSTEMD_UNIT}.timer`]]) { const r = run(exec, argv); if (!r.ok) throw scheduleError("E_SCHEDULE_HOST", `${argv.join(" ")} failed: ${r.err}`); }
+    return hostUnitStatus({ exec, os, unitDir });
+  }
+  throw scheduleError("E_SCHEDULE_HOST", `no host timer support on ${os}`);
+}
+
+/** Uninstall reports the OS's answer: a unit that stays loaded after the
+ *  OS refused to unload it is an error, not a removed file. */
+export function uninstallHostUnit({ exec, os = platform(), unitDir } = {}) {
+  const p = hostUnitPaths(os, { unitDir });
+  if (p.kind === "launchd") {
+    const before = hostUnitStatus({ exec, os, unitDir });
+    if (before.active) {
+      const r = run(exec, ["launchctl", "bootout", `gui/${userInfo().uid}/${LAUNCHD_LABEL}`]);
+      if (!r.ok || hostUnitStatus({ exec, os, unitDir }).active) throw scheduleError("E_SCHEDULE_HOST", `launchctl bootout did not unload ${LAUNCHD_LABEL}: ${r.err || "still loaded"}; the unit file is kept`);
+    }
+    rmSync(p.plist, { force: true });
+    return hostUnitStatus({ exec, os, unitDir });
+  }
+  if (p.kind === "systemd") {
+    const before = hostUnitStatus({ exec, os, unitDir });
+    if (before.active) {
+      const r = run(exec, ["systemctl", "--user", "disable", "--now", `${SYSTEMD_UNIT}.timer`]);
+      if (!r.ok || hostUnitStatus({ exec, os, unitDir }).active) throw scheduleError("E_SCHEDULE_HOST", `systemctl --user disable --now ${SYSTEMD_UNIT}.timer failed: ${r.err || "still active"}; the unit files are kept`);
+    }
+    rmSync(p.timer, { force: true }); rmSync(p.service, { force: true });
+    const r = run(exec, ["systemctl", "--user", "daemon-reload"]);
+    if (!r.ok) throw scheduleError("E_SCHEDULE_HOST", `systemctl --user daemon-reload failed: ${r.err}`);
+    return hostUnitStatus({ exec, os, unitDir });
+  }
+  throw scheduleError("E_SCHEDULE_HOST", `no host timer support on ${os}`);
+}