arisa 5.1.2 → 5.1.8

package/src/runtime/arisa-capabilities.js

@@ -5,6 +5,8 @@ import {
   getToolStateDir,
   getToolTmpDir
 } from "./paths.js";
+import { ToolResourceNoteStore } from "../core/tools/tool-resource-note-store.js";
+import { installBundledOfficialTool } from "../core/tools/official-tool-installer.js";
 
 function requireToolName(toolName) {
   if (typeof toolName !== "string" || !toolName.trim()) {
@@ -41,7 +43,14 @@ function normalizeLimit(limit) {
   return Math.min(value, 100);
 }
 
-export function createArisaCapabilities({ artifactStore, taskStore, toolRegistry, agentManager } = {}) {
+export function createArisaCapabilities({
+  artifactStore,
+  taskStore,
+  toolRegistry,
+  agentManager,
+  resourceNotes = new ToolResourceNoteStore(),
+  installOfficialTool = installBundledOfficialTool
+} = {}) {
   async function dispatch({ method, toolName, chatId = null, params = {} } = {}) {
     const scopedToolName = requireToolName(toolName);
 
@@ -70,6 +79,25 @@ export function createArisaCapabilities({ artifactStore, taskStore, toolRegistry
       );
     }
 
+    if (method === "tools.setResourceNote") {
+      const scopedChatId = requireChatId(chatId, method);
+      return resourceNotes.set(
+        scopedChatId,
+        scopedToolName,
+        requireString(params.resourceId, "resourceId"),
+        String(params.note ?? "")
+      );
+    }
+
+    if (method === "tools.getResourceNote") {
+      const scopedChatId = requireChatId(chatId, method);
+      return {
+        toolName: scopedToolName,
+        resourceId: requireString(params.resourceId, "resourceId"),
+        note: await resourceNotes.get(scopedChatId, scopedToolName, params.resourceId)
+      };
+    }
+
     if (method === "tools.run") {
       if (!agentManager?.runTool) {
         throw new Error("tools.run requires agentManager");
@@ -89,12 +117,23 @@ export function createArisaCapabilities({ artifactStore, taskStore, toolRegistry
         request: {
           artifact,
           text: params.text,
+          resourceId: params.resourceId,
           args: normalizeArgs(params.args)
         },
         chatId: scopedChatId
       });
     }
 
+    if (method === "tools.installOfficial") {
+      const name = requireString(params.name, "name");
+      if (params.confirmName !== name) {
+        throw new Error("tools.installOfficial requires confirmName equal to name");
+      }
+      const installed = await installOfficialTool(name);
+      await toolRegistry.load();
+      return installed;
+    }
+
     if (method === "artifacts.createText") {
       const scopedChatId = requireChatId(chatId, method);
       return artifactStore.forChat(scopedChatId).createText({
@@ -164,12 +203,13 @@ export function createArisaCapabilities({ artifactStore, taskStore, toolRegistry
 
     if (method === "agent.enqueueEvent") {
       const scopedChatId = requireChatId(chatId, method);
+      const resourceId = String(params.resourceId || "").trim();
       return taskStore.add({
         kind: "agent_event",
-        payload: { prompt: requireString(params.prompt, "prompt") }
+        payload: { prompt: requireString(params.prompt, "prompt"), resourceId }
       }, {
         payload: { chatId: scopedChatId },
-        source: { type: "tool", toolName: scopedToolName, chatId: scopedChatId }
+        source: { type: "tool", toolName: scopedToolName, chatId: scopedChatId, resourceId }
       });
     }
 

package/src/runtime/create-app.js

@@ -135,6 +135,15 @@ export async function createApp({ logger, runtimeOverrides, requestRestart } = {
       toolProcessSupervisor,
       daemonPolicy: config.daemons,
       doctorPolicy: config.doctor,
+      inspectInfrastructure: async () => {
+        const tool = toolRegistry.get("master-slave");
+        if (!tool) return null;
+        const result = await toolRegistry.run({
+          name: "master-slave",
+          request: { args: { action: "master.status" } }
+        });
+        return result.ok ? result.output?.json || null : { error: result.error };
+      },
       logger
     }),
     checkUpdates: async (chatId) => formatUpdateReport(await checkForUpdates({ chatId, toolRegistry })),

package/src/runtime/create-headless-app.js

@@ -0,0 +1,77 @@
+import { ArtifactStore } from "../core/artifacts/artifact-store.js";
+import { loadConfig } from "../core/config/config-store.js";
+import { TaskStore } from "../core/tasks/task-store.js";
+import { ToolRegistry } from "../core/tools/tool-registry.js";
+import { createDaemonRuntime } from "../core/tools/daemon-runtime.js";
+import { createArisaCapabilities } from "./arisa-capabilities.js";
+import { createHeadlessToolExecutor } from "./headless-tool-executor.js";
+import { createIpcServer } from "./ipc/ipc-server.js";
+import { createToolProcessSupervisor } from "./tool-process-supervisor.js";
+
+export async function createHeadlessApp({
+  logger,
+  configLoader = loadConfig,
+  artifactStoreFactory = () => new ArtifactStore(),
+  taskStoreFactory = () => new TaskStore(),
+  toolRegistryFactory = () => new ToolRegistry({ logger }),
+  supervisorFactory = (options) => createToolProcessSupervisor(options),
+  capabilitiesFactory = (options) => createArisaCapabilities(options),
+  ipcServerFactory = (options) => createIpcServer(options)
+} = {}) {
+  logger?.log("app", "loading headless config");
+  const config = await configLoader();
+  const artifactStore = artifactStoreFactory();
+  const taskStore = taskStoreFactory();
+  const toolRegistry = toolRegistryFactory();
+  await toolRegistry.load();
+  const toolProcessSupervisor = supervisorFactory({ logger, policy: config.daemons, toolRegistry });
+  const toolExecutor = createHeadlessToolExecutor({ artifactStore, taskStore, toolRegistry });
+  const capabilities = capabilitiesFactory({
+    artifactStore,
+    taskStore,
+    toolRegistry,
+    agentManager: toolExecutor
+  });
+  const ipcServer = ipcServerFactory({ capabilities, logger });
+  const autoStartedDaemons = [];
+
+  async function startGlobalDaemons() {
+    for (const listed of toolRegistry.list()) {
+      const tool = toolRegistry.get(listed.name);
+      if (!tool?.daemon?.autoStart || tool.daemon.scope === "chat") continue;
+      const runtime = createDaemonRuntime({
+        toolName: tool.name,
+        entryPath: tool.entry,
+        scope: { type: "global" },
+        autoStart: true
+      });
+      await runtime.start();
+      autoStartedDaemons.push(runtime);
+    }
+  }
+
+  return {
+    toolRegistry,
+    toolProcessSupervisor,
+    ipcServer,
+    async start() {
+      let ipcStarted = false;
+      try {
+        await ipcServer.start();
+        ipcStarted = true;
+        await taskStore.recoverInterrupted();
+        await startGlobalDaemons();
+        await toolProcessSupervisor.start();
+        logger?.log("app", "Arisa Slave headless host started");
+      } catch (error) {
+        if (ipcStarted) await ipcServer.stop();
+        throw error;
+      }
+    },
+    async stop() {
+      await toolProcessSupervisor.stop();
+      await Promise.allSettled(autoStartedDaemons.splice(0).map((runtime) => runtime.stop()));
+      await ipcServer.stop();
+    }
+  };
+}

package/src/runtime/doctor.js

@@ -224,6 +224,21 @@ export function formatDoctorReport(report) {
   lines.push("", "Daemons");
   lines.push(...reportRow("Checked", report.daemons.length));
   if (report.daemons.length) lines.push(...reportRow("Status", daemonResultSummary(report.daemons)));
+  if (report.infrastructure) {
+    lines.push("", "Master/Slave");
+    if (report.infrastructure.error) {
+      lines.push(...reportRow("Status", `unavailable: ${report.infrastructure.error}`));
+    } else {
+      lines.push(...reportRow("Role", report.infrastructure.role || "unknown"));
+      lines.push(...reportRow("Daemon", report.infrastructure.daemon?.state || "unknown"));
+      lines.push(...reportRow("Endpoint", report.infrastructure.endpoint || "not configured"));
+      lines.push(...reportRow("Identity", report.infrastructure.identityFingerprint || "not configured"));
+      lines.push(...reportRow("Paired", report.infrastructure.paired == null ? "n/a" : report.infrastructure.paired ? "yes" : "no"));
+      lines.push(...reportRow("Tools", report.infrastructure.toolCount ?? "unknown"));
+      lines.push(...reportRow("Jobs", `active=${report.infrastructure.jobs?.active ?? "unknown"}, queued=${report.infrastructure.jobs?.queued ?? "unknown"}, failed=${report.infrastructure.jobs?.failed ?? "unknown"}`));
+      lines.push(...reportRow("Pending secrets", report.infrastructure.pendingSecrets ?? "unknown"));
+    }
+  }
   if (report.system) {
     const memoryPercent = report.system.memoryTotal ? (report.system.memoryUsed / report.system.memoryTotal) * 100 : 0;
     const diskPercent = report.system.diskTotal ? (report.system.diskUsed / report.system.diskTotal) * 100 : 0;
@@ -257,7 +272,8 @@ export async function runDoctor({
   serviceStatus = getServiceStatus,
   stopDaemon = stopManagedDaemon,
   unregisterDaemon = unregisterManagedDaemon,
-  inspectResources = inspectSystemResources
+  inspectResources = inspectSystemResources,
+  inspectInfrastructure = null
 }) {
   assertDoctorPolicy(doctorPolicy);
   const runtime = await agentManager.getRuntimeDiagnostic({
@@ -270,9 +286,18 @@ export async function runDoctor({
     repairs: [],
     attention: [],
     system: null,
-    systemError: null
+    systemError: null,
+    infrastructure: null
   };
   addContextAttention(report);
+  if (inspectInfrastructure) {
+    try {
+      report.infrastructure = await inspectInfrastructure();
+    } catch (error) {
+      report.infrastructure = { error: error?.message || String(error) };
+      report.attention.push(`Master/Slave inspection failed: ${report.infrastructure.error}`);
+    }
+  }
   try {
     report.system = await inspectResources();
   } catch (error) {

package/src/runtime/headless-tool-executor.js

@@ -0,0 +1,45 @@
+import path from "node:path";
+import { unlink } from "node:fs/promises";
+
+export function createHeadlessToolExecutor({ artifactStore, taskStore, toolRegistry } = {}) {
+  if (!artifactStore || !taskStore || !toolRegistry) {
+    throw new Error("Headless tool executor requires artifact, task, and tool stores");
+  }
+
+  return {
+    async runTool({ name, request, chatId }) {
+      await toolRegistry.load();
+      const result = await toolRegistry.run({ name, request, chatId });
+      const chatArtifacts = artifactStore.forChat(chatId);
+
+      if (result.output?.text) {
+        const artifact = await chatArtifacts.createText({
+          text: result.output.text,
+          source: { type: "tool", toolName: name },
+          metadata: { tool: name }
+        });
+        result.output.artifactId = artifact.id;
+      }
+      if (result.output?.filePath) {
+        const generated = await chatArtifacts.createFromFile({
+          originalPath: result.output.filePath,
+          fileName: result.output.fileName || path.basename(result.output.filePath),
+          kind: result.output.kind || "file",
+          mimeType: result.output.mimeType || "application/octet-stream",
+          source: { type: "tool", toolName: name },
+          metadata: { tool: name, delivery: result.output.delivery }
+        });
+        result.output.artifactId = generated.id;
+        await unlink(result.output.filePath).catch(() => {});
+      }
+      if (result.asyncTask || result.asyncTasks?.length) {
+        result.asyncTasks = await taskStore.addMany(result.asyncTasks || [result.asyncTask], {
+          payload: { chatId },
+          source: { type: "tool", toolName: name, chatId }
+        });
+        delete result.asyncTask;
+      }
+      return result;
+    }
+  };
+}

package/src/runtime/paths.js

@@ -27,6 +27,14 @@ export const toolsDir = path.join(arisaHomeDir, "tools");
 export const chatsDir = path.join(arisaHomeDir, "chats");
 export const toolStateDir = path.join(stateDir, "tools");
 
+export function requireToolName(toolName) {
+  const name = String(toolName ?? "");
+  if (!/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(name)) {
+    throw new Error(`Invalid tool name: ${name || "empty"}`);
+  }
+  return name;
+}
+
 export function getChatDir(chatId) {
   return path.join(chatsDir, String(chatId));
 }
@@ -47,8 +55,12 @@ export function getChatToolUsageFile(chatId) {
   return path.join(getChatDir(chatId), "state", "tool-usage.json");
 }
 
+export function getChatToolResourceNotesFile(chatId) {
+  return path.join(getChatDir(chatId), "state", "tool-resource-notes.json");
+}
+
 export function getChatToolStateDir(chatId, toolName) {
-  return path.join(getChatDir(chatId), "state", "tools", toolName);
+  return path.join(getChatDir(chatId), "state", "tools", requireToolName(toolName));
 }
 
 export function normalizeDaemonScope(scope = { type: "global" }) {
@@ -91,7 +103,7 @@ export function getChatPiSessionsDir(chatId, sessionRevision = 0) {
 }
 
 export function getToolDir(toolName) {
-  return path.join(toolsDir, toolName);
+  return path.join(toolsDir, requireToolName(toolName));
 }
 
 export function getToolConfigPath(toolName) {
@@ -107,11 +119,11 @@ export function getChatTmpDir(chatId) {
 }
 
 export function getChatToolConfigPath(chatId, toolName) {
-  return path.join(getChatConfigDir(chatId), "tools", toolName, "config.js");
+  return path.join(getChatConfigDir(chatId), "tools", requireToolName(toolName), "config.js");
 }
 
 export function getToolStateDir(toolName) {
-  return path.join(toolStateDir, toolName);
+  return path.join(toolStateDir, requireToolName(toolName));
 }
 
 export function getToolTmpDir(toolName) {

package/src/runtime/secure-request-file.js

@@ -0,0 +1,21 @@
+import crypto from "node:crypto";
+import { chmod, mkdir, open, rm } from "node:fs/promises";
+import path from "node:path";
+
+export async function withSecureRequestFile({ directory, value, prefix = "request" }, useFile) {
+  if (typeof useFile !== "function") throw new Error("Secure request handoff requires a consumer");
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  await chmod(directory, 0o700);
+  const file = path.join(directory, `.${prefix}-${process.pid}-${crypto.randomUUID()}.json`);
+  const handle = await open(file, "wx", 0o600);
+  try {
+    await handle.writeFile(`${JSON.stringify(value)}\n`, "utf8");
+  } finally {
+    await handle.close();
+  }
+  try {
+    return await useFile(file);
+  } finally {
+    await rm(file, { force: true });
+  }
+}

package/src/runtime/slave-bootstrap-url.js

@@ -0,0 +1,51 @@
+import net from "node:net";
+
+const SECRET_PATTERN = /^arisa_secret_v1_[A-Za-z0-9_-]{43}$/;
+
+export function parseSlaveBootstrapUrl(value) {
+  if (typeof value !== "string" || !value) {
+    throw new Error("Arisa Slave requires one TCP bootstrap URL");
+  }
+  if (/\s/.test(value)) throw new Error("Slave bootstrap URL must not contain whitespace");
+  if (value.includes("?")) throw new Error("Slave bootstrap URL must not contain a query");
+  if (value.includes("#")) throw new Error("Slave bootstrap URL must not contain a fragment");
+
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error("Invalid Slave bootstrap URL");
+  }
+  if (parsed.protocol !== "tcp:") throw new Error("Slave bootstrap URL must use tcp");
+  if (parsed.username || parsed.password) throw new Error("Slave bootstrap URL must not contain user information");
+  if (parsed.search) throw new Error("Slave bootstrap URL must not contain a query");
+  if (parsed.hash) throw new Error("Slave bootstrap URL must not contain a fragment");
+  if (!parsed.port) throw new Error("Slave bootstrap URL requires an explicit port");
+
+  const authority = /^tcp:\/\/([^/]+)\//.exec(value)?.[1] || "";
+  const ipv6Authority = /^\[([^\]]+)]:(\d+)$/.exec(authority);
+  const ipv4Authority = /^([^:]+):(\d+)$/.exec(authority);
+  const bracketed = Boolean(ipv6Authority);
+  const host = ipv6Authority?.[1] || ipv4Authority?.[1] || "";
+  const ipVersion = net.isIP(host);
+  if (!ipVersion) throw new Error("Slave bootstrap URL requires an IPv4 or IPv6 literal");
+  if (ipVersion === 6 && !bracketed) throw new Error("IPv6 Slave bootstrap addresses must be bracketed");
+
+  const port = Number(parsed.port);
+  if (!Number.isSafeInteger(port) || port < 1 || port > 65_535) {
+    throw new Error("Slave bootstrap URL contains an invalid port");
+  }
+  const match = /^\/([^/]+)$/.exec(parsed.pathname);
+  if (!match) throw new Error("Slave bootstrap URL requires exactly one secret path segment");
+  const secret = match[1];
+  if (!SECRET_PATTERN.test(secret)) throw new Error("Slave bootstrap URL contains an invalid connection secret");
+
+  return {
+    endpoint: `tcp://${ipVersion === 6 ? `[${host}]` : host}:${port}`,
+    host,
+    ipVersion,
+    port,
+    secret,
+    url: value
+  };
+}

package/src/runtime/slave-cli.js

@@ -0,0 +1,267 @@
+import { spawn } from "node:child_process";
+import { access, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import readline from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { applyConfigDefaults } from "../core/config/config-defaults.js";
+import { installLockedOfficialTool } from "../core/tools/official-tool-installer.js";
+import { createHeadlessApp } from "./create-headless-app.js";
+import { arisaPackageDir } from "./paths.js";
+import { readPackageVersion, readRecentLogLines, followLogFile } from "./log-viewer.js";
+import { parseSlaveBootstrapUrl } from "./slave-bootstrap-url.js";
+import { withSecureRequestFile } from "./secure-request-file.js";
+import {
+  controlSlaveService,
+  getSlavePaths,
+  installSlaveSystemdService,
+  isSlaveToolInstalled,
+  readSlaveServiceDescriptor,
+  registerSlaveServiceProcess,
+  resolveSlaveHome,
+  selectSlaveServiceAccount,
+  unregisterSlaveServiceProcess,
+  writeSlaveServiceDescriptor
+} from "./slave-service.js";
+
+const toolName = "master-slave";
+const toolLockFile = new URL("../official-tools.lock.json", import.meta.url);
+
+function exists(target) {
+  return access(target).then(() => true, () => false);
+}
+
+function runProcess(command, args, { cwd, env } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+    let output = "";
+    let diagnostics = "";
+    child.stdout.on("data", (chunk) => { output += chunk.toString("utf8"); });
+    child.stderr.on("data", (chunk) => { diagnostics += chunk.toString("utf8"); });
+    child.once("error", reject);
+    child.once("close", (code, signal) => {
+      if (code === 0) resolve({ stdout: output, stderr: diagnostics });
+      else reject(new Error(`master-slave command failed (${signal || code}): ${diagnostics.trim().slice(-1000)}`));
+    });
+  });
+}
+
+export async function ensureSlaveConfig(paths) {
+  await mkdir(paths.state, { recursive: true, mode: 0o700 });
+  await mkdir(paths.toolsDir, { recursive: true, mode: 0o700 });
+  if (await exists(paths.configFile)) return { created: false, configFile: paths.configFile };
+  const config = applyConfigDefaults({ role: "slave", createdAt: new Date().toISOString() });
+  await writeFile(paths.configFile, `${JSON.stringify(config, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+  return { created: true, configFile: paths.configFile };
+}
+
+export async function ensureMasterSlaveTool(paths, {
+  install = installLockedOfficialTool,
+  readLock = async () => JSON.parse(await readFile(toolLockFile, "utf8"))
+} = {}) {
+  if (await isSlaveToolInstalled(paths, toolName)) return { installed: false };
+  let lock;
+  try {
+    lock = await readLock();
+  } catch (error) {
+    throw new Error("This Arisa build does not include the verified master-slave tool lock", { cause: error });
+  }
+  const result = await install({
+    toolName,
+    lock,
+    destination: path.join(paths.toolsDir, toolName)
+  });
+  return { installed: true, ...result };
+}
+
+export async function invokeSlaveTool(paths, args, { run = runProcess } = {}) {
+  const toolDir = path.join(paths.toolsDir, toolName);
+  const manifest = JSON.parse(await readFile(path.join(toolDir, "tool.manifest.json"), "utf8"));
+  const entry = path.join(toolDir, manifest.entry || "index.js");
+  return withSecureRequestFile({
+    directory: paths.tmpDir,
+    prefix: "tool-request",
+    value: { args }
+  }, async (requestFile) => {
+    const result = await run(process.execPath, [entry, "run", "--request-file", requestFile], {
+      cwd: toolDir,
+      env: {
+        ...process.env,
+        ARISA_HOME: paths.home,
+        ARISA_SLAVE_HOME: paths.home,
+        ARISA_PACKAGE_DIR: arisaPackageDir,
+        ARISA_IPC_SOCKET: paths.ipcSocket || ""
+      }
+    });
+    const text = result.stdout.trim();
+    if (!text) throw new Error("master-slave returned no response");
+    const parsed = JSON.parse(text);
+    if (parsed.ok === false) throw new Error(parsed.error || "master-slave request failed");
+    return parsed;
+  });
+}
+
+async function askFromTerminal(prompt) {
+  const terminal = readline.createInterface({ input: stdin, output: stdout });
+  try {
+    return await terminal.question(`${prompt}: `);
+  } finally {
+    terminal.close();
+  }
+}
+
+async function listSlaveTools(paths) {
+  const entries = await readdir(paths.toolsDir, { withFileTypes: true }).catch(() => []);
+  const tools = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    try {
+      const manifest = JSON.parse(await readFile(path.join(paths.toolsDir, entry.name, "tool.manifest.json"), "utf8"));
+      tools.push({ name: manifest.name, description: manifest.description || "" });
+    } catch {}
+  }
+  return tools.sort((left, right) => left.name.localeCompare(right.name));
+}
+
+async function showSlaveLogs(paths, { follow, output = process.stdout, signal } = {}) {
+  const version = await readPackageVersion();
+  const snapshot = await readRecentLogLines(paths.logFile, 100);
+  output.write(`Arisa Slave v${version} | Recent logs\n`);
+  output.write(`${follow ? "Following new logs; press Ctrl+C to exit." : "Log follow disabled."}\n\n`);
+  if (snapshot.text) output.write(`${snapshot.text}${snapshot.endsWithNewline ? "\n" : ""}`);
+  else output.write("No logs yet.\n");
+  if (!follow) return;
+  await followLogFile({
+    logFile: paths.logFile,
+    initialSize: snapshot.size,
+    initialIno: snapshot.ino,
+    write: (content) => output.write(content),
+    signal
+  });
+}
+
+function parseSlaveToolOutput(result) {
+  if (result?.output?.json && typeof result.output.json === "object") return result.output.json;
+  if (typeof result?.output?.text === "string") {
+    try {
+      return JSON.parse(result.output.text);
+    } catch {}
+  }
+  return result?.output && typeof result.output === "object" ? result.output : result;
+}
+
+export function formatSlaveStatus({ systemd, diagnostic }) {
+  const jobs = diagnostic?.jobs && typeof diagnostic.jobs === "object" ? diagnostic.jobs : {};
+  return [
+    "Arisa Slave status",
+    `Systemd: ${systemd.running ? "active" : systemd.status || "inactive"}`,
+    `Daemon: ${diagnostic?.daemon?.state || diagnostic?.daemonState || "unknown"}`,
+    `Role: ${diagnostic?.role || "unknown"}`,
+    `Endpoint: ${diagnostic?.endpoint || "not configured"}`,
+    `Identity: ${diagnostic?.identityFingerprint || diagnostic?.identity || "not configured"}`,
+    `Paired: ${diagnostic?.paired === true ? "yes" : diagnostic?.paired === false ? "no" : "unknown"}`,
+    `Tools: ${Number.isSafeInteger(diagnostic?.toolCount) ? diagnostic.toolCount : "unknown"}`,
+    `Jobs: active=${jobs.active ?? "unknown"}, queued=${jobs.queued ?? "unknown"}, failed=${jobs.failed ?? "unknown"}`,
+    `Pending secrets: ${Number.isSafeInteger(diagnostic?.pendingSecrets) ? diagnostic.pendingSecrets : "unknown"}`
+  ].join("\n");
+}
+
+export async function runSlaveBootstrap(url, {
+  paths = getSlavePaths(resolveSlaveHome()),
+  ask = askFromTerminal,
+  selectAccount = selectSlaveServiceAccount,
+  ensureTool = ensureMasterSlaveTool,
+  installService = installSlaveSystemdService,
+  invokeTool = invokeSlaveTool,
+  entryFile,
+  output = console,
+  platform = process.platform
+} = {}) {
+  parseSlaveBootstrapUrl(url);
+  if (platform !== "linux") throw new Error("Arisa Slave service installation currently requires Linux with systemd");
+  const account = await selectAccount({ ask });
+  await ensureSlaveConfig(paths);
+  await ensureTool(paths);
+  const result = await withSecureRequestFile({
+    directory: paths.tmpDir,
+    prefix: "bootstrap",
+    value: { url }
+  }, (bootstrapFile) => invokeTool(paths, { action: "slave.bootstrap", bootstrapFile }));
+  await installService({ account, slaveHome: paths.home, entryFile });
+  await writeSlaveServiceDescriptor(paths, { version: 1, account, installedAt: new Date().toISOString() });
+  output.log(`Arisa Slave paired and running as ${account.user}${account.root ? " (root)" : ""}.`);
+  return result;
+}
+
+export async function runSlaveService({ paths = getSlavePaths(resolveSlaveHome()), logger } = {}) {
+  await ensureSlaveConfig(paths);
+  await registerSlaveServiceProcess(paths);
+  const app = await createHeadlessApp({ logger });
+  try {
+    await app.start();
+    return app;
+  } catch (error) {
+    await unregisterSlaveServiceProcess(paths);
+    throw error;
+  }
+}
+
+export async function runSlaveCli({
+  positionals = [],
+  flags = {},
+  logger,
+  entryFile,
+  output = console,
+  paths = getSlavePaths(resolveSlaveHome()),
+  controlService = controlSlaveService,
+  invokeTool = invokeSlaveTool,
+  toolInstalled = isSlaveToolInstalled
+} = {}) {
+  if (flags["service-runner"]) {
+    const app = await runSlaveService({ paths, logger });
+    return { serviceRunner: true, app, paths };
+  }
+
+  const action = positionals[0];
+  if (flags.help || action === "help") {
+    output.log("Usage: arisa slave <tcp://ip:port/secret> | start | stop | restart | status | log | tools | unpair");
+    return { help: true };
+  }
+  if (action?.startsWith("tcp://")) {
+    if (positionals.length !== 1) throw new Error("arisa slave accepts exactly one bootstrap URL");
+    return runSlaveBootstrap(action, { paths, entryFile, output });
+  }
+  if (["start", "stop", "restart"].includes(action)) {
+    if (positionals.length !== 1) throw new Error(`arisa slave ${action} does not accept additional arguments`);
+    const result = await controlService(paths, action);
+    output.log(`Arisa Slave ${action} requested.`);
+    return result;
+  }
+  if (action === "status") {
+    if (positionals.length !== 1) throw new Error("arisa slave status does not accept additional arguments");
+    const systemd = await controlService(paths, "status");
+    const diagnostic = await toolInstalled(paths, toolName)
+      ? parseSlaveToolOutput(await invokeTool(paths, { action: "slave.status" }))
+      : { daemonState: "not-installed", role: "slave", paired: false, toolCount: 0, pendingSecrets: 0 };
+    output.log(formatSlaveStatus({ systemd, diagnostic }));
+    return { systemd, diagnostic };
+  }
+  if (action === "log") {
+    if (positionals.length !== 1) throw new Error("arisa slave log does not accept additional arguments");
+    await showSlaveLogs(paths, { follow: !flags["no-follow"] });
+    return { ok: true };
+  }
+  if (action === "tools") {
+    if (positionals.length !== 1) throw new Error("arisa slave tools does not accept additional arguments");
+    const tools = await listSlaveTools(paths);
+    for (const tool of tools) output.log(`${tool.name}${tool.description ? ` — ${tool.description}` : ""}`);
+    return { tools };
+  }
+  if (action === "unpair") {
+    if (positionals.length !== 1) throw new Error("arisa slave unpair does not accept additional arguments");
+    await readSlaveServiceDescriptor(paths);
+    const result = await invokeTool(paths, { action: "slave.unpair" });
+    output.log("Arisa Slave unpaired. The local service remains installed and stopped from reconnecting.");
+    return result;
+  }
+  throw new Error("Usage: arisa slave <tcp://ip:port/secret> | start | stop | restart | status | log | tools | unpair");
+}