@indigoai-us/hq-cli 5.115.6 → 5.117.0

package/dist/lib/bot/self-heal.js

@@ -0,0 +1,79 @@
+/**
+ * Self-heal for a launchd registration that outlived its bot.
+ *
+ * `hq bot run <name>` is what the LaunchAgent runs. When the bot's local
+ * config is gone — a wiped ~/.hq, a half-finished reinstall, a bot removed by
+ * hand — the run used to exit non-zero, and KeepAlive{SuccessfulExit:false}
+ * with ThrottleInterval 5 relaunched it every five seconds forever (one test
+ * Mac logged 267 identical "No bot named" lines). So the run now does two
+ * things instead: it exits 0, which KeepAlive does not restart, and it removes
+ * its own registration, so a stale plist cannot outlive the bot it points at.
+ *
+ * Order matters here because this code usually IS the launchd job: the log
+ * line is written and the plist unlinked first, and the `bootout` — which
+ * terminates the caller — goes last, in a detached session that survives it.
+ *
+ * Everything is injectable (platform, launchctl, fs, home) so tests never
+ * touch the real service manager or the real LaunchAgents folder.
+ */
+import { buildBotDaemonPaths, uninstallBotDaemon } from "./daemon.js";
+import { launchdLabel } from "./paths.js";
+/**
+ * Take away the startup registration of a bot that has no local config here.
+ * Never throws: an unresolvable `hq` binary or an unwritable LaunchAgents
+ * folder must not turn into a crash loop of its own.
+ */
+export function removeOrphanBotDaemon(opts, deps = {}) {
+    const label = launchdLabel(opts.name);
+    const toOutcome = (result) => {
+        const removed = /^Removed /.test(result.message);
+        return {
+            name: opts.name,
+            label,
+            removed,
+            ...(result.dest ? { dest: result.dest } : {}),
+            message: removed
+                ? `Removed the startup agent ${label} so it stops relaunching.`
+                : `No startup agent for ${opts.name} to remove.`,
+        };
+    };
+    let result;
+    try {
+        const paths = buildBotDaemonPaths({
+            name: opts.name,
+            botDir: opts.botDir,
+            ...(opts.home ? { home: opts.home } : {}),
+            // The plist path depends only on the name and home; a placeholder keeps
+            // an environment without a resolvable `hq` on PATH from throwing here.
+            hqBinary: "hq",
+            nodeBinary: process.execPath,
+        });
+        result = uninstallBotDaemon(paths, {
+            ...deps,
+            // This runs inside the very job being removed, so the bootout has to
+            // outlive us: detached by default, overridable for tests and for callers
+            // that are not the job.
+            bootout: deps.bootout ?? "detached",
+            ...(opts.announce ? { announce: (r) => opts.announce(toOutcome(r)) } : {}),
+        });
+    }
+    catch (err) {
+        const problem = err instanceof Error ? err.message : String(err);
+        return { name: opts.name, label, removed: false, problem, message: `Could not remove the startup agent ${label}: ${problem}` };
+    }
+    return toOutcome(result);
+}
+/**
+ * What `hq bot run <name>` prints, once, when the bot is not set up on this
+ * computer — plain enough that a person reading ~/.hq/bots/<name>/logs/bot.log
+ * knows exactly what to do next.
+ */
+export function orphanBotRunMessage(name, outcome) {
+    const lines = [
+        `No bot named "${name}" is set up on this computer, so there is nothing to run.`,
+        outcome.message,
+        `Bring it back with: hq bot adopt ${name}   (or restore every bot you own: hq bot restore)`,
+    ];
+    return lines.join("\n");
+}
+//# sourceMappingURL=self-heal.js.map

