@realqiyan/agent-task 0.0.0-stage → 0.0.1-rc.1

package/scripts/install-lib.mjs

@@ -0,0 +1,191 @@
+import { spawnSync } from "node:child_process";
+import { DatabaseSync } from "node:sqlite";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, lstatSync, realpathSync, readdirSync, unlinkSync, rmdirSync, openSync, closeSync, fsyncSync, renameSync } from "node:fs";
+import { dirname, join, resolve, isAbsolute, basename } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { setTimeout as delay } from "node:timers/promises";
+
+export const packageRoot = realpathSync(fileURLToPath(new URL("..", import.meta.url)));
+
+export const label = "com.agent-task.service";
+export const unit = "agent-task.service";
+export const packages = {
+  pi: ["@earendil-works/pi-coding-agent@1.3.0", "pi-acp@0.0.34"],
+  codex: ["@agentclientprotocol/codex-acp@2.2.2"],
+  opencode: ["opencode-ai@1.19.3"],
+};
+export function argumentsFor(argv) {
+  const flags = new Set(["prepare-only", "service", "check", "probe", "resume", "help"]), options = {};
+  for (let i = 0; i < argv.length; i++) {
+    const key = argv[i].replace(/^--/, "");
+    if (!argv[i].startsWith("--") || key in options) throw new Error("Invalid or repeated option");
+    if (flags.has(key)) options[key] = true;
+    else if (["home", "executors", "cwd", "provider", "model", "port"].includes(key) && argv[i + 1] && !argv[i + 1].startsWith("--")) options[key] = argv[++i];
+    else throw new Error("Unknown option or missing value: " + key);
+  }
+  return options;
+}
+export function installRoot(options) {
+  if (!["linux", "darwin"].includes(process.platform)) throw new Error("Only Linux and macOS are supported");
+  const [major, minor] = process.versions.node.split(".").map(Number);
+  if (major < 22 || (major === 22 && minor < 19)) throw new Error("Node.js 22.19+ is required");
+  const path = options.home ?? join(homedir(), process.platform === "darwin" ? "Library/Application Support/agent-task" : ".local/share/agent-task");
+  if (!isAbsolute(path) || /[\x00-\x1f\x7f]/.test(path)) throw new Error("Installation home must be an absolute path without control characters");
+  let parent = resolve(path);
+  const tail = [];
+  while (!existsSync(parent)) { tail.unshift(basename(parent)); parent = dirname(parent); }
+  return join(realpathSync(parent), ...tail);
+}
+export function privateFile(path) {
+  const stat = lstatSync(path);
+  if (!stat.isFile() || stat.uid !== process.getuid() || (stat.mode & 0o077)) throw new Error("Expected a private, owned regular file: " + path);
+}
+export function json(path) {
+  privateFile(path);
+  try { return JSON.parse(readFileSync(path, "utf8")); }
+  catch { throw new Error("Cannot read valid JSON from " + path); } // JSON parser diagnostics can quote secrets.
+}
+export function createFile(path, text) {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  writeFileSync(path, text, { flag: "wx", mode: 0o600 });
+}
+export function run(command, args, options = {}) {
+  const env = Object.fromEntries(["HOME", "PATH", "LANG", "LC_ALL", "TZ", "TMPDIR"].filter(key => process.env[key] !== undefined).map(key => [key, process.env[key]]));
+  const result = spawnSync(command, args, { encoding: "utf8", timeout: 300000, stdio: "pipe", env, ...options });
+  if (result.error || result.status !== 0) throw new Error("Command failed (diagnostics withheld; may contain credentials): " + command + " " + args[0]);
+  return result.stdout?.trim();
+}
+export function operationLock(root) {
+  const db = new DatabaseSync(join(root, "setup-lock.sqlite"));
+  try { db.exec("PRAGMA busy_timeout=0; BEGIN EXCLUSIVE"); }
+  catch { db.close(); throw new Error("Another setup/uninstall operation owns this installation"); }
+  return () => db.close();
+}
+export function readManifest(root) {
+  if (realpathSync(root) !== root || lstatSync(root).uid !== process.getuid() || (lstatSync(root).mode & 0o077)) throw new Error("Installation home must be canonical, owned and private");
+  const value = json(join(root, "installation.json"));
+  if (value.project !== "agent-task" || value.root !== root || value.platform !== process.platform || value.home !== homedir() || typeof value.node !== "string" || !isAbsolute(value.node) || value.app !== packageRoot) throw new Error("Installation ownership does not match this user/platform");
+  return value;
+}
+export function saveManifest(root, manifest) {
+  // Preserve the last committed inventory even if a disk-full write fails.
+  const temporary = join(root, `installation-${process.pid}.tmp`);
+  let fd;
+  try {
+    fd = openSync(temporary, "wx", 0o600);
+    writeFileSync(fd, JSON.stringify(manifest, null, 2) + "\n"); fsyncSync(fd);
+    closeSync(fd); fd = undefined;
+    renameSync(temporary, join(root, "installation.json"));
+    const directory = openSync(root, "r");
+    try { fsyncSync(directory); } finally { closeSync(directory); }
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+    if (existsSync(temporary)) unlinkSync(temporary);
+  }
+}
+export function runtimeBaseEnv(manifest) {
+  // Do not inherit shell/service-manager credentials, loader hooks or executor overrides.
+  return { HOME: manifest.home, PATH: [join(manifest.root, "components/node_modules/.bin"), dirname(manifest.node), "/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin"].join(":"), LANG: "en_US.UTF-8" };
+}
+export function runtimeEnv(manifest) {
+  const values = json(join(manifest.root, "environment.json"));
+  if (!values || typeof values !== "object" || Array.isArray(values) || Object.entries(values).some(([key, value]) => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || ["__proto__", "constructor", "prototype"].includes(key) || typeof value !== "string" || value.includes("\0"))) throw new Error("Invalid environment.json");
+  return { ...runtimeBaseEnv(manifest), ...values };
+}
+const xml = value => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+const systemdQuote = value => '"' + value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("%", "%%").replaceAll("$", "$$") + '"';
+export function serviceDefinition(manifest) {
+  const runner = join(manifest.app, "scripts/service-runner.mjs");
+  if (manifest.platform === "linux") return {
+    path: join(manifest.home, ".config/systemd/user", unit),
+    text: `[Unit]\nDescription=Agent Task (managed by setup)\nAfter=network.target\n\n[Service]\nType=simple\nExecStart=${[manifest.node, runner, manifest.root].map(systemdQuote).join(" ")}\nRestart=on-failure\nRestartSec=5\nTimeoutStopSec=20\nKillMode=control-group\nUMask=0077\n\n[Install]\nWantedBy=default.target\n`,
+  };
+  return { path: join(manifest.home, "Library/LaunchAgents", label + ".plist"), text:
+    `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict>\n<key>Label</key><string>${label}</string>\n<key>ProgramArguments</key><array>${[manifest.node, runner, manifest.root].map(value => `<string>${xml(value)}</string>`).join("")}</array>\n<key>RunAtLoad</key><true/>\n<key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>\n<key>ThrottleInterval</key><integer>5</integer>\n<key>ExitTimeOut</key><integer>20</integer>\n<key>AbandonProcessGroup</key><false/>\n<key>Umask</key><integer>63</integer>\n<key>StandardOutPath</key><string>${xml(join(manifest.root, "service.log"))}</string>\n<key>StandardErrorPath</key><string>${xml(join(manifest.root, "service-error.log"))}</string>\n</dict></plist>\n` };
+}
+export function serviceEnv() {
+  const keys = ["HOME", "PATH", "LANG", "LC_ALL", "DBUS_SESSION_BUS_ADDRESS"];
+  return { ...Object.fromEntries(keys.filter(key => process.env[key] !== undefined).map(key => [key, process.env[key]])),
+    XDG_RUNTIME_DIR: process.env.XDG_RUNTIME_DIR ?? `/run/user/${process.getuid()}` };
+}
+export async function checkHealth(config, env, waitMs = 5000) {
+  const token = env[config.tokenEnv ?? "AGENT_TASK_TOKEN"];
+  if (!token || token.length < 32) throw new Error("A valid service token is required for the health check");
+  const deadline = Date.now() + waitMs;
+  do {
+    try {
+      const response = await fetch(`http://127.0.0.1:${config.port}/mcp`, {
+        method: "POST", headers: { Authorization: "Bearer " + token, "Content-Type": "application/json", Accept: "application/json, text/event-stream" },
+        body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "service_status", arguments: {} } }),
+        signal: AbortSignal.timeout(1000),
+      });
+      const body = await response.json();
+      if (response.ok && body.result?.structuredContent?.ok && body.result.structuredContent.data?.running) return;
+    } catch { /* Startup can take several seconds; never log the authenticated request. */ }
+    await delay(200);
+  } while (Date.now() < deadline);
+  throw new Error("Authenticated MCP health check failed; inspect the service manager and private configuration");
+}
+export function verifyServiceFile(manifest) {
+  const definition = serviceDefinition(manifest);
+  if (existsSync(definition.path)) {
+    privateFile(definition.path);
+    if (readFileSync(definition.path, "utf8") !== definition.text) throw new Error("Service file differs; refusing to overwrite or remove it: " + definition.path);
+  }
+  return definition;
+}
+export function activate(manifest) {
+  const definition = verifyServiceFile(manifest);
+  if (!existsSync(definition.path)) createFile(definition.path, definition.text);
+  if (manifest.platform === "linux") {
+    run("systemctl", ["--user", "daemon-reload"], { env: serviceEnv() });
+    run("systemctl", ["--user", "enable", "--now", unit], { env: serviceEnv() });
+    run("systemctl", ["--user", "is-active", unit], { env: serviceEnv() });
+  } else {
+    const domain = `gui/${process.getuid()}`;
+    const active = spawnSync("launchctl", ["print", domain + "/" + label], { stdio: "ignore" });
+    if (active.status !== 0) run("launchctl", ["bootstrap", domain, definition.path]);
+    run("launchctl", ["kickstart", domain + "/" + label]);
+    run("launchctl", ["print", domain + "/" + label]);
+  }
+}
+export function deactivate(manifest) {
+  const definition = verifyServiceFile(manifest);
+  if (!existsSync(definition.path)) {
+    if (manifest.serviceInstalled) throw new Error("Managed service file is missing; verify it is unloaded before cleanup");
+    return;
+  }
+  if (manifest.platform === "linux") {
+    run("systemctl", ["--user", "disable", "--now", unit], { env: serviceEnv() });
+    // Do not remove code while the service is still active or deactivating.
+    const state = run("systemctl", ["--user", "show", "--property=ActiveState", "--value", unit], { env: serviceEnv() });
+    if (!["inactive", "failed"].includes(state)) throw new Error("Service has not stopped");
+  } else {
+    const target = `gui/${process.getuid()}/${label}`;
+    const active = spawnSync("launchctl", ["print", target], { stdio: "ignore" });
+    if (active.status === 0) run("launchctl", ["bootout", target]);
+    if (spawnSync("launchctl", ["print", target], { stdio: "ignore" }).status === 0) throw new Error("LaunchAgent is still loaded");
+  }
+  unlinkSync(definition.path);
+  if (manifest.platform === "linux") run("systemctl", ["--user", "daemon-reload"], { env: serviceEnv() });
+}
+export function inventory(root, relative) {
+  const path = join(root, relative), stat = lstatSync(path);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) return [relative];
+  return readdirSync(path).flatMap(name => inventory(root, join(relative, name))).concat(relative);
+}
+export function removeInventory(root, files) {
+  for (const relative of files) {
+    if (!/^components(\/|$)/.test(relative) || relative.split("/").includes("..")) throw new Error("Invalid component inventory");
+    const path = join(root, relative);
+    // Never follow a directory replaced by a symlink outside the installation.
+    try {
+      if (realpathSync(dirname(path)) !== dirname(path)) throw new Error("Component parent path changed; cleanup stopped");
+      const stat = lstatSync(path);
+      if (stat.isDirectory() && !stat.isSymbolicLink()) {
+        try { rmdirSync(path); } catch (error) { if (error.code !== "ENOTEMPTY") throw error; }
+      } else unlinkSync(path);
+    } catch (error) { if (error.code !== "ENOENT") throw error; }
+  }
+}

