@fitchmultz/pi-subagents 0.0.0-stage → 0.44.5

package/scripts/build.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+/**
+ * Purpose: Produce the compiled runtime files that the Pi extension manifest loads.
+ * Responsibilities: Run TypeScript emit into a staging directory, then atomically swap it
+ * into dist/ so a failed TypeScript emit never destroys a previously working dist.
+ * Usage: `npm run build`; also invoked by scripts/prepare.mjs during install lifecycles, which may pass
+ * the path of a throwaway compiler's `bin/tsc` as the first argument.
+ * Invariants/Assumptions: `node_modules` (or that argument) provides `typescript`; deleting `dist/` is safe generated output.
+ */
+
+import { execFile as execFileCallback } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import process from "node:process";
+import { setTimeout as delay } from "node:timers/promises";
+import { promisify } from "node:util";
+
+const execFile = promisify(execFileCallback);
+const RM_OPTIONS = { force: true, maxRetries: 5, recursive: true, retryDelay: 100 };
+const RENAME_RETRY_LIMIT = 50;
+const RENAME_RETRY_MS = 50;
+// Use the current Node binary without a shell, including install paths with spaces.
+const tscPath = process.argv[2] ?? join(process.cwd(), "node_modules", "typescript", "bin", "tsc");
+
+async function discardStaging(path) {
+	try {
+		await rm(path, RM_OPTIONS);
+	} catch (error) {
+		// Cleanup is always best-effort: it must not turn a successful race loss
+		// into failure or replace the compiler/publish error that matters.
+		console.warn(`could not remove staging ${path}: ${error?.message ?? error}`);
+	}
+}
+
+function isOwnerGone(pid) {
+	try {
+		process.kill(pid, 0);
+		return false;
+	} catch (error) {
+		return error?.code === "ESRCH";
+	}
+}
+
+async function hasPublishedDist(path) {
+	try {
+		return (await readdir(path)).length > 0;
+	} catch {
+		return false;
+	}
+}
+
+async function reapStrandedStaging(cwd) {
+	// Signal 0 proves only that the owner was gone at probe time. Pid reuse
+	// between this probe and removal is inherent to pid-based reaping.
+	for (const entry of await readdir(cwd, { withFileTypes: true })) {
+		const match = /^dist\.staging\.(\d+)$/.exec(entry.name);
+		if (!match || !entry.isDirectory()) continue;
+		const ownerPid = Number(match[1]);
+		if (ownerPid === process.pid || !isOwnerGone(ownerPid)) continue;
+		await discardStaging(join(cwd, entry.name));
+	}
+}
+
+async function compileToStaging(cwd, stagingDir) {
+	try {
+		const { stderr, stdout } = await execFile(
+			process.execPath,
+			[tscPath, "-p", "tsconfig.build.json", "--outDir", stagingDir],
+			{ cwd, maxBuffer: 10 * 1024 * 1024 },
+		);
+		if (stdout) process.stdout.write(stdout);
+		if (stderr) process.stderr.write(stderr);
+		const stamp = "extension/build-info.js";
+		const hash = createHash("sha256");
+		for (const file of (await readdir(stagingDir, { recursive: true })).filter((file) => file.endsWith(".js") && file !== stamp).sort()) {
+			hash.update(file).update("\0").update(await readFile(join(stagingDir, file))).update("\0");
+		}
+		const { version } = JSON.parse(await readFile(join(cwd, "package.json"), "utf8"));
+		await writeFile(join(stagingDir, stamp), `export const EXTENSION_BUILD = Object.freeze(${JSON.stringify({ version, sha256: hash.digest("hex") })});\n`);
+	} catch (error) {
+		if (error?.stdout) process.stdout.write(error.stdout);
+		if (error?.stderr) process.stderr.write(error.stderr);
+		await discardStaging(stagingDir);
+		throw error;
+	}
+}
+
+async function publishStaging(stagingDir, distDir) {
+	try {
+		// A failed dist removal must fail loudly; keep it outside the retry loop.
+		// Remove dist exactly once so retries never delete a concurrent winner.
+		await rm(distDir, RM_OPTIONS);
+		for (let retry = 0; ; retry++) {
+			try {
+				await rename(stagingDir, distDir);
+				return;
+			} catch (error) {
+				// A completed staged build is non-empty; a bare directory is not proof
+				// that a concurrent publisher won the race.
+				if (await hasPublishedDist(distDir)) {
+					console.warn("dist/ was published by a concurrent build; discarding this build's staging tree.");
+					return;
+				}
+				// At most 50 retries (~2.5s) keep persistent filesystem errors bounded.
+				if (existsSync(stagingDir) && retry < RENAME_RETRY_LIMIT) {
+					await delay(RENAME_RETRY_MS);
+					continue;
+				}
+				throw error;
+			}
+		}
+	} finally {
+		// Safe after success too: rename moved stagingDir, so force makes this a no-op.
+		await discardStaging(stagingDir);
+	}
+}
+
+async function main() {
+	const cwd = process.cwd();
+	if (!existsSync(tscPath)) throw new Error(`typescript is not installed at ${tscPath}; run npm install first.`);
+	await reapStrandedStaging(cwd);
+	// Pid-scoped staging isolates concurrent emits; only a complete tree publishes.
+	const stagingDir = join(cwd, `dist.staging.${process.pid}`);
+	await rm(stagingDir, RM_OPTIONS);
+	await compileToStaging(cwd, stagingDir);
+	await publishStaging(stagingDir, join(cwd, "dist"));
+}
+
+main().catch((error) => {
+	console.error(error instanceof Error ? error.message : String(error));
+	process.exitCode = 1;
+});