package/dist/lib/bot/split.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A long reply, cut into posts HQ Cloud will actually accept.
+ *
+ * `POST /v1/notify/dm` refuses a body over DM_BODY_MAX characters with
+ * `400: Message body exceeds 4000 characters`. Nothing used to split, so a
+ * model answer over the limit was sent whole, refused, saved on the in-flight
+ * marker and re-sent identically on every poll — the answer was lost, the
+ * person was never told, and the bot asked the API to do the impossible about
+ * twice a second for as long as it ran.
+ *
+ * `splitBody` is the fix, and it is pure so it can be tested on its own:
+ *
+ * - a body at or under the limit comes back untouched, as one part
+ * - a longer body is cut on paragraph boundaries first, then on sentence
+ *   boundaries, and only hard-wrapped when a single sentence is still too long
+ * - a fenced code block is kept whole when it fits; when it cannot fit, the
+ *   fence is closed at the end of one part and reopened (with its language) at
+ *   the start of the next, so neither part renders as broken markdown
+ * - when there is more than one part, each is prefixed `(2/3)` on its own line
+ *   so the reader can see the order; the prefix is paid for out of the limit,
+ *   never added on top of it
+ *
+ * Every returned part is guaranteed to be at most `max` characters long.
+ */
+/** The largest body HQ Cloud accepts on a DM or channel post. */
+export declare const DM_BODY_MAX = 4000;
+/**
+ * One outbound body as the ordered parts to post, each at most `max`
+ * characters. A body that already fits comes back unchanged.
+ */
+export declare function splitBody(body: string, max?: number): string[];
+//# sourceMappingURL=split.d.ts.map

package/dist/lib/bot/split.js

