arisa 5.1.2 → 5.1.8

package/src/runtime/slave-service.js

@@ -0,0 +1,225 @@
+import { spawn } from "node:child_process";
+import { access, mkdir, open, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+export const slaveServiceName = "arisa-slave.service";
+
+function exists(target) {
+  return access(target).then(() => true, () => false);
+}
+
+function requireAccountName(value) {
+  const name = String(value || "").trim();
+  if (!/^[a-z_][a-z0-9_-]*[$]?$/i.test(name)) throw new Error(`Invalid service account: ${name || "empty"}`);
+  return name;
+}
+
+export function resolveSlaveHome({ environment = process.env, euid = process.geteuid?.(), homedir = os.homedir() } = {}) {
+  if (environment.ARISA_SLAVE_HOME) return path.resolve(environment.ARISA_SLAVE_HOME);
+  return euid === 0 ? "/var/lib/arisa-slave" : path.join(homedir, ".arisa-slave");
+}
+
+export function getSlavePaths(slaveHome) {
+  const home = path.resolve(slaveHome);
+  const state = path.join(home, "state");
+  return {
+    home,
+    state,
+    configFile: path.join(state, "config.json"),
+    descriptorFile: path.join(state, "service.json"),
+    pidFile: path.join(state, "arisa-slave.pid"),
+    logFile: path.join(state, "arisa-slave.log"),
+    ipcSocket: process.platform === "win32" ? null : path.join(state, "arisa.sock"),
+    toolsDir: path.join(home, "tools"),
+    tmpDir: path.join(state, "tmp")
+  };
+}
+
+export async function selectSlaveServiceAccount({
+  euid = process.geteuid?.(),
+  currentUser = os.userInfo().username,
+  ask
+} = {}) {
+  if (euid !== 0) {
+    return { scope: "user", user: requireAccountName(currentUser), root: false, dedicated: false };
+  }
+  if (typeof ask !== "function") throw new Error("Running Arisa Slave as UID 0 requires an explicit account selection");
+  const choice = String(await ask([
+    "Run Arisa Slave as:",
+    "1. dedicated user arisa-slave (recommended)",
+    "2. another existing user",
+    "3. root",
+    "Selection"
+  ].join("\n"))).trim();
+  if (choice === "1") return { scope: "system", user: "arisa-slave", root: false, dedicated: true };
+  if (choice === "2") {
+    return { scope: "system", user: requireAccountName(await ask("Existing service user")), root: false, dedicated: false };
+  }
+  if (choice === "3") {
+    const confirmation = String(await ask("Type RUN AS ROOT to confirm full root authority")).trim();
+    if (confirmation !== "RUN AS ROOT") throw new Error("Root execution was not confirmed");
+    return { scope: "system", user: "root", root: true, dedicated: false };
+  }
+  throw new Error("Invalid Arisa Slave service account selection");
+}
+
+function quoteSystemd(value) {
+  return `"${String(value).replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}
+
+export function buildSlaveSystemdUnit({ account, slaveHome, entryFile, nodePath = process.execPath }) {
+  if (!account?.scope || !account?.user) throw new Error("Slave systemd unit requires a service account");
+  if (typeof entryFile !== "string" || !path.isAbsolute(entryFile)) throw new Error("Slave systemd unit requires an absolute Arisa entry file");
+  const paths = getSlavePaths(slaveHome);
+  const userDirective = account.scope === "system" ? `User=${account.user}\n` : "";
+  return [
+    "[Unit]",
+    "Description=Arisa Slave headless host",
+    "After=network-online.target",
+    "Wants=network-online.target",
+    "",
+    "[Service]",
+    "Type=simple",
+    userDirective.trimEnd(),
+    `Environment=${quoteSystemd(`ARISA_HOME=${paths.home}`)}`,
+    `Environment=${quoteSystemd(`ARISA_SLAVE_HOME=${paths.home}`)}`,
+    `WorkingDirectory=${quoteSystemd(paths.home)}`,
+    `ExecStart=${quoteSystemd(nodePath)} ${quoteSystemd(entryFile)} slave --service-runner`,
+    `StandardOutput=append:${paths.logFile}`,
+    `StandardError=append:${paths.logFile}`,
+    "Restart=on-failure",
+    "RestartSec=2",
+    "",
+    "[Install]",
+    account.scope === "system" ? "WantedBy=multi-user.target" : "WantedBy=default.target",
+    ""
+  ].filter((line, index, lines) => line || lines[index - 1] !== "").join("\n");
+}
+
+export function runCommand(command, args, { cwd, env = process.env } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => { stdout += chunk.toString("utf8"); });
+    child.stderr.on("data", (chunk) => { stderr += chunk.toString("utf8"); });
+    child.once("error", reject);
+    child.once("close", (code, signal) => {
+      if (code === 0) resolve({ stdout, stderr });
+      else reject(new Error(`${command} failed (${signal || code}): ${(stderr || stdout).trim().slice(-1000)}`));
+    });
+  });
+}
+
+async function ensureSystemAccount(account, execute) {
+  if (account.scope !== "system" || account.user === "root") return "root";
+  try {
+    await execute("id", ["-u", account.user]);
+  } catch (error) {
+    if (!account.dedicated) throw new Error(`Service user does not exist: ${account.user}`, { cause: error });
+    await execute("useradd", ["--system", "--home-dir", "/var/lib/arisa-slave", "--create-home", "--shell", "/usr/sbin/nologin", account.user]);
+  }
+  return (await execute("id", ["-gn", account.user])).stdout.trim();
+}
+
+export async function installSlaveSystemdService({
+  account,
+  slaveHome,
+  entryFile,
+  execute = runCommand,
+  environment = process.env,
+  platform = process.platform,
+  systemUnitDir = "/etc/systemd/system",
+  userUnitDir = path.join(os.homedir(), ".config", "systemd", "user")
+}) {
+  if (platform !== "linux") throw new Error("Arisa Slave service installation currently requires Linux with systemd");
+  const accountGroup = await ensureSystemAccount(account, execute);
+  const paths = getSlavePaths(slaveHome);
+  if (account.scope === "system") {
+    await execute("install", ["-d", "-m", "0700", "-o", account.user, "-g", accountGroup, paths.home]);
+  } else {
+    await mkdir(paths.state, { recursive: true, mode: 0o700 });
+  }
+  const unitDir = account.scope === "system"
+    ? systemUnitDir
+    : userUnitDir;
+  await mkdir(unitDir, { recursive: true });
+  const unitFile = path.join(unitDir, slaveServiceName);
+  await writeFile(unitFile, buildSlaveSystemdUnit({ account, slaveHome: paths.home, entryFile }), { mode: 0o644 });
+  if (account.scope === "system") {
+    await execute("chown", ["-R", `${account.user}:${accountGroup}`, paths.home]);
+  }
+  const systemctlArgs = account.scope === "user" ? ["--user"] : [];
+  await execute("systemctl", [...systemctlArgs, "daemon-reload"], { env: environment });
+  await execute("systemctl", [...systemctlArgs, "enable", "--now", slaveServiceName], { env: environment });
+  return { unitFile, serviceName: slaveServiceName, account, paths };
+}
+
+export async function writeSlaveServiceDescriptor(paths, descriptor) {
+  await mkdir(paths.state, { recursive: true, mode: 0o700 });
+  await writeFile(paths.descriptorFile, `${JSON.stringify(descriptor, null, 2)}\n`, { mode: 0o600 });
+}
+
+export async function readSlaveServiceDescriptor(paths) {
+  try {
+    return JSON.parse(await readFile(paths.descriptorFile, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") throw new Error("Arisa Slave service is not installed");
+    throw error;
+  }
+}
+
+export async function controlSlaveService(paths, operation, { execute = runCommand } = {}) {
+  const descriptor = await readSlaveServiceDescriptor(paths);
+  const prefix = descriptor.account?.scope === "user" ? ["--user"] : [];
+  if (operation === "status") {
+    try {
+      const result = await execute("systemctl", [...prefix, "is-active", slaveServiceName]);
+      return { running: result.stdout.trim() === "active", status: result.stdout.trim() };
+    } catch {
+      return { running: false, status: "inactive" };
+    }
+  }
+  if (!["start", "stop", "restart"].includes(operation)) throw new Error(`Unsupported Slave service operation: ${operation}`);
+  await execute("systemctl", [...prefix, operation, slaveServiceName]);
+  return { ok: true, operation };
+}
+
+export async function registerSlaveServiceProcess(paths) {
+  await mkdir(paths.state, { recursive: true, mode: 0o700 });
+  let registeredPid = null;
+  try {
+    registeredPid = Number.parseInt((await readFile(paths.pidFile, "utf8")).trim(), 10);
+  } catch {}
+  if (Number.isSafeInteger(registeredPid) && registeredPid > 0 && registeredPid !== process.pid) {
+    try {
+      process.kill(registeredPid, 0);
+      throw new Error(`Arisa Slave is already running (pid ${registeredPid})`);
+    } catch (error) {
+      if (error?.code !== "ESRCH") throw error;
+    }
+  }
+  const handle = await open(paths.pidFile, "w", 0o600);
+  try {
+    await handle.writeFile(`${process.pid}\n`, "utf8");
+  } finally {
+    await handle.close();
+  }
+}
+
+export async function unregisterSlaveServiceProcess(paths) {
+  try {
+    const registeredPid = Number.parseInt((await readFile(paths.pidFile, "utf8")).trim(), 10);
+    if (registeredPid !== process.pid) return false;
+    await rm(paths.pidFile, { force: true });
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+export async function isSlaveToolInstalled(paths, toolName = "master-slave") {
+  return exists(path.join(paths.toolsDir, toolName, "tool.manifest.json"));
+}

package/src/runtime/tool-usage-report.js

@@ -1,10 +1,18 @@
-import { renderTextReport, reportRow } from "./report-format.js";
+import { renderTextReport } from "./report-format.js";
 
 export function formatToolUsageReport(tools) {
   const lines = ["Arisa tools", "===========", "Usage count"];
   if (!tools.length) lines.push("  (none installed)");
-  for (const tool of tools) {
-    lines.push(...reportRow(tool.name, tool.count, { labelWidth: 24 }));
+
+  const sortedTools = [...tools].sort((left, right) =>
+    Number(right.count) - Number(left.count) || String(left.name).localeCompare(String(right.name))
+  );
+  const nameWidth = Math.max(0, ...sortedTools.map((tool) => String(tool.name).length));
+  const countWidth = Math.max(1, ...sortedTools.map((tool) => String(tool.count).length));
+  for (const tool of sortedTools) {
+    const name = String(tool.name).padEnd(nameWidth);
+    const count = String(tool.count).padStart(countWidth);
+    lines.push(`- ${name}  ${count}`);
   }
   return renderTextReport(lines);
 }

package/src/transport/telegram/bot.js

@@ -15,6 +15,7 @@ import { formatPortableSessionHistory } from "../../core/agent/agent-manager.js"
 import { ConversationHistoryStore } from "../../core/conversation/conversation-history-store.js";
 import { formatDoctorReport } from "../../runtime/doctor.js";
 import { formatToolUsageReport } from "../../runtime/tool-usage-report.js";
+import { ToolResourceNoteStore } from "../../core/tools/tool-resource-note-store.js";
 
 const slowPromptNoticeMs = 300_000;
 
@@ -220,12 +221,31 @@ function buildNewSessionPrompt(ctx) {
   ].join("\n");
 }
 
-async function buildAsyncTaskPrompt({ task, artifactStore, toolRegistry, logger }) {
+export function isScheduledTaskPrompt(prompt) {
+  return String(prompt || "").startsWith("Scheduled task fired.\n");
+}
+
+export async function withPromptSpeed({ speedController, speed, restoreSpeed }, work) {
+  if (!speedController || speed === undefined) return work();
+  speedController.setSpeed(speed);
+  try {
+    return await work();
+  } finally {
+    speedController.setSpeed(restoreSpeed());
+  }
+}
+
+export async function buildAsyncTaskPrompt({ task, artifactStore, toolRegistry, resourceNotes, logger }) {
   const taskText = task.payload.prompt || "";
+  const resourceId = String(task.source?.resourceId || task.payload?.resourceId || "").trim();
+  const resourceNote = resourceId && task.source?.toolName
+    ? await resourceNotes.get(task.payload.chatId, task.source.toolName, resourceId)
+    : "";
   const parts = [
     "Scheduled task fired.",
     `taskId: ${task.id}`,
     `chatId: ${task.payload.chatId}`,
+    resourceNote ? `resourceNote: ${resourceNote}` : null,
     taskText ? `text: ${taskText}` : null
   ];
 
@@ -268,11 +288,16 @@ async function buildAsyncTaskPrompt({ task, artifactStore, toolRegistry, logger
   return parts.filter(Boolean).join("\n");
 }
 
-function buildAsyncEventPrompt(task) {
+async function buildAsyncEventPrompt(task, resourceNotes) {
+  const resourceId = String(task.source?.resourceId || task.payload?.resourceId || "").trim();
+  const resourceNote = resourceId && task.source?.toolName
+    ? await resourceNotes.get(task.payload.chatId, task.source.toolName, resourceId)
+    : "";
   return [
     "External event arrived.",
     `taskId: ${task.id}`,
     `chatId: ${task.payload.chatId}`,
+    resourceNote ? `resourceNote: ${resourceNote}` : null,
     task.payload.prompt ? `event: ${task.payload.prompt}` : null,
     "A polling checker detected this external event. Evaluate it and decide the next action.",
     "If it warrants no action, you may stay silent.",
@@ -544,6 +569,7 @@ export async function closeModelPicker(ctx, { messageText, callbackText }) {
 }
 
 export async function createTelegramBot({ config, artifactStore, toolRegistry, taskStore, agentManager, saveConfig, updateConfig, doctor, checkUpdates, requestRestart, logger }) {
+  const resourceNotes = new ToolResourceNoteStore();
   const bot = new Bot(config.telegram.token);
   const perChatState = createChatStateStore();
   const conversationHistory = new ConversationHistoryStore();
@@ -916,7 +942,7 @@ export async function createTelegramBot({ config, artifactStore, toolRegistry, t
 
   async function processPromptForChat({ chatId, prompt, ctx = null }) {
     const work = async () => {
-      const { session } = await agentManager.getSessionContext(chatId, createTelegramSessionBridge(chatId));
+      const { session, speedController } = await agentManager.getSessionContext(chatId, createTelegramSessionBridge(chatId));
       const historyRevision = getChatState(chatId).historyRevision;
       await conversationHistory.ensureSeed(chatId, {
         runtime: "pi",
@@ -928,14 +954,18 @@ export async function createTelegramBot({ config, artifactStore, toolRegistry, t
       chatState.activeSession = session;
       chatState.activeSteers = [];
       try {
-        text = await collectText(session, prompt, {
+        text = await withPromptSpeed({
+          speedController,
+          speed: isScheduledTaskPrompt(prompt) ? 1 : undefined,
+          restoreSpeed: () => clampModelSpeed(session.model, resolveChatSpeed(config, chatId))
+        }, () => collectText(session, prompt, {
           logger,
           chatId,
           onSlowPrompt: () => bot.api.sendMessage(
             chatId,
             "This is taking longer than 5 minutes, so I will keep the current session running instead of starting over. Send /new if you want to abandon it and start fresh."
           )
-        });
+        }));
       } catch (error) {
         agentManager.resetSession(chatId);
         throw error;
@@ -1082,7 +1112,7 @@ export async function createTelegramBot({ config, artifactStore, toolRegistry, t
       logger?.log("tasks", `running task ${task.id} for chat ${chatId}`);
       await enqueuePrompt({
         chatId,
-        prompt: await buildAsyncTaskPrompt({ task, artifactStore, toolRegistry, logger }),
+        prompt: await buildAsyncTaskPrompt({ task, artifactStore, toolRegistry, resourceNotes, logger }),
         label: `scheduled task ${task.id}`
       });
       await taskStore.complete(task.id);
@@ -1093,7 +1123,7 @@ export async function createTelegramBot({ config, artifactStore, toolRegistry, t
       logger?.log("tasks", `agent event ${task.id} for chat ${chatId}`);
       await enqueuePrompt({
         chatId,
-        prompt: buildAsyncEventPrompt(task),
+        prompt: await buildAsyncEventPrompt(task, resourceNotes),
         label: `agent event ${task.id}`
       });
       await taskStore.complete(task.id);

package/test/capabilities-security.test.js

@@ -238,6 +238,35 @@ test("rejects missing artifact input before running a tool", async () => {
   assert.equal(calls.length, 0);
 });
 
+test("requires exact confirmation before installing a bundled official tool", async () => {
+  const calls = [];
+  const toolRegistry = { load: async () => calls.push("reload") };
+  const capabilities = createArisaCapabilities({
+    artifactStore: createFakeArtifactStore(),
+    taskStore: createFakeTaskStore(),
+    toolRegistry,
+    installOfficialTool: async (name) => {
+      calls.push(name);
+      return { toolName: name, installed: true };
+    }
+  });
+
+  await assert.rejects(() => capabilities.dispatch({
+    method: "tools.installOfficial",
+    toolName: "master-slave",
+    params: { name: "fixture", confirmName: "other" }
+  }), /confirmName equal to name/);
+  assert.deepEqual(calls, []);
+
+  const result = await capabilities.dispatch({
+    method: "tools.installOfficial",
+    toolName: "master-slave",
+    params: { name: "fixture", confirmName: "fixture" }
+  });
+  assert.deepEqual(result, { toolName: "fixture", installed: true });
+  assert.deepEqual(calls, ["fixture", "reload"]);
+});
+
 test("normalizes list limits for artifact reads", async () => {
   const observedLimits = [];
   const artifactStore = {

package/test/daemon-catalog-conformance.test.js

@@ -10,7 +10,8 @@ const expected = {
   "whatsapp-web": { scope: "chat", autoStart: false },
   "roster-sites": { scope: "global", autoStart: true },
   "turn-server": { scope: "global", autoStart: true },
-  "signaling-server": { scope: "global", autoStart: true }
+  "signaling-server": { scope: "global", autoStart: true },
+  "master-slave": { scope: "global", autoStart: true, protocol: "arisa-daemon-v1" }
 };
 
 for (const [toolName, daemon] of Object.entries(expected)) {
@@ -22,6 +23,7 @@ for (const [toolName, daemon] of Object.entries(expected)) {
     assert.equal(manifest.daemon.scope, daemon.scope);
     assert.equal(manifest.daemon.autoStart, daemon.autoStart);
     assert.equal(manifest.daemon.health, "internal");
+    if (daemon.protocol) assert.equal(manifest.daemon.protocol, daemon.protocol);
     assert.match(source, /createDaemonRuntime/);
     assert.match(source, /healthCheck/);
   });

package/test/daemon-runtime.test.js

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { mkdtemp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
@@ -38,7 +38,8 @@ const {
   readJson,
   stopManagedDaemon,
   unregisterManagedDaemon,
-  writeDaemonStatus
+  writeDaemonStatus,
+  writeJson
 } = await import("../src/core/tools/daemon-processes.js");
 const {
   createDaemonRuntime,
@@ -101,6 +102,61 @@ test("runs health through the queue before accepting jobs", async () => {
   await runtime.stop();
 });
 
+test("streams ordered daemon events and persists the terminal result", async () => {
+  const runtime = runtimeFor({ type: "global" });
+  const events = [];
+  const output = await runtime.submit({ action: "stream", value: "done" }, {
+    timeoutMs: 1_000,
+    onEvent: (event) => events.push(event)
+  });
+
+  assert.deepEqual(output, { echo: "done" });
+  assert.deepEqual(events.map((event) => event.type), ["accepted", "progress", "chunk", "completed"]);
+  assert.deepEqual(events.map((event) => event.sequence), [1, 2, 3, 4]);
+  assert.ok((await readdir(runtime.paths.commandsDir)).some((file) => file.endsWith(".result.json")));
+  await runtime.stop();
+});
+
+test("deduplicates repeated notifications for one durable job id", async () => {
+  const runtime = runtimeFor({ type: "global" });
+  const jobId = "job-deduplicated";
+  const [first, second] = await Promise.all([
+    runtime.submit({ action: "count" }, { timeoutMs: 1_000, jobId }),
+    runtime.submit({ action: "count" }, { timeoutMs: 1_000, jobId })
+  ]);
+
+  assert.deepEqual(first, { count: 1 });
+  assert.deepEqual(second, { count: 1 });
+  assert.deepEqual(await readJson(path.join(runtime.paths.root, "effects.json"), {}), { count: 1 });
+  await runtime.stop();
+});
+
+test("recovers queued and accepted journal records after daemon start", async () => {
+  const runtime = runtimeFor({ type: "global" });
+  await runtime.ensure();
+  await writeJson(path.join(runtime.paths.commandsDir, "job-recovered.request.json"), {
+    id: "job-recovered",
+    status: "queued",
+    queuedAt: new Date().toISOString(),
+    payload: { value: "queued" }
+  });
+  await writeJson(path.join(runtime.paths.commandsDir, "job-accepted.processing.json"), {
+    id: "job-accepted",
+    status: "accepted",
+    queuedAt: new Date().toISOString(),
+    acceptedAt: new Date().toISOString(),
+    payload: { value: "accepted" }
+  });
+
+  const [queued, accepted] = await Promise.all([
+    runtime.submit({ value: "ignored" }, { timeoutMs: 1_000, jobId: "job-recovered" }),
+    runtime.submit({ value: "ignored" }, { timeoutMs: 1_000, jobId: "job-accepted" })
+  ]);
+  assert.deepEqual(queued, { echo: "queued" });
+  assert.deepEqual(accepted, { echo: "accepted" });
+  await runtime.stop();
+});
+
 test("isolates daemon process files and context by chat scope", async () => {
   const first = runtimeFor({ type: "chat", chatId: "101" });
   const second = runtimeFor({ type: "chat", chatId: "202" });

package/test/official-tool-installer.test.js

@@ -0,0 +1,107 @@
+import assert from "node:assert/strict";
+import crypto from "node:crypto";
+import { cp, mkdir, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import {
+  installBundledOfficialTool,
+  installLockedOfficialTool,
+  validateOfficialToolLock,
+  verifyOfficialToolTree
+} from "../src/core/tools/official-tool-installer.js";
+
+async function digest(file) {
+  return crypto.createHash("sha256").update(await readFile(file)).digest("hex");
+}
+
+async function fixture(t) {
+  const root = await mkdtemp(path.join(os.tmpdir(), "arisa-official-tool-"));
+  t.after(() => rm(root, { recursive: true, force: true }));
+  const source = path.join(root, "source", "tools", "master-slave");
+  await mkdir(source, { recursive: true });
+  await writeFile(path.join(source, "tool.manifest.json"), `${JSON.stringify({ name: "master-slave", entry: "index.js" })}\n`);
+  await writeFile(path.join(source, "index.js"), "process.stdout.write('ok');\n");
+  await mkdir(path.join(source, "lib"));
+  await writeFile(path.join(source, "lib", "helper.js"), "export {};\n");
+  const files = {
+    "index.js": await digest(path.join(source, "index.js")),
+    "lib/helper.js": await digest(path.join(source, "lib", "helper.js")),
+    "tool.manifest.json": await digest(path.join(source, "tool.manifest.json"))
+  };
+  return { root, source, files };
+}
+
+function lock(files) {
+  return {
+    version: 1,
+    repository: "https://github.com/clasen/Arisa.git",
+    commit: "a".repeat(40),
+    tools: { "master-slave": { files } }
+  };
+}
+
+test("requires immutable commits and exact SHA-256 entries", () => {
+  assert.throws(
+    () => validateOfficialToolLock({ ...lock({ "index.js": "f".repeat(64) }), commit: "main" }, "master-slave"),
+    /immutable 40-character commit/
+  );
+  assert.throws(
+    () => validateOfficialToolLock(lock({ "../index.js": "f".repeat(64) }), "master-slave"),
+    /Invalid official tool file path/
+  );
+});
+
+test("verifies the exact file set and digests", async (t) => {
+  const { source, files } = await fixture(t);
+  assert.deepEqual(await verifyOfficialToolTree(source, files), { files: 3 });
+  await writeFile(path.join(source, "extra.js"), "unexpected\n");
+  await assert.rejects(() => verifyOfficialToolTree(source, files), /unexpected=extra.js/);
+});
+
+test("rejects symbolic links before deployment", async (t) => {
+  const { source, files } = await fixture(t);
+  await symlink(path.join(source, "index.js"), path.join(source, "link.js"));
+  await assert.rejects(() => verifyOfficialToolTree(source, { ...files, "link.js": files["index.js"] }), /symbolic link/);
+});
+
+test("installs a verified staged tree without overwriting an existing tool", async (t) => {
+  const { root, source, files } = await fixture(t);
+  const destination = path.join(root, "installed", "master-slave");
+  const checkout = async ({ checkoutDir }) => {
+    await mkdir(path.join(checkoutDir, "tools"), { recursive: true });
+    await cp(source, path.join(checkoutDir, "tools", "master-slave"), { recursive: true });
+  };
+  const result = await installLockedOfficialTool({
+    toolName: "master-slave",
+    lock: lock(files),
+    destination,
+    scratchRoot: root,
+    checkout,
+    validate: async () => {}
+  });
+  assert.equal(result.commit, "a".repeat(40));
+  assert.equal(await readFile(path.join(destination, "index.js"), "utf8"), "process.stdout.write('ok');\n");
+  await assert.rejects(
+    () => installLockedOfficialTool({ toolName: "master-slave", lock: lock(files), destination, scratchRoot: root, checkout }),
+    /Refusing to overwrite/
+  );
+});
+
+test("loads the bundled lock before selecting the canonical tool destination", async (t) => {
+  const { root, files } = await fixture(t);
+  const lockFile = path.join(root, "official-tools.lock.json");
+  await writeFile(lockFile, `${JSON.stringify(lock(files))}\n`);
+  const calls = [];
+  const result = await installBundledOfficialTool("master-slave", {
+    lockFile,
+    install: async (request) => {
+      calls.push(request);
+      return { installed: true };
+    }
+  });
+  assert.deepEqual(result, { installed: true });
+  assert.equal(calls[0].toolName, "master-slave");
+  assert.deepEqual(calls[0].lock, lock(files));
+  assert.match(calls[0].destination, /tools\/master-slave$/);
+});

package/test/paths.test.js

@@ -50,20 +50,14 @@ test("keeps chat tool state and config paths scoped below the chat directory for
   );
 });
 
-test("documents current traversal behavior for unsanitized tool names", () => {
-  const expectedRoot = path.join(chatsDir, "chat-1", "state", "tools");
-  const traversed = getChatToolStateDir("chat-1", "../../evil");
-
-  assert.equal(path.resolve(traversed), path.join(chatsDir, "chat-1", "evil"));
-  assert.equal(path.resolve(traversed).startsWith(`${expectedRoot}${path.sep}`), false);
+test("rejects traversal and non-canonical chat tool names", () => {
+  assert.throws(() => getChatToolStateDir("chat-1", "../../evil"), /Invalid tool name/);
+  assert.throws(() => getChatToolConfigPath("chat-1", "Upper_Case"), /Invalid tool name/);
 });
 
-test("documents current traversal behavior for global tool state paths", () => {
-  const expectedRoot = path.join(stateDir, "tools");
-  const traversed = getToolStateDir("../../evil");
-
-  assert.equal(path.resolve(traversed), path.join(path.dirname(stateDir), "evil"));
-  assert.equal(path.resolve(traversed).startsWith(`${expectedRoot}${path.sep}`), false);
+test("rejects traversal and non-canonical global tool names", () => {
+  assert.throws(() => getToolStateDir("../../evil"), /Invalid tool name/);
+  assert.throws(() => getToolStateDir("-invalid"), /Invalid tool name/);
 });
 
 test("creates POSIX IPC socket paths under the state directory", () => {