package/scripts/mcp-call.mjs

@@ -0,0 +1,17 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { version } from "../dist/version.js";
+const [tool, input = "{}"] = process.argv.slice(2);
+if (!tool || !process.env.AGENT_TASK_TOKEN) {
+  console.error("Usage: AGENT_TASK_TOKEN=... node scripts/mcp-call.mjs <tool|--list> '[JSON arguments]'\nAGENT_TASK_URL defaults to http://127.0.0.1:8765/mcp");
+  process.exit(2);
+}
+const client = new Client({ name: "agent-task-command", version });
+try {
+  await client.connect(new StreamableHTTPClientTransport(new URL(process.env.AGENT_TASK_URL ?? "http://127.0.0.1:8765/mcp"),
+    { requestInit: { headers: { Authorization: "Bearer " + process.env.AGENT_TASK_TOKEN } } }));
+  const result = tool === "--list" ? await client.listTools() : await client.callTool({ name: tool, arguments: JSON.parse(input) });
+  console.log(JSON.stringify(result, null, 2));
+  if ("isError" in result && result.isError) process.exitCode = 1;
+} catch (error) { console.error(error.message); process.exitCode = 1; }
+finally { await client.close(); }

package/scripts/probe-agent.mjs

@@ -0,0 +1,34 @@
+// Real ACP initialization only: no session/new, prompt, login, or model request.
+import { spawn } from "node:child_process";
+import { Readable, Writable } from "node:stream";
+import * as acp from "@agentclientprotocol/sdk";
+import { loadConfig, executorEnv } from "../dist/config.js";
+import { terminateGroup } from "../dist/acp.js";
+import { version } from "../dist/version.js";
+const [file, id] = process.argv.slice(2);
+if (!file || !id) { console.error("Usage: node scripts/probe-agent.mjs <config.json> <executorId>"); process.exit(2); }
+const config = loadConfig(file);
+const executor = config.executors.find(value => value.id === id);
+if (!executor) throw new Error("Executor not found");
+const child = spawn(executor.command, executor.args, {
+  cwd: executor.cwd, env: executorEnv(executor.envKeys), detached: true, stdio: ["pipe", "pipe", "pipe"],
+});
+child.stderr.resume();
+let connection;
+const closed = new Promise(resolve => child.once("close", resolve));
+child.once("error", error => { console.error("ACP executable could not start"); connection?.close(error); });
+const timer = setTimeout(() => {
+  connection?.close(new Error("ACP initialization timed out"));
+  void terminateGroup(child);
+}, 10000);
+try {
+  connection = await acp.client({ name: "agent-task-probe" }).connect(acp.ndJsonStream(
+    Writable.toWeb(child.stdin), Readable.toWeb(child.stdout), { maxMessageBytes: 1048576 }));
+  const result = await connection.agent.request(acp.methods.agent.initialize, {
+    protocolVersion: acp.PROTOCOL_VERSION, clientCapabilities: {},
+    clientInfo: { name: "agent-task-probe", version },
+  });
+  if (result.protocolVersion !== acp.PROTOCOL_VERSION) throw new Error("Incompatible ACP protocol version");
+  console.log(JSON.stringify(result, null, 2));
+} catch { console.error("ACP initialize failed; inspect native configuration in a private terminal. No task was sent."); process.exitCode = 1; }
+finally { clearTimeout(timer); connection?.close(); await terminateGroup(child); await closed; }