@@ -0,0 +1,241 @@
+/**
+ * A long reply, cut into posts HQ Cloud will actually accept.
+ *
+ * `POST /v1/notify/dm` refuses a body over DM_BODY_MAX characters with
+ * `400: Message body exceeds 4000 characters`. Nothing used to split, so a
+ * model answer over the limit was sent whole, refused, saved on the in-flight
+ * marker and re-sent identically on every poll — the answer was lost, the
+ * person was never told, and the bot asked the API to do the impossible about
+ * twice a second for as long as it ran.
+ *
+ * `splitBody` is the fix, and it is pure so it can be tested on its own:
+ *
+ * - a body at or under the limit comes back untouched, as one part
+ * - a longer body is cut on paragraph boundaries first, then on sentence
+ *   boundaries, and only hard-wrapped when a single sentence is still too long
+ * - a fenced code block is kept whole when it fits; when it cannot fit, the
+ *   fence is closed at the end of one part and reopened (with its language) at
+ *   the start of the next, so neither part renders as broken markdown
+ * - when there is more than one part, each is prefixed `(2/3)` on its own line
+ *   so the reader can see the order; the prefix is paid for out of the limit,
+ *   never added on top of it
+ *
+ * Every returned part is guaranteed to be at most `max` characters long.
+ */
+/** The largest body HQ Cloud accepts on a DM or channel post. */
+export const DM_BODY_MAX = 4000;
+const FENCE_RE = /^[ \t]*(`{3,}|~{3,})(.*)$/;
+function bare(line) {
+    return line.replace(/\r?\n$/, "");
+}
+/**
+ * The body as paragraphs and whole fenced code blocks, in order. Concatenating
+ * every `raw` reproduces the input exactly, so nothing is lost or reflowed
+ * before a cut is actually needed.
+ */
+function segmentize(body) {
+    const segments = [];
+    let buf = "";
+    let fence = null;
+    const flush = (fenceOpen) => {
+        if (buf)
+            segments.push({ raw: buf, fenceOpen });
+        buf = "";
+    };
+    for (const line of body.split(/(?<=\n)/)) {
+        const text = bare(line);
+        if (fence) {
+            buf += line;
+            const m = FENCE_RE.exec(text);
+            // A closing fence is the same character, at least as long, and bare.
+            if (m && m[1][0] === fence.marker[0] && m[1].length >= fence.marker.length && m[2].trim() === "") {
+                flush(fence.open);
+                fence = null;
+            }
+            continue;
+        }
+        const m = FENCE_RE.exec(text);
+        if (m) {
+            flush(null);
+            fence = { open: text.trimEnd(), marker: m[1] };
+            buf = line;
+            continue;
+        }
+        if (text.trim() === "") {
+            // A blank line closes the paragraph it follows.
+            if (buf)
+                buf += line;
+            else
+                buf = line;
+            flush(null);
+            continue;
+        }
+        buf += line;
+    }
+    flush(fence ? fence.open : null);
+    return segments;
+}
+/** Break points inside a paragraph: after sentence-ending punctuation, or at a line end. */
+function splitSentences(text) {
+    const parts = [];
+    const re = /(?:[.!?…]["'”’)\]]*|\n)[ \t]*\n?[ \t]*/g;
+    let start = 0;
+    let m;
+    while ((m = re.exec(text)) !== null) {
+        const end = m.index + m[0].length;
+        if (end <= start) {
+            re.lastIndex = start + 1;
+            continue;
+        }
+        parts.push(text.slice(start, end));
+        start = end;
+    }
+    if (start < text.length)
+        parts.push(text.slice(start));
+    return parts.length > 0 ? parts : [text];
+}
+/** Last resort: a run of text with no usable break, cut at whitespace when there is any. */
+function hardWrap(text, budget) {
+    const out = [];
+    let rest = text;
+    while (rest.length > budget) {
+        const window = rest.slice(0, budget);
+        const ws = Math.max(window.lastIndexOf(" "), window.lastIndexOf("\n"));
+        const cut = ws > 0 && ws >= Math.floor(budget * 0.6) ? ws : budget;
+        const piece = rest.slice(0, cut).trim();
+        if (piece)
+            out.push(piece);
+        rest = rest.slice(cut).replace(/^[ \t\n]+/, "");
+    }
+    const tail = rest.trim();
+    if (tail)
+        out.push(tail);
+    return out;
+}
+/** A code block too long for one part: closed and reopened around every cut. */
+function splitFenced(segment, budget) {
+    const open = segment.fenceOpen ?? "```";
+    const marker = FENCE_RE.exec(open)?.[1] ?? "```";
+    const overhead = open.length + marker.length + 2; // the two fence lines and their newlines
+    const inner = budget - overhead;
+    if (inner < 1)
+        return splitPlain(segment.raw, budget);
+    const lines = segment.raw.split(/(?<=\n)/).slice(1);
+    const last = lines[lines.length - 1];
+    if (last !== undefined) {
+        const m = FENCE_RE.exec(bare(last));
+        if (m && m[1][0] === marker[0] && m[2].trim() === "")
+            lines.pop();
+    }
+    const pieces = [];
+    let buf = "";
+    const emit = () => {
+        const code = buf.replace(/\n+$/, "");
+        buf = "";
+        if (code.trim() === "")
+            return;
+        pieces.push(`${open}\n${code}\n${marker}`);
+    };
+    for (const line of lines) {
+        if ((buf + line).replace(/\n+$/, "").length <= inner) {
+            buf += line;
+            continue;
+        }
+        emit();
+        const one = bare(line);
+        if (one.length <= inner) {
+            buf = line;
+            continue;
+        }
+        for (const wrapped of hardWrap(one, inner)) {
+            buf = wrapped;
+            emit();
+        }
+    }
+    emit();
+    return pieces.length > 0 ? pieces : splitPlain(segment.raw, budget);
+}
+/** A paragraph too long for one part: sentences first, hard wrap only if one sentence is still too long. */
+function splitPlain(text, budget) {
+    const out = [];
+    let buf = "";
+    const flush = () => {
+        const t = buf.trim();
+        buf = "";
+        if (t)
+            out.push(t);
+    };
+    for (const sentence of splitSentences(text)) {
+        if ((buf + sentence).trim().length <= budget) {
+            buf += sentence;
+            continue;
+        }
+        flush();
+        if (sentence.trim().length <= budget) {
+            buf = sentence;
+            continue;
+        }
+        for (const wrapped of hardWrap(sentence.trim(), budget))
+            out.push(wrapped);
+    }
+    flush();
+    return out.length > 0 ? out : hardWrap(text.trim(), budget);
+}
+function pack(body, budget) {
+    const out = [];
+    let acc = "";
+    const flush = () => {
+        const t = acc.trim();
+        acc = "";
+        if (t)
+            out.push(t);
+    };
+    for (const segment of segmentize(body)) {
+        if ((acc + segment.raw).trim().length <= budget) {
+            acc += segment.raw;
+            continue;
+        }
+        flush();
+        if (segment.raw.trim().length <= budget) {
+            acc = segment.raw;
+            continue;
+        }
+        for (const piece of segment.fenceOpen ? splitFenced(segment, budget) : splitPlain(segment.raw, budget)) {
+            out.push(piece);
+        }
+    }
+    flush();
+    return out;
+}
+/** `(2/3)` and its newline, at the widest the count can make it. */
+function prefixWidth(count) {
+    return `(${count}/${count})\n`.length;
+}
+function label(parts) {
+    if (parts.length < 2)
+        return parts;
+    return parts.map((part, i) => `(${i + 1}/${parts.length})\n${part}`);
+}
+/**
+ * One outbound body as the ordered parts to post, each at most `max`
+ * characters. A body that already fits comes back unchanged.
+ */
+export function splitBody(body, max = DM_BODY_MAX) {
+    const limit = Math.max(1, Math.floor(max));
+    if (body.length <= limit)
+        return [body];
+    let reserve = prefixWidth(2);
+    let parts = [];
+    for (let round = 0; round < 6; round += 1) {
+        parts = pack(body, Math.max(1, limit - reserve));
+        const needed = parts.length > 1 ? prefixWidth(parts.length) : 0;
+        if (needed <= reserve)
+            break;
+        reserve = needed;
+    }
+    if (parts.length === 0)
+        parts = [body.trim() || body];
+    // Belt and braces: whatever the shape of the input, no part may exceed the limit.
+    return label(parts).flatMap((part) => (part.length <= limit ? [part] : hardWrap(part, limit)));
+}
+//# sourceMappingURL=split.js.map