package/scripts/check-compat.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+
+if (process.argv.includes("--help") || process.argv.includes("-h")) {
+  console.log("Usage: node scripts/check-compat.mjs\n\nRun selected-host full CI and native package checks with actual editor receipts.\nAn owned temporary editor checkout is removed after checks; supplied sources stay read-only.\nEnvironment: PI_EDITOR_RECEIPT_TEST_ROOT optionally supplies a clean frozen Git checkout.\nExamples:\n  npm run check:compat\n  PI_EDITOR_RECEIPT_TEST_ROOT=/path/to/pi-apply-edits npm run check:compat\nExit codes: 0 passed; 1 invalid input, unavailable source or failed checks.");
+  process.exit(0);
+}
+assert.equal(process.argv.length, 2, "Expected no arguments; use --help");
+await import("./compat-host.mjs");
+const run = (command, args, options = {}) => {
+  const result = spawnSync(command, args, { stdio: "inherit", timeout: 1_200_000, ...options });
+  if (result.error) throw result.error;
+  assert.equal(result.status, 0, `${command} ${args.join(" ")} failed (${result.status ?? result.signal})`);
+  return result.stdout?.trim();
+};
+const git = (cwd, args) => run("git", args, { cwd, stdio: ["ignore", "pipe", "inherit"], encoding: "utf8" });
+const root = mkdtempSync(join(tmpdir(), "ps-editor-"));
+const editor = join(root, "source");
+try {
+  const supplied = process.env.PI_EDITOR_RECEIPT_TEST_ROOT;
+  let expectedRef;
+  if (supplied) {
+    const source = resolve(supplied);
+    expectedRef = git(source, ["rev-parse", "HEAD"]);
+    assert.equal(git(source, ["status", "--porcelain", "--untracked-files=all"]), "", "Supplied editor source must be clean");
+    run("git", ["clone", "--no-hardlinks", "--quiet", source, editor]);
+    git(editor, ["checkout", "--quiet", "--detach", expectedRef]);
+  } else {
+    run("git", ["clone", "--depth", "1", "--branch", "main", "--single-branch", "--quiet", "https://github.com/fitchmultz/pi-apply-edits.git", editor]);
+  }
+  const ref = git(editor, ["rev-parse", "HEAD"]);
+  assert.match(ref, /^[a-f0-9]{40}$/);
+  if (expectedRef) assert.equal(ref, expectedRef);
+  assert.ok(existsSync(join(editor, "extensions", "apply-edits.ts")), "Editor source lacks its native extension");
+  // Only the editor's real third-party runtime dependencies; Pi supplies its own peers through the loader.
+  run("npm", ["ci", "--omit=dev", "--ignore-scripts", "--legacy-peer-deps", "--no-audit", "--no-fund"], { cwd: editor });
+  git(editor, ["diff", "--exit-code"]);
+  console.log(JSON.stringify({ nativeEditor: { ref, source: editor, supplied: supplied ? resolve(supplied) : null } }));
+  const env = { ...process.env, PI_EDITOR_RECEIPT_TEST_ROOT: editor };
+  run("npm", ["run", "ci"], { env });
+  run(process.execPath, ["scripts/native-package-smoke.mjs"], { env });
+} finally {
+  rmSync(root, { recursive: true, force: true });
+}

package/scripts/compat-host.mjs

