@piagent/platform 1.4.0 → 1.5.1

package/schemas/piagent-webui/document-workspace-v1.schema.json

@@ -0,0 +1,155 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://piagent.io.vn/schemas/piagent-webui/document-workspace-v1.schema.json",
+  "title": "Piagent WebUI bounded document workspace v1",
+  "oneOf": [
+    { "$ref": "#/$defs/listing" },
+    { "$ref": "#/$defs/document" }
+  ],
+  "$defs": {
+    "displayText": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024,
+      "pattern": "^[^\\u0000-\\u001F\\u007F]*$"
+    },
+    "nullableDisplayText": {
+      "anyOf": [
+        { "$ref": "#/$defs/displayText" },
+        { "type": "null" }
+      ]
+    },
+    "root": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["rootRef", "path", "source", "documentCount"],
+      "properties": {
+        "rootRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+        "path": { "$ref": "#/$defs/displayText" },
+        "source": { "enum": ["project", "profile", "environment"] },
+        "documentCount": { "type": "integer", "minimum": 0, "maximum": 2000 }
+      }
+    },
+    "entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["documentRef", "rootRef", "name", "relativePath", "extension", "sizeBytes", "modifiedAt"],
+      "properties": {
+        "documentRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+        "rootRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+        "name": { "$ref": "#/$defs/displayText" },
+        "relativePath": { "$ref": "#/$defs/displayText" },
+        "extension": {
+          "enum": ["md", "markdown", "txt", "text", "csv", "tsv", "json", "yaml", "yml", "pdf", "docx"]
+        },
+        "sizeBytes": { "type": "integer", "minimum": 1, "maximum": 12582912 },
+        "modifiedAt": { "$ref": "common-v1.schema.json#/$defs/timestamp" }
+      }
+    },
+    "listing": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "version", "messageType", "generatedAt", "state", "roots", "documents", "truncated", "reasonCode"],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "version": { "const": "piagent-webui-document-workspace-v1" },
+        "messageType": { "const": "listing" },
+        "generatedAt": { "$ref": "common-v1.schema.json#/$defs/timestamp" },
+        "state": { "enum": ["ready", "unavailable"] },
+        "roots": {
+          "type": "array",
+          "maxItems": 32,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/root" }
+        },
+        "documents": {
+          "type": "array",
+          "maxItems": 2000,
+          "items": { "$ref": "#/$defs/entry" }
+        },
+        "truncated": { "type": "boolean" },
+        "reasonCode": { "$ref": "common-v1.schema.json#/$defs/nullableReasonCode" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "state": { "const": "unavailable" } }, "required": ["state"] },
+          "then": {
+            "properties": {
+              "roots": { "type": "array", "maxItems": 0 },
+              "documents": { "type": "array", "maxItems": 0 },
+              "reasonCode": { "$ref": "common-v1.schema.json#/$defs/reasonCode" }
+            }
+          }
+        },
+        {
+          "if": { "properties": { "state": { "const": "ready" } }, "required": ["state"] },
+          "then": {
+            "properties": {
+              "roots": { "type": "array", "minItems": 1 },
+              "reasonCode": { "type": "null" }
+            }
+          }
+        }
+      ]
+    },
+    "document": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "version", "messageType", "generatedAt", "documentRef", "state", "name", "relativePath", "rootRef", "format", "text", "sizeBytes", "truncated", "redacted", "reasonCode"],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "version": { "const": "piagent-webui-document-workspace-v1" },
+        "messageType": { "const": "document" },
+        "generatedAt": { "$ref": "common-v1.schema.json#/$defs/timestamp" },
+        "documentRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+        "state": { "enum": ["ready", "unavailable"] },
+        "name": { "$ref": "#/$defs/nullableDisplayText" },
+        "relativePath": { "$ref": "#/$defs/nullableDisplayText" },
+        "rootRef": { "$ref": "common-v1.schema.json#/$defs/nullableOpaqueRef" },
+        "format": { "enum": ["text", "docx", "pdf", null] },
+        "text": {
+          "anyOf": [
+            { "type": "string", "maxLength": 400000 },
+            { "type": "null" }
+          ]
+        },
+        "sizeBytes": {
+          "anyOf": [
+            { "type": "integer", "minimum": 1, "maximum": 12582912 },
+            { "type": "null" }
+          ]
+        },
+        "truncated": { "type": "boolean" },
+        "redacted": { "type": "boolean" },
+        "reasonCode": { "$ref": "common-v1.schema.json#/$defs/nullableReasonCode" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "state": { "const": "ready" } }, "required": ["state"] },
+          "then": {
+            "properties": {
+              "name": { "$ref": "#/$defs/displayText" },
+              "relativePath": { "$ref": "#/$defs/displayText" },
+              "rootRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+              "format": { "enum": ["text", "docx", "pdf"] },
+              "text": { "type": "string", "maxLength": 400000 },
+              "reasonCode": { "type": "null" }
+            }
+          }
+        },
+        {
+          "if": { "properties": { "state": { "const": "unavailable" } }, "required": ["state"] },
+          "then": {
+            "properties": {
+              "text": { "type": "null" },
+              "format": { "type": "null" },
+              "truncated": { "const": false },
+              "redacted": { "const": false },
+              "reasonCode": { "$ref": "common-v1.schema.json#/$defs/reasonCode" }
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/schemas/piagent-webui/session-command-v1.schema.json

@@ -56,7 +56,11 @@
                 "modelRef": { "$ref": "common-v1.schema.json#/$defs/nullableOpaqueRef" },
                 "thinkingLevel": { "$ref": "#/$defs/thinkingLevel" },
                 "message": { "type": "string", "minLength": 1, "maxLength": 32768, "pattern": "^[^\\u0000]*$" },
-                "messageRequestId": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" }
+                "messageRequestId": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+                "deferInitialMessage": {
+                  "description": "Create the durable session without dispatching the first turn so the client can stage selected attachments against the new session before sending it.",
+                  "type": "boolean"
+                }
               }
             }
           }