package/dist/lib/service-manager/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Install / uninstall / status for a SET of user-level services, dispatching
+ * to launchd or systemd. All filesystem and process-control effects are
+ * injectable so the kit tests exercise the real rendering and dispatch
+ * without touching the host's service manager.
+ */
+import * as fs from "node:fs";
+import { type RunCommand } from "./launchd.js";
+import { type ServiceHostPaths, type ServicePlatform, type ServiceSpec } from "./types.js";
+export type { ServiceSpec, ServiceHostPaths, ServicePlatform } from "./types.js";
+export { detectServicePlatform } from "./types.js";
+export { renderLaunchdPlist } from "./launchd.js";
+export { renderSystemdUserUnit, systemdUnitName } from "./systemd.js";
+export declare const defaultRunCommand: RunCommand;
+export interface ServiceManagerDeps {
+    platform?: ServicePlatform;
+    run?: RunCommand;
+    writeFileSync?: typeof fs.writeFileSync;
+    mkdirSync?: typeof fs.mkdirSync;
+    unlinkSync?: typeof fs.unlinkSync;
+    existsSync?: typeof fs.existsSync;
+    /** When false, render + write units but do not (de)activate them. */
+    activate?: boolean;
+}
+export interface ServiceUnitResult {
+    name: string;
+    unitPath: string;
+    rendered?: string;
+    installed: boolean;
+    running?: boolean;
+    error?: string;
+}
+export interface ServiceSetResult {
+    platform: ServicePlatform;
+    units: ServiceUnitResult[];
+    /** Human hint when the platform has no service manager integration. */
+    manualCommands?: string[];
+}
+export declare function renderUnit(platform: ServicePlatform, spec: ServiceSpec, host: ServiceHostPaths): string;
+export declare function installServices(specs: ServiceSpec[], host: ServiceHostPaths, deps?: ServiceManagerDeps): ServiceSetResult;
+export declare function uninstallServices(specs: ServiceSpec[], host: ServiceHostPaths, deps?: ServiceManagerDeps): ServiceSetResult;
+export declare function servicesStatus(specs: ServiceSpec[], host: ServiceHostPaths, deps?: ServiceManagerDeps): ServiceSetResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/service-manager/index.js