@@ -0,0 +1,19 @@
+// Validate the graph prepared by the compatibility runner; never install a host here.
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { readFileSync, realpathSync } from "node:fs";
+import { findPackageJSON } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const hostRoot = realpathSync(dirname(findPackageJSON("@earendil-works/pi-coding-agent", import.meta.url)));
+export const hostIndex = join(hostRoot, "dist/index.js");
+const manifest = JSON.parse(readFileSync(join(hostRoot, "package.json"), "utf8"));
+export const hostCli = realpathSync(join(hostRoot, manifest.bin.pi));
+for (const [name, actual] of [["PI_COMPAT_EXPECTED_PACKAGE_DIR", hostRoot], ["PI_HOST_INDEX", hostIndex], ["PI_HOST_CLI", hostCli]]) {
+  if (process.env[name]) assert.equal(realpathSync(process.env[name]), realpathSync(actual), `${name} must select the installed graph`);
+}
+if (process.env.PI_COMPAT_EXPECTED_VERSION) assert.equal(manifest.version, process.env.PI_COMPAT_EXPECTED_VERSION);
+assert.equal(realpathSync(fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"))), realpathSync(hostIndex));
+const hash = path => createHash("sha256").update(readFileSync(path)).digest("hex");
+console.log(JSON.stringify({ host: process.env.PI_COMPAT_HOST ?? "local", version: manifest.version, node: process.version, hostRoot, hostIndex, hostCli, indexSha256: hash(hostIndex), cliSha256: hash(hostCli) }));

package/scripts/intercom-bridge-credentials.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { randomBytes, X509Certificate } from "node:crypto";
+import { lstatSync, mkdirSync, readFileSync, renameSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { parseArgs } from "node:util";
+
+function help() {
+  console.log(`Usage: node scripts/intercom-bridge-credentials.mjs <init|issue|revoke> DIR [NAME] [--cwd PATH]
+
+init    Create a new private CA, loopback server certificate and grok-bot credential.
+issue   Issue a fresh 7-day client certificate; replace that name's old authorization.
+revoke  Remove the named client from the allowlist. Does not delete saved credentials.
+
+Options: --cwd PATH  Local project identity for init/issue (default: current directory)
+         -h, --help  Show help
+Environment: OPENSSL  OpenSSL executable (default: openssl; requires -addext support)
+
+Examples:
+  node scripts/intercom-bridge-credentials.mjs init ~/.pi/intercom-bridge --cwd "$PWD"
+  node scripts/intercom-bridge-credentials.mjs issue ~/.pi/intercom-bridge grok-bot
+  node scripts/intercom-bridge-credentials.mjs revoke ~/.pi/intercom-bridge grok-bot
+
+After issue/revoke, send SIGHUP to the helper PID to activate the allowlist.
+Concurrent credential commands fail rather than overwrite each other's authorization.
+After a crashed command, inspect DIR/.credentials.lock/owner and remove that lock
+only after confirming its process has stopped.
+Exit: 0 success, 1 filesystem/OpenSSL failure, 2 invalid arguments.
+Never transfer ca.key or server.key to the remote host.`);
+}
+
+function privatePath(path, directory = false) {
+  const st = lstatSync(path);
+  if (st.isSymbolicLink() || !(directory ? st.isDirectory() : st.isFile()) ||
+      st.uid !== process.getuid() || (st.mode & 0o077)) {
+    throw new Error(`Expected an owned, private ${directory ? "directory" : "file"}: ${path}`);
+  }
+}
+
+function atomicConfig(path, config) {
+  const temp = `${path}.${randomBytes(8).toString("hex")}.tmp`;
+  try {
+    writeFileSync(temp, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+    renameSync(temp, path);
+  } finally {
+    rmSync(temp, { force: true });
+  }
+}
+
+function openssl(...args) {
+  execFileSync(process.env.OPENSSL || "openssl", args, { stdio: ["ignore", "pipe", "pipe"], timeout: 30000 });
+}
+
+function key(path) {
+  openssl("ecparam", "-name", "prime256v1", "-genkey", "-noout", "-out", path);
+  privatePath(path);
+}
+
+function issueCertificate(dir, stem, name, server = false) {
+  const keyPath = join(dir, `${stem}.key`);
+  const certPath = join(dir, `${stem}.crt`);
+  const csrPath = join(dir, `${stem}.csr`);
+  const extPath = join(dir, `${stem}.ext`);
+  key(keyPath);
+  try {
+    openssl("req", "-new", "-key", keyPath, "-subj", `/CN=${name}`, "-out", csrPath);
+    writeFileSync(extPath, `basicConstraints=critical,CA:FALSE\nkeyUsage=critical,digitalSignature\nextendedKeyUsage=${server ? "serverAuth" : "clientAuth"}\n${server ? "subjectAltName=DNS:localhost,IP:127.0.0.1\n" : ""}`, { mode: 0o600, flag: "wx" });
+    openssl("x509", "-req", "-in", csrPath, "-CA", join(dir, "ca.crt"), "-CAkey", join(dir, "ca.key"),
+      "-set_serial", `0x${randomBytes(16).toString("hex")}`, "-days", server ? "365" : "7", "-sha256", "-extfile", extPath, "-out", certPath);
+  } finally {
+    rmSync(csrPath, { force: true });
+    rmSync(extPath, { force: true });
+  }
+  const cert = new X509Certificate(readFileSync(certPath));
+  return { cert: certPath, key: keyPath, fingerprint256: cert.fingerprint256, expires: cert.validTo };
+}
+
+let args;
+try {
+  args = parseArgs({ allowPositionals: true, options: { help: { type: "boolean", short: "h" }, cwd: { type: "string" } } });
+  if (args.values.help) { help(); process.exit(0); }
+  const [action, dir, name] = args.positionals;
+  if (!["init", "issue", "revoke"].includes(action) || !dir || args.positionals.length > 3 ||
+      (action !== "init" && !name) || (name && !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(name)) ||
+      (action === "revoke" && args.values.cwd)) throw new Error("Invalid arguments; use --help.");
+} catch (error) {
+  console.error(error.message);
+  process.exit(2);
+}
+
+let lock;
+try {
+  process.umask(0o077);
+  const [action, rawDir, suppliedName] = args.positionals;
+  const dir = resolve(rawDir);
+  const name = suppliedName || "grok-bot";
+  const configPath = join(dir, "config.json");
+  let config;
+  if (action === "init") mkdirSync(dir, { mode: 0o700 }); // Never overwrite a CA.
+  privatePath(dir, true);
+  const lockPath = join(dir, ".credentials.lock");
+  try { mkdirSync(lockPath, { mode: 0o700 }); }
+  catch (error) {
+    if (error.code === "EEXIST") throw new Error(`Another credential command holds ${lockPath}; inspect its owner before retrying.`);
+    throw error;
+  }
+  lock = lockPath;
+  writeFileSync(join(lock, "owner"), `${process.pid}\n`, { mode: 0o600, flag: "wx" });
+  if (action === "init") {
+    key(join(dir, "ca.key"));
+    openssl("req", "-new", "-x509", "-key", join(dir, "ca.key"), "-days", "3650", "-sha256", "-subj", "/CN=Pi Intercom Bridge CA",
+      "-addext", "basicConstraints=critical,CA:TRUE,pathlen:0", "-addext", "keyUsage=critical,keyCertSign,cRLSign", "-out", join(dir, "ca.crt"));
+    const server = issueCertificate(dir, "server", "localhost", true);
+    config = { port: 9443, ca: join(dir, "ca.crt"), cert: server.cert, key: server.key, clients: [] };
+  } else {
+    privatePath(dir, true);
+    privatePath(configPath);
+    config = JSON.parse(readFileSync(configPath, "utf8"));
+    if (!Array.isArray(config.clients)) throw new Error("Invalid clients allowlist.");
+  }
+  if (action === "revoke") {
+    if (!config.clients.some((client) => client.name === name)) throw new Error(`No authorized client named ${name}.`);
+    config.clients = config.clients.filter((client) => client.name !== name);
+    atomicConfig(configPath, config);
+    console.log(JSON.stringify({ revoked: name, config: configPath, next: "Send SIGHUP to the helper PID." }));
+  } else {
+    privatePath(join(dir, "ca.key"));
+    const credential = issueCertificate(dir, `${name}-${randomBytes(8).toString("hex")}`, name);
+    const previous = config.clients.find((client) => client.name === name);
+    config.clients = config.clients.filter((client) => client.name !== name);
+    config.clients.push({ fingerprint256: credential.fingerprint256, name, cwd: resolve(args.values.cwd || previous?.cwd || process.cwd()) });
+    atomicConfig(configPath, config);
+    console.log(JSON.stringify({ name, ...credential, ca: config.ca, config: configPath, next: "Transfer only client cert/key and ca.crt; reload helper allowlist with SIGHUP." }));
+  }
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+} finally {
+  if (lock) {
+    rmSync(join(lock, "owner"), { force: true });
+    rmdirSync(lock);
+  }
+}

package/scripts/intercom-remote.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+import https from "node:https";
+import { lstatSync, readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+
+function help() {
+  console.log(`Usage: node intercom-remote.mjs <register|list|inbox|send|ask|reply|ack> [options] [IDs...]
+
+Environment (required):
+  INTERCOM_BRIDGE_CA    Path to trusted bridge CA certificate
+  INTERCOM_BRIDGE_CERT  Path to your client certificate
+  INTERCOM_BRIDGE_KEY   Path to your private client key (owned, mode 0600)
+  INTERCOM_BRIDGE_URL   HTTPS origin (default: https://127.0.0.1:9443)
+
+Options:
+  --to PEER            Recipient name or ID for send/ask
+  --message TEXT       Message for send/ask/reply
+  --reply-to ID        Inbound ask ID from inbox, for reply
+  --timeout-ms MS      Ask timeout (100..120000, default: 120000)
+  -h, --help           Show help
+
+Examples:
+  node intercom-remote.mjs list
+  node intercom-remote.mjs ask --to planner --message 'What is the current status?'
+  node intercom-remote.mjs inbox
+  node intercom-remote.mjs reply --reply-to QUESTION_ID --message 'Proceed.'
+  node intercom-remote.mjs ack MESSAGE_ID
+
+Outputs JSON. Exit: 0 success, 1 API/TLS/transport failure, 2 invalid arguments.
+No automatic retries: a lost response does not prove a message was unsent.`);
+}
+
+let options, body, action, origin, timeout;
+try {
+  const parsed = parseArgs({ allowPositionals: true, options: {
+    help: { type: "boolean", short: "h" }, to: { type: "string" }, message: { type: "string" },
+    "reply-to": { type: "string" }, "timeout-ms": { type: "string" },
+  } });
+  if (parsed.values.help) { help(); process.exit(0); }
+  options = parsed.values;
+  [action] = parsed.positionals;
+  if (!["register", "list", "inbox", "send", "ask", "reply", "ack"].includes(action)) throw new Error("Choose an action; use --help.");
+  const allowed = ["send", "ask"].includes(action) ? ["to", "message", ...(action === "ask" ? ["timeout-ms"] : [])] : action === "reply" ? ["reply-to", "message"] : [];
+  if (Object.keys(options).some((key) => !allowed.includes(key)) ||
+      (action !== "ack" && parsed.positionals.length !== 1)) throw new Error("Unexpected arguments for this action.");
+  timeout = options["timeout-ms"] === undefined ? 120000 : Number(options["timeout-ms"]);
+  if (!Number.isInteger(timeout) || timeout < 100 || timeout > 120000) throw new Error("--timeout-ms must be 100..120000.");
+  body = ["send", "ask"].includes(action) ? { to: options.to, message: options.message, ...(action === "ask" ? { timeoutMs: timeout } : {}) }
+    : action === "reply" ? { replyTo: options["reply-to"], message: options.message }
+    : action === "ack" ? { ids: parsed.positionals.slice(1) } : {};
+  if (["send", "ask", "reply"].includes(action) && (!body.message?.trim() || !(action === "reply" ? body.replyTo : body.to)?.trim())) throw new Error("Recipient/ask ID and message are required.");
+  if (action === "ack" && body.ids.length === 0) throw new Error("ack needs at least one message ID.");
+  origin = new URL(process.env.INTERCOM_BRIDGE_URL || "https://127.0.0.1:9443");
+  if (origin.protocol !== "https:" || origin.username || origin.password || origin.pathname !== "/" || origin.search || origin.hash) throw new Error("INTERCOM_BRIDGE_URL must be an HTTPS origin, without credentials or a path.");
+} catch (error) {
+  console.error(JSON.stringify({ ok: false, error: { code: "invalid_arguments", message: error.message } }));
+  process.exit(2);
+}
+
+try {
+  const files = {};
+  for (const field of ["CA", "CERT", "KEY"]) {
+    const path = process.env[`INTERCOM_BRIDGE_${field}`];
+    if (!path) throw new Error(`INTERCOM_BRIDGE_${field} is required.`);
+    if (field === "KEY") {
+      const st = lstatSync(path);
+      if (!st.isFile() || st.uid !== process.getuid() || (st.mode & 0o077)) throw new Error("Client key must be an owned private regular file (0600).");
+    }
+    files[field] = readFileSync(path);
+  }
+  origin.pathname = `/v1/${action}`;
+  const payload = JSON.stringify(body);
+  const get = ["list", "inbox"].includes(action);
+  const result = await new Promise((resolve, reject) => {
+    const req = https.request(origin, {
+      method: get ? "GET" : "POST", ca: files.CA, cert: files.CERT, key: files.KEY,
+      rejectUnauthorized: true, minVersion: "TLSv1.2", agent: false,
+      headers: get ? {} : { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(payload) },
+    }, (res) => {
+      const chunks = [];
+      let bytes = 0;
+      res.on("data", (chunk) => {
+        bytes += chunk.length;
+        if (bytes > 16 * 1024 * 1024) { req.destroy(new Error("Bridge response exceeds 16 MiB.")); return; }
+        chunks.push(chunk);
+      });
+      res.on("error", reject);
+      res.on("end", () => {
+        try { resolve({ status: res.statusCode, value: JSON.parse(Buffer.concat(chunks).toString("utf8")) }); }
+        catch { reject(new Error("Bridge returned invalid JSON.")); }
+      });
+    });
+    const timer = setTimeout(() => req.destroy(new Error("Bridge request deadline exceeded; delivery may be unknown.")), (action === "ask" ? timeout : 0) + 15000);
+    req.once("close", () => clearTimeout(timer));
+    req.once("error", reject);
+    req.end(get ? undefined : payload);
+  });
+  console.log(JSON.stringify(result.value, null, 2));
+  if (result.status < 200 || result.status >= 300 || result.value?.ok !== true) process.exitCode = 1;
+} catch (error) {
+  console.error(JSON.stringify({ ok: false, error: { code: "transport_error", message: error.message, delivery: "unknown; do not blindly retry mutations" } }));
+  process.exitCode = 1;
+}

package/scripts/linux-smoke.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  printf '%s\n' 'Usage: bash scripts/linux-smoke.sh
+
+Validate committed HEAD in Docker against a credential-free, prebuilt Pi 1.0
+Linux archive with a single top-level pi/ directory and built SDK/CLI output.
+
+Example:
+  PI_LINUX_PI_ARCHIVE=/tmp/pi-linux.tar.gz bash scripts/linux-smoke.sh
+
+Environment:
+  PI_LINUX_PI_ARCHIVE  Absolute archive path (required)
+  PI_LINUX_IMAGE      Node 24.21.0+ Linux image (default: node:24-bookworm)
+
+Exit codes: 0 passed; 1 validation failed; 2 invalid arguments.'
+  exit 0
+fi
+if [[ $# -ne 0 ]]; then
+  printf '%s\n' 'No arguments accepted; use --help.' >&2
+  exit 2
+fi
+: "${PI_LINUX_PI_ARCHIVE:?Set PI_LINUX_PI_ARCHIVE to an absolute path to a credential-free prebuilt Linux Pi 1.0 .tar.gz (top-level pi/) with its Linux dependencies and built SDK/CLI.}"
+
+# Validate committed HEAD without passing host credentials or mounting the checkout.
+git -C "$(dirname "$0")/.." archive HEAD | docker run --rm --init -i \
+  --mount "type=bind,src=$PI_LINUX_PI_ARCHIVE,dst=/native-pi.tar.gz,readonly" \
+  "${PI_LINUX_IMAGE:-node:24-bookworm}" bash -c '
+set -euo pipefail
+mkdir /workspace /native-pi
+tar -xf - -C /workspace
+tar -xzf /native-pi.tar.gz -C /native-pi --strip-components=1
+chown -R node:node /workspace /native-pi
+runuser -u node -- bash -c '\''
+set -euo pipefail
+cd /workspace
+node --version
+npm --version
+uname -sm
+npm ci
+ln -sf /native-pi/packages/coding-agent/dist/bundle/cli.js node_modules/.bin/pi
+export PI_INTERCOM_TEST_SDK=/native-pi/packages/coding-agent
+export PI_OWNERSHIP_TEST_PACKAGE_ROOT="$PI_INTERCOM_TEST_SDK"
+export PI_CONTEXT_TEST_PACKAGE_ROOT="$PI_INTERCOM_TEST_SDK"
+export PI_PACKAGE_DIR="$PI_INTERCOM_TEST_SDK"
+export PATH="$PWD/node_modules/.bin:$PATH"
+pi --version
+npm run ci
+'\''
+'

package/scripts/local-install-smoke.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import process from "node:process";
+import { hostCli } from "./compat-host.mjs";
+
+if (process.argv.includes("--help") || process.argv.includes("-h")) {
+	console.log(`Usage: node scripts/local-install-smoke.mjs\n\nInstalls this repository into an isolated temporary Pi home, then verifies pi list\ncan resolve the single package. User-level Pi settings are not modified.\n\nExit codes:\n  0  local path install/list smoke passed\n  1  pi install or pi list failed, or the installed package was not listed`);
+	process.exit(0);
+}
+
+function isolatedEnv(home) {
+	const env = { ...process.env };
+	for (const key of Object.keys(env)) if (key.startsWith("PI_SUBAGENT_")) delete env[key];
+	return {
+		...env,
+		HOME: home,
+		XDG_CONFIG_HOME: join(home, ".config"),
+		XDG_CACHE_HOME: join(home, ".cache"),
+		PI_CODING_AGENT_DIR: join(home, ".pi", "agent"),
+		PI_OFFLINE: "1",
+		PATH: process.env.PATH ?? "",
+	};
+}
+
+function runPi(args, env) {
+	const result = spawnSync(process.execPath, [hostCli, ...args], {
+		cwd: process.cwd(),
+		env,
+		encoding: "utf-8",
+		stdio: ["ignore", "pipe", "pipe"],
+	});
+	return {
+		ok: !result.error && result.status === 0,
+		output: result.error ? result.error.message : `${result.stdout ?? ""}${result.stderr ?? ""}`,
+		status: result.status,
+	};
+}
+
+function requireSuccess(label, result) {
+	if (result.ok) return;
+	throw new Error(`${label} failed with ${result.status ?? "spawn error"}:\n${result.output}`);
+}
+
+const repoRoot = resolve(process.cwd());
+const home = mkdtempSync(join(tmpdir(), "pi-subagents-install-smoke-"));
+
+try {
+	const env = isolatedEnv(home);
+	requireSuccess("pi install pi-subagents", runPi(["install", repoRoot, "--approve"], env));
+
+	const list = runPi(["list", "--approve"], env);
+	requireSuccess("pi list", list);
+	if (!list.output.includes(repoRoot)) {
+		throw new Error(`pi list did not include installed local path ${repoRoot}:\n${list.output}`);
+	}
+
+	console.log("[local-install-smoke] installed and listed the single pi-subagents package with bundled intercom");
+} catch (error) {
+	console.error(`[local-install-smoke] ${error instanceof Error ? error.message : String(error)}`);
+	process.exitCode = 1;
+} finally {
+	rmSync(home, { recursive: true, force: true });
+}

package/scripts/native-package-smoke.mjs

@@ -0,0 +1,82 @@
+// Full runtime-only package: native SDK + bundled CLI, one private Intercom broker, no model calls.
+import assert from "node:assert/strict";
+import { spawn, spawnSync } from "node:child_process";
+import { once } from "node:events";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { pathToFileURL } from "node:url";
+import { hostCli, hostIndex, hostRoot } from "./compat-host.mjs";
+
+const packageRoot = resolve(process.argv[2] ?? ".");
+const root = mkdtempSync(join(tmpdir(), "ps-native-"));
+const agentDir = join(root, "agent");
+mkdirSync(agentDir);
+Object.assign(process.env, { HOME: root, USERPROFILE: root, PI_CODING_AGENT_DIR: agentDir, PI_SUBAGENT_TEMP_ROOT: join(root, "pi-subagents-runs"), PI_OFFLINE: "1", PI_TELEMETRY: "0", PI_PACKAGE_DIR: hostRoot });
+// A pruned extension cannot discover the embedding SDK via its own node_modules or PATH.
+// PI_PACKAGE_DIR is the existing detached-runtime host contract, not a loader workaround.
+const sdk = await import(pathToFileURL(hostIndex).href);
+const broker = spawn(process.execPath, [join(packageRoot, "dist/pi-intercom/broker/broker.js")], { cwd: root, env: process.env, stdio: ["ignore", "pipe", "pipe"] });
+let brokerLog = "";
+broker.stdout.on("data", data => { brokerLog += data; });
+broker.stderr.on("data", data => { brokerLog += data; });
+let session;
+try {
+  for (let i = 0; !brokerLog.includes("Intercom broker started"); i++) {
+    assert.ok(i < 100 && broker.exitCode === null, brokerLog || "Private broker did not start");
+    await delay(50);
+  }
+  const settingsManager = sdk.SettingsManager.inMemory({ packages: [packageRoot], compaction: { enabled: false }, retry: { enabled: false } });
+  const loader = new sdk.DefaultResourceLoader({ cwd: root, agentDir, settingsManager, noSkills: true, noContextFiles: true, noPromptTemplates: true, noThemes: true });
+  await loader.reload();
+  assert.deepEqual(loader.getExtensions().errors, []);
+  assert.deepEqual(loader.getExtensions().warnings ?? [], []);
+  assert.equal(loader.getExtensions().extensions.length, 2);
+  const modelRuntime = await sdk.ModelRuntime.create({ authPath: join(agentDir, "auth.json"), modelsPath: null, modelsStorePath: join(agentDir, "models-store.json"), allowModelNetwork: false });
+  ({ session } = await sdk.createAgentSession({ cwd: root, agentDir, settingsManager, resourceLoader: loader, modelRuntime, sessionManager: sdk.SessionManager.create(root, join(root, "sessions")), noTools: "builtin" }));
+  const errors = [];
+  await session.bindExtensions({ mode: "print", onError: error => errors.push(error) });
+  for (const name of ["delegate", "load_subagent", "load_intercom"]) assert.ok(session.getActiveToolNames().includes(name), name);
+  for (const name of ["agent_runs", "subagent", "intercom"]) assert.ok(!session.getActiveToolNames().includes(name), `${name} starts lazy`);
+  await session.agent.state.tools.find(tool => tool.name === "load_subagent").execute("controls", { advanced: false }, new AbortController().signal);
+  assert.ok(session.getActiveToolNames().includes("agent_runs"));
+  assert.ok(!session.getActiveToolNames().includes("subagent"));
+  await session.agent.state.tools.find(tool => tool.name === "load_intercom").execute("peers", {}, new AbortController().signal);
+  const status = await session.agent.state.tools.find(tool => tool.name === "intercom").execute("status", { action: "status" }, new AbortController().signal);
+  assert.match(JSON.stringify(status.content), /Connected: Yes/);
+  const runs = await session.agent.state.tools.find(tool => tool.name === "agent_runs").execute("history-list", { action: "list" }, new AbortController().signal);
+  assert.notEqual(runs.isError, true, JSON.stringify(runs.content));
+  assert.equal(runs.details.runList.total, 0);
+  assert.deepEqual(errors, []);
+  const marker = join(root, "cli.json");
+  const observer = join(root, "observer.ts");
+  writeFileSync(observer, `import { writeFileSync } from "node:fs";
+import { SubagentHistoryIndex } from ${JSON.stringify(join(packageRoot, "dist/history/index.js"))};
+export default function(pi) { pi.on("session_start", async (_event, ctx) => {
+const index = new SubagentHistoryIndex(${JSON.stringify(agentDir)});
+try {
+  await index.setOwner({ ownerSessionId: ctx.sessionManager.getSessionId(), runs: [] });
+  const history = await index.listRuns();
+  writeFileSync(${JSON.stringify(marker)}, JSON.stringify({ tools: pi.getActiveTools(), commands: pi.getCommands().map(c => c.name), historyRuns: history.total }));
+} finally { await index.close(); ctx.shutdown(); }
+}); }`);
+  const cliEnv = { ...process.env, PATH: "/usr/bin:/bin" };
+  delete cliEnv.PI_PACKAGE_DIR; // Ordinary CLI consumers locate their host through argv, unlike detached SDK embeddings.
+  const child = spawnSync(process.execPath, [hostCli, "--mode", "rpc", "--no-session", "-ne", "-ns", "-np", "-nc", "--no-themes", "--approve", "-e", packageRoot, "-e", observer], { cwd: root, env: cliEnv, input: "", encoding: "utf8", timeout: 30_000 });
+  assert.equal(child.status, 0, `${child.error ?? ""}\n${child.stderr}`);
+  assert.doesNotMatch(child.stderr, /Failed to load extension|ERR_INTERNAL_ASSERTION|Extension error/);
+  const observed = JSON.parse(readFileSync(marker, "utf8"));
+  assert.equal(observed.historyRuns, 0, "CLI workers must inherit the selected host without Pi on PATH");
+  for (const name of ["delegate", "load_subagent", "load_intercom"]) assert.ok(observed.tools.includes(name), name);
+  for (const name of ["agent_runs", "subagent", "intercom"]) assert.ok(!observed.tools.includes(name), `${name} starts lazy in CLI`);
+  assert.ok(observed.commands.includes("subagents-doctor"));
+  console.log("[native-package-smoke] both compiled entries, history worker, broker registration/status, bundled RPC startup, and shutdown passed");
+} finally {
+  try {
+    if (session) { await session.extensionRunner.emit({ type: "session_shutdown", reason: "quit" }); session.dispose(); }
+  } finally {
+    if (broker.exitCode === null) { const exited = once(broker, "exit"); broker.kill("SIGTERM"); await exited; }
+    rmSync(root, { recursive: true, force: true });
+  }
+}