@piagent/platform 1.43.9 → 1.44.2

package/scripts/company-terminal.mjs

@@ -9,6 +9,7 @@ import { execFile } from 'node:child_process';
 import { pathToFileURL } from 'node:url';
 
 import { registerTerminalUpdateOffer } from '../packages/piagent-core/runtime/update/terminal-update-offer.mjs';
+import { registerStyleCommand } from '../packages/piagent-core/runtime/terminal/terminal-style.mjs';
 import { parseFailure } from '../packages/piagent-core/runtime/managed-failure.mjs';
 import { checkpointsOf } from '../packages/piagent-core/managed/checkpoints.mjs';
 import { bypassAllowed, effectivePermission } from '../packages/piagent-core/managed/permission.mjs';
@@ -59,7 +60,7 @@ export function memoryResultLines(text, expanded = false) {
 const branchOf = (cwd) => new Promise((resolve) => execFile('git', ['-C', cwd, 'rev-parse', '--abbrev-ref', 'HEAD'], { timeout: 3000 },
   (error, out) => resolve(error ? null : String(out).trim() || null)));
 export const HELP_TEXT = [
-  'Cuộc trò chuyện công ty: /undo hoàn tác file lượt trước đã sửa · /bypass on|full|off|status quyền của cuộc trò chuyện · /fast on|off|status (khi Harness cho phép) · /skill:<tên> hoặc /<lệnh> của bạn và của project.',
+  'Cuộc trò chuyện công ty: /undo hoàn tác file lượt trước đã sửa · /bypass on|full|off|status quyền của cuộc trò chuyện · /fast on|off|status (khi Harness cho phép) · /style giao diện Terminal · /skill:<tên> hoặc /<lệnh> của bạn và của project.',
   'Pi: /session thông tin cuộc trò chuyện · /resume mở cuộc trò chuyện công ty khác · /new cuộc mới · /compact nén ngữ cảnh · /tree, /fork nhánh · /name đặt tên · /copy, /export · /hotkeys toàn bộ phím tắt · /quit thoát.',
   'Phím: ! <lệnh> chạy shell · Esc dừng lượt đang chạy · Ctrl+C xoá ô nhập, hai lần để thoát · Ctrl+O xem thêm.',
   'Mở lại sau: piagent studio --project <thư mục>, rồi /resume. Đừng mở cuộc trò chuyện công ty bằng pi cá nhân.',
@@ -112,7 +113,7 @@ export function companyCommandText(name, summary = {}) {
     case 'login': case 'logout': return 'Cuộc trò chuyện công ty dùng tài khoản AI của team qua Agent Watch: không cần /login hay /logout. Tài khoản và API key cá nhân chỉ dùng trong pi cá nhân.';
     case 'model': case 'scoped-models': return `Model do Harness của team quyết định${main}; Terminal không chọn model. ${ADMIN}`;
     case 'thinking': return `Mức suy luận do Harness của team quyết định${main}. ${ADMIN}`;
-    case 'settings': return `Cài đặt của cuộc trò chuyện công ty (compaction, retry…) do Harness quyết định. Phím tắt: /hotkeys. ${ADMIN}`;
+    case 'settings': return `Cài đặt của cuộc trò chuyện công ty (compaction, retry…) do Harness quyết định. Giao diện Terminal: /style. Phím tắt: /hotkeys. ${ADMIN}`;
     default: return null;
   }
 }
@@ -288,6 +289,9 @@ export function companyTerminalExtension({ managed, packageRoot, sdkRoot, bindin
     registerTerminalUpdateOffer(pi, { installed, packageRoot, restart: 'piagent studio',
       afterUpdate: () => bindingChanged() ? 'Bản mới đổi trình khởi chạy công ty: Agent Watch tự cập nhật cấu hình (cần Agent Watch đang chạy); piagent studio chờ việc này khi mở lại.' : null });
 
+    // The member's pick of look (/style); /settings is not offered here.
+    registerStyleCommand(pi, { remember: true });
+
     // Ask first or Bypass, kept with the conversation like the dashboard's switch.
     const showPermission = (ctx) => { const mode = managed() ? effectivePermission(managed()) : null; ctx.ui?.setStatus?.(PERMISSION_STATUS, mode && mode !== 'workspace-write' ? PERMISSION_NAME[mode] : undefined); };
     pi.on('session_start', async (_event, ctx) => showPermission(ctx));

package/scripts/install-global.sh

@@ -701,7 +701,19 @@ else
   if [[ "$pi_version_output" =~ ([0-9]+\.[0-9]+\.[0-9]+([+-][0-9A-Za-z.-]+)?) ]]; then
     current_pi_version="${BASH_REMATCH[1]}"
   fi
-  if [[ "$current_pi_version" != "$EXPECTED_PI_VERSION" ]]; then
+  pi_host_plan="$(node --input-type=module -e 'const { hostPlan } = await import(process.argv[1]); process.stdout.write(hostPlan(process.argv[2] || null));' "$PLATFORM_ROOT/packages/piagent-core/managed/pi-host.mjs" "$current_pi_version")"
+  if [[ "$pi_host_plan" == "private" ]]; then
+    # The member's own, newer pi stays: it loads the Piagent package as any Pi
+    # package, and company sessions and `piagent pi` run the private pinned host.
+    echo "NOTE: your pi $current_pi_version stays as it is; Piagent is qualified on Pi $EXPECTED_PI_VERSION." >&2
+    pi_host_args=(ensure --force)
+    [[ "$DRY_RUN" == true ]] && pi_host_args+=(--dry-run)
+    if ! node "$PLATFORM_ROOT/scripts/pi-host.mjs" "${pi_host_args[@]}" >&2; then
+      echo "FAIL: could not install the private Pi $EXPECTED_PI_VERSION." >&2
+      exit 1
+    fi
+    echo "NOTE: run \`piagent pi\` for the qualified release; \`pi\` ($current_pi_version) loads Piagent too, unqualified." >&2
+  elif [[ "$current_pi_version" != "$EXPECTED_PI_VERSION" ]]; then
     echo "FAIL: Pi Coding Agent $EXPECTED_PI_VERSION is required; found ${current_pi_version:-${pi_version_output:-unknown}}." >&2
     echo "Install the supported host with: npm install -g --ignore-scripts @earendil-works/pi-coding-agent@$EXPECTED_PI_VERSION" >&2
     exit 1

package/scripts/pi-host.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// The Pi host Piagent runs on, when the member keeps a Pi of their own.
+//
+// Piagent pins one Pi release (package.json peerDependencies). A member who
+// already uses Pi may run a newer one: setup used to replace it with the
+// pinned release. Now theirs stays as it is, and the pinned release is
+// installed privately (packages/piagent-core/managed/pi-host.mjs); company
+// sessions and the dashboard run it, and `piagent pi` opens it for personal use.
+//
+//   pi-host.mjs status [--json]      the pinned host, the `pi` on PATH, the private copy
+//   pi-host.mjs ensure [--dry-run]   install the private copy when PATH has another Pi
+//   pi-host.mjs root                 the host root Piagent runs (empty when none)
+//   pi-host.mjs run [-- args]        run Pi on the pinned host
+import { spawn, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { PI_HOST_VERSION, hostCli, hostPlan, installPrivateHost, privateHostRoot } from '../packages/piagent-core/managed/pi-host.mjs';
+
+const HOST_NAME = '@earendil-works/pi-coding-agent';
+
+function usage() {
+  return `Usage:
+  piagent pi [pi arguments]        Run Pi ${PI_HOST_VERSION} (the release Piagent is qualified on)
+  piagent pi-host status [--json]  Show the pinned host, your own pi and the private copy
+  piagent pi-host ensure [--dry-run]
+                                   Install the pinned host privately when your pi is another release
+`;
+}
+
+// The `pi` on PATH: its package root and version, or nulls.
+export function pathHost(env = process.env, { probe = true } = {}) {
+  for (const dir of (env.PATH ?? '').split(path.delimiter)) {
+    if (!path.isAbsolute(dir)) continue;
+    let root;
+    try { root = path.dirname(fs.realpathSync(path.join(dir, process.platform === 'win32' ? 'pi.cmd' : 'pi'))); } catch { continue; }
+    for (let depth = 0; depth < 4; depth += 1, root = path.dirname(root)) {
+      try {
+        const manifest = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+        if (manifest.name === HOST_NAME) return { root, version: manifest.version ?? null };
+      } catch { /* keep walking up */ }
+    }
+  }
+  if (!probe) return { root: null, version: null };
+  // A `pi` that is not an npm package (a standalone build): ask it.
+  const output = spawnSync('pi', ['--version'], { encoding: 'utf8', timeout: 5_000, shell: process.platform === 'win32' });
+  const version = output.status === 0 ? /(\d+\.\d+\.\d+(?:[+-][0-9A-Za-z.-]+)?)/.exec(output.stdout)?.[1] ?? null : null;
+  return { root: null, version };
+}
+
+// The host Piagent runs: the `pi` on PATH when it is the pinned release, else
+// the private copy, else (not installed yet) whatever PATH has.
+export function activeHostRoot({ env = process.env, home } = {}) {
+  const own = pathHost(env, { probe: false });
+  if (own.root && own.version === PI_HOST_VERSION) return own.root;
+  return privateHostRoot(PI_HOST_VERSION, home) ?? own.root;
+}
+
+export function status({ env = process.env, home } = {}) {
+  const own = pathHost(env), privateRoot = privateHostRoot(PI_HOST_VERSION, home);
+  return { pinned: PI_HOST_VERSION, own: own.version, ownRoot: own.root, privateRoot, plan: hostPlan(own.version), active: activeHostRoot({ env, home }) };
+}
+
+function describe(report) {
+  const lines = [`Piagent runs on Pi ${report.pinned}.`];
+  if (!report.own) lines.push('No `pi` on PATH.');
+  else if (report.plan === 'current') lines.push(`Your pi is ${report.own}: the same release, used as it is.`);
+  else if (report.plan === 'private') lines.push(`Your pi is ${report.own}: kept as it is. Company sessions and \`piagent pi\` use a private Pi ${report.pinned}.`);
+  else lines.push(`Your pi is ${report.own}: older than ${report.pinned}; piagent-setup updates it.`);
+  lines.push(report.privateRoot ? `Private copy: ${report.privateRoot}` : 'Private copy: not installed');
+  return lines.join('\n');
+}
+
+async function main(argv) {
+  const [command, ...rest] = argv;
+  if ([undefined, 'help', '--help', '-h'].includes(command)) { process.stdout.write(usage()); return 0; }
+  if (command === 'status') {
+    const report = status();
+    process.stdout.write(rest.includes('--json') ? `${JSON.stringify(report, null, 2)}\n` : `${describe(report)}\n`);
+    return 0;
+  }
+  if (command === 'root') { process.stdout.write(`${activeHostRoot() ?? ''}\n`); return 0; }
+  if (command === 'ensure') {
+    const report = status(), dryRun = rest.includes('--dry-run');
+    if (report.plan !== 'private' && !rest.includes('--force')) { process.stdout.write(`${describe(report)}\n`); return 0; }
+    try {
+      const root = installPrivateHost({ dryRun, log: (line) => process.stdout.write(`${line}\n`) });
+      process.stdout.write(`${dryRun ? 'DRY RUN: ' : ''}Pi ${PI_HOST_VERSION} for Piagent: ${root}\n`);
+      if (report.own) process.stdout.write(`Your pi ${report.own} is unchanged.\n`);
+      return 0;
+    } catch (error) { process.stderr.write(`FAIL: ${error.message}\n`); return 1; }
+  }
+  if (command === 'run') {
+    const args = rest[0] === '--' ? rest.slice(1) : rest;
+    const root = activeHostRoot();
+    if (!root || JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).version !== PI_HOST_VERSION) {
+      process.stderr.write(`FAIL: Pi ${PI_HOST_VERSION} is not installed for Piagent. Run: piagent pi-host ensure --force\n`);
+      return 1;
+    }
+    const child = spawn(process.execPath, [hostCli(root), ...args], { stdio: 'inherit' });
+    for (const signal of ['SIGTERM', 'SIGHUP']) process.on(signal, () => { try { child.kill(signal); } catch { /* gone */ } });
+    process.on('SIGINT', () => {});
+    return await new Promise((resolve) => child.once('exit', (code, signal) => resolve(signal ? 1 : code ?? 1)));
+  }
+  process.stderr.write(usage());
+  return 2;
+}
+
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) process.exitCode = await main(process.argv.slice(2));

package/scripts/piagent-cli.mjs

@@ -26,7 +26,9 @@ const scriptByCommand = {
   "piagent-context": "scripts/context-engine.mjs",
   "piagent-explain": "scripts/explain-command.mjs",
   "piagent-webui": "scripts/piagent-webui-launcher.mjs",
-  "piagent-dashboard": "scripts/piagent-dashboard.mjs"
+  "piagent-dashboard": "scripts/piagent-dashboard.mjs",
+  "piagent-pi-host": "scripts/pi-host.mjs",
+  "piagent-skills": "scripts/skill-sources.mjs"
 };
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -42,6 +44,10 @@ if (invokedAs === "piagent") {
   } else if (subcommand === "dashboard") {
     script = "scripts/piagent-dashboard.mjs";
     forwardedArgs = forwardedArgs.slice(1);
+  } else if (subcommand === "pi") {
+    // Pi itself, on the release Piagent is qualified on, whatever `pi` the member keeps.
+    script = "scripts/pi-host.mjs";
+    forwardedArgs = ["run", "--", ...forwardedArgs.slice(1)];
   } else if (subcommand === "explain") {
     script = "scripts/explain-command.mjs";
     forwardedArgs = forwardedArgs.slice(1);
@@ -64,6 +70,9 @@ if (invokedAs === "piagent") {
     console.log("Commands:");
     console.log("  dashboard   Open and manage the local session hub");
     console.log("  studio      Open the managed company agent imported by Agent Watch");
+    console.log("  pi          Run Pi on the release Piagent is qualified on (your own pi stays as it is)");
+    console.log("  pi-host     Show or install the Pi host Piagent runs");
+    console.log("  skills      Add, list or remove skill sources such as mattpocock/skills");
     console.log("  explain     Say why the guard would allow or block a shell command");
     console.log("  approve-verification  Preview or approve an independent verification plan");
     console.log("  select-verification   Preview reusable contracts for exact task criteria");
@@ -95,8 +104,10 @@ function benchmarkSourceRoot() {
   process.exit(1);
 }
 
-// The Pi host this member runs: the `pi` found on PATH, as its package root.
-function piHost() {
+// The Pi host this member runs: the `pi` on PATH when it is the pinned release,
+// else Piagent's private copy (a member keeping a newer Pi of their own).
+async function piHost() {
+  try { return (await import("./pi-host.mjs")).activeHostRoot(); } catch { /* the `pi` on PATH, below */ }
   for (const dir of (process.env.PATH ?? "").split(path.delimiter)) {
     if (!path.isAbsolute(dir)) continue;
     let root;
@@ -113,7 +124,7 @@ function piHost() {
 // entrypoint, the Node running it and the Pi host. Source checkouts never
 // register, and a failure here never blocks the command. Asking for help or the
 // version changes nothing in the operator's agent directory.
-function recordRuntime() {
+async function recordRuntime() {
   try {
     if (forwardedArgs.some((value) => ["--help", "-h", "--version", "-v"].includes(value))) return;
     if (!packageRoot.split(path.sep).includes("node_modules")) return;
@@ -129,7 +140,7 @@ function recordRuntime() {
       version: JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")).version,
       entrypoint: fs.realpathSync(path.join(packageRoot, "scripts", "piagent-studio.mjs")),
       node: fs.realpathSync(process.execPath),
-      pi_sdk_root: piHost()
+      pi_sdk_root: await piHost()
     }, null, 2)}\n`;
     const file = path.join(agentDir, "piagent-runtime.json");
     try { if (fs.readFileSync(file, "utf8") === body) return; } catch { /* first run */ }
@@ -138,7 +149,7 @@ function recordRuntime() {
     fs.renameSync(temporary, file);
   } catch { /* optional: Agent Watch falls back to known install locations */ }
 }
-recordRuntime();
+await recordRuntime();
 
 const sourceRoot = invokedAs === "piagent-benchmark" ? benchmarkSourceRoot() : packageRoot;
 const target = path.join(sourceRoot, script);

package/scripts/piagent-dashboard.mjs

@@ -7,7 +7,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { requestGatewayControl } from "../packages/piagent-webui/gateway/control-socket.ts";
 import { browserCommand } from "../packages/piagent-core/runtime/host/browser-opener.mjs";
-import { installedPiHostRoot } from "../packages/piagent-webui/gateway/pi-host.ts";
+import { pinnedPiHostRoot } from "../packages/piagent-webui/gateway/pi-host.ts";
 import { gatewayProfileState, profileRef, readGatewayDescriptor, readOrCreateCatalogKey,
   removeGatewayDescriptor } from "../packages/piagent-webui/gateway/profile-state.ts";
 import { startPiagentGateway } from "../packages/piagent-webui/gateway/gateway-service.ts";
@@ -266,7 +266,7 @@ async function main() {
     const key = readOrCreateCatalogKey(state), descriptor = readGatewayDescriptor(state);
     let actual = null;
     try {
-      const hostRoot = installedPiHostRoot();
+      const hostRoot = pinnedPiHostRoot(expectedPiVersion);
       actual = JSON.parse(fs.readFileSync(path.join(hostRoot, "package.json"), "utf8")).version;
     } catch { /* reported as a failed check below */ }
     let health = null;

package/scripts/runtime-advisory-exceptions.json

@@ -24,6 +24,46 @@
       "decided": "2026-10-24",
       "until": "2026-11-07",
       "reason": "Subresource Integrity check bypassed with a non-lowercase algorithm token; Pi does not fetch with integrity metadata. Pinned by the Pi host as above; fixed in undici 8.12.2."
+    },
+    {
+      "id": "GHSA-4w7w-5xrc-9h26",
+      "package": "undici",
+      "node": "node_modules/undici",
+      "decided": "2026-10-28",
+      "until": "2026-11-07",
+      "reason": "Cache poisoning and cross-user disclosure through cross-origin redirects in undici's cache; Pi does not share an HTTP cache between users. Pinned by the Pi host as above (8.10.2 in 1.3.0 and 1.4.0); fixed in undici 8.12.2."
+    },
+    {
+      "id": "GHSA-2m5v-pch6-74hx",
+      "package": "undici",
+      "node": "node_modules/undici",
+      "decided": "2026-10-28",
+      "until": "2026-11-07",
+      "reason": "TLS certificate validation bypassed when an Agent drops its tls options; affects callers that pass custom tls settings to an undici Agent. Pinned by the Pi host as above; fixed in undici 8.12.2. Owner accepted on 2026-10-28 to keep releases going; revisit as soon as a Pi host carries undici >= 8.12.2."
+    },
+    {
+      "id": "GHSA-qrxm-fqhp-jwvm",
+      "package": "undici",
+      "node": "node_modules/undici",
+      "decided": "2026-10-28",
+      "until": "2026-11-07",
+      "reason": "Denial of service through a TLS 1.2 certificate-changing renegotiation by a hostile server; no data exposure. Pinned by the Pi host as above; fixed in undici 8.12.2."
+    },
+    {
+      "id": "GHSA-9fm3-97px-rjf6",
+      "package": "undici",
+      "node": "node_modules/undici",
+      "decided": "2026-10-28",
+      "until": "2026-11-07",
+      "reason": "Denial of service from unbounded automatic PONG buffering in the WebSocket client fed by a hostile server; no data exposure. Pinned by the Pi host as above; fixed in undici 8.12.2."
+    },
+    {
+      "id": "GHSA-55wc-3pg8-jfw6",
+      "package": "undici",
+      "node": "node_modules/undici",
+      "decided": "2026-10-28",
+      "until": "2026-11-07",
+      "reason": "Denial of service from an unhandled exception in the decompress interceptor; no data exposure. Pinned by the Pi host as above; fixed in undici 8.12.2."
     }
   ]
 }

package/scripts/setup.sh

@@ -80,6 +80,7 @@ CONFIGURE_MODEL_SCOPE=true
 MODEL_SCOPE_PRESET="full"
 DEFAULT_MODEL="openai-codex/gpt-6-sol:high"
 AUTO_INSTALL_PI=true
+PI_HOST_PRIVATE=false
 FORCE_PROFILE=false
 FORCE_SETTINGS=false
 SKIP_AGENTS=false
@@ -347,6 +348,19 @@ ensure_pi_cli() {
     if [[ "$current_version" == "$expected_pi_version" ]]; then
       return
     fi
+    # A newer pi is the member's own: it stays, and the pinned host is
+    # installed privately beside it (scripts/pi-host.mjs).
+    if [[ -n "$current_version" ]] && [[ "$(node -e 'const [a,b]=process.argv.slice(1).map(v=>v.split(/[+-]/)[0].split(".").map(Number)); for (let i=0;i<3;i++) if (a[i]!==b[i]) { process.stdout.write(a[i]>b[i]?"newer":"older"); process.exit(0); } process.stdout.write("same");' "$current_version" "$expected_pi_version")" == "newer" ]]; then
+      echo "Pi CLI $current_version is your own and stays as it is; Piagent runs on a private Pi $expected_pi_version."
+      local ensure_args=(ensure --force)
+      [[ "$DRY_RUN" == true ]] && ensure_args+=(--dry-run)
+      if ! node "$PLATFORM_ROOT/scripts/pi-host.mjs" "${ensure_args[@]}"; then
+        echo "FAIL: could not install the private Pi $expected_pi_version." >&2
+        exit 1
+      fi
+      PI_HOST_PRIVATE=true
+      return
+    fi
     if [[ "$AUTO_INSTALL_PI" == false ]]; then
       echo "FAIL: Pi Coding Agent $expected_pi_version is required; found ${current_version:-${current_output:-unknown}}. Remove --no-install-pi or upgrade it manually." >&2
       exit 1
@@ -490,7 +504,11 @@ echo "Next:"
 if [[ "$DO_PROJECT" == true ]]; then
   echo "  cd \"$PROJECT_PATH\""
 fi
-echo "  pi"
+if [[ "$PI_HOST_PRIVATE" == true ]]; then
+  echo "  piagent pi         # Pi $(node -p 'require(process.argv[1]).peerDependencies["@earendil-works/pi-coding-agent"]' "$PLATFORM_ROOT/package.json"), the release Piagent is qualified on; your own pi also loads Piagent"
+else
+  echo "  pi"
+fi
 echo "  /login             # first time only"
 if [[ "$DO_PROJECT" == true ]]; then
   echo "  /model             # or Ctrl+L: select provider/model from Pi selector"

package/scripts/skill-sources.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+// Skill repositories a member adds to Piagent, such as mattpocock/skills.
+//
+// A source is a public GitHub repository of Agent Skills (folders with a
+// SKILL.md). `add` keeps it at one commit under ~/.piagent/skill-sources, so
+// what the agent reads changes only on `update`; the index lists it
+// (~/.piagent/skill-sources.json), and plugin-skills.mjs offers its skills to
+// personal Pi, the company Terminal and the dashboard, as it does a Claude
+// plugin's. A repository with a plugin manifest (.claude-plugin/plugin.json)
+// loads only the skills the manifest publishes. Skills are instructions: a
+// script they bundle runs only through the session's own tools and approvals.
+//
+//   piagent skills add <owner/repo> [--ref <branch|tag|commit>]
+//   piagent skills list [--json]
+//   piagent skills update [<owner/repo>]
+//   piagent skills remove <owner/repo>
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { skillSourcePlugin, skillSourcesIndex, skillSourcesRoot } from '../packages/piagent-core/runtime/resources/plugin-skills.mjs';
+
+// Short names for sources the team recommends.
+export const KNOWN_SOURCES = { mattpocock: 'mattpocock/skills', 'matt-pocock': 'mattpocock/skills' };
+
+function usage() {
+  return `Usage:
+  piagent skills add <owner/repo> [--ref <branch|tag|commit>]
+                                  Add a GitHub skill repository, kept at one commit
+                                  (for example: piagent skills add mattpocock/skills)
+  piagent skills list [--json]    Skill sources and the skills each one adds
+  piagent skills update [<owner/repo>]
+                                  Move a source (or all) to the newest commit of its ref
+  piagent skills remove <owner/repo>
+                                  Stop reading a source and delete its copy
+
+Skills from a source appear in Pi as /skill:<name>, in the company Terminal and
+in the dashboard, after the next /reload or new conversation.
+`;
+}
+
+// owner/repo from what the member typed: owner/repo, a github.com URL, or a known name.
+export function parseRepository(value) {
+  const typed = KNOWN_SOURCES[String(value ?? '').trim().toLowerCase()] ?? String(value ?? '').trim();
+  const match = /^(?:https:\/\/github\.com\/|git:github\.com\/|github\.com\/)?([A-Za-z0-9](?:[A-Za-z0-9-]{0,38}))\/([A-Za-z0-9._-]{1,100}?)(?:\.git)?\/?$/.exec(typed);
+  if (!match || match[2] === '.' || match[2] === '..') return null;
+  return `${match[1]}/${match[2]}`;
+}
+
+const validRef = (ref) => typeof ref === 'string' && /^[A-Za-z0-9][A-Za-z0-9._/-]{0,199}$/.test(ref) && !ref.includes('..');
+
+export function readIndex(home = os.homedir()) {
+  try {
+    const value = JSON.parse(fs.readFileSync(skillSourcesIndex(home), 'utf8'));
+    return { schema_version: 1, sources: Array.isArray(value?.sources) ? value.sources : [] };
+  } catch { return { schema_version: 1, sources: [] }; }
+}
+
+function writeIndex(index, home) {
+  const file = skillSourcesIndex(home);
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify(index, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(temporary, file);
+}
+
+function git(args, options = {}) {
+  const result = spawnSync('git', args, { encoding: 'utf8', timeout: 120_000, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' }, ...options });
+  if (result.error) throw new Error(`git could not start: ${result.error.message}`);
+  if (result.status !== 0) throw new Error((result.stderr || result.stdout || `git ${args[0]} failed`).trim().split('\n').at(-1));
+  return result.stdout.trim();
+}
+
+// The repository at `ref` (default branch when none), copied without its
+// history into <root>/github.com/<owner>/<repo>/<commit>. Returns the entry.
+export function fetchSource(repo, { ref, home = os.homedir(), runGit = git } = {}) {
+  const url = `https://github.com/${repo}.git`, root = skillSourcesRoot(home);
+  const parent = path.join(root, 'github.com', ...repo.split('/'));
+  fs.mkdirSync(parent, { recursive: true, mode: 0o700 });
+  const staging = fs.mkdtempSync(path.join(parent, '.incoming-'));
+  try {
+    const checkout = path.join(staging, 'checkout');
+    if (ref && /^[0-9a-f]{40}$/i.test(ref)) {
+      fs.mkdirSync(checkout);
+      runGit(['init', '-q', checkout]);
+      runGit(['-C', checkout, 'fetch', '-q', '--depth', '1', url, ref]);
+      runGit(['-C', checkout, 'checkout', '-q', 'FETCH_HEAD']);
+    } else {
+      runGit(['clone', '-q', '--depth', '1', ...(ref ? ['--branch', ref] : []), url, checkout]);
+    }
+    const commit = runGit(['-C', checkout, 'rev-parse', 'HEAD']);
+    if (!/^[0-9a-f]{40}$/.test(commit)) throw new Error('could not read the commit');
+    fs.rmSync(path.join(checkout, '.git'), { recursive: true, force: true });
+    const target = path.join(parent, commit);
+    if (!fs.existsSync(target)) fs.renameSync(checkout, target);
+    return { repo, ref: ref ?? null, commit, path: path.relative(root, target), added_at: new Date().toISOString() };
+  } finally { fs.rmSync(staging, { recursive: true, force: true }); }
+}
+
+// The skills a source adds, as the agent will see them.
+export function sourceSkills(entry, home = os.homedir()) {
+  const found = skillSourcePlugin(path.join(skillSourcesRoot(home), entry.path), entry.repo);
+  if (!found) return [];
+  const names = [];
+  const walk = (dir, depth) => {
+    if (depth > 4 || names.length >= 400) return;
+    if (fs.existsSync(path.join(dir, 'SKILL.md'))) { names.push(path.basename(dir)); return; }
+    let entries = [];
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const child of entries) if (child.isDirectory() && !child.name.startsWith('.') && child.name !== 'node_modules') walk(path.join(dir, child.name), depth + 1);
+  };
+  for (const dir of found.skills) walk(dir, 0);
+  return [...new Set(names)].sort();
+}
+
+function removeCopy(entry, home) {
+  const root = skillSourcesRoot(home), dir = path.resolve(root, entry.path);
+  if (dir.startsWith(root + path.sep)) fs.rmSync(dir, { recursive: true, force: true });
+}
+
+function add(repo, { ref, home }) {
+  const index = readIndex(home), existing = index.sources.find((item) => item.repo === repo);
+  const entry = fetchSource(repo, { ref: ref ?? existing?.ref ?? undefined, home });
+  const skills = sourceSkills(entry, home);
+  if (!skills.length) {
+    removeCopy(entry, home);
+    throw new Error(`${repo} has no skill (no SKILL.md under the folders it publishes)`);
+  }
+  if (existing && existing.path !== entry.path) removeCopy(existing, home);
+  index.sources = [...index.sources.filter((item) => item.repo !== repo), { ...entry, name: repo }];
+  writeIndex(index, home);
+  return { entry, skills, replaced: existing?.commit ?? null };
+}
+
+function main(argv, home = os.homedir()) {
+  const [command, ...rest] = argv;
+  const flag = (name) => { const at = rest.indexOf(name); return at >= 0 ? rest[at + 1] : undefined; };
+  const positional = rest.filter((value, at) => !value.startsWith('--') && !(at > 0 && rest[at - 1] === '--ref'));
+  if ([undefined, 'help', '--help', '-h'].includes(command)) { process.stdout.write(usage()); return 0; }
+  try {
+    if (command === 'list') {
+      const sources = readIndex(home).sources.map((entry) => ({ ...entry, skills: sourceSkills(entry, home) }));
+      if (rest.includes('--json')) { process.stdout.write(`${JSON.stringify({ sources }, null, 2)}\n`); return 0; }
+      if (!sources.length) { process.stdout.write('No skill source yet. Add one: piagent skills add mattpocock/skills\n'); return 0; }
+      for (const entry of sources) process.stdout.write(`${entry.repo} @ ${entry.commit.slice(0, 12)}${entry.ref ? ` (${entry.ref})` : ''}: ${entry.skills.length} skill(s)\n  ${entry.skills.join(', ')}\n`);
+      return 0;
+    }
+    if (command === 'add') {
+      const repo = parseRepository(positional[0]), ref = flag('--ref');
+      if (!repo) throw new Error('name a GitHub repository as owner/repo, for example mattpocock/skills');
+      if (ref !== undefined && !validRef(ref)) throw new Error('--ref needs a branch, tag or commit');
+      const { entry, skills, replaced } = add(repo, { ref, home });
+      process.stdout.write(`${replaced && replaced !== entry.commit ? 'Updated' : 'Added'} ${repo} @ ${entry.commit.slice(0, 12)}: ${skills.length} skill(s)\n  ${skills.join(', ')}\n`);
+      process.stdout.write('Use them as /skill:<name> after /reload in Pi, or in a new company conversation.\n');
+      return 0;
+    }
+    if (command === 'update') {
+      const only = positional[0] ? parseRepository(positional[0]) : null;
+      if (positional[0] && !only) throw new Error('name a GitHub repository as owner/repo');
+      const targets = readIndex(home).sources.filter((entry) => !only || entry.repo === only);
+      if (!targets.length) throw new Error(only ? `${only} is not a skill source` : 'no skill source to update');
+      for (const entry of targets) {
+        const { entry: next, skills } = add(entry.repo, { ref: entry.ref ?? undefined, home });
+        process.stdout.write(`${entry.repo}: ${entry.commit.slice(0, 12)} -> ${next.commit.slice(0, 12)} (${skills.length} skill(s))\n`);
+      }
+      return 0;
+    }
+    if (command === 'remove') {
+      const repo = parseRepository(positional[0]);
+      if (!repo) throw new Error('name a GitHub repository as owner/repo');
+      const index = readIndex(home), entry = index.sources.find((item) => item.repo === repo);
+      if (!entry) throw new Error(`${repo} is not a skill source`);
+      removeCopy(entry, home);
+      index.sources = index.sources.filter((item) => item.repo !== repo);
+      writeIndex(index, home);
+      process.stdout.write(`Removed ${repo}.\n`);
+      return 0;
+    }
+  } catch (error) {
+    process.stderr.write(`FAIL: ${error.message}\n`);
+    return 1;
+  }
+  process.stderr.write(usage());
+  return 2;
+}
+
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) process.exitCode = main(process.argv.slice(2), os.homedir());

package/scripts/uninstall-global.sh

@@ -212,7 +212,24 @@ fi
 
 if [[ "$WITH_HOST" == true ]]; then
   echo
-  if command -v npm >/dev/null 2>&1; then
+  # Piagent's private host (kept beside a member's own, newer pi) is Piagent's to remove.
+  PRIVATE_HOSTS="${HOME}/.piagent/pi-host"
+  if [[ -d "$PRIVATE_HOSTS" ]]; then
+    echo "Removing Piagent's private Pi host:"
+    run_cmd rm -rf "$PRIVATE_HOSTS"
+  fi
+  # A pi newer than the pinned release is the member's own: it stays.
+  own_pi_version=""
+  if command -v pi >/dev/null 2>&1 && [[ "$(pi --version 2>/dev/null || true)" =~ ([0-9]+\.[0-9]+\.[0-9]+([+-][0-9A-Za-z.-]+)?) ]]; then
+    own_pi_version="${BASH_REMATCH[1]}"
+  fi
+  own_pi_plan=""
+  if [[ -n "$own_pi_version" ]]; then
+    own_pi_plan="$(node --input-type=module -e 'const { hostPlan } = await import(process.argv[1]); process.stdout.write(hostPlan(process.argv[2]));' "$ROOT/packages/piagent-core/managed/pi-host.mjs" "$own_pi_version" 2>/dev/null || true)"
+  fi
+  if [[ "$own_pi_plan" == "private" ]]; then
+    echo "Pi $own_pi_version is your own (newer than the release Piagent pins): left in place."
+  elif command -v npm >/dev/null 2>&1; then
     echo "Uninstalling Pi host:"
     HOST_PREFIX="$(npm_prefix_override)"
     if [[ -n "$HOST_PREFIX" ]]; then

package/scripts/update-global.mjs

@@ -22,6 +22,7 @@ import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { inspect as inspectPersonalPi } from "./personal-pi-config.mjs";
+import { hostPlan, installPrivateHost, privateHostRoot } from "../packages/piagent-core/managed/pi-host.mjs";
 
 const HELPER_PACKAGE = "@piagent/platform";
 const HOST_PACKAGE = "@earendil-works/pi-coding-agent";
@@ -426,11 +427,15 @@ function main() {
 
   // npm exec is temporary even when its version already matches the target.
   const helperNeedsChange = options.force || currentHelper !== targetHelper || isNpxCacheRoot(platformRoot);
-  const hostNeedsChange = options.host && (options.force || currentHost !== targetHost);
+  // A newer pi is the member's own: kept, with the target host installed privately.
+  const ownHost = hostPlan(currentHost, targetHost) === "private";
+  const hostNeedsChange = options.host && (ownHost ? !privateHostRoot(targetHost) : options.force || currentHost !== targetHost);
 
   console.log("Pi Agent Platform update");
   console.log(`  helper:  ${currentHelper} -> ${targetHelper}${helperNeedsChange ? "" : " (already current)"}`);
-  console.log(`  host:    ${currentHost ?? "not installed"} -> ${targetHost}${hostNeedsChange ? "" : " (already current)"}`);
+  console.log(ownHost
+    ? `  host:    your pi ${currentHost} stays; Piagent's private Pi -> ${targetHost}${hostNeedsChange ? "" : " (already current)"}`
+    : `  host:    ${currentHost ?? "not installed"} -> ${targetHost}${hostNeedsChange ? "" : " (already current)"}`);
   // The Pi package can lag the helper (installed from an older tag), and
   // personal Pi can hold conflicting Piagent or old company entries.
   const personal = inspectPersonalPi(process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent"));
@@ -473,7 +478,7 @@ function main() {
   // here rather than trusted from before the move.
   let effectiveHost = currentHost;
   let effectiveHostNeedsChange = hostNeedsChange;
-  if (npmTarget.bin) {
+  if (npmTarget.bin && !ownHost) {
     const activeHost = installedHostVersion();
     if (activeHost !== currentHost) {
       effectiveHost = activeHost;
@@ -484,14 +489,17 @@ function main() {
   }
 
   // Refuse an impossible package installation before replacing either global.
-  if (options.package && !options.host && effectiveHost !== targetHost) {
+  if (options.package && !options.host && effectiveHost !== targetHost && !(ownHost && privateHostRoot(targetHost))) {
     fail(`--no-host cannot install this Pi package: active Pi is ${effectiveHost ?? "missing"}, but v${targetHelper} requires ${targetHost}. Rerun without --no-host.`);
   }
 
   // Host first: piagent-install refuses to run against a host that does not match
   // the version its package.json pins, so a helper installed ahead of the host
   // would fail on its very next step.
-  if (effectiveHostNeedsChange) {
+  if (effectiveHostNeedsChange && ownHost) {
+    try { installPrivateHost({ version: targetHost, dryRun: options.dryRun, log: (line) => console.log(line.startsWith("DRY RUN") ? line : `run: ${line}`) }); }
+    catch { fail(`could not install the private ${HOST_PACKAGE}@${targetHost}`); }
+  } else if (effectiveHostNeedsChange) {
     const args = npmInstallArgs(`${HOST_PACKAGE}@${targetHost}`, npmTarget);
     describeStep(options.dryRun, "npm", args);
     if (!options.dryRun && !run("npm", args).ok) fail(`could not install ${HOST_PACKAGE}@${targetHost}`);