@piagent/platform 1.4.0 → 1.4.1

package/packages/piagent-webui/dist/client/index.html

@@ -7,7 +7,7 @@
     <meta name="csp-nonce" content="__PIAGENT_CSP_NONCE__" />
     <meta name="piagent-webui-mode" content="__PIAGENT_WEBUI_MODE__" />
     <title>Piagent WebUI</title>
-    <script type="module" crossorigin src="/assets/index-DjMntaK5.js"></script>
+    <script type="module" crossorigin src="/assets/index-bu7XpD9Q.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-DwKCWbwd.css">
   </head>
   <body>

package/packages/piagent-webui/extension/lifecycle-controller.ts

@@ -131,6 +131,21 @@ export class LifecycleController {
     return !inspectTaskControlState(current.cwd, task).dispatchBlocked && !this.#pendingStop;
   }
 
+  inputAllowed(ctx?: ExtensionContext): boolean {
+    const current = ctx ?? this.#ctx; if (!current || !this.#sameSession(current) || this.#pendingStop) return false;
+    const task = this.#task(current); if (!task) return true;
+    const state = inspectTaskControlState(current.cwd, task).state;
+    return state === "active" || state === "terminal";
+  }
+
+  toolAllowed(toolName: string, ctx?: ExtensionContext): boolean {
+    if (this.dispatchAllowed(ctx)) return true;
+    const current = ctx ?? this.#ctx; if (!current || !this.#sameSession(current) || this.#pendingStop) return false;
+    const task = this.#task(current);
+    return toolName === "piagent_task_start" && Boolean(task)
+      && inspectTaskControlState(current.cwd, task).state === "terminal";
+  }
+
   observeAgentStart(ctx: ExtensionContext): void { if (!this.#sameSession(ctx)) return; this.#phase = "model"; }
   observeToolStart(ctx: ExtensionContext): void { if (!this.#sameSession(ctx)) return; this.#toolDepth += 1; this.#phase = "tool"; }
   observeToolEnd(ctx: ExtensionContext): void { if (!this.#sameSession(ctx)) return; this.#toolDepth = Math.max(0, this.#toolDepth - 1);

package/packages/piagent-webui/extension/piagent-webui.ts

@@ -398,10 +398,10 @@ export default function piagentWebUiExtension(pi: ExtensionAPI): void {
     }
   });
 
-  pi.on("tool_call", (_event, ctx) => { publishPersisted(ctx); if (!isGatewayRuntimeContext(ctx) && !terminalAdapter?.dispatchAllowed(ctx)) return { block: true,
+  pi.on("tool_call", (event, ctx) => { publishPersisted(ctx); if (!isGatewayRuntimeContext(ctx) && !terminalAdapter?.dispatchAllowed(ctx)) return { block: true,
     reason: `Piagent cannot prove this terminal owns the session (${terminalAdapter?.reasonCode() ?? "terminal-session-adapter-unavailable"}).` };
-    if (!lifecycle.dispatchAllowed(ctx)) return { block: true,
-    reason: "Piagent lifecycle control blocks new tool work while the task is paused or stopping." }; });
+    if (!lifecycle.toolAllowed(String(event.toolName ?? ""), ctx)) return { block: true,
+    reason: "Piagent lifecycle control blocks tool work while the task is paused, stopping, or terminal. A terminal task may only start its successor." }; });
   pi.on("tool_result", (_event, ctx) => publishPersisted(ctx));
   pi.on("input", (event, ctx) => {
     if (!isGatewayRuntimeContext(ctx) && !terminalAdapter?.dispatchAllowed(ctx)) {
@@ -409,7 +409,7 @@ export default function piagentWebUiExtension(pi: ExtensionAPI): void {
       catch { /* optional UI */ }
       return { action: "handled" } as const;
     }
-    if (!lifecycle.dispatchAllowed(ctx)) {
+    if (!lifecycle.inputAllowed(ctx)) {
       try { ctx.ui.notify("Piagent task is paused or stopping. Resume it before sending new work.", "warning"); } catch { /* optional UI */ }
       return { action: "handled" } as const;
     }

package/packages/piagent-webui/extension/same-session-bridge.ts

@@ -371,11 +371,11 @@ export class SameSessionPiBridge {
       return this.#rejection(command, "stale-revision", "stale-revision", "The current Pi session changed before dispatch.");
     if (this.#sessionOptionPermit)
       return this.#rejection(command, "capability-unavailable", "session-option-change-in-progress", "A model or thinking change is being settled.");
+    const delivery = command.payload.delivery;
     const controlState = this.#taskFacts(binding.ctx)?.controlState;
-    if (controlState && controlState !== "active")
+    if (controlState && controlState !== "active" && !(controlState === "terminal" && delivery === "new-operation"))
       return this.#rejection(command, "capability-unavailable", controlState === "terminal" ? "task-terminal" : "task-control-gate-closed",
-        controlState === "terminal" ? "A completed task cannot accept another dispatch." : "Task lifecycle control currently blocks dispatch.");
-    const delivery = command.payload.delivery;
+        controlState === "terminal" ? "A terminal task accepts only a new operation that can establish its successor." : "Task lifecycle control currently blocks dispatch.");
     if (delivery === "new-operation" && (!binding.ctx.isIdle() || binding.identity.agentOperationId))
       return this.#rejection(command, "dispatch-rejected", "agent-not-idle", "A new operation can start only while the Pi session is idle.");
     if (delivery !== "new-operation" && (binding.ctx.isIdle() || !binding.identity.agentOperationId))

package/packages/piagent-webui/gateway/extension-authority.ts

@@ -0,0 +1,47 @@
+import fs from "node:fs";
+import path from "node:path";
+
+type ExtensionLoadResult = {
+  extensions: Array<{ path: string; resolvedPath: string }>;
+  errors: Array<{ path: string; error: string }>;
+  runtime: unknown;
+};
+
+const PIAGENT_GUARD_SUFFIX = path.join("packages", "piagent-core", "extensions", "piagent-guard.ts");
+
+function canonicalExtensionPath(value: string): string {
+  try { return fs.realpathSync.native(value); }
+  catch { return path.resolve(value); }
+}
+
+function isPiagentGuardPath(value: string): boolean {
+  const normalized = path.normalize(value);
+  return normalized === PIAGENT_GUARD_SUFFIX || normalized.endsWith(`${path.sep}${PIAGENT_GUARD_SUFFIX}`);
+}
+
+export function preferAuthoritativePiagentGuard(
+  guardPath: string
+): (base: ExtensionLoadResult) => ExtensionLoadResult {
+  const authoritative = canonicalExtensionPath(guardPath);
+  const authorityAliases = [guardPath, path.resolve(guardPath), authoritative].map((value) => path.normalize(value));
+  return (base) => {
+    const loadedAuthoritative = base.extensions.some((extension) =>
+      canonicalExtensionPath(extension.resolvedPath || extension.path) === authoritative);
+    if (!loadedAuthoritative) return base;
+    const removed = new Set<string>();
+    const extensions = base.extensions.filter((extension) => {
+      const resolved = canonicalExtensionPath(extension.resolvedPath || extension.path);
+      const duplicate = resolved !== authoritative && isPiagentGuardPath(resolved);
+      if (duplicate) removed.add(resolved);
+      return !duplicate;
+    });
+    if (removed.size === 0) return base;
+    const errors = base.errors.filter((diagnostic) => {
+      const diagnosticPath = canonicalExtensionPath(diagnostic.path);
+      return !(removed.has(diagnosticPath)
+        && diagnostic.error.includes("conflicts with")
+        && authorityAliases.some((value) => diagnostic.error.includes(value)));
+    });
+    return { ...base, extensions, errors };
+  };
+}

package/packages/piagent-webui/gateway/session-inspection-registry.ts

@@ -19,9 +19,12 @@ type PiHost = {
     listAll(): Promise<PiSessionInfo[]>;
     open(file: string): {
       getBranch(): unknown[];
-      buildSessionContext(): { model: { provider: string; modelId: string } | null; thinkingLevel: string };
+      buildSessionContext(): { model: { provider: string; modelId: string } | null; thinkingLevel: string; messages: unknown[] };
     };
   };
+  calculateContextTokens(usage: unknown): number;
+  estimateTokens(message: unknown): number;
+  getLatestCompactionEntry(entries: unknown[]): unknown | null;
 };
 
 type ModelRuntime = {
@@ -59,6 +62,36 @@ function safeModelId(value: unknown): string | null {
   return redactSensitiveText(value).redacted ? null : value;
 }
 
+function persistedContextUsage(host: PiHost, entries: unknown[], messages: unknown[], model: Record<string, unknown> | undefined) {
+  const contextWindow = Number(model?.contextWindow);
+  if (!Number.isFinite(contextWindow) || contextWindow <= 0) return undefined;
+  const latestCompaction = host.getLatestCompactionEntry(entries);
+  if (latestCompaction) {
+    const boundary = entries.lastIndexOf(latestCompaction);
+    let hasPostCompactionUsage = false;
+    for (let index = entries.length - 1; index > boundary; index -= 1) {
+      const entry = entries[index] as { type?: unknown; message?: { role?: unknown; stopReason?: unknown; usage?: unknown } } | undefined;
+      const message = entry?.type === "message" ? entry.message : undefined;
+      if (message?.role === "assistant" && message.usage && message.stopReason !== "aborted" && message.stopReason !== "error"
+        && host.calculateContextTokens(message.usage) > 0) {
+        hasPostCompactionUsage = true;
+        break;
+      }
+    }
+    if (!hasPostCompactionUsage) return { tokens: null, contextWindow, percent: null };
+  }
+  let lastUsageIndex = -1, tokens = 0;
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index] as { role?: unknown; stopReason?: unknown; usage?: unknown } | undefined;
+    if (message?.role !== "assistant" || !message.usage || message.stopReason === "aborted" || message.stopReason === "error") continue;
+    const measured = host.calculateContextTokens(message.usage);
+    if (measured > 0) { tokens = measured; lastUsageIndex = index; break; }
+  }
+  for (let index = lastUsageIndex + 1; index < messages.length; index += 1) tokens += host.estimateTokens(messages[index]);
+  if (!Number.isFinite(tokens) || tokens < 0) return undefined;
+  return { tokens, contextWindow, percent: tokens / contextWindow * 100 };
+}
+
 export class SessionInspectionRegistry {
   readonly #gatewayInstanceRef: string;
   readonly #host: PiHost;
@@ -173,9 +206,10 @@ export class SessionInspectionRegistry {
     let manager: ReturnType<PiHost["SessionManager"]["open"]>;
     try { manager = this.#host.SessionManager.open(info.path); }
     catch { throw new ReadModelNotFound(); }
-    const context = safeRead(() => manager.buildSessionContext(), { model: null, thinkingLevel: "unknown" });
+    const context = safeRead(() => manager.buildSessionContext(), { model: null, thinkingLevel: "unknown", messages: [] });
     const model = context.model ? this.#models?.getModel(context.model.provider, context.model.modelId) : undefined;
     const entries = safeRead(() => manager.getBranch(), []);
+    const contextUsage = safeRead(() => persistedContextUsage(this.#host, entries, context.messages, model), undefined);
     const eventStore = {
       retention: () => ({ eventRetentionCount: 0, eventRetentionSeconds: 0 }),
       currentCursor: () => null,
@@ -191,6 +225,7 @@ export class SessionInspectionRegistry {
       activityEvents: () => safeRead(() => readContextTelemetry(info.cwd, { limit: 5_000 }), []),
       sessionEntries: () => entries,
       protectedPaths: () => runtimeProtectedPaths(this.#packageRoot, info.cwd),
+      contextUsage: () => contextUsage,
       model: () => model,
       thinkingLevel: () => context.thinkingLevel,
       approvalProjection: () => piApprovalBroker.projection(info.cwd, info.id),

package/packages/piagent-webui/gateway/session-runtime-supervisor.ts

@@ -12,6 +12,7 @@ import { SessionLeaseStore, type SessionLeaseSnapshot } from "./session-lease-st
 import { GatewayEventStore } from "./gateway-events.ts";
 import { GatewaySessionStream } from "./gateway-session-stream.ts";
 import { GATEWAY_RUNTIME_UI_MARKER } from "../ownership/gateway-runtime-context.ts";
+import { preferAuthoritativePiagentGuard } from "./extension-authority.ts";
 
 const MAX_WARM_RUNTIMES = 10;
 
@@ -55,7 +56,10 @@ function productionRuntimeFactory(options: { host: any; agentDir: string; packag
     const createRuntime = async ({ cwd, agentDir, sessionManager, sessionStartEvent }: any) => {
       const services = await options.host.createAgentSessionServices({
         cwd, agentDir, modelRuntime: options.modelRuntime,
-        resourceLoaderOptions: { additionalExtensionPaths: [guard] }
+        resourceLoaderOptions: {
+          additionalExtensionPaths: [guard],
+          extensionsOverride: preferAuthoritativePiagentGuard(guard)
+        }
       });
       const extensionErrors = services.resourceLoader.getExtensions().errors;
       if (extensionErrors.length) throw new Error("session-runtime-extension-load-failed");

package/packages/piagent-webui/server/core-inspection-provider.ts

@@ -101,7 +101,7 @@ export class CoreInspectionProvider implements WebUiReadModelProvider {
     if (control?.state === "ready" && control.identity && control.revisions && !this.#input.eventStore.resyncRequired()) {
       const available = { available: true, reasonCode: null }, disabled = (reasonCode: string) => ({ available: false, reasonCode });
       const lifecycle = this.#input.lifecycleControl?.(), terminal = control.taskState === "terminal";
-      const dispatchBlocked = terminal || lifecycle?.dispatchBlocked === true;
+      const dispatchBlocked = lifecycle?.dispatchBlocked === true && lifecycle.state !== "terminal";
       value.snapshot.identity = structuredClone(control.identity);
       value.snapshot.capabilities.identity = structuredClone(control.identity);
       for (const name of ["runtimeRevision", "taskRevision", "controlRevision", "sessionOptionRevision", "queueRevision"])
@@ -109,11 +109,11 @@ export class CoreInspectionProvider implements WebUiReadModelProvider {
       value.snapshot.capabilities.mode = "control-enabled";
       value.snapshot.capabilities.capabilities["control.chat"] = {
         status: "available", version: 1, reason: null, queuePersistence: "runtime-lifetime",
-        actions: { send: dispatchBlocked ? disabled(terminal ? "task-terminal" : "task-control-gate-closed") : available, hold: available, editHeld: available,
-          deleteHeld: available, dispatchHeld: dispatchBlocked ? disabled(terminal ? "task-terminal" : "task-control-gate-closed") : available,
-          interruptAndSend: dispatchBlocked ? disabled(terminal ? "task-terminal" : "task-control-gate-closed") : control.liveness === "running" ? available : disabled("agent-not-running") }
+        actions: { send: dispatchBlocked ? disabled("task-control-gate-closed") : available, hold: available, editHeld: available,
+          deleteHeld: available, dispatchHeld: dispatchBlocked ? disabled("task-control-gate-closed") : available,
+          interruptAndSend: dispatchBlocked ? disabled("task-control-gate-closed") : control.liveness === "running" ? available : disabled("agent-not-running") }
       };
-      if (!terminal && this.#input.attachmentCapability) {
+      if (this.#input.attachmentCapability) {
         const attachment = this.#input.attachmentCapability();
         value.snapshot.capabilities.capabilities.attachments = { status: "available", version: 1, reason: null,
           kinds: attachment.kinds, mimeTypes: attachment.mimeTypes };

package/packages/piagent-webui/server/transcript-projection.ts

@@ -41,6 +41,19 @@ function messageText(message: any): string {
   if (!Array.isArray(message?.content)) return "";
   return message.content.filter((item: any) => item?.type === "text" && typeof item.text === "string").map((item: any) => item.text).join("\n");
 }
+function assistantFailureReason(message: any): string | null {
+  if (message?.role !== "assistant" || message?.stopReason !== "error") return null;
+  const detail = String(message?.errorMessage ?? "").toLowerCase();
+  if (/(?:authentication|auth|token|credential).{0,48}expired|expired.{0,48}(?:authentication|auth|token|credential)/.test(detail)) {
+    return "provider-auth-expired";
+  }
+  if (/(?:authentication|unauthorized|forbidden|credential|api[ _-]?key|log[ -]?in|sign[ -]?in)/.test(detail)) {
+    return "provider-auth-required";
+  }
+  if (/(?:rate[ _-]?limit|too many requests|quota)/.test(detail)) return "provider-rate-limited";
+  if (/(?:network|fetch failed|econn|timed? ?out|unavailable)/.test(detail)) return "provider-unavailable";
+  return "provider-response-failed";
+}
 function safeText(value: string): { full: string; preview: string; redacted: boolean; truncated: boolean } {
   const clean = value.replace(ANSI, "").replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, " ");
   const redaction = redactSensitiveText(clean);
@@ -78,6 +91,8 @@ function item(entry: any, identity: TranscriptIdentity): TranscriptItem | null {
   if (!itemRole || !recordedAt || typeof entry.id !== "string" || entry.id.length === 0) return null;
   const content = itemRole === "tool-result" ? unavailableContent("tool-output-in-activity-preview") : (() => {
     const projected = safeText(messageText(entry.message));
+    const failureReason = projected.full.length === 0 ? assistantFailureReason(entry.message) : null;
+    if (failureReason) return unavailableContent(failureReason);
     return { state: projected.redacted ? "redacted" as const : "available" as const, text: projected.preview,
       textChars: Math.min(1_000_000_000, projected.full.length), digest: `sha256:${hash(projected.full)}`, truncated: projected.truncated,
       redacted: projected.redacted, imageCount: imageCount(entry.message), reasonCode: projected.redacted ? "sensitive-values-redacted" as const : null };

package/scripts/build-docs-site.mjs

@@ -24,6 +24,26 @@ const SITE = {
   facebook: "https://www.facebook.com/vinhtam0544/"
 };
 
+// Vercel Web Analytics, added here rather than to a page so all locales and
+// every generated page carry the same one. It is cookieless and stores no
+// identifier in the browser, so the site needs no consent banner -- which is
+// the reason to prefer it over an analytics product that would.
+//
+// The route only exists once Web Analytics is enabled for the Vercel project
+// (dashboard -> Analytics -> Enable) and the site is redeployed. Until then the
+// request 404s and the page is otherwise unaffected: the inline shim below
+// queues calls instead of throwing on an undefined `window.va`.
+//
+// Enabling also provisions a second, project-unique route that ad blockers do
+// not recognise. Swapping this src for that path collects more of the traffic;
+// this stable one is used because it does not embed a per-project secret in a
+// public repository.
+const ANALYTICS_SNIPPET = `    <script>
+      window.va = window.va || function () { (window.vaq = window.vaq || []).push(arguments); };
+    </script>
+    <script defer src="/_vercel/insights/script.js"></script>
+`;
+
 // Order here is the order in the sidebar, and it is also the order of the
 // previous/next links at the foot of each page.
 const NAV = [
@@ -527,7 +547,7 @@ ${renderPager(index, pages, locale)}
         <nav data-toc></nav>
       </aside>
     </div>
-  </body>
+${ANALYTICS_SNIPPET}  </body>
 </html>
 `;
 }

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);
+}