@@ -0,0 +1,114 @@
+/**
+ * Install / uninstall / status for a SET of user-level services, dispatching
+ * to launchd or systemd. All filesystem and process-control effects are
+ * injectable so the kit tests exercise the real rendering and dispatch
+ * without touching the host's service manager.
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import { activateLaunchd, deactivateLaunchd, launchAgentsDir, launchdIsLoaded, launchdPlistPath, renderLaunchdPlist, } from "./launchd.js";
+import { activateSystemd, deactivateSystemd, renderSystemdUserUnit, systemdIsActive, systemdUnitName, systemdUnitPath, systemdUserDir, } from "./systemd.js";
+import { detectServicePlatform, } from "./types.js";
+export { detectServicePlatform } from "./types.js";
+export { renderLaunchdPlist } from "./launchd.js";
+export { renderSystemdUserUnit, systemdUnitName } from "./systemd.js";
+export const defaultRunCommand = (cmd, args) => {
+    const r = spawnSync(cmd, args, { encoding: "utf8" });
+    return {
+        status: r.status,
+        stdout: r.stdout ?? "",
+        stderr: r.error ? r.error.message : (r.stderr ?? ""),
+    };
+};
+function unitPathFor(platform, home, spec) {
+    return platform === "darwin" ? launchdPlistPath(home, spec) : systemdUnitPath(home, spec);
+}
+export function renderUnit(platform, spec, host) {
+    return platform === "darwin"
+        ? renderLaunchdPlist(spec, host)
+        : renderSystemdUserUnit(spec, host);
+}
+export function installServices(specs, host, deps = {}) {
+    const platform = deps.platform ?? detectServicePlatform();
+    const run = deps.run ?? defaultRunCommand;
+    const writeFileSync = deps.writeFileSync ?? fs.writeFileSync;
+    const mkdirSync = deps.mkdirSync ?? fs.mkdirSync;
+    const activate = deps.activate ?? true;
+    if (platform === "other") {
+        return {
+            platform,
+            units: specs.map((s) => ({ name: s.name, unitPath: "", installed: false })),
+            manualCommands: specs.map((s) => `${host.nodeBinary} ${host.hqBinary} ${s.args.join(" ")}  # >> ${s.logPath}`),
+        };
+    }
+    const dir = platform === "darwin" ? launchAgentsDir(host.home) : systemdUserDir(host.home);
+    mkdirSync(dir, { recursive: true });
+    const units = [];
+    for (const spec of specs) {
+        const unitPath = unitPathFor(platform, host.home, spec);
+        const rendered = renderUnit(platform, spec, host);
+        writeFileSync(unitPath, rendered, { mode: 0o600 });
+        const unit = { name: spec.name, unitPath, rendered, installed: true };
+        if (activate) {
+            try {
+                if (platform === "darwin")
+                    activateLaunchd(unitPath, run);
+                else
+                    activateSystemd(systemdUnitName(spec), run);
+                unit.running = true;
+            }
+            catch (err) {
+                unit.running = false;
+                unit.error = err instanceof Error ? err.message : String(err);
+            }
+        }
+        units.push(unit);
+    }
+    return { platform, units };
+}
+export function uninstallServices(specs, host, deps = {}) {
+    const platform = deps.platform ?? detectServicePlatform();
+    const run = deps.run ?? defaultRunCommand;
+    const unlinkSync = deps.unlinkSync ?? fs.unlinkSync;
+    const existsSync = deps.existsSync ?? fs.existsSync;
+    const activate = deps.activate ?? true;
+    if (platform === "other") {
+        return { platform, units: specs.map((s) => ({ name: s.name, unitPath: "", installed: false })) };
+    }
+    const units = [];
+    for (const spec of specs) {
+        const unitPath = unitPathFor(platform, host.home, spec);
+        const present = existsSync(unitPath);
+        if (present) {
+            if (activate) {
+                if (platform === "darwin")
+                    deactivateLaunchd(unitPath, run);
+                else
+                    deactivateSystemd(systemdUnitName(spec), run);
+            }
+            unlinkSync(unitPath);
+        }
+        units.push({ name: spec.name, unitPath, installed: false, running: false });
+    }
+    return { platform, units };
+}
+export function servicesStatus(specs, host, deps = {}) {
+    const platform = deps.platform ?? detectServicePlatform();
+    const run = deps.run ?? defaultRunCommand;
+    const existsSync = deps.existsSync ?? fs.existsSync;
+    if (platform === "other") {
+        return { platform, units: specs.map((s) => ({ name: s.name, unitPath: "", installed: false })) };
+    }
+    const units = specs.map((spec) => {
+        const unitPath = unitPathFor(platform, host.home, spec);
+        const installed = existsSync(unitPath);
+        const running = installed
+            ? platform === "darwin"
+                ? launchdIsLoaded(spec.label, run)
+                : systemdIsActive(systemdUnitName(spec), run)
+            : false;
+        return { name: spec.name, unitPath, installed, running };
+    });
+    return { platform, units };
+}
+//# sourceMappingURL=index.js.map

package/dist/lib/service-manager/launchd.d.ts

@@ -0,0 +1,23 @@
+/**
+ * macOS LaunchAgent rendering + activation for kit services.
+ *
+ * Units live at ~/Library/LaunchAgents/<label>.plist. Activation uses the
+ * modern `launchctl bootstrap gui/<uid>` form (bootout first so a re-install
+ * picks up a changed plist). Command execution is injected so tests never
+ * touch launchctl.
+ */
+import { type ServiceHostPaths, type ServiceSpec } from "./types.js";
+export declare const LAUNCHD_PATH_ENV = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin";
+export declare function launchAgentsDir(home: string): string;
+export declare function launchdPlistPath(home: string, spec: Pick<ServiceSpec, "label">): string;
+export declare function renderLaunchdPlist(spec: ServiceSpec, host: ServiceHostPaths): string;
+export type RunCommand = (cmd: string, args: string[]) => {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+};
+/** (Re)load a plist: bootout is best-effort (not loaded yet is fine). */
+export declare function activateLaunchd(plistPath: string, run: RunCommand, uid?: number): void;
+export declare function deactivateLaunchd(plistPath: string, run: RunCommand, uid?: number): void;
+export declare function launchdIsLoaded(label: string, run: RunCommand, uid?: number): boolean;
+//# sourceMappingURL=launchd.d.ts.map

