@h-rig/cli 0.0.6-alpha.6 → 0.0.6-alpha.61

package/dist/src/commands/inspect.js

@@ -1,14 +1,12 @@
 // @bun
 // packages/cli/src/commands/inspect.ts
-import { existsSync, readFileSync } from "fs";
-import { resolve } from "path";
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
+import { resolve as resolve3 } from "path";
 
 // packages/cli/src/runner.ts
 import { EventBus } from "@rig/runtime/control-plane/runtime/events";
 import { CliError } from "@rig/runtime/control-plane/errors";
 import { evaluate, loadPolicy, resolveAction } from "@rig/runtime/control-plane/runtime/guard";
-import { PluginManager } from "@rig/runtime/control-plane/runtime/plugins";
-import { loadRuntimeContextFromEnv } from "@rig/runtime/control-plane/runtime/context";
 import { buildBinary } from "@rig/runtime/control-plane/runtime/isolation";
 import { CliError as CliError2 } from "@rig/runtime/control-plane/errors";
 function takeOption(args, option) {
@@ -55,19 +53,294 @@ import {
 import { changedFilesForTask } from "@rig/runtime/control-plane/native/task-ops";
 import { resolveHarnessPaths, resolveMonorepoRoot, runCapture } from "@rig/runtime/control-plane/native/utils";
 import { readTaskArtifactPreview } from "@rig/runtime/control-plane/native/workspace-ops";
+
+// packages/cli/src/commands/_server-client.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { resolve as resolve2 } from "path";
+import { ensureLocalRigServerConnection } from "@rig/runtime/local-server";
+
+// packages/cli/src/commands/_connection-state.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, resolve } from "path";
+function resolveGlobalConnectionsPath(env = process.env) {
+  const explicit = env.RIG_CONNECTIONS_FILE?.trim();
+  if (explicit)
+    return resolve(explicit);
+  const stateDir = env.RIG_GLOBAL_STATE_DIR?.trim();
+  if (stateDir)
+    return resolve(stateDir, "connections.json");
+  return resolve(homedir(), ".rig", "connections.json");
+}
+function resolveRepoConnectionPath(projectRoot) {
+  return resolve(projectRoot, ".rig", "state", "connection.json");
+}
+function readJsonFile(path) {
+  if (!existsSync(path))
+    return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    throw new CliError2(`Invalid Rig connection state at ${path}: ${error instanceof Error ? error.message : String(error)}`, 1);
+  }
+}
+function writeJsonFile(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+}
+function normalizeConnection(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return null;
+  const record = value;
+  if (record.kind === "local")
+    return { kind: "local", mode: "auto" };
+  if (record.kind === "remote" && typeof record.baseUrl === "string" && record.baseUrl.trim()) {
+    const baseUrl = record.baseUrl.trim().replace(/\/+$/, "");
+    return { kind: "remote", baseUrl };
+  }
+  return null;
+}
+function readGlobalConnections(options = {}) {
+  const path = resolveGlobalConnectionsPath(options.env ?? process.env);
+  const payload = readJsonFile(path);
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    return { connections: {} };
+  }
+  const rawConnections = payload.connections;
+  const connections = {};
+  if (rawConnections && typeof rawConnections === "object" && !Array.isArray(rawConnections)) {
+    for (const [alias, raw] of Object.entries(rawConnections)) {
+      const connection = normalizeConnection(raw);
+      if (connection)
+        connections[alias] = connection;
+    }
+  }
+  return { connections };
+}
+function readRepoConnection(projectRoot) {
+  const payload = readJsonFile(resolveRepoConnectionPath(projectRoot));
+  if (!payload || typeof payload !== "object" || Array.isArray(payload))
+    return null;
+  const record = payload;
+  const selected = typeof record.selected === "string" ? record.selected.trim() : "";
+  if (!selected)
+    return null;
+  return {
+    selected,
+    project: typeof record.project === "string" ? record.project : undefined,
+    linkedAt: typeof record.linkedAt === "string" ? record.linkedAt : undefined,
+    serverProjectRoot: typeof record.serverProjectRoot === "string" && record.serverProjectRoot.trim() ? record.serverProjectRoot.trim() : undefined
+  };
+}
+function writeRepoConnection(projectRoot, state) {
+  writeJsonFile(resolveRepoConnectionPath(projectRoot), state);
+}
+function resolveSelectedConnection(projectRoot, options = {}) {
+  const repo = readRepoConnection(projectRoot);
+  if (!repo)
+    return null;
+  if (repo.selected === "local")
+    return { alias: "local", connection: { kind: "local", mode: "auto" }, serverProjectRoot: repo.serverProjectRoot };
+  const global = readGlobalConnections(options);
+  const connection = global.connections[repo.selected];
+  if (!connection) {
+    throw new CliError2(`Selected Rig server "${repo.selected}" was not found. Run \`rig server list\` or \`rig server use local\`.`, 1);
+  }
+  return { alias: repo.selected, connection, serverProjectRoot: repo.serverProjectRoot };
+}
+function writeRepoServerProjectRoot(projectRoot, serverProjectRoot) {
+  const repo = readRepoConnection(projectRoot);
+  if (!repo)
+    return;
+  writeRepoConnection(projectRoot, { ...repo, serverProjectRoot });
+}
+
+// packages/cli/src/commands/_server-client.ts
+var scopedGitHubBearerTokens = new Map;
+function cleanToken(value) {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : null;
+}
+function readPrivateRemoteSessionToken(projectRoot) {
+  const path = resolve2(projectRoot, ".rig", "state", "github-auth.json");
+  if (!existsSync2(path))
+    return null;
+  try {
+    const parsed = JSON.parse(readFileSync2(path, "utf8"));
+    return cleanToken(typeof parsed.apiSessionToken === "string" ? parsed.apiSessionToken : typeof parsed.sessionToken === "string" ? parsed.sessionToken : undefined);
+  } catch {
+    return null;
+  }
+}
+function readGitHubBearerTokenForRemote(projectRoot) {
+  const scopedKey = resolve2(projectRoot);
+  if (scopedGitHubBearerTokens.has(scopedKey))
+    return scopedGitHubBearerTokens.get(scopedKey) ?? null;
+  const privateSession = readPrivateRemoteSessionToken(projectRoot);
+  if (privateSession)
+    return privateSession;
+  return cleanToken(process.env.RIG_SERVER_AUTH_TOKEN) ?? cleanToken(process.env.RIG_REMOTE_AUTH_TOKEN);
+}
+function readStoredGitHubAuthToken(projectRoot) {
+  const path = resolve2(projectRoot, ".rig", "state", "github-auth.json");
+  if (!existsSync2(path))
+    return null;
+  try {
+    const parsed = JSON.parse(readFileSync2(path, "utf8"));
+    return cleanToken(typeof parsed.token === "string" ? parsed.token : undefined);
+  } catch {
+    return null;
+  }
+}
+function readLocalConnectionFallbackToken(projectRoot) {
+  return readGitHubBearerTokenForRemote(projectRoot) ?? cleanToken(process.env.RIG_GITHUB_TOKEN) ?? readStoredGitHubAuthToken(projectRoot);
+}
+async function ensureServerForCli(projectRoot) {
+  try {
+    const selected = resolveSelectedConnection(projectRoot);
+    if (selected?.connection.kind === "remote") {
+      const authToken = readGitHubBearerTokenForRemote(projectRoot);
+      const serverProjectRoot = selected.serverProjectRoot ?? await backfillRemoteServerProjectRoot(projectRoot, selected.connection.baseUrl, authToken);
+      return {
+        baseUrl: selected.connection.baseUrl,
+        authToken,
+        connectionKind: "remote",
+        serverProjectRoot
+      };
+    }
+    const connection = await ensureLocalRigServerConnection(projectRoot);
+    return {
+      baseUrl: connection.baseUrl,
+      authToken: connection.authToken ?? readLocalConnectionFallbackToken(projectRoot),
+      connectionKind: "local",
+      serverProjectRoot: resolve2(projectRoot)
+    };
+  } catch (error) {
+    if (error instanceof Error) {
+      throw new CliError2(error.message, 1);
+    }
+    throw error;
+  }
+}
+async function backfillRemoteServerProjectRoot(projectRoot, baseUrl, authToken) {
+  const repo = readRepoConnection(projectRoot);
+  const slug = repo?.project?.trim();
+  if (!slug)
+    return null;
+  try {
+    const response = await fetch(`${baseUrl}/api/projects/${encodeURIComponent(slug)}`, {
+      headers: mergeHeaders(undefined, authToken)
+    });
+    if (!response.ok)
+      return null;
+    const payload = await response.json();
+    const project = payload.project && typeof payload.project === "object" && !Array.isArray(payload.project) ? payload.project : null;
+    const checkouts = Array.isArray(project?.checkouts) ? project.checkouts : [];
+    const latestCheckout = [...checkouts].reverse().find((entry) => Boolean(entry && typeof entry === "object" && !Array.isArray(entry) && typeof entry.path === "string"));
+    const path = typeof latestCheckout?.path === "string" && latestCheckout.path.trim() ? latestCheckout.path.trim() : null;
+    if (path)
+      writeRepoServerProjectRoot(projectRoot, path);
+    return path;
+  } catch {
+    return null;
+  }
+}
+function mergeHeaders(headers, authToken) {
+  const merged = new Headers(headers);
+  if (authToken) {
+    merged.set("authorization", `Bearer ${authToken}`);
+  }
+  return merged;
+}
+function diagnosticMessage(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload))
+    return null;
+  const record = payload;
+  const diagnostics = Array.isArray(record.diagnostics) ? record.diagnostics : [];
+  const messages = diagnostics.flatMap((entry) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry))
+      return [];
+    const diagnostic = entry;
+    const kind = typeof diagnostic.kind === "string" ? diagnostic.kind : "task-source";
+    const message = typeof diagnostic.message === "string" ? diagnostic.message : null;
+    return message ? [`${kind}: ${message}`] : [];
+  });
+  return messages.length > 0 ? messages.join("; ") : null;
+}
+async function requestServerJson(context, pathname, init = {}) {
+  const server = await ensureServerForCli(context.projectRoot);
+  const headers = mergeHeaders(init.headers, server.authToken);
+  if (server.serverProjectRoot)
+    headers.set("x-rig-project-root", server.serverProjectRoot);
+  const response = await fetch(`${server.baseUrl}${pathname}`, {
+    ...init,
+    headers
+  });
+  const text = await response.text();
+  const payload = text.trim().length > 0 ? (() => {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return null;
+    }
+  })() : null;
+  if (!response.ok) {
+    const diagnostics = diagnosticMessage(payload);
+    const detail = diagnostics ?? (text || response.statusText);
+    throw new CliError2(`Rig server request failed (${response.status}): ${detail}`, 1);
+  }
+  return payload;
+}
+async function listRunsViaServer(context, options = {}) {
+  const url = new URL("http://rig.local/api/runs");
+  if (options.limit !== undefined)
+    url.searchParams.set("limit", String(options.limit));
+  const payload = await requestServerJson(context, `${url.pathname}${url.search}`);
+  const runs = Array.isArray(payload) ? payload : payload && typeof payload === "object" && !Array.isArray(payload) && Array.isArray(payload.runs) ? payload.runs : [];
+  return runs.filter((entry) => Boolean(entry && typeof entry === "object" && !Array.isArray(entry)));
+}
+async function getRunLogsViaServer(context, runId, options = {}) {
+  const url = new URL(`http://rig.local/api/runs/${encodeURIComponent(runId)}/logs`);
+  if (options.limit !== undefined)
+    url.searchParams.set("limit", String(options.limit));
+  if (options.cursor)
+    url.searchParams.set("cursor", options.cursor);
+  const payload = await requestServerJson(context, `${url.pathname}${url.search}`);
+  return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { entries: [] };
+}
+
+// packages/cli/src/commands/inspect.ts
 async function executeInspect(context, args) {
   const [command = "failures", ...rest] = args;
   switch (command) {
     case "logs": {
       const { value: task, rest: remaining } = takeOption(rest, "--task");
-      requireNoExtraArgs(remaining, "bun run rig inspect logs --task <beads-id>");
-      const requiredTask = requireTask(task, "bun run rig inspect logs --task <beads-id>");
+      requireNoExtraArgs(remaining, "rig inspect logs --task <task-id>");
+      const requiredTask = requireTask(task, "rig inspect logs --task <task-id>");
       const latestRun = listAuthorityRuns(context.projectRoot).map((entry) => readAuthorityRun(context.projectRoot, entry.runId)).filter((run) => Boolean(run)).filter((run) => run.taskId === requiredTask).sort((left, right) => String(right.updatedAt ?? "").localeCompare(String(left.updatedAt ?? "")))[0];
       if (!latestRun) {
-        throw new CliError2(`No runs found for ${requiredTask}.`);
+        const serverRuns = await listRunsViaServer(context, { limit: 200 }).catch(() => []);
+        const serverRun = serverRuns.filter((run) => String(run.taskId ?? "") === requiredTask).sort((left, right) => String(right.updatedAt ?? "").localeCompare(String(left.updatedAt ?? "")))[0];
+        if (!serverRun || typeof serverRun.runId !== "string") {
+          throw new CliError2(`No runs found for ${requiredTask} (local or on the selected server).`);
+        }
+        const page = await getRunLogsViaServer(context, serverRun.runId, { limit: 500 });
+        const entries = Array.isArray(page.entries) ? page.entries : [];
+        if (context.outputMode === "text") {
+          for (const entry of entries) {
+            const record = entry && typeof entry === "object" ? entry : {};
+            const title = String(record.title ?? "");
+            const detail = String(record.detail ?? "");
+            console.log([title, detail].filter(Boolean).join(" \u2014 "));
+          }
+          if (entries.length === 0)
+            console.log(`(no log entries for run ${serverRun.runId})`);
+        }
+        return { ok: true, group: "inspect", command, details: { task: requiredTask, runId: serverRun.runId, source: "server", entries } };
       }
-      const logsPath = resolve(resolveAuthorityRunDir(context.projectRoot, latestRun.runId), "logs.jsonl");
-      if (!existsSync(logsPath)) {
+      const logsPath = resolve3(resolveAuthorityRunDir(context.projectRoot, latestRun.runId), "logs.jsonl");
+      if (!existsSync3(logsPath)) {
         throw new CliError2(`No logs found for run ${latestRun.runId}.`);
       }
       await context.runCommand(["cat", logsPath]);
@@ -75,9 +348,9 @@ async function executeInspect(context, args) {
     }
     case "artifacts": {
       const { value: task, rest: remaining } = takeOption(rest, "--task");
-      requireNoExtraArgs(remaining, "bun run rig inspect artifacts --task <beads-id>");
-      const requiredTask = requireTask(task, "bun run rig inspect artifacts --task <beads-id>");
-      const artifactRoot = resolveTaskArtifactDirs(context.projectRoot, requiredTask).find((path) => existsSync(path));
+      requireNoExtraArgs(remaining, "rig inspect artifacts --task <task-id>");
+      const requiredTask = requireTask(task, "rig inspect artifacts --task <task-id>");
+      const artifactRoot = resolveTaskArtifactDirs(context.projectRoot, requiredTask).find((path) => existsSync3(path));
       if (!artifactRoot) {
         throw new CliError2(`No artifacts found for ${requiredTask}.`);
       }
@@ -90,8 +363,8 @@ async function executeInspect(context, args) {
       previewPending = task.rest;
       const file = takeOption(previewPending, "--file");
       previewPending = file.rest;
-      requireNoExtraArgs(previewPending, "bun run rig inspect artifact --task <beads-id> --file <name>");
-      const requiredTask = requireTask(task.value, "bun run rig inspect artifact --task <beads-id> --file <name>");
+      requireNoExtraArgs(previewPending, "rig inspect artifact --task <task-id> --file <name>");
+      const requiredTask = requireTask(task.value, "rig inspect artifact --task <task-id> --file <name>");
       if (!file.value) {
         throw new CliError2("Missing --file for rig inspect artifact.");
       }
@@ -120,7 +393,7 @@ async function executeInspect(context, args) {
     }
     case "diff": {
       const { value: task, rest: remaining } = takeOption(rest, "--task");
-      requireNoExtraArgs(remaining, "bun run rig inspect diff [--task <beads-id>]");
+      requireNoExtraArgs(remaining, "rig inspect diff [--task <task-id>]");
       if (task) {
         const files = changedFilesForTask(context.projectRoot, task, false);
         for (const file of files) {
@@ -132,17 +405,17 @@ async function executeInspect(context, args) {
       return { ok: true, group: "inspect", command, details: { task: task || null } };
     }
     case "failures": {
-      requireNoExtraArgs(rest, "bun run rig inspect failures");
+      requireNoExtraArgs(rest, "rig inspect failures");
       const failed = resolveHarnessPaths(context.projectRoot).failedApproachesPath;
-      if (!existsSync(failed)) {
+      if (!existsSync3(failed)) {
         console.log("No failures recorded.");
       } else {
-        process.stdout.write(readFileSync(failed, "utf-8"));
+        process.stdout.write(readFileSync3(failed, "utf-8"));
       }
       return { ok: true, group: "inspect", command };
     }
     case "graph":
-      requireNoExtraArgs(rest, "bun run rig inspect graph");
+      requireNoExtraArgs(rest, "rig inspect graph");
       {
         const monorepoRoot = resolveMonorepoRoot(context.projectRoot);
         const result = runCapture(["br", "--no-db", "list", "--pretty"], monorepoRoot);
@@ -153,12 +426,12 @@ async function executeInspect(context, args) {
       }
       return { ok: true, group: "inspect", command };
     case "audit": {
-      requireNoExtraArgs(rest, "bun run rig inspect audit");
-      const auditPath = resolve(resolveHarnessPaths(context.projectRoot).logsDir, "audit.jsonl");
-      if (!existsSync(auditPath)) {
+      requireNoExtraArgs(rest, "rig inspect audit");
+      const auditPath = resolve3(resolveHarnessPaths(context.projectRoot).logsDir, "audit.jsonl");
+      if (!existsSync3(auditPath)) {
         console.log("No audit log found.");
       } else {
-        const lines = readFileSync(auditPath, "utf-8").split(/\r?\n/).filter(Boolean).slice(-20);
+        const lines = readFileSync3(auditPath, "utf-8").split(/\r?\n/).filter(Boolean).slice(-20);
         for (const line of lines) {
           console.log(line);
         }

package/dist/src/commands/inspector.js

@@ -6,8 +6,6 @@ import { iterateServerSentEvents } from "@rig/client";
 import { EventBus } from "@rig/runtime/control-plane/runtime/events";
 import { CliError } from "@rig/runtime/control-plane/errors";
 import { evaluate, loadPolicy, resolveAction } from "@rig/runtime/control-plane/runtime/guard";
-import { PluginManager } from "@rig/runtime/control-plane/runtime/plugins";
-import { loadRuntimeContextFromEnv } from "@rig/runtime/control-plane/runtime/context";
 import { buildBinary } from "@rig/runtime/control-plane/runtime/isolation";
 import { CliError as CliError2 } from "@rig/runtime/control-plane/errors";
 function takeFlag(args, flag) {
@@ -104,7 +102,7 @@ async function executeInspector(context, args) {
       pending = secondsResult.rest;
       const pollMsResult = takeOption(pending, "--poll-ms");
       pending = pollMsResult.rest;
-      requireNoExtraArgs(pending, "bun run rig inspector stream [--once] [--seconds <n>] [--poll-ms <n>]");
+      requireNoExtraArgs(pending, "rig inspector stream [--once] [--seconds <n>] [--poll-ms <n>]");
       const seconds = secondsResult.value ? parseRequiredPositiveInt(secondsResult.value, "--seconds") : null;
       const pollMs = pollMsResult.value ? parseRequiredPositiveInt(pollMsResult.value, "--poll-ms") : null;
       if (context.outputMode === "json" && !onceResult.value && !seconds) {
@@ -198,7 +196,7 @@ async function executeInspector(context, args) {
       let pending = rest;
       const scanIdResult = takeOption(pending, "--scan-id");
       pending = scanIdResult.rest;
-      requireNoExtraArgs(pending, "bun run rig inspector scan-upstream-drift [--scan-id <id>]");
+      requireNoExtraArgs(pending, "rig inspector scan-upstream-drift [--scan-id <id>]");
       const connection = await ensureLocalRigServerConnection(context.projectRoot);
       const response = await fetch(new URL("/api/inspector/tools/invoke", connection.baseUrl), {
         method: "POST",

package/dist/src/commands/pi.js

@@ -0,0 +1,168 @@
+// @bun
+// packages/cli/src/commands/pi.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, resolve } from "path";
+
+// packages/cli/src/runner.ts
+import { EventBus } from "@rig/runtime/control-plane/runtime/events";
+import { CliError } from "@rig/runtime/control-plane/errors";
+import { evaluate, loadPolicy, resolveAction } from "@rig/runtime/control-plane/runtime/guard";
+import { buildBinary } from "@rig/runtime/control-plane/runtime/isolation";
+import { CliError as CliError2 } from "@rig/runtime/control-plane/errors";
+function requireNoExtraArgs(args, usage) {
+  if (args.length > 0) {
+    throw new CliError(`Unexpected arguments: ${args.join(" ")}
+Usage: ${usage}`);
+  }
+}
+
+// packages/cli/src/commands/pi.ts
+function settingsPath(root) {
+  return resolve(root, ".pi", "settings.json");
+}
+function userSettingsPath() {
+  return resolve(homedir(), ".pi", "agent", "settings.json");
+}
+function readJson(path, fallback) {
+  if (!existsSync(path))
+    return fallback;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return fallback;
+  }
+}
+function packageKey(entry) {
+  if (typeof entry === "string")
+    return entry;
+  if (entry && typeof entry === "object" && typeof entry.source === "string") {
+    return entry.source;
+  }
+  return JSON.stringify(entry);
+}
+function writeSettings(path, settings) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(settings, null, 2)}
+`, "utf-8");
+}
+async function searchNpmForPiExtensions(term) {
+  const query = encodeURIComponent(term ? `${term} pi extension` : "pi extension");
+  const url = `https://registry.npmjs.org/-/v1/search?text=${query}&size=20`;
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new CliError2(`npm registry search failed (${response.status}).`, 2);
+  }
+  const payload = await response.json();
+  const results = [];
+  for (const entry of payload.objects ?? []) {
+    const pkg = entry.package;
+    if (!pkg?.name)
+      continue;
+    const keywords = (pkg.keywords ?? []).map((k) => k.toLowerCase());
+    const piLike = pkg.name.startsWith("pi-") || pkg.name.includes("-pi") || keywords.includes("pi") || keywords.includes("pi-extension") || (pkg.description ?? "").toLowerCase().includes("pi extension") || (pkg.description ?? "").toLowerCase().includes("pi coding agent");
+    if (!piLike)
+      continue;
+    results.push({ name: pkg.name, version: pkg.version ?? "", description: pkg.description ?? "" });
+  }
+  return results;
+}
+async function executePi(context, args) {
+  const [command = "list", ...rest] = args;
+  const projectSettingsPath = settingsPath(context.projectRoot);
+  const managedRecordPath = resolve(context.projectRoot, ".rig", "state", "pi-managed-packages.json");
+  switch (command) {
+    case "list": {
+      requireNoExtraArgs(rest, "rig pi list");
+      const project = readJson(projectSettingsPath, {});
+      const managed = new Set(readJson(managedRecordPath, []));
+      const user = readJson(userSettingsPath(), {});
+      const projectPackages = (Array.isArray(project.packages) ? project.packages : []).map((entry) => ({
+        source: packageKey(entry),
+        managedByRigConfig: managed.has(packageKey(entry))
+      }));
+      const userPackages = (Array.isArray(user.packages) ? user.packages : []).map(packageKey);
+      if (context.outputMode === "text") {
+        console.log("Project Pi packages (.pi/settings.json):");
+        if (projectPackages.length === 0)
+          console.log("  (none)");
+        for (const pkg of projectPackages) {
+          console.log(`  ${pkg.source}${pkg.managedByRigConfig ? "  [from rig.config runtime.pi.packages]" : ""}`);
+        }
+        console.log("User Pi packages (~/.pi/agent/settings.json):");
+        if (userPackages.length === 0)
+          console.log("  (none)");
+        for (const pkg of userPackages)
+          console.log(`  ${pkg}`);
+        console.log("Add more: `rig pi add <npm-package>` \xB7 discover: `rig pi search <term>`");
+      }
+      return { ok: true, group: "pi", command, details: { projectPackages, userPackages } };
+    }
+    case "add": {
+      const [source, ...extra] = rest;
+      requireNoExtraArgs(extra, "rig pi add <package-source>");
+      if (!source) {
+        throw new CliError2("Usage: rig pi add <package-source> (npm name, name@version, or git URL)", 2);
+      }
+      const settings = readJson(projectSettingsPath, {});
+      const packages = Array.isArray(settings.packages) ? settings.packages : [];
+      if (packages.some((entry) => packageKey(entry) === source)) {
+        throw new CliError2(`"${source}" is already in ${projectSettingsPath}.`, 2);
+      }
+      writeSettings(projectSettingsPath, { ...settings, packages: [...packages, source] });
+      if (context.outputMode === "text") {
+        console.log(`Added ${source} to ${projectSettingsPath}.`);
+        console.log("Pi installs missing packages automatically at the next session start (local and worker).");
+      }
+      return { ok: true, group: "pi", command, details: { source, settingsPath: projectSettingsPath } };
+    }
+    case "remove": {
+      const [source, ...extra] = rest;
+      requireNoExtraArgs(extra, "rig pi remove <package-source>");
+      if (!source) {
+        throw new CliError2("Usage: rig pi remove <package-source>", 2);
+      }
+      const managed = new Set(readJson(managedRecordPath, []));
+      if (managed.has(source)) {
+        throw new CliError2(`"${source}" is managed by rig.config.ts (runtime.pi.packages); remove it there instead.`, 2);
+      }
+      const settings = readJson(projectSettingsPath, {});
+      const packages = Array.isArray(settings.packages) ? settings.packages : [];
+      const next = packages.filter((entry) => packageKey(entry) !== source);
+      if (next.length === packages.length) {
+        throw new CliError2(`"${source}" is not in ${projectSettingsPath}.`, 2);
+      }
+      const nextSettings = { ...settings };
+      if (next.length > 0)
+        nextSettings.packages = next;
+      else
+        delete nextSettings.packages;
+      writeSettings(projectSettingsPath, nextSettings);
+      if (context.outputMode === "text") {
+        console.log(`Removed ${source} from ${projectSettingsPath}.`);
+      }
+      return { ok: true, group: "pi", command, details: { source } };
+    }
+    case "search": {
+      const term = rest.join(" ").trim();
+      const results = await searchNpmForPiExtensions(term);
+      if (context.outputMode === "text") {
+        if (results.length === 0) {
+          console.log(`No Pi extension packages found on npm${term ? ` for "${term}"` : ""}.`);
+        } else {
+          console.log(`Pi extension packages on npm${term ? ` matching "${term}"` : ""}:`);
+          for (const pkg of results) {
+            console.log(`  ${pkg.name}@${pkg.version}  ${pkg.description.slice(0, 80)}`);
+          }
+          console.log("Install one: `rig pi add <name>`");
+        }
+      }
+      return { ok: true, group: "pi", command, details: { term, results } };
+    }
+    default:
+      throw new CliError2(`Unknown pi command: ${command}. Use list|add|remove|search.`);
+  }
+}
+export {
+  executePi
+};