package/scripts/service-runner.mjs

@@ -0,0 +1,14 @@
+// Same process as the service: the service manager supervises the actual HTTP owner.
+import { join } from "node:path";
+import { readManifest, runtimeBaseEnv } from "./install-lib.mjs";
+
+process.umask(0o077);
+const root = process.argv[2];
+if (!root || process.argv.length !== 3) throw new Error("Expected installation home");
+const manifest = readManifest(root);
+if (manifest.phase !== "ready") throw new Error("Installation is not ready");
+const env = runtimeBaseEnv(manifest);
+for (const key of Object.keys(process.env)) delete process.env[key];
+Object.assign(process.env, env);
+process.argv = [process.execPath, join(manifest.app, "dist/main.js"), "--config", join(root, "config.json"), "--environment", join(root, "environment.json")];
+await import("../dist/main.js");

package/scripts/setup-wizard.mjs

@@ -0,0 +1,29 @@
+import { createInterface } from "node:readline/promises";
+
+export async function setupWizard(options, root) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) throw new Error("Interactive setup requires a terminal; use --executors none|pi,codex,opencode and --cwd ABSOLUTE_DIR for noninteractive setup");
+  const input = createInterface({ input: process.stdin, output: process.stdout });
+  const abort = new AbortController();
+  input.on("SIGINT", () => abort.abort());
+  const ask = async (question, fallback) => (await input.question(`${question}${fallback ? " [" + fallback + "]" : ""}: `, { signal: abort.signal })).trim() || fallback;
+  try {
+    console.log(`Private installation: ${root}\nNo credentials are requested here. Use the local Web console or a private editor after setup.\nExecutors are optional; installing one does not authorize it.`);
+    options.executors ??= await ask("Executors to install (none or comma-separated pi,codex,opencode)", "none");
+    options.cwd ??= await ask("Existing absolute workspace (outside installation and npm package)", process.cwd());
+    if (!options.provider) {
+      const provider = await ask("Coordinator provider (none/openai/anthropic/deepseek; configurable later in Web)", "none");
+      if (provider !== "none") options.provider = provider;
+    }
+    if (options.provider) options.model ??= await ask("Coordinator model ID", "");
+    options.port ??= await ask("Loopback HTTP port", "8765");
+    if (!options["prepare-only"] && !options.service) {
+      const answer = await ask("Install and start the background service now? (yes/no)", "no");
+      if (!["yes", "no"].includes(answer)) throw new Error("Expected yes or no; setup cancelled");
+      if (answer === "yes") options.service = true;
+    }
+    if (await ask("Write private configuration and install selected components? (yes/no)", "no") !== "yes") throw new Error("Setup cancelled; no configuration written");
+  } catch (error) {
+    if (abort.signal.aborted) throw new Error("Setup cancelled; no configuration written");
+    throw error;
+  } finally { input.close(); }
+}

