dexterm-cli 0.1.6 → 0.2.0

package/dist/packages/autotrade/src/safety.js

@@ -0,0 +1,243 @@
+// dexterm autotrade — safety: stop, flatten, pause, the kill switch every step, the dead-man, the run audit and the
+// session isolation proof (task-1509 AT-7, AUTOTRADE-SPEC §6.3, §6.4). PAPER ONLY.
+//
+// Control file: $DEXTERM_HOME/autotrade/control.json (`dexterm-autotrade-control/1`) carries ONE request for ONE run
+// (its runId): stop (soft: no new entries, every session closed, orders dropped, mechanical exits keep running),
+// flatten (a stop, then every position sold at its next tick), pause / resume-entries (new entries only). The CLI
+// (`dexterm autotrade stop|flatten`) and the Q screen (`!`, `f` + y, `p`) write it; the runner re-reads it on every
+// step (a stat, then a parse when it changed). A request for another run never touches this one. A file that cannot
+// be read counts as a stop (fail closed), like the panic file. A stop or flatten is final for the run: a later
+// request can escalate a stop to a flatten but never lift it, and nothing here lifts the panic file.
+//
+// RunnerSafety.step() is what the runner calls every step. It folds in:
+//   - the panic file (`dexterm wallet panic`, KillSwitch), re-read every step; the halt is sticky for the run, and
+//     a new run refuses to start while it is engaged (resume is `dexterm wallet resume`, a keypress on a real TTY);
+//   - the control file;
+//   - the dead-man for entries: no new entries while the runner's own heartbeat cannot be written (the TUI and the
+//     monitor would see it as dead), or while the position monitor is down when it runs the exits (desk executor).
+//     Those lift by themselves; mechanical exits never wait on any of them.
+//
+// Audit: auditRun() recomputes the hash chain of runs/<runId>.jsonl (verifyChain) and checks it against the run's
+// summary (written on every heartbeat with the head at that moment), so lines cut from the END of a ledger, which a
+// chain alone cannot see, show up as missing events.
+//
+// Isolation: sessionIsolation() reads a session's stream-json init event: tools and MCP servers must be 0 (the
+// session is ended otherwise, sessions.ts); plugins, agents, skills and slash commands are counted for the ledger.
+// The user's plugins and agents still list as loaded with these flags; with no tools they cannot act (§4).
+//
+// Nothing here holds a key, touches a wallet, the signer or the network, and no model can reach any of it: sessions
+// have no tools, and only a keypress or a command the user runs writes the control file.
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { GENESIS, RUN_SUMMARY_SCHEMA, readLedgerFile, runFiles, runsDir, verifyChain, writeJsonAtomic } from "./ledger.js";
+import { runLockPath, runnerRendezvousPath } from "./runner.js";
+export const CONTROL_SCHEMA = 'dexterm-autotrade-control/1';
+const ACTIONS = ['stop', 'flatten', 'pause', 'resume-entries'];
+export const controlPath = (home) => join(home, 'autotrade', 'control.json');
+/** The request in the control file, `unreadable` when it exists but cannot be parsed, or null when there is none. */
+export function readControl(home) {
+    const p = controlPath(home);
+    if (!existsSync(p))
+        return null;
+    try {
+        const d = JSON.parse(readFileSync(p, 'utf8'));
+        if (d.schema !== CONTROL_SCHEMA || typeof d.runId !== 'string' || !ACTIONS.includes(d.action) || typeof d.at !== 'number')
+            return 'unreadable';
+        return { schema: CONTROL_SCHEMA, runId: d.runId, action: d.action, at: d.at, by: d.by === 'tui' || d.by === 'chat' ? d.by : 'cli' };
+    }
+    catch {
+        return 'unreadable';
+    }
+}
+const FINAL = ['stop', 'flatten'];
+/**
+ * Write a request for a run. A stop or flatten already on file for the same run is never lifted: pause and
+ * resume-entries are refused, a second stop is a no-op, and only stop → flatten escalates.
+ */
+export function requestControl(home, runId, action, by, now = Date.now()) {
+    const cur = readControl(home);
+    if (cur && cur !== 'unreadable' && cur.runId === runId && FINAL.includes(cur.action)) {
+        if (cur.action === action || (cur.action === 'flatten' && action === 'stop'))
+            return { ok: true, request: cur, already: true };
+        if (action !== 'flatten')
+            return { ok: false, why: `the runner is already ${cur.action === 'stop' ? 'stopping' : 'flattening'}; only a flatten can follow a stop`, current: cur };
+    }
+    const request = { schema: CONTROL_SCHEMA, runId, action, at: now, by };
+    mkdirSync(join(home, 'autotrade'), { recursive: true, mode: 0o700 });
+    writeJsonAtomic(controlPath(home), request);
+    return { ok: true, request, already: false };
+}
+/**
+ * At a runner's start: a request left for an older run is removed (it can never apply to this one). Returns false
+ * when the file cannot be read: the new run must refuse to start until the user looks at it (fail closed).
+ */
+export function clearStaleControl(home, runId) {
+    const cur = readControl(home);
+    if (cur === 'unreadable')
+        return false;
+    if (cur && cur.runId !== runId)
+        rmSync(controlPath(home), { force: true });
+    return true;
+}
+/** At a runner's end: remove its own request (a later run never sees it). */
+export function clearControl(home, runId) {
+    const cur = readControl(home);
+    if (cur && cur !== 'unreadable' && cur.runId === runId)
+        rmSync(controlPath(home), { force: true });
+}
+export const HEARTBEAT_STALE_MS = 30_000;
+export class RunnerSafety {
+    haltWhy = null;
+    haltDetail = '';
+    flattening = false;
+    /** A stop or flatten was asked for (also after a panic halt): the run ends once nothing is held. */
+    stopAsked = false;
+    sig = '';
+    ctl = null;
+    o;
+    constructor(o) { this.o = o; }
+    /** The control request, re-parsed only when the file changed (a stat per step). */
+    control() {
+        const p = controlPath(this.o.home);
+        let sig = '';
+        try {
+            const st = statSync(p);
+            sig = `${st.mtimeMs}:${st.size}:${st.ino}`;
+        }
+        catch {
+            sig = '';
+        }
+        if (sig !== this.sig) {
+            this.sig = sig;
+            this.ctl = sig ? readControl(this.o.home) : null;
+        }
+        return this.ctl;
+    }
+    step() {
+        const halt = (why, detail) => { if (!this.haltWhy) {
+            this.haltWhy = why;
+            this.haltDetail = detail;
+        } };
+        const panic = this.o.killSwitch?.engaged() ?? null;
+        if (panic)
+            halt('kill-switch', `panic file: ${panic.reason}`);
+        const c = this.control();
+        let pause = null;
+        if (c === 'unreadable') {
+            halt('control-unreadable', 'the control file cannot be read (treated as a stop)');
+            this.stopAsked = true;
+        }
+        else if (c && c.runId === this.o.runId) {
+            if (c.action === 'stop' || c.action === 'flatten') {
+                halt(c.action, `requested from the ${c.by === 'tui' ? 'Q screen' : c.by === 'chat' ? 'paired chat' : 'command line'}`);
+                this.stopAsked = true;
+                if (c.action === 'flatten')
+                    this.flattening = true;
+            }
+            else if (c.action === 'pause')
+                pause = 'paused';
+        }
+        if (!pause && (this.o.heartbeatAgeMs?.() ?? 0) > (this.o.staleMs ?? HEARTBEAT_STALE_MS))
+            pause = 'heartbeat-stale';
+        if (!pause && this.o.monitorAlive && !this.o.monitorAlive())
+            pause = 'monitor-heartbeat-stale';
+        return { halt: this.haltWhy, ...(this.haltWhy ? { detail: this.haltDetail } : {}), flatten: this.flattening, pauseEntries: pause, endWhenFlat: this.stopAsked };
+    }
+}
+// ───────────────────────────── the active runner ─────────────────────────────
+const alive = (pid) => { try {
+    process.kill(pid, 0);
+    return true;
+}
+catch (e) {
+    return e.code === 'EPERM';
+} };
+/** The runner holding run.lock with a live pid (and what its rendezvous says), or null. */
+export function activeRunner(home) {
+    let lock;
+    try {
+        lock = JSON.parse(readFileSync(runLockPath(home), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (typeof lock.pid !== 'number' || typeof lock.runId !== 'string' || !alive(lock.pid))
+        return null;
+    const r = readRendezvousLoose(home);
+    const same = r && r.runId === lock.runId;
+    return {
+        runId: lock.runId, pid: lock.pid, startedAt: lock.startedAt,
+        state: same && typeof r.state === 'string' ? r.state : null,
+        haltReason: same && typeof r.haltReason === 'string' ? r.haltReason : null,
+        heartbeatAt: same && typeof r.heartbeatAt === 'number' ? r.heartbeatAt : null,
+        positions: same && Array.isArray(r.positions) ? r.positions.length : 0,
+        sessions: same && Array.isArray(r.sessions) ? r.sessions.length : 0,
+    };
+}
+function readRendezvousLoose(home) {
+    try {
+        return JSON.parse(readFileSync(runnerRendezvousPath(home), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Run ids with a ledger under runs/, oldest first (ids sort by start time). */
+export function listRunIds(home) {
+    const dir = runsDir(home);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir).filter((f) => f.endsWith('.jsonl') && !f.endsWith('.stream.jsonl')).map((f) => f.slice(0, -'.jsonl'.length)).filter((id) => { try {
+        runFiles(home, id);
+        return true;
+    }
+    catch {
+        return false;
+    } }).sort();
+}
+/** Recompute one run's chain and check it against its summary. */
+export function auditRun(home, runId) {
+    const files = runFiles(home, runId);
+    const active = activeRunner(home);
+    const running = active?.runId === runId;
+    const base = { runId, ledger: files.ledger, running };
+    let events;
+    try {
+        events = readLedgerFile(files.ledger);
+    }
+    catch (e) {
+        return { ...base, events: 0, ok: false, head: null, brokenAt: 0, error: `cannot read the ledger: ${e.message.slice(0, 160)}`, ended: false, summary: null, strategy: null };
+    }
+    const chain = verifyChain(events);
+    const start = events.find((e) => e.kind === 'run_start');
+    const strategy = start && typeof start.strategy === 'string' ? { id: start.strategy, version: String(start.version ?? ''), hash: String(start.strategyHash ?? '') } : null;
+    // A parallel run's own ledger (task-1529) closes with fleet_end; each strategy's ledger with run_end.
+    const ended = events.length > 0 && (events[events.length - 1].kind === 'run_end' || events[events.length - 1].kind === 'fleet_end');
+    let summary = null;
+    try {
+        const s = JSON.parse(readFileSync(files.summary, 'utf8'));
+        if (s.schema === RUN_SUMMARY_SCHEMA && typeof s.events === 'number' && typeof s.ledgerHead === 'string') {
+            const at = s.events === 0 ? GENESIS : events[s.events - 1]?.hash;
+            summary = { events: s.events, head: s.ledgerHead, matches: at === s.ledgerHead };
+        }
+    }
+    catch {
+        summary = null;
+    }
+    if (!chain.ok)
+        return { ...base, events: events.length, ok: false, head: null, brokenAt: chain.at, error: chain.error, ended, summary, strategy };
+    if (summary && summary.events > events.length) {
+        return { ...base, events: events.length, ok: false, head: chain.head, brokenAt: events.length + 1, error: `the summary counts ${summary.events} events but the ledger has ${events.length} (lines were cut from the end)`, ended, summary, strategy };
+    }
+    if (summary && !summary.matches) {
+        return { ...base, events: events.length, ok: false, head: chain.head, brokenAt: summary.events, error: `the summary's head for event ${summary.events} does not match the ledger (the ledger was rewritten)`, ended, summary, strategy };
+    }
+    return { ...base, events: events.length, ok: true, head: chain.head, ended, summary, strategy };
+}
+/** Counts from a stream-json init event (-1 when a list is missing). Tools and MCP servers must both be 0. */
+export function sessionIsolation(init) {
+    const n = (k) => (Array.isArray(init[k]) ? init[k].length : -1);
+    const tools = n('tools');
+    const mcpServers = n('mcp_servers');
+    return { tools, mcpServers, plugins: n('plugins'), agents: n('agents'), skills: n('skills'), slashCommands: n('slash_commands'), ok: tools === 0 && mcpServers === 0 };
+}

package/dist/packages/autotrade/src/service-guard.js

@@ -0,0 +1,125 @@
+// dexterm autotrade — the always-on service's guard aggregator (0.2.0 card B, AUTOTRADE-SPEC §7.3 / §7.4).
+//
+// Every 10 s (and on demand) the service folds what it can see into named guard states. Each state has ONE effect:
+//   stop            the service stops the fleet (a soft stop: no new entries, sessions closed, exits keep running)
+//   pause-entries   no new entries while it holds; lifts by itself (hysteresis where a value can flap)
+//   notice          shown in `service status` and sent once as a notification; nothing pauses
+// Open positions are never paused by any state: their exits keep running (the monitor is never paused, §7.4).
+//
+//   state id         effect          from
+//   stop-file        stop            the service STOP marker (`service stop`, a plain `touch`)
+//   panic            stop            the panic file (`dexterm wallet panic`); the fleet halts itself too
+//   disk-low         pause-entries   free space under runner.json disk.minFreeGb (default 5 GB); +1 GB to lift
+//   load-high        pause-entries   1-min load above load.pauseAboveLoad1m for load.sustainSec; lifts below resumeBelowLoad1m
+//   busy-process     pause-entries   a runner.json load.busyProcs pattern matches a running process (not ours)
+//   data-stale       pause-entries   no strategy has seen a market tick for dataStaleSec (default 300 s)
+//   runner-stale     notice          the fleet's heartbeat (runner-status.json) is older than 30 s
+//   allowance-high   notice          the model usage windows are above runner.json allowanceGuard (the fleet pauses sessions itself)
+//   day-cap          notice          the fleet's global day caps are used up (sessions resume when the day rolls)
+//   recorder-down    notice          the market recorder is installed but has written nothing for recorderStaleSec
+//                                    (default 15 min); not installed → notice with `dexterm record install`
+//   strategy-halted  notice          a strategy halted itself (daily loss / drawdown caps); one per strategy
+//
+// The guard is pure over its inputs (the service collects them); transitions come back so the caller can log one
+// ledger line and send one notification per change, never one per tick.
+export const DEFAULT_GUARD_CONFIG = {
+    minFreeGb: 5, pauseAboveLoad1m: 25, resumeBelowLoad1m: 20, sustainSec: 120, busyProcs: [],
+    dataStaleSec: 300, recorderStaleSec: 900, fiveHourMax: 0.6, sevenDayMax: 0.8,
+};
+/** runner.json → the guard's knobs (the stricter of the two never matters here: these only pause). */
+export function guardConfigFrom(rc, over = {}) {
+    return {
+        ...DEFAULT_GUARD_CONFIG,
+        ...(rc?.load ? { pauseAboveLoad1m: rc.load.pauseAboveLoad1m, resumeBelowLoad1m: rc.load.resumeBelowLoad1m, sustainSec: rc.load.sustainSec, busyProcs: [...rc.load.busyProcs] } : {}),
+        ...(rc?.disk ? { minFreeGb: rc.disk.minFreeGb } : {}),
+        ...(rc?.allowanceGuard ? { fiveHourMax: rc.allowanceGuard.fiveHourMax, sevenDayMax: rc.allowanceGuard.sevenDayMax } : {}),
+        ...over,
+    };
+}
+const gb = (n) => `${n.toFixed(1)} GB`;
+export class ServiceGuard {
+    cfg;
+    active = new Map();
+    loadAboveSince = null;
+    loadPaused = false;
+    diskLow = false;
+    constructor(cfg = DEFAULT_GUARD_CONFIG) { this.cfg = cfg; }
+    evaluate(i) {
+        const c = this.cfg;
+        const want = new Map();
+        const on = (id, effect, detail) => { want.set(id, { effect, detail }); };
+        if (i.stopFile)
+            on('stop-file', 'stop', i.stopFile);
+        if (i.panic)
+            on('panic', 'stop', `the panic switch is engaged (${i.panic}); \`dexterm wallet resume\` lifts it`);
+        if (i.freeGb !== null) {
+            if (!this.diskLow && i.freeGb < c.minFreeGb)
+                this.diskLow = true;
+            else if (this.diskLow && i.freeGb >= c.minFreeGb + 1)
+                this.diskLow = false;
+            if (this.diskLow)
+                on('disk-low', 'pause-entries', `${gb(i.freeGb)} free, under the ${gb(c.minFreeGb)} floor (runner.json disk.minFreeGb); lifts at ${gb(c.minFreeGb + 1)}`);
+        }
+        if (i.load1m !== null) {
+            if (i.load1m > c.pauseAboveLoad1m) {
+                this.loadAboveSince ??= i.now;
+                if (i.now - this.loadAboveSince >= c.sustainSec * 1000)
+                    this.loadPaused = true;
+            }
+            else {
+                this.loadAboveSince = null;
+                if (i.load1m < c.resumeBelowLoad1m)
+                    this.loadPaused = false;
+            }
+            if (this.loadPaused)
+                on('load-high', 'pause-entries', `1-min load ${i.load1m.toFixed(1)} (pauses above ${c.pauseAboveLoad1m} for ${c.sustainSec} s, resumes below ${c.resumeBelowLoad1m})`);
+        }
+        if (i.busy.length)
+            on('busy-process', 'pause-entries', `a busy process is running (${i.busy.slice(0, 3).join(', ')})`);
+        if (i.upMs >= c.dataStaleSec * 1000 && (i.dataAgeMs === null || i.dataAgeMs > c.dataStaleSec * 1000)) {
+            on('data-stale', 'pause-entries', i.dataAgeMs === null ? `no market tick since the start (${Math.round(i.upMs / 1000)} s)` : `the newest market tick is ${Math.round(i.dataAgeMs / 1000)} s old (limit ${c.dataStaleSec} s)`);
+        }
+        if (i.runnerAgeMs !== null && i.runnerAgeMs > 30_000)
+            on('runner-stale', 'notice', `the strategies' heartbeat is ${Math.round(i.runnerAgeMs / 1000)} s old`);
+        const a = i.allowance;
+        if (a && ((a.fiveHour ?? 0) > c.fiveHourMax || (a.sevenDay ?? 0) > c.sevenDayMax)) {
+            on('allowance-high', 'notice', `model usage 5 h ${pctOf(a.fiveHour)} / 7 d ${pctOf(a.sevenDay)} (limits ${pctOf(c.fiveHourMax)} / ${pctOf(c.sevenDayMax)}): no new sessions until it falls`);
+        }
+        if (i.dayCap)
+            on('day-cap', 'notice', `${i.dayCap}: no new sessions until the day rolls`);
+        if (i.recorder) {
+            if (!i.recorder.installed)
+                on('recorder-down', 'notice', 'the market recorder is not installed: backtests and tuning see no new history (`dexterm record install`)');
+            else if (i.recorder.newestAgeMs === null || i.recorder.newestAgeMs > c.recorderStaleSec * 1000)
+                on('recorder-down', 'notice', `the market recorder has written nothing for ${i.recorder.newestAgeMs === null ? 'ever' : `${Math.round(i.recorder.newestAgeMs / 60_000)} min`} (\`dexterm record status\`)`);
+        }
+        for (const [id, why] of Object.entries(i.halted))
+            on(`strategy-halted:${id}`, 'notice', `strategy ${id} halted itself (${why}); its open positions keep their exits`);
+        const transitions = [];
+        for (const [id, w] of want) {
+            const cur = this.active.get(id);
+            if (!cur) {
+                this.active.set(id, { id, effect: w.effect, detail: w.detail, since: i.now });
+                transitions.push({ id, on: true, effect: w.effect, detail: w.detail });
+            }
+            else
+                cur.detail = w.detail;
+        }
+        for (const [id, cur] of [...this.active]) {
+            if (want.has(id))
+                continue;
+            this.active.delete(id);
+            transitions.push({ id, on: false, effect: cur.effect, detail: cur.detail });
+        }
+        const states = [...this.active.values()].map((s) => ({ ...s }));
+        const stop = states.find((s) => s.effect === 'stop')?.id ?? null;
+        const pause = states.find((s) => s.effect === 'pause-entries')?.id ?? null;
+        return { states, stop, pauseEntries: pause ? `guard:${pause}` : null, transitions };
+    }
+}
+const pctOf = (v) => (v === null ? '?' : `${Math.round(v * 100)}%`);
+/** A one-line notification text for a guard transition (plain text, no paths, no secrets). */
+export function guardNoticeText(t) {
+    const what = t.effect === 'stop' ? 'STOP' : t.effect === 'pause-entries' ? 'ENTRIES PAUSED' : 'NOTICE';
+    return t.on ? `autotrade service · ${what} · ${t.id}: ${t.detail}` : `autotrade service · cleared · ${t.id}${t.effect === 'pause-entries' ? ': entries resume' : ''}`;
+}

package/dist/packages/autotrade/src/service-install.js

@@ -0,0 +1,213 @@
+// dexterm autotrade — the always-on service's OS installers (0.2.0 card B, AUTOTRADE-SPEC §7.4).
+//
+// Every platform runs the same thing: `dexterm autotrade service ensure` once a minute and at login. `ensure` exits at
+// once while the service's heartbeat is fresh and otherwise starts it detached, so a crash costs at most one tick and
+// a clean stop stays stopped. The generators are pure (golden-file tested); the CLI shows the user every file and
+// command before anything is written, and records what it wrote (install manifest) so uninstall removes exactly that.
+//
+//   macOS    ~/Library/LaunchAgents/<label>.plist: StartInterval 60, RunAtLoad, ProcessType Background, Nice 10,
+//            LowPriorityIO, AbandonProcessGroup (the started service outlives the tick). NO KeepAlive and never
+//            `launchctl submit` (a KeepAlive job relaunches forever). Loaded with `launchctl bootout` + `bootstrap`:
+//            `kickstart -k` does NOT re-read the plist's arguments.
+//   Linux    ~/.config/systemd/user/<unit>.service (oneshot ensure, Nice 10, idle IO, KillMode=process so the started
+//            service survives the tick) + <unit>.timer (30 s after login, then every 60 s). Without
+//            `loginctl enable-linger` a user unit runs only while the user is logged in.
+//   Windows  a scheduled task (XML for `schtasks /Create /XML`): at logon + every minute, ignore-new on overlap,
+//            below-normal priority, least privilege, 5-minute limit for the tick itself.
+//
+// One label per DEXTERM_HOME: the default home gets `xyz.dexterm.autotrade`; any other home gets a suffix from a hash
+// of its path, so a test home never replaces (or removes) the real one. A non-default home is passed as `--home`.
+// Only PATH is copied into the job's environment (the service needs to find `claude`); nothing else, no secrets.
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+export const SERVICE_LABEL = 'xyz.dexterm.autotrade';
+export const INSTALL_MANIFEST_SCHEMA = 'dexterm-autotrade-service-install/1';
+/** The label for a DEXTERM_HOME: the default one, or one suffixed by a hash of the path. */
+export function serviceLabel(dexHome, defaultHome) {
+    if (dexHome === defaultHome)
+        return SERVICE_LABEL;
+    return `${SERVICE_LABEL}.h${createHash('sha256').update(dexHome).digest('hex').slice(0, 8)}`;
+}
+/** The tick's command line (`--quiet`: a tick that changes nothing prints nothing, so the tick log stays small). */
+export const ensureArgs = (s) => [s.nodePath, s.binPath, 'autotrade', 'service', 'ensure', '--quiet', ...(s.dexHome ? ['--home', s.dexHome] : [])];
+// ───────────────────────────── macOS ─────────────────────────────
+const xml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+export const launchAgentPath = (s) => join(s.userHome, 'Library', 'LaunchAgents', `${s.label}.plist`);
+export function renderLaunchAgent(s) {
+    const args = ensureArgs(s).map((a) => `    <string>${xml(a)}</string>`).join('\n');
+    const env = s.path ? `  <key>EnvironmentVariables</key>\n  <dict>\n    <key>PATH</key>\n    <string>${xml(s.path)}</string>\n  </dict>\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>${xml(s.label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${xml(s.workingDir)}</string>
+${env}  <key>StartInterval</key>
+  <integer>60</integer>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>ProcessType</key>
+  <string>Background</string>
+  <key>Nice</key>
+  <integer>10</integer>
+  <key>LowPriorityIO</key>
+  <true/>
+  <key>AbandonProcessGroup</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${xml(s.tickLog)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xml(s.tickLog)}</string>
+</dict>
+</plist>
+`;
+}
+// ───────────────────────────── Linux (systemd user) ─────────────────────────────
+export const systemdUnit = (s) => s.label.replace(/^xyz\./, '').replace(/\./g, '-');
+export const systemdDir = (s) => join(s.userHome, '.config', 'systemd', 'user');
+/** systemd quoting: double quotes, backslash and quote escaped, `%` doubled (specifier expansion). */
+const sd = (a) => `"${a.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/%/g, '%%')}"`;
+export function renderSystemdService(s) {
+    return `[Unit]
+Description=dexterm autotrade service: start it when it is not running (one tick)
+
+[Service]
+Type=oneshot
+ExecStart=${ensureArgs(s).map(sd).join(' ')}
+WorkingDirectory=${s.workingDir.replace(/%/g, '%%')}
+${s.path ? `Environment=${sd(`PATH=${s.path}`)}\n` : ''}Nice=10
+IOSchedulingClass=idle
+KillMode=process
+StandardOutput=append:${s.tickLog.replace(/%/g, '%%')}
+StandardError=append:${s.tickLog.replace(/%/g, '%%')}
+`;
+}
+export function renderSystemdTimer(s) {
+    return `[Unit]
+Description=dexterm autotrade service tick (every minute)
+
+[Timer]
+OnStartupSec=30
+OnUnitActiveSec=60
+AccuracySec=10
+Unit=${systemdUnit(s)}.service
+
+[Install]
+WantedBy=timers.target
+`;
+}
+// ───────────────────────────── Windows (scheduled task) ─────────────────────────────
+export const windowsTaskName = (s) => `\\dexterm\\${s.label.replace(/^xyz\.dexterm\./, '')}`;
+export const windowsTaskFile = (dexHome, s) => join(dexHome, 'autotrade', 'service', `${s.label}.task.xml`);
+/** Windows command-line quoting for one argument (CommandLineToArgvW rules). */
+export function winArg(a) {
+    if (a && !/[\s"]/.test(a))
+        return a;
+    let out = '"';
+    let bs = 0;
+    for (const ch of a) {
+        if (ch === '\\') {
+            bs++;
+            continue;
+        }
+        if (ch === '"') {
+            out += '\\'.repeat(bs * 2 + 1) + '"';
+            bs = 0;
+            continue;
+        }
+        out += '\\'.repeat(bs) + ch;
+        bs = 0;
+    }
+    return `${out}${'\\'.repeat(bs * 2)}"`;
+}
+export function renderWindowsTask(s) {
+    const [cmd, ...rest] = ensureArgs(s);
+    return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>dexterm autotrade service: start it when it is not running (one tick a minute)</Description>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+    </LogonTrigger>
+    <TimeTrigger>
+      <Repetition>
+        <Interval>PT1M</Interval>
+        <StopAtDurationEnd>false</StopAtDurationEnd>
+      </Repetition>
+      <StartBoundary>2026-01-01T00:00:00</StartBoundary>
+      <Enabled>true</Enabled>
+    </TimeTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <ExecutionTimeLimit>PT5M</ExecutionTimeLimit>
+    <Priority>7</Priority>
+    <Enabled>true</Enabled>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>${xml(cmd)}</Command>
+      <Arguments>${xml(rest.map(winArg).join(' '))}</Arguments>
+      <WorkingDirectory>${xml(s.workingDir)}</WorkingDirectory>
+    </Exec>
+  </Actions>
+</Task>
+`;
+}
+// ───────────────────────────── the plan ─────────────────────────────
+export function installPlan(s, dexHome) {
+    if (s.platform === 'darwin') {
+        const path = launchAgentPath(s);
+        const domain = `gui/${s.uid}`;
+        return {
+            platform: s.platform, label: s.label, name: s.label,
+            files: [{ path, content: renderLaunchAgent(s) }],
+            activate: [['launchctl', 'bootout', `${domain}/${s.label}`], ['launchctl', 'bootstrap', domain, path]],
+            deactivate: [['launchctl', 'bootout', `${domain}/${s.label}`]],
+            notes: ['A LaunchAgent starts at login: the service runs while you are logged in on this Mac.', 'To change it later: edit nothing by hand; run `dexterm autotrade service install --load` again (bootout + bootstrap; `kickstart -k` would keep the old arguments).'],
+        };
+    }
+    if (s.platform === 'linux') {
+        const unit = systemdUnit(s);
+        const dir = systemdDir(s);
+        return {
+            platform: s.platform, label: s.label, name: `${unit}.timer`,
+            files: [{ path: join(dir, `${unit}.service`), content: renderSystemdService(s) }, { path: join(dir, `${unit}.timer`), content: renderSystemdTimer(s) }],
+            activate: [['systemctl', '--user', 'daemon-reload'], ['systemctl', '--user', 'enable', '--now', `${unit}.timer`]],
+            deactivate: [['systemctl', '--user', 'disable', '--now', `${unit}.timer`]],
+            notes: ['A systemd user timer runs while you are logged in; `loginctl enable-linger` (your choice) keeps it running after logout and from boot.'],
+        };
+    }
+    const file = windowsTaskFile(dexHome, s);
+    const name = windowsTaskName(s);
+    return {
+        platform: s.platform, label: s.label, name,
+        files: [{ path: file, content: renderWindowsTask(s), encoding: 'utf16le' }],
+        activate: [['schtasks', '/Create', '/TN', name, '/XML', file, '/F']],
+        deactivate: [['schtasks', '/Delete', '/TN', name, '/F']],
+        notes: ['The task runs at logon and every minute while you are logged in.'],
+    };
+}
+export const fileSha = (content, encoding = 'utf8') => createHash('sha256').update(encode(content, encoding)).digest('hex');
+/** The bytes written for a file (UTF-16 LE with a BOM for the Windows task XML). */
+export function encode(content, encoding = 'utf8') {
+    return encoding === 'utf16le' ? Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(content, 'utf16le')]) : Buffer.from(content, 'utf8');
+}
+export const installManifestPath = (dexHome) => join(dexHome, 'autotrade', 'service', 'install.json');