package/dist/lib/service-manager/launchd.js

@@ -0,0 +1,81 @@
+/**
+ * macOS LaunchAgent rendering + activation for kit services.
+ *
+ * Units live at ~/Library/LaunchAgents/<label>.plist. Activation uses the
+ * modern `launchctl bootstrap gui/<uid>` form (bootout first so a re-install
+ * picks up a changed plist). Command execution is injected so tests never
+ * touch launchctl.
+ */
+import * as os from "node:os";
+import * as path from "node:path";
+import { escapeXml, } from "./types.js";
+export const LAUNCHD_PATH_ENV = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin";
+export function launchAgentsDir(home) {
+    return path.join(home, "Library", "LaunchAgents");
+}
+export function launchdPlistPath(home, spec) {
+    return path.join(launchAgentsDir(home), `${spec.label}.plist`);
+}
+export function renderLaunchdPlist(spec, host) {
+    const args = [host.nodeBinary, host.hqBinary, ...spec.args]
+        .map((a) => `    <string>${escapeXml(a)}</string>`)
+        .join("\n");
+    const env = {
+        HOME: host.home,
+        PATH: LAUNCHD_PATH_ENV,
+        ...spec.env,
+    };
+    const envXml = Object.entries(env)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, v]) => `    <key>${escapeXml(k)}</key>\n    <string>${escapeXml(v)}</string>`)
+        .join("\n");
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${escapeXml(spec.label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${escapeXml(spec.workingDir)}</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>${spec.restartSec}</integer>
+  <key>StandardOutPath</key>
+  <string>${escapeXml(spec.logPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(spec.logPath)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+${envXml}
+  </dict>
+</dict>
+</plist>
+`;
+}
+function guiDomain(uid = os.userInfo().uid) {
+    return `gui/${uid}`;
+}
+/** (Re)load a plist: bootout is best-effort (not loaded yet is fine). */
+export function activateLaunchd(plistPath, run, uid) {
+    const domain = guiDomain(uid);
+    run("launchctl", ["bootout", domain, plistPath]);
+    const r = run("launchctl", ["bootstrap", domain, plistPath]);
+    if (r.status !== 0) {
+        throw new Error(`launchctl bootstrap failed for ${plistPath}: ${r.stderr.trim() || r.stdout.trim() || `exit ${r.status}`}`);
+    }
+}
+export function deactivateLaunchd(plistPath, run, uid) {
+    run("launchctl", ["bootout", guiDomain(uid), plistPath]);
+}
+export function launchdIsLoaded(label, run, uid) {
+    const r = run("launchctl", ["print", `${guiDomain(uid)}/${label}`]);
+    return r.status === 0;
+}
+//# sourceMappingURL=launchd.js.map

package/dist/lib/service-manager/systemd.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Linux systemd USER unit rendering + activation for kit services.
+ *
+ * Units live at ~/.config/systemd/user/<name>.service and are enabled with
+ * `systemctl --user enable --now`. A host without a user session bus (some
+ * containers, headless boxes) cannot run user units; the kit's Docker image
+ * is the escape hatch there. Command execution is injected for tests.
+ */
+import { type ServiceHostPaths, type ServiceSpec } from "./types.js";
+import type { RunCommand } from "./launchd.js";
+export declare const SYSTEMD_PATH_ENV = "/usr/local/bin:/usr/bin:/bin";
+export declare function systemdUserDir(home: string): string;
+export declare function systemdUnitName(spec: Pick<ServiceSpec, "name">): string;
+export declare function systemdUnitPath(home: string, spec: Pick<ServiceSpec, "name">): string;
+export declare function renderSystemdUserUnit(spec: ServiceSpec, host: ServiceHostPaths): string;
+export declare function activateSystemd(unitName: string, run: RunCommand): void;
+export declare function deactivateSystemd(unitName: string, run: RunCommand): void;
+export declare function systemdIsActive(unitName: string, run: RunCommand): boolean;
+//# sourceMappingURL=systemd.d.ts.map