package/scripts/setup.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, realpathSync, lstatSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { homedir } from "node:os";
+import { randomBytes } from "node:crypto";
+import { argumentsFor, installRoot, packages, createFile, json, run, operationLock, readManifest, saveManifest,
+  runtimeEnv, activate, inventory, verifyServiceFile, packageRoot, checkHealth } from "./install-lib.mjs";
+import { setupWizard } from "./setup-wizard.mjs";
+
+process.umask(0o077);
+let unlock;
+try {
+  const options = argumentsFor(process.argv.slice(2));
+  if (options.help) {
+    console.log("Usage: agent-task setup [--home ABSOLUTE_PRIVATE_DIR]\nInteractive on a terminal for a new installation. Noninteractive: --executors pi,codex,opencode|none --cwd ABSOLUTE_DIR [--provider openai|anthropic|deepseek --model ID] [--port 8765]\nDefault: --prepare-only (no background service). --service explicitly installs/starts the background service.\nExisting installation: --check [--probe] | --resume. No credentials accepted on the command line. Existing configuration is never replaced.");
+    process.exit(0);
+  }
+  if (options.service && (options["prepare-only"] || options.check)) throw new Error("--service cannot be combined with --prepare-only or --check");
+  if (options.probe && !options.check) throw new Error("--probe requires --check");
+  const root = installRoot(options), manifestPath = join(root, "installation.json");
+  if (!existsSync(manifestPath) && !options.check && !options.resume && (!options.executors || !options.cwd)) await setupWizard(options, root);
+  if (!existsSync(root)) mkdirSync(root, { recursive: true, mode: 0o700 });
+  if (realpathSync(root) !== root || lstatSync(root).uid !== process.getuid() || (lstatSync(root).mode & 0o077)) throw new Error("Installation home must be canonical, owned and private");
+  unlock = operationLock(root);
+  let manifest;
+  if (existsSync(manifestPath)) {
+    manifest = readManifest(root);
+    if (["executors", "cwd", "provider", "model", "port"].some(key => options[key] !== undefined)) throw new Error("Installation already exists; initialization options cannot replace existing configuration");
+    if (manifest.phase !== "ready" && !options.resume) throw new Error("Incomplete or uninstalled components; use --resume explicitly (configuration will be preserved)");
+  } else {
+    if (options.check || options.probe || options.resume) throw new Error("No installation to check/resume");
+    if (!options.executors || !options.cwd) throw new Error("Select --executors pi,codex,opencode|none and --cwd ABSOLUTE_DIR");
+    const selected = options.executors === "none" ? [] : options.executors.split(",");
+    if (selected.some(id => !Object.hasOwn(packages, id)) || new Set(selected).size !== selected.length) throw new Error("Invalid executor selection");
+    if (!options.cwd.startsWith("/") || !lstatSync(realpathSync(options.cwd)).isDirectory()) throw new Error("cwd must be an existing absolute directory");
+    const cwd = realpathSync(options.cwd);
+    if ([root, packageRoot].some(path => cwd === path || cwd.startsWith(path + "/"))) throw new Error("Workspace must be outside the installation home and npm package");
+    if (Boolean(options.provider) !== Boolean(options.model) || (options.provider && !["openai", "anthropic", "deepseek"].includes(options.provider))) throw new Error("Specify a supported --provider together with --model");
+    const port = Number(options.port ?? 8765);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error("Invalid port");
+    // Reject unowned artifacts. This script never adopts or clears an existing installation.
+    for (const name of ["components", "config.json", "environment.json", "data"]) {
+      if (existsSync(join(root, name))) throw new Error("Existing unowned installation artifact: " + name);
+    }
+    manifest = { project: "agent-task", root, home: homedir(), platform: process.platform, node: process.execPath, app: packageRoot,
+      selected, cwd, port, coordinator: options.provider ? { provider: options.provider, model: options.model } : undefined,
+      phase: "installing", serviceInstalled: false, files: [] };
+    createFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+  }
+  verifyServiceFile(manifest);
+  const app = manifest.app, components = join(root, "components");
+  if (!existsSync(join(app, "dist/main.js"))) throw new Error("Prebuilt runtime is missing; reinstall the npm package (source contributors: npm run build)");
+  if (manifest.phase !== "ready") {
+    if (manifest.serviceInstalled) throw new Error("Stop/uninstall the existing service before rebuilding components");
+    for (const name of ["components"]) {
+      if (!existsSync(join(root, name))) continue;
+      const known = new Set(manifest.files);
+      if (inventory(root, name).some(file => !known.has(file))) throw new Error("Uninventoried component files exist; refusing to overwrite them during resume");
+    }
+    try {
+      console.log("Using the prebuilt npm runtime. No source checkout or compilation required.");
+      mkdirSync(components, { recursive: true, mode: 0o700 });
+      if (!existsSync(join(components, "package.json"))) createFile(join(components, "package.json"), JSON.stringify({ private: true }));
+      const dependencies = manifest.selected.flatMap(id => packages[id]);
+      if (dependencies.length) {
+        console.log("Installing selected ACP executors into private components (not global executables).");
+        const installArgs = existsSync(join(components, "package-lock.json"))
+          ? ["ci", "--ignore-scripts", "--no-audit", "--no-fund"]
+          : ["install", "--save-exact", "--ignore-scripts", "--no-audit", "--no-fund", ...dependencies];
+        run("npm", installArgs, { cwd: components });
+        if (manifest.selected.includes("opencode")) {
+          // This pinned package requires copying its platform binary. No other lifecycle scripts run.
+          run(manifest.node, [join(components, "node_modules/opencode-ai/postinstall.mjs")], { cwd: components });
+        }
+      }
+      mkdirSync(join(root, "data/results"), { recursive: true, mode: 0o700 });
+      if (!existsSync(join(root, "environment.json"))) createFile(join(root, "environment.json"), JSON.stringify({ AGENT_TASK_TOKEN: randomBytes(32).toString("hex"), AGENT_TASK_ADMIN_TOKEN: randomBytes(32).toString("hex") }, null, 2) + "\n");
+      if (!existsSync(join(root, "config.json"))) createFile(join(root, "config.json"), JSON.stringify({ dataDir: join(root, "data"), port: manifest.port,
+        tokenEnv: "AGENT_TASK_TOKEN", coordinator: manifest.coordinator,
+        executors: manifest.selected.map(id => ({ id, command: join(components, "node_modules/.bin", id === "pi" ? "pi-acp" : id === "codex" ? "codex-acp" : "opencode"),
+          args: id === "opencode" ? ["acp"] : [], cwd: manifest.cwd, envKeys: ["HOME"],
+          permissionAllowlist: [], unattendedApproved: false, resultReadRoots: [] })) }, null, 2) + "\n");
+      manifest.phase = "ready";
+    } finally {
+      manifest.files = ["components"].filter(name => existsSync(join(root, name))).flatMap(name => inventory(root, name));
+      saveManifest(root, manifest);
+    }
+  }
+  const env = runtimeEnv(manifest);
+  // Config validation and probes run in the SAME explicit environment as the background service.
+  run(manifest.node, ["--input-type=module", "-e", `import {loadConfig} from ${JSON.stringify(pathToFileURL(join(app, "dist/config.js")).href)}; loadConfig(process.argv[1]);`, join(root, "config.json")], { env });
+  const config = json(join(root, "config.json"));
+  const { executorEnv } = await import(pathToFileURL(join(app, "dist/config.js")).href);
+  for (const id of manifest.selected) {
+    const binary = id === "pi" ? "pi" : id;
+    const cliEnv = executorEnv(config.executors.find(executor => executor.id === id)?.envKeys ?? [], env);
+    run(join(components, "node_modules/.bin", binary), ["--version"], { env: cliEnv, timeout: 20000 });
+  }
+  const report = { platform: process.platform, dependencies: "ready", configuration: "valid", background: "not-checked",
+    coordinator: config.coordinator ? "configured; authentication not verified" : "not configured; task admission disabled",
+    executors: config.executors.map(executor => ({ id: executor.id, authorized: executor.unattendedApproved,
+      handshake: "not checked", execution: "not verified by setup" })) };
+  if (options.probe) {
+    for (const entry of report.executors) {
+      try { run(manifest.node, [join(app, "scripts/probe-agent.mjs"), join(root, "config.json"), entry.id], { env, timeout: 20000 }); entry.handshake = "passed (initialize only)"; }
+      catch { entry.handshake = "failed; inspect native dependencies/configuration separately"; process.exitCode = 1; }
+    }
+  }
+  if (options.service) {
+    // Record intent before activating so a failed service start is still owned by uninstall.
+    manifest.serviceInstalled = true; saveManifest(root, manifest);
+    activate(manifest);
+    report.background = "service manager registered";
+  }
+  if (manifest.serviceInstalled) {
+    try {
+      await checkHealth(config, env, 15000);
+      report.background = "authenticated MCP health check passed";
+    } catch { report.background = "not ready; run --check after startup and inspect the service manager"; process.exitCode = 1; }
+  }
+  console.log(JSON.stringify(report, null, 2));
+  console.log(`Config: ${join(root, "config.json")}\nSecrets (never printed): ${join(root, "environment.json")}\nNative login: use ${join(components, "node_modules/.bin")} executables: pi then /login; codex login; opencode auth login. No login is performed by setup.\nConsole: http://127.0.0.1:${config.port}/admin/ (use the separate AGENT_TASK_ADMIN_TOKEN from the private environment file; never place it in a URL). Configure coordinator credentials there or in environment.json, and audit native executor permissions before setting unattendedApproved=true. No permissions are granted by setup. Restart the service manually after changes.\nLinux: user service requires lingering for logout survival (administrator decision). macOS: LaunchAgent survives terminal close, not user logout; log in again to restart. Neither platform executes during sleep/shutdown.`);
+} catch (error) {
+  console.error(error.message); process.exitCode = 1;
+} finally { unlock?.(); }

