@agentprojectcontext/apx 1.77.3 → 1.79.0

package/src/core/channels/telegram/reply.js

@@ -7,9 +7,10 @@
 // of truth fixes that for good.
 import { runSuperAgent } from "#core/agent/super-agent.js";
 import { TELEGRAM_TOOL_ITERS } from "#core/agent/constants.js";
-import { stripThinking } from "#core/util/thinking.js";
+import { stripThinking, stripReasoning } from "#core/util/thinking.js";
 import { appendGlobalMessage, getRecentTelegramTurnsFromFs } from "#core/stores/messages.js";
 import { CHANNELS } from "#core/constants/channels.js";
+import { summarizeToolTrace } from "#core/agent/tool-summary.js";
 import { SUPERAGENT_ACTOR_ID } from "#core/identity/index.js";
 import { createTelegramConfirmAdapter } from "#core/confirmation/adapters/telegram.js";
 import { getConfirmationStore as getConfirmStore } from "#core/confirmation/pending-store.js";
@@ -54,7 +55,9 @@ export function buildStreamHandler(self, { chat_id, update_id, agentDisplay }) {
         return;
       }
       if (ev.type === "assistant_text" && ev.text) {
-        const piece = stripThinking(ev.text).trim();
+        // Untagged planning is suppressed mid-stream too, or the user
+        // watches the model think in real time.
+        const piece = stripReasoning(ev.text).answer.trim();
         if (!piece) return;
         await self._send({ chat_id, text: piece });
         state.lastStreamedText = piece;
@@ -183,6 +186,7 @@ export async function runFollowupTurn(self, {
     let replyAuthor;
     let saUsage = null;
     let saModel = null;
+    let saTrace = null;
     try {
       const sa = await runTelegramSuperAgent(self, {
         chat_id,
@@ -200,6 +204,7 @@ export async function runFollowupTurn(self, {
       replyAuthor = sa.name || agentDisplay;
       saUsage = sa.usage;
       saModel = sa.model || state.model || null;
+      saTrace = sa.trace || null;
     } catch (e) {
       self.log(`telegram[${self.channel.name}] a2a followup failed: ${e.message}`);
       replyText = telegramErrorText(self, e);
@@ -216,6 +221,7 @@ export async function runFollowupTurn(self, {
       replyKind: "superagent",
       saUsage,
       saModel,
+      saTrace,
       streamedCount: state.streamedCount,
       lastStreamedText: state.lastStreamedText,
       agentDisplay,
@@ -244,10 +250,22 @@ export function telegramErrorText(self, e) {
  */
 export async function sendFinalReply(self, {
   chat_id, update_id, replyText, replyAuthor, replyActorId, replyKind,
-  saUsage = null, saModel = null, streamedCount = 0, lastStreamedText = "", agentDisplay,
-  extraMeta = {},
+  saUsage = null, saModel = null, saTrace = null, streamedCount = 0, lastStreamedText = "",
+  agentDisplay, extraMeta = {},
 }) {
-  const finalClean = replyText ? stripThinking(replyText).trim() : "";
+  // A model that dumps raw planning must never have it forwarded. When that
+  // happens the answer comes back empty and the existing never-silent fallback
+  // below sends a short line instead — a worse reply, but not the model's notes.
+  const stripped = replyText ? stripReasoning(replyText) : { answer: "", leaked: false };
+  const finalClean = stripped.answer.trim();
+  if (stripped.leaked) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[apx] telegram: suppressed an untagged reasoning dump from ${saModel || "the model"} ` +
+      `(${replyText.length} chars). Check the model chain — a router that returns raw ` +
+      `chain-of-thought is not usable on a user-facing channel.`
+    );
+  }
   let toSend = "";
   if (finalClean && finalClean !== lastStreamedText) {
     toSend = finalClean;
@@ -265,8 +283,15 @@ export async function sendFinalReply(self, {
     await self._send({ chat_id, text: toSend });
     const meta = { chat_id, tg_channel: self.channel.name, in_reply_to: update_id, final: true, ...extraMeta };
     if (replyText && stripThinking(replyText) !== replyText) meta.thinking_stripped = true;
+    if (stripped.leaked) meta.reasoning_leak_suppressed = true;
     if (saUsage) meta.usage = saUsage;
     if (saModel) meta.model = saModel;
+    // A COMPACT summary, not the trace: the full one carries args and results
+    // and would bloat the day-file for a detail nobody reads back. What is
+    // worth recovering later is "it read three files and sent a message", and
+    // whether any of it failed.
+    const toolSummary = summarizeToolTrace(saTrace);
+    if (toolSummary) meta.tool_summary = toolSummary;
     appendGlobalMessage({
       channel: CHANNELS.TELEGRAM,
       direction: "out",

package/src/core/config/index.js

@@ -5,7 +5,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { APX_HOME, CONFIG_PATH } from "./paths.js";
-import { PERMISSION_MODES, DEFAULT_PERMISSION_MODE } from "../constants/permissions.js";
+import { PERMISSION_MODES } from "../constants/permissions.js";
 import { agentsMdFile, apcProjectFile } from "../apc/paths.js";
 
 export {
@@ -62,6 +62,10 @@ const DEFAULT_CONFIG = {
     // snappier but more "want me to continue?" hand-backs. 0/unset → built-in
     // default (TELEGRAM_TOOL_ITERS in src/core/agent/constants.js).
     telegram_max_iters: 0,
+    // Char cap for a FOREIGN project's AGENTS.md in the prompt. 0 = no cap.
+    // The project APX runs inside is never capped regardless of this value —
+    // a project must always read its own contract whole.
+    project_agents_max_chars: 24000,
     // Model fallback: ordered list. Each item carries its own provider
     // prefix; the array order IS the attempt order. The router tries the
     // primary (super_agent.model) first, then walks this list, skipping
@@ -522,186 +526,24 @@ export function removeProject(cfg, idOrPath) {
   if (cfg.projects.length !== before) writeConfig(cfg);
   return { removed: before - cfg.projects.length };
 }
-// ── Telegram channels (multi-channel mode) ──────────────────────────────────
-// Each entry in cfg.telegram.channels[] is { name, bot_token, chat_id,
-// route_to_agent, project, respond_with_engine, poll_interval_ms }.
-// These helpers keep the array shape stable for the CLI and the daemon API.
-
-const CHANNEL_FIELDS = [
-  "name",
-  "bot_token",
-  "chat_id",
-  "route_to_agent",
-  "project",
-  "respond_with_engine",
-  "poll_interval_ms",
-  "owner_user_id",
-];
-
-function ensureChannelsArray(cfg) {
-  cfg.telegram = cfg.telegram || {};
-  if (!Array.isArray(cfg.telegram.channels)) cfg.telegram.channels = [];
-  return cfg.telegram.channels;
-}
-
-export function listTelegramChannels(cfg) {
-  return ensureChannelsArray(cfg).slice();
-}
-
-export function findTelegramChannel(cfg, name) {
-  return ensureChannelsArray(cfg).find((c) => c.name === name) || null;
-}
-
-// Create-or-patch a channel by name. `patch` is a partial channel object;
-// unknown keys are dropped. Returns { created, channel }.
-export function upsertTelegramChannel(cfg, name, patch = {}) {
-  if (!name || typeof name !== "string")
-    throw new Error("upsertTelegramChannel: name required");
-  const channels = ensureChannelsArray(cfg);
-  let entry = channels.find((c) => c.name === name);
-  const created = !entry;
-  if (!entry) {
-    entry = { name };
-    channels.push(entry);
-  }
-  for (const k of CHANNEL_FIELDS) {
-    if (k === "name") continue;
-    if (patch[k] !== undefined) entry[k] = patch[k];
-  }
-  // Default respond_with_engine to true on create.
-  if (created && entry.respond_with_engine === undefined) {
-    entry.respond_with_engine = true;
-  }
-  writeConfig(cfg);
-  return { created, channel: entry };
-}
-
-export function removeTelegramChannel(cfg, name) {
-  const channels = ensureChannelsArray(cfg);
-  const before = channels.length;
-  cfg.telegram.channels = channels.filter((c) => c.name !== name);
-  const removed = before - cfg.telegram.channels.length;
-  if (removed > 0) {
-    // Explicit user-initiated removal — bypass the credential-loss guard
-    // so the write goes through even when this empties the array.
-    cfg._allowClear = true;
-    writeConfig(cfg);
-  }
-  return { removed };
-}
-
-// Clear specific optional fields on a channel (project, route_to_agent, …).
-// Returns { channel } or null when no such channel.
-export function unsetTelegramChannelFields(cfg, name, fields = []) {
-  const ch = findTelegramChannel(cfg, name);
-  if (!ch) return null;
-  let mutated = false;
-  for (const f of fields) {
-    if (!CHANNEL_FIELDS.includes(f) || f === "name") continue;
-    if (f in ch) {
-      delete ch[f];
-      mutated = true;
-    }
-  }
-  if (mutated) writeConfig(cfg);
-  return { channel: ch };
-}
-
-// ── Telegram contacts (global roster, keyed by user_id) ─────────────────────
-// Identity of a person is global; the per-channel owner_user_id only marks who
-// owns a given channel. Role lives on the contact (global), per the chosen
-// design — owner_user_id overrides it to "owner" for that channel only.
-
-const CONTACT_FIELDS = [
-  "user_id",
-  "name",
-  "username",
-  "role",
-  "note",
-  "first_seen",
-  "last_seen",
-];
-
-function ensureContactsArray(cfg) {
-  cfg.telegram = cfg.telegram || {};
-  if (!Array.isArray(cfg.telegram.contacts)) cfg.telegram.contacts = [];
-  return cfg.telegram.contacts;
-}
-
-export function listContacts(cfg) {
-  return ensureContactsArray(cfg).slice();
-}
-
-export function findContact(cfg, userId) {
-  if (userId == null) return null;
-  return (
-    ensureContactsArray(cfg).find((c) => String(c.user_id) === String(userId)) ||
-    null
-  );
-}
-
-// Create-or-patch a contact by user_id. Unknown keys are dropped.
-export function upsertContact(cfg, userId, patch = {}, { persist = true } = {}) {
-  if (userId == null) throw new Error("upsertContact: user_id required");
-  const contacts = ensureContactsArray(cfg);
-  let entry = contacts.find((c) => String(c.user_id) === String(userId));
-  const created = !entry;
-  if (!entry) {
-    entry = { user_id: userId };
-    contacts.push(entry);
-  }
-  for (const k of CONTACT_FIELDS) {
-    if (k === "user_id") continue;
-    if (patch[k] !== undefined) entry[k] = patch[k];
-  }
-  if (persist) writeConfig(cfg);
-  return { created, contact: entry };
-}
-
-export function setContactRole(cfg, userId, role) {
-  const { contact } = upsertContact(cfg, userId, { role });
-  return contact;
-}
-
-export function removeContact(cfg, userId) {
-  const contacts = ensureContactsArray(cfg);
-  const before = contacts.length;
-  cfg.telegram.contacts = contacts.filter(
-    (c) => String(c.user_id) !== String(userId)
-  );
-  const removed = before - cfg.telegram.contacts.length;
-  if (removed > 0) writeConfig(cfg);
-  return { removed };
-}
-
-export function setChannelOwner(cfg, channelName, userId) {
-  return upsertTelegramChannel(cfg, channelName, { owner_user_id: userId });
-}
-
-// ── Telegram roles (role → capability map) ──────────────────────────────────
-
-export function listRoles(cfg) {
-  cfg.telegram = cfg.telegram || {};
-  return { ...(cfg.telegram.roles || {}) };
-}
-
-export function setRole(cfg, name, def) {
-  if (!name || typeof name !== "string") throw new Error("setRole: name required");
-  cfg.telegram = cfg.telegram || {};
-  cfg.telegram.roles = cfg.telegram.roles || {};
-  cfg.telegram.roles[name] = def;
-  writeConfig(cfg);
-  return cfg.telegram.roles[name];
-}
-
-export function removeRole(cfg, name) {
-  cfg.telegram = cfg.telegram || {};
-  if (!cfg.telegram.roles || !(name in cfg.telegram.roles)) return { removed: 0 };
-  if (name === "owner" || name === "guest") {
-    throw new Error(`role "${name}" is built-in and cannot be removed`);
-  }
-  delete cfg.telegram.roles[name];
-  writeConfig(cfg);
-  return { removed: 1 };
-}
 
+// ── Telegram identity ───────────────────────────────────────────────────────
+// Moved to core/channels/telegram/config.js — it is channel domain, not config
+// plumbing. Re-exported here so the CLI, the daemon API and the plugin keep
+// their existing import paths.
+export {
+  listTelegramChannels,
+  findTelegramChannel,
+  upsertTelegramChannel,
+  removeTelegramChannel,
+  unsetTelegramChannelFields,
+  listContacts,
+  findContact,
+  upsertContact,
+  setContactRole,
+  removeContact,
+  setChannelOwner,
+  listRoles,
+  setRole,
+  removeRole,
+} from "../channels/telegram/config.js";

package/src/core/config/paths.js

@@ -4,7 +4,19 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-export const APX_HOME = path.join(os.homedir(), ".apx");
+/**
+ * Where APX keeps everything. `APX_HOME` in the environment relocates it —
+ * useful for sandboxes and required by tests that need an isolated home.
+ *
+ * Resolve lazily when a caller can be reached after the environment changes
+ * (tests stub os.homedir mid-run); the eager `APX_HOME` constant below is the
+ * common case and stays for the ~30 call sites that read it at import time.
+ */
+export function apxHome() {
+  return process.env.APX_HOME || path.join(os.homedir(), ".apx");
+}
+
+export const APX_HOME = apxHome();
 export const CONFIG_PATH = path.join(APX_HOME, "config.json");
 export const PID_PATH = path.join(APX_HOME, "daemon.pid");
 export const LOG_PATH = path.join(APX_HOME, "daemon.log");
@@ -21,6 +33,50 @@ export const PROJECT_STORE_ROOT = path.join(APX_HOME, "projects");
 export const DEFAULT_PROJECT_ID = "default";
 export const DEFAULT_PROJECT_STORE = path.join(PROJECT_STORE_ROOT, DEFAULT_PROJECT_ID);
 
+// ---------------------------------------------------------------------------
+// Everything else under ~/.apx.
+//
+// These used to be rebuilt from os.homedir() at ~30 call sites, several of them
+// duplicated across modules that then drifted: the TTS scratch dir existed in
+// core/voice/tts.js *and* api/voice.js, the desktop log in core/desktop/
+// process.js *and* cli/commands/desktop.js, the log paths in core/logging.js
+// *and* cli/commands/log.js. One definition each, imported everywhere.
+// ---------------------------------------------------------------------------
+
+/** The super-agent's own notebook (see core/agent/self-memory.js). */
+export const SELF_MEMORY_PATH = path.join(APX_HOME, "memory.md");
+/** Who the super-agent is: name, personality, owner. */
+export const IDENTITY_PATH = path.join(APX_HOME, "identity.json");
+
+/** User-installed skills and the RAG index built over them. */
+export const SKILLS_DIR = path.join(APX_HOME, "skills");
+export const SKILLS_INDEX_PATH = path.join(SKILLS_DIR, ".index.json");
+
+/** Agent vault — reusable agent definitions, not tied to one project. */
+export const AGENT_VAULT_DIR = path.join(APX_HOME, "agents");
+
+/** Ledger of unrequested outbound messages and the user's feedback on them. */
+export const NUDGES_PATH = path.join(APX_HOME, "nudges.json");
+
+/** Unified log tree. Everything writes here so one tail follows the system. */
+export const LOG_DIR = path.join(APX_HOME, "logs");
+export const APX_LOG_PATH = path.join(LOG_DIR, "apx.log");
+export const ERROR_TRACE_PATH = path.join(LOG_DIR, "errors.jsonl");
+
+/** Desktop capsule (Electron) runtime state. */
+export const DESKTOP_PID_PATH = path.join(APX_HOME, "desktop.pid");
+export const DESKTOP_LOG_PATH = path.join(APX_HOME, "desktop.log");
+export const DESKTOP_AUTOSTART_LOG_PATH = path.join(APX_HOME, "desktop-autostart.log");
+
+/** Scratch space. Safe to delete between runs. */
+export const TMP_DIR = path.join(APX_HOME, "tmp");
+export const TTS_TMP_DIR = path.join(TMP_DIR, "tts");
+export const RECORDINGS_TMP_DIR = path.join(TMP_DIR, "recordings");
+
+/** Managed runtimes we install on the user's behalf. */
+export const RUNTIME_DIR = path.join(APX_HOME, "runtime");
+export const WHISPER_VENV_DIR = path.join(RUNTIME_DIR, "whisper-venv");
+
 export function projectStorageRoot(apxId) {
   return path.join(PROJECT_STORE_ROOT, apxId);
 }

package/src/core/config/redact.js

@@ -25,6 +25,11 @@ export const SECRET_PATHS = [
   // Telegram bot tokens live inside an array — handled separately in redact()
   // because dotted paths can't address array entries.
   "telegram.channels.*.bot_token",
+  // Same problem: engines.gemini.api_keys is a LIST of spare keys (quota
+  // rotation). A dotted path cannot reach into it, so redact() handles it
+  // below. Listed here so the "which keys are secrets" question still has one
+  // answer to read.
+  "engines.gemini.api_keys.*",
 ];
 
 /** Replace a secret string with the visible marker, preserving the last 5 chars. */
@@ -64,6 +69,12 @@ export function redactConfig(cfg) {
       }
     }
   }
+  // Spare Gemini keys. Missing this would have served every one of them in
+  // clear text to anyone who opened Settings → Engines.
+  const spareKeys = out?.engines?.gemini?.api_keys;
+  if (Array.isArray(spareKeys)) {
+    out.engines.gemini.api_keys = spareKeys.map(mark);
+  }
   return out;
 }
 
@@ -108,6 +119,17 @@ export function mergeRedactedSecrets(next, prior) {
   if (Array.isArray(nextChannels)) {
     next.telegram.channels = mergeRedactedChannels(nextChannels, prior?.telegram?.channels);
   }
+  // Spare Gemini keys. Without this, opening Settings → Engines and pressing
+  // Save would write the redaction MARKERS over the real keys and silently
+  // empty the rotation pool. Matched by position, which is the only identity
+  // an entry in this list has.
+  const nextSpare = next?.engines?.gemini?.api_keys;
+  if (Array.isArray(nextSpare)) {
+    const priorSpare = Array.isArray(prior?.engines?.gemini?.api_keys)
+      ? prior.engines.gemini.api_keys : [];
+    next.engines.gemini.api_keys = nextSpare.map((v, i) =>
+      isSecretMarker(v) && typeof priorSpare[i] === "string" && priorSpare[i] ? priorSpare[i] : v);
+  }
   return next;
 }
 

package/src/core/confirmation/adapters/web.js

@@ -11,7 +11,7 @@
 //      dialog. The dialog is keyed by correlationId.
 //
 //   3. The user responds → frontend POSTs to
-//      POST /super-agent/confirm/:correlationId  { confirmed: boolean }
+//      POST /api/super-agent/confirm/:correlationId  { confirmed: boolean }
 //
 //   4. The API handler (api/confirm.js) calls pendingStore.resolve(correlationId,
 //      value). This finds the in-memory resolve callback and calls it, unblocking

package/src/core/daemon/service.js

@@ -0,0 +1,238 @@
+// Run the daemon as a real, self-healing service.
+//
+// Today the daemon starts transitively — some CLI command calls ensureDaemon()
+// and one appears. If it dies at 3am nothing brings it back, so the routines
+// that were meant to run at 8:30 do not, and nobody finds out until they
+// wonder why the morning message never arrived. A scheduler you cannot rely on
+// to be running is not a scheduler.
+//
+// Per-user, never sudo, fully reversible. Same shape as core/desktop/autostart.js,
+// which this deliberately mirrors rather than reinvents:
+//
+//   macOS  → ~/Library/LaunchAgents/dev.apx.daemon.plist   (KeepAlive true)
+//   linux  → ~/.config/systemd/user/apx-daemon.service     (Restart=always)
+//   win32  → HKCU\…\Run\APXDaemon                          (see the caveat below)
+//
+// OPT-IN, always. Installing a system service without being asked is the kind
+// of thing that makes people uninstall software, and APX works perfectly well
+// without it.
+//
+// Functions return { ok, … } and never throw or exit, so the CLI and the HTTP
+// layer can both render the result.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { LOG_DIR } from "#core/config/paths.js";
+import { augmentedPath } from "#core/util/path-env.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export const SERVICE_LABEL = "dev.apx.daemon";
+export const MAC_PLIST_PATH = path.join(os.homedir(), "Library", "LaunchAgents", `${SERVICE_LABEL}.plist`);
+export const LINUX_UNIT_PATH = path.join(os.homedir(), ".config", "systemd", "user", "apx-daemon.service");
+export const WIN_RUN_KEY = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run";
+export const WIN_RUN_NAME = "APXDaemon";
+
+export const SERVICE_LOG_PATH = path.join(LOG_DIR, "daemon-service.log");
+
+/**
+ * [bin, ...args] the supervisor should run.
+ *
+ * TWO things this must NOT be, both of which look right and are not:
+ *
+ * 1. The `apx` shim. npm/pnpm shims are shell scripts that `exec node`, and a
+ *    launchd/systemd environment has a minimal PATH with no nvm and often no
+ *    /usr/local/bin, so they fail at boot with "node: not found". That exact
+ *    mistake already cost a day of silent voice failures.
+ *
+ * 2. `apx daemon start`. That command SPAWNS THE DAEMON DETACHED AND EXITS
+ *    (cli/http.js autoStart). Under KeepAlive the supervisor would see its
+ *    child exit within a second, restart it, and loop forever — spawning a new
+ *    daemon each time and never noticing the one already running. A supervised
+ *    process must be the daemon itself, in the foreground.
+ */
+export function getDaemonRunner() {
+  const entry = path.resolve(__dirname, "..", "..", "host", "daemon", "index.js");
+  return [process.execPath, entry];
+}
+
+function escapeXml(s) {
+  return String(s).replace(/[<>&'"]/g, (c) =>
+    ({ "<": "&lt;", ">": "&gt;", "&": "&amp;", "'": "&apos;", '"': "&quot;" }[c]));
+}
+
+/**
+ * launchd plist with KeepAlive TRUE — the whole point. The desktop's plist sets
+ * it false because a window the user closed should stay closed; a daemon that
+ * exits should come back.
+ */
+export function buildDaemonPlist(runner = getDaemonRunner(), logFile = SERVICE_LOG_PATH) {
+  const args = [...runner];
+  const argsXml = args.map((a) => `    <string>${escapeXml(a)}</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>${SERVICE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${argsXml}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key><string>${escapeXml(augmentedPath())}</string>
+  </dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>ThrottleInterval</key><integer>10</integer>
+  <key>ProcessType</key><string>Background</string>
+  <key>StandardOutPath</key><string>${escapeXml(logFile)}</string>
+  <key>StandardErrorPath</key><string>${escapeXml(logFile)}</string>
+</dict>
+</plist>
+`;
+}
+
+/** systemd --user unit. `default.target`, not `multi-user.target`: this is a
+ *  per-user service that should start with the user's session, not at boot. */
+export function buildSystemdUnit(runner = getDaemonRunner()) {
+  const exec = [...runner]
+    .map((a) => (/\s/.test(a) ? `"${a}"` : a))
+    .join(" ");
+  return `[Unit]
+Description=APX daemon
+After=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${exec}
+Environment=PATH=${augmentedPath()}
+Restart=always
+RestartSec=10
+# Give up only if it is crash-looping, so a genuinely broken install does not
+# spin forever writing to the log.
+StartLimitBurst=5
+StartLimitIntervalSec=120
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+/** @returns {{installed: boolean, path?: string, platform: string, supervised: boolean, note?: string}} */
+export function serviceStatus(platform = process.platform) {
+  if (platform === "darwin") {
+    return {
+      platform, supervised: true, installed: fs.existsSync(MAC_PLIST_PATH),
+      path: MAC_PLIST_PATH,
+    };
+  }
+  if (platform === "linux") {
+    return {
+      platform, supervised: true, installed: fs.existsSync(LINUX_UNIT_PATH),
+      path: LINUX_UNIT_PATH,
+    };
+  }
+  if (platform === "win32") {
+    let installed = false;
+    try {
+      const out = execFileSync("reg", ["query", WIN_RUN_KEY, "/v", WIN_RUN_NAME], {
+        stdio: ["ignore", "pipe", "ignore"],
+      }).toString();
+      installed = new RegExp(WIN_RUN_NAME).test(out);
+    } catch { /* not present */ }
+    return {
+      platform, installed, supervised: false,
+      path: `${WIN_RUN_KEY}\\${WIN_RUN_NAME}`,
+      // Said plainly rather than implied. A Run key starts the daemon at login
+      // and does NOT restart it if it dies — which is most of what a service is
+      // for. Promising self-healing here would be a lie the user only discovers
+      // the morning nothing ran.
+      note: "starts at login, but does NOT restart the daemon if it dies — " +
+            "Windows needs a real service wrapper (nssm/sc.exe) for that, which APX does not ship yet",
+    };
+  }
+  return { platform, installed: false, supervised: false, note: `not supported on ${platform}` };
+}
+
+export function installService(platform = process.platform) {
+  const runner = getDaemonRunner();
+
+  if (platform === "darwin") {
+    try {
+      fs.mkdirSync(path.dirname(MAC_PLIST_PATH), { recursive: true });
+      fs.mkdirSync(LOG_DIR, { recursive: true });
+      fs.writeFileSync(MAC_PLIST_PATH, buildDaemonPlist(runner), "utf8");
+      try { execFileSync("launchctl", ["unload", MAC_PLIST_PATH], { stdio: "ignore" }); } catch { /* not loaded */ }
+      execFileSync("launchctl", ["load", "-w", MAC_PLIST_PATH], { stdio: "ignore" });
+      return { ok: true, path: MAC_PLIST_PATH, supervised: true, log: SERVICE_LOG_PATH };
+    } catch (e) { return { ok: false, error: e.message }; }
+  }
+
+  if (platform === "linux") {
+    try {
+      fs.mkdirSync(path.dirname(LINUX_UNIT_PATH), { recursive: true });
+      fs.writeFileSync(LINUX_UNIT_PATH, buildSystemdUnit(runner), "utf8");
+      execFileSync("systemctl", ["--user", "daemon-reload"], { stdio: "ignore" });
+      execFileSync("systemctl", ["--user", "enable", "--now", "apx-daemon.service"], { stdio: "ignore" });
+      return {
+        ok: true, path: LINUX_UNIT_PATH, supervised: true,
+        // Without lingering, systemd --user stops when the last session ends,
+        // so a headless box would silently lose the daemon on logout.
+        note: "for a machine you are not logged into, run: loginctl enable-linger $USER",
+      };
+    } catch (e) { return { ok: false, error: e.message }; }
+  }
+
+  if (platform === "win32") {
+    const cmdline = [...runner]
+      .map((s) => `"${String(s).replace(/"/g, '\\"')}"`).join(" ");
+    try {
+      execFileSync("reg", ["add", WIN_RUN_KEY, "/v", WIN_RUN_NAME, "/t", "REG_SZ", "/d", cmdline, "/f"],
+        { stdio: "ignore" });
+      return {
+        ok: true, path: `${WIN_RUN_KEY}\\${WIN_RUN_NAME}`, supervised: false,
+        note: serviceStatus("win32").note,
+      };
+    } catch (e) { return { ok: false, error: e.message }; }
+  }
+
+  return { ok: false, error: `service installation not supported on platform: ${platform}` };
+}
+
+/** Idempotent: uninstalling something that was never installed is not an error. */
+export function uninstallService(platform = process.platform) {
+  if (platform === "darwin") {
+    if (!fs.existsSync(MAC_PLIST_PATH)) return { ok: true, removed: false };
+    try {
+      try { execFileSync("launchctl", ["unload", "-w", MAC_PLIST_PATH], { stdio: "ignore" }); } catch { /* not loaded */ }
+      fs.unlinkSync(MAC_PLIST_PATH);
+      return { ok: true, removed: true, path: MAC_PLIST_PATH };
+    } catch (e) { return { ok: false, error: e.message }; }
+  }
+
+  if (platform === "linux") {
+    if (!fs.existsSync(LINUX_UNIT_PATH)) return { ok: true, removed: false };
+    try {
+      try {
+        execFileSync("systemctl", ["--user", "disable", "--now", "apx-daemon.service"], { stdio: "ignore" });
+      } catch { /* already stopped */ }
+      fs.unlinkSync(LINUX_UNIT_PATH);
+      try { execFileSync("systemctl", ["--user", "daemon-reload"], { stdio: "ignore" }); } catch { /* best effort */ }
+      return { ok: true, removed: true, path: LINUX_UNIT_PATH };
+    } catch (e) { return { ok: false, error: e.message }; }
+  }
+
+  if (platform === "win32") {
+    try {
+      execFileSync("reg", ["delete", WIN_RUN_KEY, "/v", WIN_RUN_NAME, "/f"], { stdio: "ignore" });
+      return { ok: true, removed: true, path: `${WIN_RUN_KEY}\\${WIN_RUN_NAME}` };
+    } catch {
+      return { ok: true, removed: false };
+    }
+  }
+
+  return { ok: false, error: `service removal not supported on platform: ${platform}` };
+}