@addai/node 0.5.1 → 0.7.0

package/dist/autostart-win.js

@@ -0,0 +1,290 @@
+"use strict";
+// Windows backend: a Task Scheduler logon task.
+//
+// Three shapes were possible and only this one is both hidden and durable:
+//
+//   Startup-folder shortcut — trivial, but pops a console window at every
+//     logon and nothing brings the node back if it dies.
+//   Windows Service — survives with nobody logged in, but runs outside the
+//     user's session: no keychain, no user PATH, no ~/.claude. It would boot
+//     a node that fails every run.
+//   Logon task (this) — runs as the user with an InteractiveToken, so no
+//     stored password and no admin rights.
+//
+// The task is registered from generated XML rather than `schtasks` flags,
+// because the settings that decide whether it ever runs are not reachable
+// from the flag form — DisallowStartIfOnBatteries above all, which defaults
+// to TRUE and would leave a laptop node silently never starting.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.backend = exports.XML_PATH = exports.VBS_PATH = exports.CMD_PATH = exports.STARTUP_DIR = void 0;
+exports.currentUserId = currentUserId;
+exports.buildCmd = buildCmd;
+exports.buildVbs = buildVbs;
+exports.buildTaskXml = buildTaskXml;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const autostart_1 = require("./autostart");
+const paths_1 = require("./paths");
+exports.STARTUP_DIR = path.join(paths_1.RUNTIME_HOME, 'startup');
+exports.CMD_PATH = path.join(exports.STARTUP_DIR, 'ainode-startup.cmd');
+exports.VBS_PATH = path.join(exports.STARTUP_DIR, 'ainode-startup.vbs');
+exports.XML_PATH = path.join(exports.STARTUP_DIR, 'ainode-task.xml');
+function xmlEsc(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+/** The account the task runs as. `DOMAIN\User` when we have a domain — a bare
+ *  username is ambiguous on a machine joined to one. */
+function currentUserId(env = process.env) {
+    const user = env.USERNAME || os.userInfo().username;
+    const dom = env.USERDOMAIN;
+    return dom && dom.toLowerCase() !== user.toLowerCase() ? `${dom}\\${user}` : user;
+}
+/**
+ * The batch file that actually starts the node.
+ *
+ * Environment and output redirection live here, in a file where batch quoting
+ * behaves, instead of being wedged into a VBS string or a `schtasks` argument.
+ * The redirect matters: headless stdout on Windows has nowhere else to go, and
+ * a node whose only account of itself is missing is a node nobody can debug.
+ */
+function buildCmd(entry, env, logPath) {
+    const sets = Object.entries(env)
+        // `set "K=V"` quotes the whole assignment, which is the form that survives
+        // a value containing spaces, `&` or `(` — all of which appear in a real
+        // Windows PATH (`C:\Program Files (x86)\…`).
+        .map(([k, v]) => `set "${k}=${v}"`)
+        .join('\r\n');
+    const cmd = [entry.file, ...entry.args].map(a => `"${a}"`).join(' ');
+    return [
+        '@echo off',
+        'rem Generated by `ainode startup enable` — edits here are overwritten.',
+        sets,
+        `${cmd} >> "${logPath}" 2>&1`,
+        '',
+    ].join('\r\n');
+}
+/**
+ * The window-hiding shim.
+ *
+ * A task running under an InteractiveToken shows a console window for every
+ * launch; with the logon trigger repeating, that would be a window popping up
+ * on the user's desktop every five minutes. `WScript.Shell.Run(…, 0, False)`
+ * starts the batch file with no window and does not wait for it.
+ */
+function buildVbs(cmdPath) {
+    const quoted = cmdPath.replace(/"/g, '""');
+    return [
+        "' Generated by `ainode startup enable` — edits here are overwritten.",
+        'Dim sh',
+        'Set sh = CreateObject("WScript.Shell")',
+        `sh.Run """${quoted}""", 0, False`,
+        '',
+    ].join('\r\n');
+}
+/**
+ * The task definition.
+ *
+ * The repetition is what stands in for launchd's KeepAlive. Task Scheduler
+ * cannot supervise this process — the shim returns instantly, so the task is
+ * "finished" a second after it starts and RestartOnFailure never applies. So
+ * the logon trigger repeats every five minutes and the action is
+ * `run --ensure`, which exits immediately when a live daemon already owns the
+ * node. Crash recovery therefore costs at most five minutes and never stacks
+ * a second daemon.
+ */
+function buildTaskXml(spec) {
+    return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Date>${xmlEsc(spec.createdAt)}</Date>
+    <Author>@addai/node</Author>
+    <Description>Runs this +Ai Node so entities can reach it. Created by \`ainode startup enable\`.</Description>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+      <UserId>${xmlEsc(spec.userId)}</UserId>
+      <Repetition>
+        <Interval>PT5M</Interval>
+        <StopAtDurationEnd>false</StopAtDurationEnd>
+      </Repetition>
+    </LogonTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <UserId>${xmlEsc(spec.userId)}</UserId>
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
+    <IdleSettings>
+      <StopOnIdleEnd>false</StopOnIdleEnd>
+      <RestartOnIdle>false</RestartOnIdle>
+    </IdleSettings>
+    <AllowStartOnDemand>true</AllowStartOnDemand>
+    <Enabled>true</Enabled>
+    <Hidden>false</Hidden>
+    <RunOnlyIfIdle>false</RunOnlyIfIdle>
+    <WakeToRun>false</WakeToRun>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Priority>7</Priority>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>${xmlEsc(spec.wscriptPath)}</Command>
+      <Arguments>"${xmlEsc(spec.vbsPath)}"</Arguments>
+    </Exec>
+  </Actions>
+</Task>
+`;
+}
+function schtasks(args) {
+    try {
+        const out = (0, child_process_1.execFileSync)('schtasks', args, { encoding: 'utf8', timeout: 30_000, windowsHide: true });
+        return { ok: true, output: out.toString().trim() };
+    }
+    catch (err) {
+        const e = err;
+        const text = [e.stderr?.toString(), e.stdout?.toString()].filter(Boolean).join(' ').trim();
+        return { ok: false, output: text || e.message || 'schtasks failed' };
+    }
+}
+/* `schtasks /Query` costs a process spawn, and status() rides every heartbeat.
+ * Cache the answer briefly; enable/disable clear it so the CLI and the TUI
+ * never show a stale yes/no straight after a change. */
+let queryCache = null;
+const QUERY_TTL_MS = 5 * 60_000;
+function taskExists() {
+    if (queryCache && Date.now() - queryCache.at < QUERY_TTL_MS)
+        return queryCache.exists;
+    const r = schtasks(['/Query', '/TN', autostart_1.TASK_NAME]);
+    queryCache = { at: Date.now(), exists: r.ok };
+    return r.ok;
+}
+function wscriptPath(env = process.env) {
+    const root = env.SystemRoot || 'C:\\Windows';
+    return path.join(root, 'System32', 'wscript.exe');
+}
+// Windows has no equivalent of macOS's protected folders, so `force` has
+// nothing to override here — the parameter exists to satisfy one interface.
+function enable(entry, env, logPath) {
+    const warnings = [];
+    fs.mkdirSync(exports.STARTUP_DIR, { recursive: true });
+    // `--ensure` is what makes the five-minute repeat safe: it stands down
+    // instantly when a daemon already owns the lockfile.
+    const runEntry = { file: entry.file, args: [...entry.args, 'run', '--ensure'] };
+    fs.writeFileSync(exports.CMD_PATH, buildCmd(runEntry, env, logPath), 'utf8');
+    fs.writeFileSync(exports.VBS_PATH, buildVbs(exports.CMD_PATH), 'utf8');
+    const xml = buildTaskXml({
+        userId: currentUserId(),
+        vbsPath: exports.VBS_PATH,
+        wscriptPath: wscriptPath(),
+        createdAt: new Date().toISOString().replace(/\.\d+Z$/, ''),
+    });
+    // schtasks reads task XML as Unicode. Handed a UTF-8 file it fails with
+    // "The task XML contains a value which is incorrectly formatted or out of
+    // range" — an error that says nothing about encoding and has cost people
+    // hours. UTF-16LE with a BOM is what it wants.
+    fs.writeFileSync(exports.XML_PATH, Buffer.from('\uFEFF' + xml, 'utf16le'));
+    const created = schtasks(['/Create', '/TN', autostart_1.TASK_NAME, '/XML', exports.XML_PATH, '/F']);
+    queryCache = null;
+    if (!created.ok) {
+        return { ok: false, path: exports.XML_PATH, warnings, error: `schtasks could not register the task: ${created.output}` };
+    }
+    // Registering does not run it — the logon trigger has already passed for
+    // this session. Start it now so enabling has a visible effect today; the
+    // action is `--ensure`, so this is a no-op when a node is already up.
+    const ran = schtasks(['/Run', '/TN', autostart_1.TASK_NAME]);
+    if (!ran.ok)
+        warnings.push(`task registered but would not start now (${ran.output}); it will start at your next logon`);
+    return { ok: true, path: exports.XML_PATH, warnings };
+}
+function disable() {
+    const r = schtasks(['/Delete', '/TN', autostart_1.TASK_NAME, '/F']);
+    queryCache = null;
+    for (const f of [exports.CMD_PATH, exports.VBS_PATH, exports.XML_PATH]) {
+        try {
+            fs.unlinkSync(f);
+        }
+        catch { /* already gone */ }
+    }
+    // A missing task is the desired end state, not a failure.
+    if (!r.ok && !/cannot find|does not exist/i.test(r.output)) {
+        return { ok: false, error: r.output };
+    }
+    return { ok: true };
+}
+function status() {
+    const exists = taskExists();
+    if (!exists)
+        return { supported: true, enabled: false, supervisor: 'schtasks' };
+    const issues = [];
+    let entry;
+    try {
+        const body = fs.readFileSync(exports.CMD_PATH, 'utf8');
+        const line = body.split(/\r?\n/).find(l => l.trim().startsWith('"'));
+        if (line) {
+            const parts = [...line.matchAll(/"([^"]+)"/g)].map(m => m[1]);
+            // Last quoted token is the log path from the redirect, not an argument.
+            if (parts.length >= 2)
+                entry = { file: parts[0], args: parts.slice(1, -1) };
+        }
+    }
+    catch {
+        issues.push('the task exists but its launcher script is missing — re-run `ainode startup enable`');
+    }
+    if (entry && !fs.existsSync(entry.args[0] ?? entry.file)) {
+        issues.push(`the pinned program is gone (${entry.args[0] ?? entry.file}) — re-run \`ainode startup enable\``);
+    }
+    return {
+        supported: true,
+        enabled: true,
+        supervisor: 'schtasks',
+        entry,
+        path: exports.XML_PATH,
+        ...(issues.length ? { issues } : {}),
+    };
+}
+exports.backend = { supervisor: 'schtasks', status, enable, disable };

package/dist/autostart.d.ts

@@ -0,0 +1,81 @@
+export type Supervisor = 'launchd' | 'schtasks';
+/** The exact command a supervisor is told to run. */
+export interface AutostartEntry {
+    file: string;
+    args: string[];
+}
+export interface AutostartState {
+    /** False on platforms we don't manage (Linux, anything exotic). */
+    supported: boolean;
+    /** An entry exists AND its pinned program is still on disk. */
+    enabled: boolean;
+    supervisor: Supervisor | null;
+    entry?: AutostartEntry;
+    /** Where the plist / task definition lives, for the user to go look. */
+    path?: string;
+    /** Non-fatal problems worth surfacing — chiefly a pinned path that rotted. */
+    issues?: string[];
+}
+export interface EnableResult {
+    ok: boolean;
+    path?: string;
+    error?: string;
+    warnings: string[];
+}
+export interface DisableResult {
+    ok: boolean;
+    error?: string;
+}
+export interface EnableOptions {
+    /** Arm it anyway when a platform check says it will not work. Exists for
+     *  one case: a Mac whose `node` has been granted Full Disk Access, where
+     *  our ~/Documents refusal is the wrong answer. */
+    force?: boolean;
+}
+/** What each platform backend must provide. */
+export interface AutostartBackend {
+    supervisor: Supervisor;
+    status(): AutostartState;
+    enable(entry: AutostartEntry, env: Record<string, string>, logPath: string, opts: EnableOptions): EnableResult;
+    disable(): DisableResult;
+}
+export declare const LABEL = "ai.add.node";
+/** Task Scheduler's name for the same thing. Space-free: `schtasks` quoting
+ *  through cmd.exe is a known source of Windows breakage in this codebase. */
+export declare const TASK_NAME = "AiNode";
+export interface ResolvedEntry {
+    entry?: AutostartEntry;
+    error?: string;
+}
+/**
+ * The command to write into the supervisor's definition.
+ *
+ * Absolute node + absolute script, never a shim name. launchd hands a job
+ * `PATH=/usr/bin:/bin:/usr/sbin:/sbin`, where neither `node` nor `ainode`
+ * exists on any machine of ours — the job would fail to launch at every login
+ * and the only evidence would be a launchd error nobody reads.
+ *
+ * npx is refused outright. An `_npx/<hash>/` directory is a throwaway cache
+ * pinned to ONE version; writing it into a plist relaunches that version at
+ * every login forever, which is the pin trap we have already been bitten by.
+ * `global` and `source` both pin to a stable path: npm overwrites a global
+ * install in place, and a checkout is a checkout.
+ */
+export declare function resolveEntry(scriptPath?: string, execPath?: string, exists?: (p: string) => boolean): ResolvedEntry;
+/**
+ * Environment the supervised daemon starts with.
+ *
+ * PATH is captured from the live shell at enable time and frozen into the
+ * definition. This is the single most important line in the feature: without
+ * it the node boots under launchd's minimal PATH and cannot find `claude`,
+ * `codex`, `git` or any harness — an node that is "online" and fails
+ * everything is worse than one that is plainly offline.
+ */
+export declare function buildEnv(supervisor: Supervisor, env?: NodeJS.ProcessEnv, home?: string): Record<string, string>;
+export declare function status(): AutostartState;
+export declare function enable(opts?: EnableOptions): EnableResult;
+export declare function disable(): DisableResult;
+/** Is a supervisor going to restart us if we exit? Decides whether a remote
+ *  roll self-respawns or simply stands down and lets the supervisor act. */
+export declare function isSupervised(state?: AutostartState, env?: NodeJS.ProcessEnv): boolean;
+export declare function describeStatus(s: AutostartState): string;

package/dist/autostart.js

@@ -0,0 +1,224 @@
+"use strict";
+// Start this node when the machine starts.
+//
+// Until now a node only ran while somebody kept a terminal open. Reboot the
+// machine, close the window, or miss a crash, and every entity pinned to that
+// node sat at "Getting ready…" until a human walked over and typed `ainode`.
+// self-update.ts says it outright: "The daemon is NOT supervised on any of our
+// nodes — nothing restarts it if it merely exits."
+//
+// This hands supervision to the OS: launchd on macOS, Task Scheduler on
+// Windows. Both run the daemon AS THE USER at login — never as a system
+// service. The daemon needs the login keychain (Claude/Codex auth), the user's
+// PATH (Homebrew, nvm, ~/.local/bin) and ~/.claude / ~/.codex. A root
+// LaunchDaemon or a Windows Service has none of those, so it would faithfully
+// boot a node that then fails every single run.
+//
+// The cost of that choice, stated plainly: a machine that reboots unattended
+// only comes back once somebody logs in, unless auto-login is on.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TASK_NAME = exports.LABEL = void 0;
+exports.resolveEntry = resolveEntry;
+exports.buildEnv = buildEnv;
+exports.status = status;
+exports.enable = enable;
+exports.disable = disable;
+exports.isSupervised = isSupervised;
+exports.describeStatus = describeStatus;
+const os = __importStar(require("os"));
+const fs = __importStar(require("fs"));
+const self_update_1 = require("./self-update");
+const lockfile_1 = require("./lockfile");
+const paths_1 = require("./paths");
+exports.LABEL = 'ai.add.node';
+/** Task Scheduler's name for the same thing. Space-free: `schtasks` quoting
+ *  through cmd.exe is a known source of Windows breakage in this codebase. */
+exports.TASK_NAME = 'AiNode';
+/**
+ * The command to write into the supervisor's definition.
+ *
+ * Absolute node + absolute script, never a shim name. launchd hands a job
+ * `PATH=/usr/bin:/bin:/usr/sbin:/sbin`, where neither `node` nor `ainode`
+ * exists on any machine of ours — the job would fail to launch at every login
+ * and the only evidence would be a launchd error nobody reads.
+ *
+ * npx is refused outright. An `_npx/<hash>/` directory is a throwaway cache
+ * pinned to ONE version; writing it into a plist relaunches that version at
+ * every login forever, which is the pin trap we have already been bitten by.
+ * `global` and `source` both pin to a stable path: npm overwrites a global
+ * install in place, and a checkout is a checkout.
+ */
+function resolveEntry(scriptPath = (0, lockfile_1.entryScript)(), execPath = process.execPath, exists = p => fs.existsSync(p)) {
+    if (!scriptPath) {
+        return { error: 'cannot tell which script this daemon is running' };
+    }
+    const mode = (0, self_update_1.detectLaunchMode)(scriptPath);
+    if (mode === 'npx') {
+        return {
+            error: `this node runs from an npx cache, which is thrown away and pinned to one version.\n`
+                + `Install it properly first, then re-run:\n\n    npm i -g ${self_update_1.PACKAGE_NAME}\n`,
+        };
+    }
+    // realpath so a symlinked global bin resolves to the file npm actually
+    // overwrites on upgrade — pinning the symlink would be fine too, but the
+    // real path is what the lockfile records, so the two agree.
+    const real = (() => {
+        try {
+            return fs.realpathSync(scriptPath);
+        }
+        catch {
+            return scriptPath;
+        }
+    })();
+    if (!exists(real)) {
+        return { error: `entry script does not exist: ${real}` };
+    }
+    return { entry: { file: execPath, args: [real] } };
+}
+/**
+ * Environment the supervised daemon starts with.
+ *
+ * PATH is captured from the live shell at enable time and frozen into the
+ * definition. This is the single most important line in the feature: without
+ * it the node boots under launchd's minimal PATH and cannot find `claude`,
+ * `codex`, `git` or any harness — an node that is "online" and fails
+ * everything is worse than one that is plainly offline.
+ */
+function buildEnv(supervisor, env = process.env, home = os.homedir()) {
+    const out = {
+        PATH: env.PATH || '',
+        HOME: env.HOME || home,
+        // Supervised output goes to a log file, so escape sequences would be
+        // noise at best. cli.ts already falls back to plain lines when not a TTY;
+        // this makes it explicit and survives a supervisor that fakes a TTY.
+        AINODE_NO_TUI: '1',
+        AINODE_SUPERVISOR: supervisor,
+    };
+    if (env.LANG)
+        out.LANG = env.LANG;
+    if (process.platform === 'win32') {
+        if (env.USERPROFILE)
+            out.USERPROFILE = env.USERPROFILE;
+        if (env.APPDATA)
+            out.APPDATA = env.APPDATA;
+        if (env.LOCALAPPDATA)
+            out.LOCALAPPDATA = env.LOCALAPPDATA;
+        if (env.SystemRoot)
+            out.SystemRoot = env.SystemRoot;
+    }
+    return out;
+}
+/* ── platform dispatch ────────────────────────────────────────────────── */
+function backend(platform = process.platform) {
+    // Required lazily: each backend reaches for platform tools at module scope
+    // in tests, and loading the Windows one on a Mac (or vice versa) has no
+    // reason to happen at all.
+    if (platform === 'darwin') {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        return require('./autostart-mac').backend;
+    }
+    if (platform === 'win32') {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        return require('./autostart-win').backend;
+    }
+    return null;
+}
+const UNSUPPORTED = { supported: false, enabled: false, supervisor: null };
+function status() {
+    const b = backend();
+    if (!b)
+        return UNSUPPORTED;
+    try {
+        return b.status();
+    }
+    catch (err) {
+        // Reading state must never throw into the heartbeat — capabilities go out
+        // every few seconds and one bad plist would take the node offline.
+        return { supported: true, enabled: false, supervisor: b.supervisor, issues: [err.message] };
+    }
+}
+function enable(opts = {}) {
+    const b = backend();
+    if (!b) {
+        return { ok: false, warnings: [], error: `starting at login is not supported on ${process.platform} yet` };
+    }
+    const resolved = resolveEntry();
+    if (!resolved.entry)
+        return { ok: false, warnings: [], error: resolved.error };
+    try {
+        return b.enable(resolved.entry, buildEnv(b.supervisor), paths_1.RUNTIME_LOG_FILE, opts);
+    }
+    catch (err) {
+        return { ok: false, warnings: [], error: err.message };
+    }
+}
+function disable() {
+    const b = backend();
+    if (!b)
+        return { ok: true }; // nothing was ever installed; nothing to remove
+    try {
+        return b.disable();
+    }
+    catch (err) {
+        return { ok: false, error: err.message };
+    }
+}
+/** Is a supervisor going to restart us if we exit? Decides whether a remote
+ *  roll self-respawns or simply stands down and lets the supervisor act. */
+function isSupervised(state = status(), env = process.env) {
+    // launchd is a live supervisor: KeepAlive brings the job straight back.
+    // Task Scheduler is not — its logon trigger has already fired, and the
+    // 5-minute repeat is a backstop measured in minutes, not a restart path.
+    // So only launchd earns exit-and-be-restarted.
+    if (env.AINODE_SUPERVISOR === 'launchd')
+        return true;
+    return state.supervisor === 'launchd' && state.enabled;
+}
+/* ── human-readable state, shared by the CLI and the TUI ──────────────── */
+function describeStatus(s) {
+    if (!s.supported)
+        return `Starts at login: not supported on ${process.platform}`;
+    const lines = [
+        `Starts at login: ${s.enabled ? 'yes' : 'no'}${s.supervisor ? ` (${s.supervisor})` : ''}`,
+    ];
+    if (s.path)
+        lines.push(`  definition: ${s.path}`);
+    if (s.entry)
+        lines.push(`  runs: ${[s.entry.file, ...s.entry.args].join(' ')}`);
+    for (const issue of s.issues ?? [])
+        lines.push(`  ! ${issue}`);
+    return lines.join('\n');
+}

package/dist/capabilities.d.ts

@@ -1,3 +1,4 @@
+import { type AutostartState } from './autostart';
 interface AuthShape {
     authed: boolean;
     account?: string;
@@ -37,6 +38,10 @@ interface CapabilitiesShape {
         models?: string[];
     };
     git: BinaryProbe;
+    /** Does this node come back on its own after a reboot? Rides the heartbeat
+     *  rather than a column of its own — same channel Studio already reads the
+     *  harness grid from. */
+    autostart?: AutostartState;
 }
 /** Codex's credential store: $CODEX_HOME (or ~/.codex) + /auth.json. */
 export declare function codexHome(): string;

package/dist/capabilities.js

@@ -52,6 +52,7 @@ const grok_binary_1 = require("./grok-binary");
 const codex_binary_1 = require("./codex-binary");
 const win_1 = require("./win");
 const harness_registry_1 = require("./harness-registry");
+const autostart_1 = require("./autostart");
 function readDaemonVersion() {
     try {
         // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -396,6 +397,7 @@ async function probeCapabilities() {
     });
     return {
         daemon_version: readDaemonVersion(),
+        autostart: (0, autostart_1.status)(),
         claude: deco('claude', claude),
         codex: deco('codex', codex),
         kimi: deco('kimi', kimi),