@piagent/platform 1.3.0-ie.9 → 1.3.1

package/docs-site/mcp-approval.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.3.0-ie.9 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.3.1 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/mcp-approval" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/mcp-approval" hreflang="en" lang="en">EN</a>

package/docs-site/mcp-auth.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.3.0-ie.9 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.3.1 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/mcp-auth" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/mcp-auth" hreflang="en" lang="en">EN</a>

package/docs-site/mcp-servers.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.3.0-ie.9 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.3.1 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/mcp-servers" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/mcp-servers" hreflang="en" lang="en">EN</a>

package/docs-site/mcp.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.3.0-ie.9 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.3.1 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/mcp" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/mcp" hreflang="en" lang="en">EN</a>

package/docs-site/permissions.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.3.0-ie.9 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.3.1 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/permissions" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/permissions" hreflang="en" lang="en">EN</a>

package/docs-site/profiles.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.3.0-ie.9 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.3.1 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/profiles" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/profiles" hreflang="en" lang="en">EN</a>

package/docs-site/quickstart.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.3.0-ie.9 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.3.1 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/quickstart" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/quickstart" hreflang="en" lang="en">EN</a>

package/docs-site/runtime.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.3.0-ie.9 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.3.1 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/runtime" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/runtime" hreflang="en" lang="en">EN</a>

package/docs-site/scope.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.3.0-ie.9 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.3.1 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/scope" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/scope" hreflang="en" lang="en">EN</a>

package/docs-site/security.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.3.0-ie.9 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.3.1 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/security" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/security" hreflang="en" lang="en">EN</a>

package/docs-site/team.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.3.0-ie.9 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.3.1 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/team" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/team" hreflang="en" lang="en">EN</a>

package/docs-site/whats-new.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.3.0-ie.9 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.3.1 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/whats-new" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/whats-new" hreflang="en" lang="en">EN</a>

package/docs-site/workflows.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.3.0-ie.9 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.3.1 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/workflows" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/workflows" hreflang="en" lang="en">EN</a>

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "@piagent/platform",
-  "version": "1.3.0-ie.9",
+  "version": "1.3.1",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
-    "provenance": true,
-    "tag": "next"
+    "provenance": true
   },
   "type": "module",
   "description": "Reusable Pi agent platform, project adapters, MCP/tool policy, and coding workflow harness.",

package/packages/piagent-core/capabilities/capability-verification-cache.js