@@ -75,12 +79,19 @@
             "payload": {
               "type": "object",
               "additionalProperties": false,
-              "required": ["delivery", "message", "messageRequestId", "expectedOperationRef"],
+              "required": ["delivery", "message", "messageRequestId", "expectedOperationRef", "attachmentRefs"],
               "properties": {
                 "delivery": { "enum": ["new-operation", "follow-up", "steer"] },
                 "message": { "type": "string", "minLength": 1, "maxLength": 32768, "pattern": "^[^\\u0000]*$" },
                 "messageRequestId": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
-                "expectedOperationRef": { "$ref": "common-v1.schema.json#/$defs/nullableOpaqueRef" }
+                "expectedOperationRef": { "$ref": "common-v1.schema.json#/$defs/nullableOpaqueRef" },
+                "attachmentRefs": {
+                  "description": "Refs staged for this exact messageRequestId. Claimed once at dispatch and consumed.",
+                  "type": "array",
+                  "maxItems": 4,
+                  "uniqueItems": true,
+                  "items": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" }
+                }
               },
               "allOf": [
                 {

package/schemas/piagent-webui/transcript-v1.schema.json

@@ -188,6 +188,12 @@
         "agentOperationId": { "$ref": "common-v1.schema.json#/$defs/nullableOpaqueRef" },
         "turnIndex": { "$ref": "#/$defs/nullableCount" },
         "content": { "$ref": "#/$defs/content" },
+        "attachments": {
+          "type": "array",
+          "maxItems": 4,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/attachmentSummary" }
+        },
         "toolCalls": {
           "type": "array",
           "maxItems": 64,
@@ -217,6 +223,27 @@
         }
       ]
     },
+    "attachmentSummary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["displayName", "kind", "mimeType", "truncated"],
+      "properties": {
+        "displayName": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 160,
+          "pattern": "^[^\\u0000-\\u001F\\u007F/\\\\]*$"
+        },
+        "kind": { "enum": ["file", "image", "document"] },
+        "mimeType": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 120,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9.+-]*/[A-Za-z0-9][A-Za-z0-9.+-]*$"
+        },
+        "truncated": { "type": "boolean" }
+      }
+    },
     "page": {
       "type": "object",
       "additionalProperties": false,

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

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"