@piagent/platform 1.3.1 → 1.4.1

package/scripts/explain-command.mjs

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+// Answers the one question the guard never answers: why.
+//
+// A blocked command is the only interface most operators ever have with this
+// policy, and a denial that says "no" without saying "what now" leaves them
+// guessing. This runs the guard's static shell preflight, in the same order,
+// over the same resolved protected paths, and prints what each step saw.
+//
+// It reuses `shell-reach.js` rather than re-deriving anything. A second opinion
+// about what a command reaches would be worse than no opinion: the operator
+// would tune a command until this said allow and still be blocked at run time.
+// The final decision also depends on live session/task facts this standalone
+// process does not own, so passing static preflight is deliberately reported as
+// indeterminate rather than as permission to execute.
+
+import path from "node:path";
+
+import { evaluateExecPolicyCore, findProtectedPathInCommand, unresolvedPathExpansions } from "../packages/piagent-core/extensions/policy-core.js";
+import {
+  findResolvedProtectedPathInCommand,
+  shellGlobTargetsProtectedPath,
+  unresolvedExpansionReason
+// `.ts` rather than the `.js` specifier the TypeScript sources use: this file is
+// plain ESM, so the loader resolves what is actually on disk.
+} from "../packages/piagent-core/extensions/shell-reach.ts";
+import { effectiveProtectedPaths, loadProjectContextIndexPolicy } from "../packages/piagent-core/extensions/context-index-policy.js";
+
+const platformRoot = path.resolve(import.meta.dirname, "..");
+
+function usage() {
+  return [
+    "Usage: piagent explain <command> [--project <path>] [--json]",
+    "       piagent explain --scope [--project <path>] [--json]",
+    "",
+    "Prints a fail-closed static preflight for a shell command and what to do",
+    "next. A static pass is indeterminate until the live Pi runtime evaluates",
+    "Task Contract, scope, permission, lifecycle, approval, and budget state.",
+    "Nothing is executed.",
+    "",
+    "  --scope            List the boundary in effect instead of judging a command",
+    "  --project <path>   Evaluate against this project's profile (default: cwd)",
+    "  --json             Machine-readable output",
+    "  -h, --help         Show this help"
+  ].join("\n");
+}
+
+function parseArgs(argv) {
+  let project = process.cwd(), json = false, scope = false;
+  const words = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === "-h" || value === "--help") return { help: true };
+    if (value === "--json") { json = true; continue; }
+    if (value === "--scope") { scope = true; continue; }
+    if (value === "--project") {
+      const next = argv[index += 1];
+      if (!next || next.startsWith("--")) throw new Error("--project needs a path");
+      project = path.resolve(next);
+      continue;
+    }
+    if (value.startsWith("--")) throw new Error(`Unknown option: ${value}`);
+    words.push(value);
+  }
+  return { help: false, project, json, scope, command: words.join(" ").trim() };
+}
+
+// What the operator should do next. The guard states 74 refusals and only three
+// of them say this, which is why a denial so often ends the conversation.
+const REMEDY = {
+  "protected-path": "Use an approved context projection if one is available. Direct access requires the operator to change the protected-path policy; task scope alone does not override it.",
+  "protected-glob": "Name the file you mean instead of a pattern; a pattern is refused when any name it can match is protected.",
+  "resolved-protected": "The path resolves to a protected file through a link or a parent directory. Use the real path you intend.",
+  "unresolved": "Write the path out, or put the expansion in its own argument, so the guard can see what is being opened.",
+  "exec-policy": "This is refused by an exec-policy rule, not by a path. Change the command, or ask the operator to run it.",
+  "runtime-required": "Run the command through the current Pi session. Only that runtime owns the Task Contract, scope, permission, lifecycle, approval, and budget facts needed for a final decision."
+};
+
+const RUNTIME_GATES = [
+  "task-contract",
+  "task-scope",
+  "permission-profile",
+  "lifecycle-control",
+  "approval-state",
+  "context-budget"
+];
+
+function explain(command, protectedPaths, policy, cwd) {
+  const steps = [];
+  const record = (name, hit, detail) => { steps.push({ step: name, matched: Boolean(hit), detail }); return hit; };
+
+  const exec = evaluateExecPolicyCore(command, { policy, mode: "enforce" });
+  record("exec-policy", exec.decision === "forbid", exec.reasons.length ? exec.reasons.join("; ") : "no rule matched");
+  if (exec.decision === "forbid") {
+    return { decision: "deny", kind: "exec-policy", confidence: "exact", reason: exec.reasons.join("; "), steps, exec };
+  }
+
+  const literal = findProtectedPathInCommand(command, protectedPaths);
+  record("literal-path", literal, literal ? `${literal.candidate} matches ${literal.pattern}` : "no word names a protected path");
+  if (literal) {
+    return {
+      decision: "deny", kind: "protected-path", confidence: "exact",
+      reason: `Command touches protected path: ${literal.candidate} matches ${literal.pattern}`, steps, exec
+    };
+  }
+
+  const glob = shellGlobTargetsProtectedPath(command, protectedPaths);
+  record("glob", glob, glob ? `${glob.glob} can match ${glob.example} via ${glob.pattern}` : "no pattern can reach a protected name");
+  if (glob) {
+    return {
+      decision: "deny", kind: "protected-glob",
+      // A pattern is matched against generated examples of each protected
+      // pattern, not against the filesystem, so this answers for names that may
+      // not exist. That is deliberate, and worth saying out loud.
+      confidence: "over-approximate",
+      reason: `Command glob can target protected path: ${glob.glob} can match ${glob.example} via ${glob.pattern}`, steps, exec
+    };
+  }
+
+  const resolved = findResolvedProtectedPathInCommand(cwd, command, protectedPaths);
+  record("resolved-path", resolved, resolved ? `${resolved.candidate} resolves to ${resolved.resolved}` : "no candidate resolves onto a protected path");
+  if (resolved) {
+    return {
+      decision: "deny", kind: "resolved-protected", confidence: "exact",
+      reason: `Command resolves to protected path: ${resolved.candidate} resolves to ${resolved.resolved} matching ${resolved.pattern}`, steps, exec
+    };
+  }
+
+  const unresolved = protectedPaths.length > 0 ? unresolvedPathExpansions(command) : [];
+  record("unresolved-expansion", unresolved.length > 0, unresolved.length ? unresolved.join(", ") : "every path is resolvable");
+  if (unresolved.length > 0) {
+    return {
+      decision: "deny", kind: "unresolved",
+      // Nothing was proven to be protected here. The command is refused because
+      // its target is unknowable before it runs, which is a different statement
+      // and leads the operator to a different fix.
+      confidence: "unknown-target",
+      reason: unresolvedExpansionReason("Command", unresolved), steps, exec
+    };
+  }
+
+  const staticDecision = exec.decision === "prompt" ? "confirm" : "allow";
+  return {
+    decision: "indeterminate", kind: "runtime-required", confidence: "runtime-required",
+    staticDecision,
+    reason: staticDecision === "confirm"
+      ? `Static preflight requires confirmation (${exec.reasons.join("; ")}), but the live runtime may still block it.`
+      : "Static preflight found no refusal. A final decision requires live session and task state.",
+    remainingGates: RUNTIME_GATES,
+    steps, exec
+  };
+}
+
+function render(result, context) {
+  const lines = [`decision: ${result.decision}`, ""];
+  lines.push(`  reason      ${result.reason}`);
+  lines.push(`  confidence  ${result.confidence}`);
+  if (result.staticDecision) lines.push(`  static      ${result.staticDecision}`);
+  lines.push(`  remedy      ${REMEDY[result.kind] ?? REMEDY["runtime-required"]}`);
+  if (result.remainingGates?.length) lines.push(`  still needs ${result.remainingGates.join(", ")}`);
+  lines.push("", "  static chain (the order the guard asks these):");
+  for (const step of result.steps) {
+    lines.push(`    ${step.matched ? "HIT " : "    "} ${step.step.padEnd(20)} ${step.detail}`);
+  }
+  lines.push("", `  profile     ${context.profileSource} (${context.profilePath})`);
+  lines.push(`  protected   ${context.protectedPaths.length} patterns in effect`);
+  return lines.join("\n");
+}
+
+function renderScope(loaded, effective) {
+  const lines = ["boundary in effect", ""];
+  lines.push(`  profile     ${loaded.profileSource} (${loaded.profilePath})`);
+  lines.push(`  mode        ${loaded.profile.mode ?? "unset"}`);
+  if (typeof loaded.profile.displayName === "string") lines.push(`  project     ${loaded.profile.displayName}`);
+  // Packs are `{name, version}` records, not names, so joining them raw printed
+  // `[object Object]` where the operator expected to read what is loaded.
+  const packs = (Array.isArray(loaded.profile.capabilityPacks) ? loaded.profile.capabilityPacks : [])
+    .map((pack) => (pack && typeof pack === "object" ? `${pack.name}@${pack.version}` : String(pack)));
+  lines.push(`  packs       ${packs.length > 0 ? packs.join(", ") : "none"}`);
+  for (const [label, key] of [
+    ["shell", "shellProtectedPaths"],
+    ["read", "readProtectedPaths"],
+    ["write", "writeProtectedPaths"],
+    ["read-only", "readOnlyPaths"]
+  ]) {
+    const values = effective[key];
+    lines.push("", `  ${label} (${values.length})`);
+    for (const value of values) lines.push(`    ${value}`);
+    if (values.length === 0) lines.push("    (none)");
+  }
+  return lines.join("\n");
+}
+
+let parsed;
+try {
+  parsed = parseArgs(process.argv.slice(2));
+} catch (error) {
+  console.error(`FAIL: ${error.message}\n\n${usage()}`);
+  process.exit(2);
+}
+if (parsed.help) { process.stdout.write(`${usage()}\n`); process.exit(0); }
+if (!parsed.command && !parsed.scope) { console.error(`FAIL: nothing to explain\n\n${usage()}`); process.exit(2); }
+
+try {
+  const loaded = loadProjectContextIndexPolicy(platformRoot, parsed.project, { profilePath: process.env.PIAGENT_PROFILE });
+  const effective = effectiveProtectedPaths(loaded.policy, loaded.profile);
+  const protectedPaths = effective.shellProtectedPaths;
+  if (parsed.scope) {
+    // The boundary is otherwise only visible by running into it.
+    if (parsed.json) {
+      process.stdout.write(`${JSON.stringify({
+        profileSource: loaded.profileSource, profilePath: loaded.profilePath,
+        mode: loaded.profile.mode ?? null, capabilityPacks: loaded.profile.capabilityPacks ?? [], ...effective
+      }, null, 2)}\n`);
+    } else {
+      process.stdout.write(`${renderScope(loaded, effective)}\n`);
+    }
+    process.exit(0);
+  }
+  const result = explain(parsed.command, protectedPaths, loaded.policy, parsed.project);
+  const context = { profileSource: loaded.profileSource, profilePath: loaded.profilePath, protectedPaths };
+  if (parsed.json) {
+    process.stdout.write(`${JSON.stringify({
+      command: parsed.command, decision: result.decision, kind: result.kind, confidence: result.confidence,
+      reason: result.reason, remedy: REMEDY[result.kind] ?? REMEDY["runtime-required"],
+      staticDecision: result.staticDecision ?? null,
+      remainingGates: result.remainingGates ?? [], steps: result.steps,
+      protectedPatternCount: protectedPaths.length, profileSource: loaded.profileSource
+    }, null, 2)}\n`);
+  } else {
+    process.stdout.write(`${render(result, context)}\n`);
+  }
+  // Exit status is a permission signal for existing shell callers: 0 is reserved
+  // for commands that are conclusively allowed. This standalone process can no
+  // longer make that claim; 1 is a conclusive static denial and 2 means the live
+  // runtime still has to decide.
+  process.exit(result.decision === "deny" ? 1 : 2);
+} catch (error) {
+  console.error(`FAIL: ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+}

package/scripts/install-global.sh

@@ -4,7 +4,32 @@ set -euo pipefail
 usage() {
   cat <<'USAGE'
 Usage:
-  scripts/install-global.sh [--stable|--dev|--local|--channel <stable|dev|local>] [--version <tag>] [--resolve-tag] [--package-source <source>] [--dry-run] [--with-mcp|--no-mcp] [--mcp-preset <preset>] [--with-subagents|--no-subagents] [--subagents-preset <preset>] [--with-web-access|--no-web-access] [--with-herdr] [--model-scope <preset>|--no-model-scope]
+  scripts/install-global.sh [--stable|--dev|--local|--channel <stable|dev|local>] [--version <tag>] [--resolve-tag] [--package-source <source>] [--dry-run] [--with-mcp|--no-mcp] [--mcp-preset <preset>] [--with-subagents|--no-subagents] [--subagents-preset <preset>] [--subagents-model-scope <scope>] [--with-web-access|--no-web-access] [--with-herdr] [--model-scope <preset>|--no-model-scope] [--default-model <model>] [-h|--help]
+
+Options:
+  --channel <stable|dev|local>    Package channel; --stable/--dev/--local are shorthands.
+  --version, --tag <tag>          Pin a release tag (pair with --resolve-tag for a SHA).
+  --resolve-tag                   Resolve the tag to a commit SHA before installing.
+  --package-source <source>       Explicit package source; overrides the channel.
+  --dry-run                       Print the planned steps without changing user config.
+  --with-mcp | --no-mcp           Install the MCP adapter (default: install).
+  --mcp-preset <preset>           MCP server set (default: core).
+  --with-subagents | --no-subagents
+                                  Install pi-subagents (default: only if already present).
+  --subagents-preset <minimal|safe|async|parallel>
+                                  Subagent runtime preset (default: safe).
+  --subagents-model-scope <none|piagent|codex|claude>
+                                  Model family the subagents run on (default: none).
+  --with-web-access | --no-web-access
+                                  Install pi-web-access for the researcher subagent (default: install).
+  --with-herdr                    Also configure Herdr integration.
+  --model-scope <full|codex|claude>
+                                  Model families to enable in Pi (default: full).
+  --no-model-scope                Leave the user's enabledModels untouched.
+  --default-model <provider/model[:thinking]>
+                                  Default model written to Pi settings
+                                  (default: openai-codex/gpt-5.5:high).
+  -h, --help                      Print this help and exit.
 
 Purpose:
   Install the piagent Pi package into the current user's global Pi settings.
@@ -74,6 +99,7 @@ RESOLVE_TAG=false
 RESOLVED_PACKAGE_TAG=""
 RESOLVED_PACKAGE_COMMIT=""
 CLI_PACKAGE_SELECTOR=""
+LOCAL_HELPER_PREFIX="${PIAGENT_LOCAL_HELPER_PREFIX:-}"
 PI_MCP_ADAPTER_SOURCE="npm:pi-mcp-adapter@2.15.0"
 PI_SUBAGENTS_SOURCE="npm:pi-subagents@0.38.0"
 PI_WEB_ACCESS_SOURCE="npm:pi-web-access@0.17.0"
@@ -181,6 +207,61 @@ run_cmd() {
   fi
 }
 
+active_piagent_helper_prefix() {
+  if [[ -n "$LOCAL_HELPER_PREFIX" ]]; then
+    printf '%s\n' "$LOCAL_HELPER_PREFIX"
+    return 0
+  fi
+
+  local helper_command
+  helper_command="$(command -v piagent 2>/dev/null || true)"
+  [[ -n "$helper_command" ]] || return 1
+
+  node --input-type=module - "$helper_command" <<'NODE'
+import fs from "node:fs";
+import path from "node:path";
+
+try {
+  const command = path.resolve(process.argv[2]);
+  if (path.basename(path.dirname(command)) === "bin") {
+    process.stdout.write(`${path.dirname(path.dirname(command))}\n`);
+    process.exit(0);
+  }
+  const target = fs.realpathSync(command);
+  const marker = `${path.sep}lib${path.sep}node_modules${path.sep}@piagent${path.sep}platform${path.sep}`;
+  const index = target.indexOf(marker);
+  if (index <= 0) process.exit(1);
+  process.stdout.write(`${target.slice(0, index)}\n`);
+} catch {
+  process.exit(1);
+}
+NODE
+}
+
+sync_local_helper() {
+  [[ "$RESOLVED_CHANNEL_LABEL" == "local" ]] || return 0
+
+  if ! command -v npm >/dev/null 2>&1; then
+    echo "FAIL: npm is required to synchronize the local Piagent helper and Gateway runtime." >&2
+    exit 1
+  fi
+
+  local prefix="" used_fallback=false
+  prefix="$(active_piagent_helper_prefix 2>/dev/null || true)"
+  if [[ -z "$prefix" ]]; then
+    prefix="${HOME}/.pi/npm-global"
+    used_fallback=true
+  fi
+
+  echo "Synchronizing local terminal helper and Gateway runtime:"
+  run_cmd npm install -g --ignore-scripts --prefix "$prefix" "$PLATFORM_ROOT"
+
+  if [[ "$used_fallback" == true ]]; then
+    echo "NOTE: no existing Piagent helper was found; the local helper was installed under $prefix." >&2
+    echo "NOTE: add $prefix/bin to PATH if piagent is not found after this run." >&2
+  fi
+}
+
 resolve_user_package_path() {
   local source="$1"
   local pi_agent_dir="${PI_CODING_AGENT_DIR:-"${HOME}/.pi/agent"}"
@@ -285,10 +366,29 @@ verify_npm_integrity() {
     echo "FAIL: npm is required to verify package integrity for $package_spec." >&2
     exit 1
   fi
-  local actual
-  actual="$(npm view "$package_spec" dist.integrity 2>/dev/null | tr -d '\r\n')"
+  # The status is captured rather than left to `set -e`. Declaring `local actual`
+  # and assigning on the next line makes the command substitution's own status the
+  # status of the assignment, so under `pipefail` an unreachable registry -- no
+  # network, a proxy, a private registry, an npm outage -- killed the script on
+  # this line. The `FAIL:` below was never reached and npm's stderr was already
+  # discarded, so the run ended with an empty screen and exit 1, after `pi install`
+  # had already succeeded. The operator was left half-installed with no reason
+  # given. (Writing `local actual="$(...)"` also avoids the exit, but by hiding the
+  # failure inside the empty-value branch, which then reports a digest mismatch --
+  # a security message for what is usually a network problem.)
+  local actual="" status=0
+  actual="$(npm view "$package_spec" dist.integrity 2>/dev/null | tr -d '\r\n')" || status=$?
+  if [[ "$status" -ne 0 ]]; then
+    echo "FAIL: could not reach the npm registry to verify $package_spec (npm exited $status)." >&2
+    echo "      Nothing further was installed. Check network, proxy, or registry auth," >&2
+    echo "      then re-run. To see npm's own message: npm view $package_spec dist.integrity" >&2
+    exit 1
+  fi
   if [[ -z "$actual" || "$actual" != "$expected" ]]; then
     echo "FAIL: registry integrity does not match the approved digest for $package_spec." >&2
+    echo "      approved: $expected" >&2
+    echo "      registry: ${actual:-<empty>}" >&2
+    echo "      Do not proceed. The published package differs from the reviewed release." >&2
     exit 1
   fi
 }
@@ -609,6 +709,7 @@ if [[ -n "$RESOLVED_PACKAGE_COMMIT" ]]; then
   echo "  resolvedCommit: $RESOLVED_PACKAGE_COMMIT"
 fi
 echo "  source: $PACKAGE_SOURCE"
+sync_local_helper
 echo "Removing previous Pi Agent Platform package registrations:"
 remove_existing_piagent_platform_sources
 run_cmd pi install "$PACKAGE_SOURCE"
@@ -677,7 +778,7 @@ echo "  /login"
 echo "  /model          # or Ctrl+L: select provider/model from Pi selector"
 echo "  /scoped-models  # optional: edit Ctrl+P model cycle scope"
 if [[ "$WITH_MCP" == true ]]; then
-  echo "  /mcp            # inspect MCP servers; authenticate Figma/GitHub only when needed"
+  echo "  /mcp            # inspect MCP servers; authenticate approved remote servers only when needed"
 fi
 echo "  /subagents-doctor"
 echo "  /workflow task Implement <task>  # parent may auto-delegate scout/planner/reviewer"

package/scripts/mcp-manage.mjs

@@ -536,7 +536,7 @@ function commandPreset(args) {
       presets: CATALOG_PRESETS,
       servers: Object.fromEntries(Object.entries(CATALOG_SERVERS).map(([name, server]) => [
         name,
-        { description: server.description, requires: CATALOG_PREREQUISITES[name] ?? [] }
+        { description: server.description, maturity: server.maturity ?? "stable", requires: CATALOG_PREREQUISITES[name] ?? [] }
       ]))
     }, null, 2)}\n`);
     return 0;
@@ -563,7 +563,9 @@ function commandPreset(args) {
   const added = [];
   const kept = [];
   const replaced = [];
-  for (const server of resolvePreset(presetName)) {
+  const resolvedPreset = resolvePreset(presetName);
+  const experimental = resolvedPreset.filter((server) => server.maturity === "experimental").map((server) => server.name);
+  for (const server of resolvedPreset) {
     if (Object.hasOwn(config.mcpServers, server.name)) {
       if (!replace) {
         kept.push(server.name);
@@ -585,6 +587,7 @@ function commandPreset(args) {
     added,
     kept,
     replaced,
+    experimental,
     serverCount: Object.keys(config.mcpServers).length
   };
 
@@ -594,11 +597,21 @@ function commandPreset(args) {
     return 0;
   }
 
+  // Warn before the write. Naming a Google preset is explicit, but it is not
+  // evidence that the operator knows the endpoint is pre-GA or that Pi OAuth
+  // has not passed a credentialed release gate yet.
+  if (experimental.length > 0) {
+    process.stderr.write(
+      `\nEXPERIMENTAL: ${experimental.join(", ")} use Google Workspace Developer Preview endpoints. `
+      + "They are not part of the default presets and have no Pi OAuth end-to-end release proof yet.\n"
+    );
+  }
+
   writeMcpConfig(file, config);
   process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
 
-  // stdout stays machine-readable; the operator note goes to stderr.
-  const lines = resolvePreset(presetName).flatMap((server) => server.requires.map((item) => `  ${server.name}: ${item}`));
+  // stdout stays machine-readable; operator notes go to stderr.
+  const lines = resolvedPreset.flatMap((server) => server.requires.map((item) => `  ${server.name}: ${item}`));
   if (lines.length > 0) {
     process.stderr.write("\nServer definitions are written. Each still needs this before it can connect:\n");
     for (const line of lines) process.stderr.write(`${line}\n`);

package/scripts/pi-session-stats.sh

@@ -108,8 +108,13 @@ RPC_OUTPUT="$(
     | pi -ne --mode rpc --session "$SESSION_FILE" --offline --approve
 )"
 
-node --input-type=module - "$RPC_OUTPUT" <<'NODE'
+node --input-type=module - "$RPC_OUTPUT" "$SCRIPT_DIR/../packages/piagent-core/runtime/session/token-economics.js" <<'NODE'
+import { pathToFileURL } from "node:url";
+
 const input = process.argv[2] ?? "";
+// The token arithmetic lives in a module both this command and its test can
+// read, so the terminal cannot drift from the definition the benchmark uses.
+const { sessionTokenEconomics, formatTokenEconomics } = await import(pathToFileURL(process.argv[3]).href);
 
   const line = input
     .split(/\n+/)
@@ -126,6 +131,7 @@ const input = process.argv[2] ?? "";
   const data = response.data;
   const tokens = data.tokens ?? {};
   const context = data.contextUsage ?? {};
+  const economics = sessionTokenEconomics(tokens);
   const number = (value) => value === null || value === undefined ? "unknown" : Math.round(Number(value)).toLocaleString("en-US");
   const money = (value) => value === null || value === undefined ? "unknown" : `$${Number(value).toFixed(6)}`;
   const percent = (value) => value === null || value === undefined ? "unknown" : `${Number(value).toFixed(1)}%`;
@@ -144,7 +150,8 @@ const input = process.argv[2] ?? "";
       output: tokens.output ?? null,
       cacheRead: tokens.cacheRead ?? null,
       cacheWrite: tokens.cacheWrite ?? null,
-      total: tokens.total ?? null
+      total: tokens.total ?? null,
+      ...economics
     },
     cost: data.cost ?? null,
     contextUsage: context.tokens === undefined ? null : {
@@ -154,6 +161,7 @@ const input = process.argv[2] ?? "";
     },
     summary: {
       tokens: `${number(tokens.total)} total (${number(tokens.input)} input, ${number(tokens.output)} output, ${number(tokens.cacheRead)} cache read, ${number(tokens.cacheWrite)} cache write)`,
+      ...formatTokenEconomics(economics, number, percent),
       cost: money(data.cost),
       context: context.tokens === undefined ? "unknown" : `${number(context.tokens)} / ${number(context.contextWindow)} (${percent(context.percent)})`
     }

package/scripts/piagent-cli.mjs

@@ -23,12 +23,39 @@ const scriptByCommand = {
   "piagent-migrate": "scripts/migrate-project-state.mjs",
   "piagent-import-instructions": "scripts/import-agent-instructions.mjs",
   "piagent-auto": "scripts/pi-auto.sh",
-  "piagent-context": "scripts/context-engine.mjs"
+  "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"
 };
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const invokedAs = path.basename(process.argv[1] ?? "");
-const script = scriptByCommand[invokedAs];
+let forwardedArgs = process.argv.slice(2);
+let script = scriptByCommand[invokedAs];
+
+if (invokedAs === "piagent") {
+  const subcommand = forwardedArgs[0];
+  if (subcommand === "dashboard") {
+    script = "scripts/piagent-dashboard.mjs";
+    forwardedArgs = forwardedArgs.slice(1);
+  } else if (subcommand === "explain") {
+    script = "scripts/explain-command.mjs";
+    forwardedArgs = forwardedArgs.slice(1);
+  } else if ([undefined, "help", "--help", "-h"].includes(subcommand)) {
+    // Subcommands are listed, their flags are not. Restating them here meant a
+    // second copy that drifts: this line still advertised the dashboard without
+    // `--repair` after that flag shipped. Each command states its own surface.
+    console.log("Usage: piagent <command> [options]");
+    console.log("");
+    console.log("Commands:");
+    console.log("  dashboard   Open and manage the local session hub");
+    console.log("  explain     Say why the guard would allow or block a shell command");
+    console.log("");
+    console.log("Run `piagent <command> --help` for that command's options.");
+    process.exit(0);
+  }
+}
 
 if (!script) {
   console.error(`Unknown Pi Agent command: ${invokedAs || "(unknown)"}`);
@@ -58,7 +85,7 @@ const runner = target.endsWith(".mjs") ? process.execPath : "bash";
 const runnerArgs = target.endsWith(".mjs")
   ? ["--disable-warning=ExperimentalWarning", "--import", path.join(sourceRoot, "scripts", "register-typescript-loader.mjs"), target]
   : [target];
-const child = spawn(runner, [...runnerArgs, ...process.argv.slice(2)], {
+const child = spawn(runner, [...runnerArgs, ...forwardedArgs], {
   cwd: process.cwd(),
   env: process.env,
   stdio: "inherit"