@@ -0,0 +1,280 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { sha256, stableJson, verifyCapabilityLock } from "./capability-core.js";
+import { resolveProjectProfileDocument } from "./project-profile.js";
+
+const compare = (left, right) => String(left).localeCompare(String(right), "en");
+const MAX_PACK_ENTRIES = 256;
+const MAX_ARTIFACTS_PER_KIND = 128;
+const MAX_JSON_BYTES = 256 * 1024;
+
+// Full capability resolution deliberately hashes every executable runtime file.
+// That is the right cold-path check, but not useful per-call work. This cache
+// remembers only a `current` full verification. Reuse still walks strong
+// metadata for every input that produced it; any change or error falls back to
+// the cryptographic verifier.
+export function createCapabilityVerificationCache() {
+  return new Map();
+}
+
+function cacheRootForPack(rootReal, pack, extraRoots) {
+  return pack.origin === "workspace"
+    ? rootReal
+    : extraRoots.find((entry) => entry.origin === pack.origin)?.root;
+}
+
+function addTarget(targets, target, kind, optional = false) {
+  const absolute = path.resolve(target);
+  const previous = targets.get(absolute);
+  if (!previous || previous.kind !== "directory") targets.set(absolute, { path: absolute, kind, optional });
+}
+
+function containedTarget(root, relativePath) {
+  if (typeof relativePath !== "string" || path.isAbsolute(relativePath)) return undefined;
+  const absolute = path.resolve(root, relativePath);
+  const relative = path.relative(root, absolute);
+  return relative.startsWith("..") || path.isAbsolute(relative) ? undefined : absolute;
+}
+
+function readBoundedJson(file) {
+  const stat = fs.lstatSync(file);
+  if (stat.isSymbolicLink() || !stat.isFile() || stat.size > MAX_JSON_BYTES) return undefined;
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+function addEvalInputs(targets, packRoot, artifactPath) {
+  const artifact = readBoundedJson(artifactPath);
+  const profile = containedTarget(packRoot, artifact?.spec?.profile);
+  const fixture = containedTarget(packRoot, artifact?.spec?.fixture?.path);
+  if (!profile || !fixture) return false;
+  addTarget(targets, profile, "file");
+  addTarget(targets, fixture, "file");
+  return true;
+}
+
+function addCatalogTargets(targets, packRoot) {
+  const packsDirectory = path.join(packRoot, "packs");
+  addTarget(targets, packsDirectory, "directory");
+  const entries = fs.readdirSync(packsDirectory, { withFileTypes: true })
+    .filter((entry) => !entry.name.startsWith("."));
+  if (entries.length > MAX_PACK_ENTRIES) return false;
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.isSymbolicLink?.()) return false;
+    const packDirectory = path.join(packsDirectory, entry.name);
+    addTarget(targets, packDirectory, "directory");
+    const manifestPath = path.join(packDirectory, "pack.json");
+    addTarget(targets, manifestPath, "file");
+    const manifest = readBoundedJson(manifestPath);
+    const provides = manifest?.spec?.provides;
+    if (!provides || typeof provides !== "object" || Array.isArray(provides)) return false;
+    for (const [kind, artifacts] of Object.entries(provides)) {
+      if (!Array.isArray(artifacts) || artifacts.length > MAX_ARTIFACTS_PER_KIND) return false;
+      for (const artifact of artifacts) {
+        const target = containedTarget(packRoot, artifact?.path);
+        if (!target) return false;
+        addTarget(targets, target, "file");
+        if (kind === "evals" && !addEvalInputs(targets, packRoot, target)) return false;
+      }
+    }
+  }
+  return true;
+}
+
+function verificationTargets(root, profilePath, lockPath, document, options = {}) {
+  const rootReal = fs.realpathSync(root);
+  const targets = new Map();
+  addTarget(targets, profilePath, "file");
+  addTarget(targets, lockPath, "file");
+  for (const target of options.identityFiles ?? []) addTarget(targets, target, "file", true);
+
+  const extraRoots = options.extraRoots ?? [];
+  const packRoots = new Map();
+  for (const pack of document?.packs ?? []) {
+    const packRoot = cacheRootForPack(rootReal, pack, extraRoots);
+    if (!packRoot) continue;
+    packRoots.set(`${pack.name}@${pack.version}`, packRoot);
+    addTarget(targets, path.join(packRoot, "packs"), "directory");
+    addTarget(targets, path.join(packRoot, "packs", pack.name), "directory");
+    addTarget(targets, path.join(packRoot, "packs", pack.name, "pack.json"), "file");
+  }
+  for (const entry of extraRoots) {
+    addTarget(targets, entry.root, "directory");
+    addTarget(targets, path.join(entry.root, "packs"), "directory");
+  }
+  for (const packRoot of [rootReal, ...extraRoots.map((entry) => entry.root)]) {
+    if (!addCatalogTargets(targets, packRoot)) return undefined;
+  }
+  for (const entry of document?.core?.runtimeFiles ?? []) {
+    const target = containedTarget(rootReal, entry.path);
+    if (!target) return undefined;
+    addTarget(targets, target, "file");
+  }
+  for (const artifact of document?.artifacts ?? []) {
+    const artifactRoot = packRoots.get(artifact.pack);
+    if (!artifactRoot) continue;
+    const target = containedTarget(artifactRoot, artifact.path);
+    if (!target) return undefined;
+    addTarget(targets, target, "file");
+  }
+  return [...targets.values()].sort((left, right) => compare(left.path, right.path));
+}
+
+function statIdentity(stat, includeTimes) {
+  const values = [stat.dev, stat.ino, stat.mode, stat.nlink, stat.uid, stat.gid, stat.rdev, stat.size];
+  if (includeTimes) values.push(stat.mtimeNs, stat.ctimeNs);
+  return values.map(String).join(":");
+}
+
+function ancestorIdentity(stat) {
+  return [stat.dev, stat.ino, stat.mode, stat.uid, stat.gid, stat.rdev]
+    .map(String)
+    .join(":");
+}
+
+function lexicalAncestors(target) {
+  const parsed = path.parse(target);
+  const segments = target.slice(parsed.root.length).split(path.sep).filter(Boolean);
+  const ancestors = [];
+  let current = parsed.root;
+  for (const segment of segments.slice(0, -1)) {
+    current = path.join(current, segment);
+    ancestors.push(current);
+  }
+  return ancestors;
+}
+
+function metadataSignature(targets) {
+  if (!targets) return undefined;
+  const records = [];
+  const ancestors = new Set(targets.flatMap((target) => lexicalAncestors(target.path)));
+  try {
+    for (const ancestor of [...ancestors].sort(compare)) {
+      const stat = fs.lstatSync(ancestor, { bigint: true });
+      const symbolic = stat.isSymbolicLink();
+      const identity = symbolic ? statIdentity(stat, true) : ancestorIdentity(stat);
+      records.push(`a:${ancestor}:${identity}:${symbolic ? fs.readlinkSync(ancestor) : "directory"}`);
+    }
+    for (const target of targets) {
+      let lexical;
+      try {
+        lexical = fs.lstatSync(target.path, { bigint: true });
+      } catch (error) {
+        if (target.optional && error?.code === "ENOENT") {
+          records.push(`t:${target.path}:absent`);
+          continue;
+        }
+        return undefined;
+      }
+      const expectedType = target.kind === "directory" ? lexical.isDirectory() : lexical.isFile();
+      if (!expectedType || lexical.isSymbolicLink()) return undefined;
+      records.push(`t:${target.path}:${statIdentity(lexical, true)}`);
+    }
+  } catch {
+    return undefined;
+  }
+  return sha256(records.join("\n"));
+}
+
+const cacheKey = (root, profilePath, lockPath) => (
+  `${path.resolve(root)}\0${path.resolve(profilePath)}\0${path.resolve(lockPath)}`
+);
+
+function cacheIdentity(lockDocument, options = {}) {
+  return sha256(stableJson({
+    lockDocument,
+    packageSource: options.packageSource,
+    extraRoots: (options.extraRoots ?? []).map((entry) => ({ origin: entry.origin, root: entry.root, source: entry.source })),
+    identityFiles: (options.identityFiles ?? []).map((entry) => path.resolve(entry)).sort(compare)
+  }));
+}
+
+function snapshotTargets(targets) {
+  const signature = metadataSignature(targets);
+  return signature ? { signature, targets } : undefined;
+}
+
+function stableSnapshot(snapshot) {
+  if (!snapshot) return false;
+  const current = metadataSignature(snapshot.targets);
+  return Boolean(current && current === snapshot.signature);
+}
+
+export function verifyCapabilityLockCached(cache, root, profilePath, lockPath, lockDocument, options = {}) {
+  const key = cacheKey(root, profilePath, lockPath);
+  const identity = cacheIdentity(lockDocument, options);
+  const cached = options.forceFull === true ? undefined : cache?.get(key);
+  if (cached?.identity === identity) {
+    const signature = metadataSignature(cached.targets);
+    if (signature && signature === cached.signature) return { ...cached.verification, cacheStatus: "hit" };
+  }
+  cache?.delete(key);
+
+  const initialTargets = verificationTargets(root, profilePath, lockPath, lockDocument, options);
+  const before = snapshotTargets(initialTargets);
+  const verification = verifyCapabilityLock(root, profilePath, lockDocument, options);
+  options.afterFullVerify?.();
+  if (verification.status === "current" && before) {
+    const after = snapshotTargets(verificationTargets(root, profilePath, lockPath, verification.expected, options));
+    if (after && before.signature === after.signature && stableSnapshot(after)) {
+      cache?.set(key, { identity, ...after, verification });
+    }
+  }
+  return { ...verification, cacheStatus: "verified" };
+}
+
+export function verifyProjectCapabilityStateCached(input) {
+  const { cache, cwd, platformRoot, profilePath, lockPath, lockDocument, storedProfile } = input;
+  const profile = resolveProjectProfileDocument(platformRoot, storedProfile).profile;
+  if (!Array.isArray(profile.capabilityPacks)) return { ok: true };
+  const packageSource = input.packageSource(cwd);
+  const extraRoots = input.extraRoots(cwd, profile);
+  const identityFiles = [path.join(cwd, ".pi", "settings.json")];
+  if (typeof storedProfile.extends === "string" && /^[a-z0-9][a-z0-9-]{0,63}$/.test(storedProfile.extends)) {
+    identityFiles.push(path.join(platformRoot, "adapters", storedProfile.extends, "profile.json"));
+  }
+  const verificationOptions = { packageSource, extraRoots, identityFiles, forceFull: input.forceFull === true };
+  const verification = verifyCapabilityLockCached(cache, platformRoot, profilePath, lockPath, lockDocument, verificationOptions);
+  const runtimeDigest = verification.expected?.core?.packageDigest;
+  if (input.allowRepin !== true && input.sessionDigest && runtimeDigest !== input.sessionDigest) {
+    return { ok: false, reason: "Installed Piagent runtime changed during this session. Restart the session to verify and re-pin the capability lock before using tools." };
+  }
+  if (verification.status === "repin" && input.allowRepin !== true) {
+    return { ok: false, reason: "Installed Piagent runtime changed during this session. Restart the session to verify and re-pin the capability lock before using tools." };
+  }
+  if (verification.status === "blocked") {
+    return { ok: false, reason: `Capability lock does not match what this project agreed to: ${verification.reasons.join("; ")}. Reapply the project profile.` };
+  }
+  const granted = {
+    filesystemRead: verification.expected.permissions.filesystemRead,
+    filesystemWrite: verification.expected.permissions.filesystemWrite
+  };
+  if (verification.status !== "repin") {
+    if (input.allowRepin === true) input.rememberSessionDigest?.(runtimeDigest);
+    return { ok: true, ...granted };
+  }
+
+  try {
+    input.writeLock(lockPath, verification.expected);
+  } catch (error) {
+    return { ok: false, reason: `Capability lock is behind the installed platform and could not be rewritten: ${error instanceof Error ? error.message : String(error)}` };
+  }
+  input.afterRepinWrite?.();
+  const confirmed = verifyCapabilityLockCached(
+    cache,
+    platformRoot,
+    profilePath,
+    lockPath,
+    verification.expected,
+    { ...verificationOptions, forceFull: true }
+  );
+  if (confirmed.status !== "current") {
+    return { ok: false, reason: "Installed Piagent runtime changed while the capability lock was being re-pinned. Restart the session and try again." };
+  }
+  input.rememberSessionDigest?.(runtimeDigest);
+  return { ok: true, repinned: verification.reasons.join("; "), ...granted };
+}