package/scripts/uninstall.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import { existsSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { argumentsFor, installRoot, readManifest, saveManifest, operationLock, deactivate, removeInventory, json } from "./install-lib.mjs";
+
+process.umask(0o077);
+const options = argumentsFor(process.argv.slice(2));
+if (options.help) {
+  console.log("Usage: agent-task uninstall [--home ABSOLUTE_PRIVATE_DIR]\nStops/removes the owned service and installed components only. Keeps configuration, credentials, logs, task history and workspaces.");
+  process.exit(0);
+}
+let unlock, release;
+try {
+  if (Object.keys(options).some(key => key !== "home")) throw new Error("Only --home is accepted");
+  const root = installRoot(options);
+  if (!existsSync(root)) { console.log("Nothing installed; nothing removed."); process.exit(0); }
+  readManifest(root);
+  unlock = operationLock(root);
+  const manifest = readManifest(root);
+  deactivate(manifest);
+  manifest.serviceInstalled = false; saveManifest(root, manifest);
+  if (existsSync(join(root, "config.json"))) {
+    const config = json(join(root, "config.json"));
+    const protectedPaths = [config.dataDir, ...config.executors.flatMap(executor => [executor.cwd, ...executor.resultReadRoots])];
+    // Verify the service is stopped, including any manually started owner.
+    const lockModule = join(manifest.app, "dist/lock.js");
+    if (existsSync(lockModule)) {
+      const { acquireLock } = await import(pathToFileURL(lockModule).href);
+      release = await acquireLock(config.dataDir);
+      const storeModule = join(manifest.app, "dist/task-storage.js");
+      if (existsSync(join(config.dataDir, "tasks.sqlite")) && existsSync(storeModule)) {
+        const { TaskStore } = await import(pathToFileURL(storeModule).href);
+        const store = new TaskStore(config.dataDir);
+        try {
+          for (const task of store.definitions()) protectedPaths.push(task.workspace, task.input.workspace, ...Object.values(task.executors).map(executor => executor.cwd));
+          for (const run of store.rounds()) for (const node of run.nodes) protectedPaths.push(node.workspace);
+        } finally { store.close(); }
+      }
+    } else if (manifest.phase !== "uninstalled") throw new Error("Cannot verify data ownership; resume setup before uninstall");
+    for (const path of protectedPaths.filter(Boolean)) {
+      const canonical = existsSync(path) ? realpathSync(path) : path;
+      const components = join(root, "components");
+      if (canonical === components || canonical.startsWith(components + "/")) {
+        throw new Error("Installed components are referenced as data/workspace; refusing to delete them");
+      }
+    }
+  }
+  removeInventory(root, manifest.files);
+  manifest.phase = "uninstalled"; manifest.files = []; saveManifest(root, manifest);
+  console.log("Owned service and inventoried components removed. Configuration, environment.json, logs, data, workspaces and all native/shared executor authentication are preserved. Repeated uninstall is safe.");
+} catch (error) { console.error(error.message); process.exitCode = 1; }
+finally { await release?.(); unlock?.(); }