package/packages/piagent-core/capabilities/runtime-integrity.js

@@ -7,17 +7,23 @@ export const CORE_RUNTIME_INTEGRITY_FILES = Object.freeze([
   "packages/piagent-core/extensions/acceptance-receipt.js",
   "packages/piagent-core/extensions/criterion-graph.js",
   "packages/piagent-core/extensions/criterion-context-pack.js",
+  "packages/piagent-core/extensions/document-intake.ts",
+  "packages/piagent-core/extensions/execution-backend.js",
   "packages/piagent-core/extensions/failure-types.ts",
   "packages/piagent-core/extensions/repository-memory.js",
+  "packages/piagent-core/extensions/state-retention.js",
   "packages/piagent-core/extensions/task-contract-view.js",
   "packages/piagent-core/extensions/task-authority-contract.js",
   "packages/piagent-core/extensions/task-digest-migration.js",
   "packages/piagent-core/extensions/task-journal.js",
   "packages/piagent-core/extensions/task-runtime-audit.js",
+  "packages/piagent-core/extensions/task-state.js",
   "packages/piagent-core/extensions/tenant-contract.js",
+  "packages/piagent-core/extensions/verification-intelligence.js",
   "packages/piagent-core/extensions/working-tree-digest.js",
   "packages/piagent-core/policy/authority-manifest.v1.json",
   "packages/piagent-core/capabilities/authority-manifest.ts",
+  "packages/piagent-core/capabilities/capability-verification-cache.js",
   "packages/piagent-core/runtime/hooks/agent-start-hook.ts",
   "packages/piagent-core/runtime/hooks/completion-hook.ts",
   "packages/piagent-core/runtime/hooks/input-hook.ts",
@@ -95,5 +101,8 @@ export const CORE_RUNTIME_INTEGRITY_FILES = Object.freeze([
   "packages/piagent-core/runtime/tools/phase-tools.ts",
   "packages/piagent-core/runtime/tools/phase-tool-runtime.ts",
   "packages/piagent-core/runtime/workflows/input-routing.ts",
-  "packages/piagent-core/runtime/workflows/task-intake.ts"
+  "packages/piagent-core/runtime/workflows/task-intake.ts",
+  "scripts/piagent-cli.mjs",
+  "scripts/register-typescript-loader.mjs",
+  "scripts/typescript-loader.mjs"
 ]);

package/packages/piagent-core/extensions/document-intake.ts

@@ -51,6 +51,8 @@ export type DocumentExtraction =
   | { status: "ok"; text: string; truncated: boolean; kind: "text" | "docx" | "pdf" }
   | { status: "error"; reason: string };
 
+type DocumentCommandResult = { status: number | null; stdout: string; stderr: string; error?: Error };
+
 export function expandHome(candidate: string, home: string | undefined): string {
   if (candidate === "~") return home ?? candidate;
   if (candidate.startsWith("~/")) {
@@ -435,7 +437,7 @@ export function extractTextDocument(buffer: Buffer): DocumentExtraction {
 // missing tool would be a lie in the direction that wastes the most time.
 export function extractPdfFromDescriptor(
   fd: number,
-  run: (command: string, args: string[], input?: number) => { status: number | null; stdout: string; stderr: string; error?: Error } = defaultRun
+  run: (command: string, args: string[], input?: number) => DocumentCommandResult = defaultRun
 ): DocumentExtraction {
   const probe = run("command", ["-v", "pdftotext"]);
   if (probe.error || probe.status !== 0) {
@@ -471,19 +473,31 @@ export function extractPdfFromDescriptor(
 // returns would hang the session rather than fail the read.
 const PDF_TIMEOUT_MS = 20_000;
 
+export function probeExecutableOnPath(executable: string): DocumentCommandResult {
+  const result = spawnSync("/bin/sh", ["-c", 'command -v "$1"', "piagent-command-probe", executable], {
+    encoding: "utf8",
+    timeout: PDF_TIMEOUT_MS
+  });
+  return {
+    status: result.status,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    error: result.error
+  };
+}
+
 function defaultRun(
   command: string,
   args: string[],
   input?: number
-): { status: number | null; stdout: string; stderr: string; error?: Error } {
-  const result = command === "command"
-    ? spawnSync("/bin/sh", ["-c", `command -v ${args[1]}`], { encoding: "utf8", timeout: PDF_TIMEOUT_MS })
-    : spawnSync(command, args, {
-      encoding: "utf8",
-      maxBuffer: MAX_DOCUMENT_BYTES,
-      timeout: PDF_TIMEOUT_MS,
-      stdio: [input ?? "ignore", "pipe", "pipe"]
-    });
+): DocumentCommandResult {
+  if (command === "command") return probeExecutableOnPath(args[1] ?? "");
+  const result = spawnSync(command, args, {
+    encoding: "utf8",
+    maxBuffer: MAX_DOCUMENT_BYTES,
+    timeout: PDF_TIMEOUT_MS,
+    stdio: [input ?? "ignore", "pipe", "pipe"]
+  });
   return {
     status: result.status,
     stdout: result.stdout ?? "",

package/packages/piagent-core/extensions/piagent-guard.ts

@@ -49,10 +49,13 @@ import * as mcpActions from "../mcp/mcp-command-actions.js";
 import { buildExtendingProfile, resolveProjectProfileDocument } from "../capabilities/project-profile.js";
 import {
   resolveCapabilityProfileDocument,
-  verifyCapabilityLock,
   writeJsonAtomic,
   writeProfileLockAtomic
 } from "../capabilities/capability-core.js";
+import {
+  createCapabilityVerificationCache,
+  verifyProjectCapabilityStateCached
+} from "../capabilities/capability-verification-cache.js";
 import { resolveCapabilitySourceRoots } from "../capabilities/capability-sources.js";
 import {
   actionTextMatchesAny, actionTokens, classifyActionTokenSequence, classifyExplicitActionValues, classifyToolNameAction,
@@ -715,7 +718,15 @@ type ProjectCapabilityState = {
   filesystemWrite?: string[];
 };
 
-function verifyProjectCapabilityState(extensionDir: string, cwd: string, projectTrusted: boolean): ProjectCapabilityState {
+const capabilityVerificationCache = createCapabilityVerificationCache();
+const sessionCapabilityDigests = new Map<string, string>();
+
+function verifyProjectCapabilityState(
+  extensionDir: string,
+  cwd: string,
+  projectTrusted: boolean,
+  options: { allowRepin?: boolean; forceFull?: boolean; sessionId?: string } = {}
+): ProjectCapabilityState {
   if (process.env.PIAGENT_PROFILE?.trim()) return { ok: true };
   if (!projectTrusted) return { ok: true };
   const profilePath = projectProfilePath(cwd);
@@ -725,46 +736,24 @@ function verifyProjectCapabilityState(extensionDir: string, cwd: string, project
   // would skip the lock entirely for every project that references an adapter.
   const stored = readJsonFile<ProjectProfile>(profilePath);
   if (!stored) return { ok: true };
-  let profile: ProjectProfile;
   try {
-    profile = resolveProjectProfileDocument(PLATFORM_ROOT, stored).profile as ProjectProfile;
+    const profile = resolveProjectProfileDocument(findPlatformRoot(extensionDir), stored).profile;
+    if (!Array.isArray(profile.capabilityPacks)) return { ok: true };
   } catch (error) {
     return { ok: false, reason: error instanceof Error ? error.message : String(error) };
   }
-  if (!Array.isArray(profile.capabilityPacks)) return { ok: true };
   const lockPath = path.join(cwd, ".pi", "piagent-profile.lock.json");
   if (!fs.existsSync(lockPath)) return { ok: false, reason: "Capability lock is missing. Reapply the project profile." };
   const lock = readJsonFile<Record<string, unknown>>(lockPath);
   if (!lock) return { ok: false, reason: "Capability lock is unreadable. Reapply the project profile." };
   try {
-    const verification = verifyCapabilityLock(findPlatformRoot(extensionDir), profilePath, lock, {
-      packageSource: projectPackageSource(cwd),
-      extraRoots: capabilitySourceRoots(cwd, profile)
+    return verifyProjectCapabilityStateCached({
+      cache: capabilityVerificationCache, cwd, platformRoot: findPlatformRoot(extensionDir), profilePath, lockPath,
+      lockDocument: lock, storedProfile: stored, packageSource: projectPackageSource, extraRoots: capabilitySourceRoots,
+      writeLock: writeJsonAtomic, allowRepin: options.allowRepin, forceFull: options.forceFull,
+      sessionDigest: options.sessionId ? sessionCapabilityDigests.get(`${cwd}\0${options.sessionId}`) : undefined,
+      rememberSessionDigest: options.sessionId ? (digest: string) => sessionCapabilityDigests.set(`${cwd}\0${options.sessionId}`, digest) : undefined
     });
-    if (verification.status === "blocked") {
-      return {
-        ok: false,
-        reason: `Capability lock does not match what this project agreed to: ${verification.reasons.join("; ")}. Reapply the project profile.`
-      };
-    }
-    const granted = {
-      filesystemRead: verification.expected.permissions.filesystemRead,
-      filesystemWrite: verification.expected.permissions.filesystemWrite
-    };
-    if (verification.status !== "repin") return { ok: true, ...granted };
-
-    // The grant is unchanged and only the platform build moved. Record the new
-    // build instead of stopping the session, which is what turned every release
-    // into a chore in every project.
-    try {
-      writeJsonAtomic(lockPath, verification.expected);
-    } catch (error) {
-      return {
-        ok: false,
-        reason: `Capability lock is behind the installed platform and could not be rewritten: ${error instanceof Error ? error.message : String(error)}`
-      };
-    }
-    return { ok: true, repinned: verification.reasons.join("; "), ...granted };
   } catch (error) {
     return { ok: false, reason: `Capability validation failed: ${error instanceof Error ? error.message : String(error)}` };
   }
@@ -4273,7 +4262,7 @@ export default function piagentGuard(pi: ExtensionAPI) {
     resolveTaskAny: (cwd, reference) => resolveTaskContract(cwd, reference, undefined) as TaskContract | undefined,
     bindTask: bindSessionTask,
     writeTask,
-    capabilityState: (ctx) => verifyProjectCapabilityState(extensionDir, ctx.cwd, ctx.isProjectTrusted()),
+    capabilityState: (ctx) => verifyProjectCapabilityState(extensionDir, ctx.cwd, ctx.isProjectTrusted(), { allowRepin: true, forceFull: true, sessionId: ctx.sessionManager.getSessionId() }),
     permissionProfile: (ctx, profile) => resolvePermissionProfile(profile, policy, permissionOverrideFromContext(ctx)),
     legacyProjectWarning: legacyProjectStateWarning,
     mcpReadinessNotice,
@@ -4311,7 +4300,10 @@ export default function piagentGuard(pi: ExtensionAPI) {
     flushObservedTaskContext,
     onTurnEnd: activityInspector.refresh,
     onAgentSettled: activityInspector.refresh,
-    beforeShutdown: activityInspector.dispose
+    beforeShutdown: (ctx) => {
+      activityInspector.dispose(ctx);
+      sessionCapabilityDigests.delete(`${ctx.cwd}\0${ctx.sessionManager.getSessionId()}`);
+    }
   });
 
   registerInputHook(pi, {
@@ -4322,7 +4314,7 @@ export default function piagentGuard(pi: ExtensionAPI) {
       const projectTrusted = ctx.isProjectTrusted();
       const profile = loadProfileFromContext(ctx);
       const permissionProfile = resolvePermissionProfile(profile, policy, permissionOverrideFromContext(ctx));
-      const capabilityState = verifyProjectCapabilityState(extensionDir, ctx.cwd, projectTrusted);
+      const capabilityState = verifyProjectCapabilityState(extensionDir, ctx.cwd, projectTrusted, { sessionId: ctx.sessionManager.getSessionId() });
       return {
         roots: resolveDocumentRoots({
           cwd: ctx.cwd,
@@ -4572,7 +4564,7 @@ export default function piagentGuard(pi: ExtensionAPI) {
     const eventInput = isPlainRecord(event.input) ? event.input : {};
     const backendDecision = executionBackendToolDecision(isTaskMutationTool(event.toolName, eventInput));
     if (!backendDecision.allowed) return { block: true, reason: backendDecision.reason };
-    const capabilityState = verifyProjectCapabilityState(extensionDir, ctx.cwd, projectTrusted);
+    const capabilityState = verifyProjectCapabilityState(extensionDir, ctx.cwd, projectTrusted, { sessionId: ctx.sessionManager.getSessionId() });
     const recoveryTools = new Set(["piagent_profile_options", "piagent_profile_apply", "piagent_context", "read", "grep", "find", "ls"]);
     if (!capabilityState.ok && !recoveryTools.has(event.toolName)) {
       return { block: true, reason: capabilityState.reason ?? "Capability lock validation failed." };