@piagent/platform 1.3.0 → 1.4.0

package/evals/fixtures/piagent-webui/task-timeline-v1.valid.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 1,
+  "version": "piagent-webui-task-timeline-v1",
+  "generatedAt": "2026-08-14T11:00:00.000Z",
+  "identity": { "projectRef": "project.fixture", "runtimeInstanceId": "runtime.fixture", "sessionRef": "session.fixture", "taskId": "task-active", "taskRunId": "task-active-run", "agentOperationId": null, "toolCallId": null },
+  "runRef": "run.fixture",
+  "state": "ready",
+  "timelineRevision": "timeline.fixture",
+  "continuity": { "crashEvidence": "unknown", "recoveryDecision": "paused", "latestCheckpointRef": "checkpoint.fixture", "reasonCode": "no-explicit-crash-evidence" },
+  "events": [
+    { "eventRef": "event.fixture", "evidenceRef": "journal.fixture", "sequence": 1, "recordedAt": "2026-08-14T10:00:00.000Z", "kind": "checkpoint", "state": "observed", "title": "Checkpoint paused", "detail": "verify · paused", "checkpointRef": "checkpoint.fixture" }
+  ],
+  "page": { "total": 1, "returned": 1, "truncated": false },
+  "warnings": [{ "code": "crash-not-observed", "count": 1, "message": "No explicit crash fact was recorded." }],
+  "health": { "state": "degraded", "reasonCode": "timeline-warning", "message": "Some continuity facts remain unknown." }
+}

package/evals/fixtures/piagent-webui/transcript-v1.invalid.json

@@ -0,0 +1,35 @@
+{
+  "schemaVersion": 1,
+  "version": "piagent-webui-transcript-v1",
+  "generatedAt": "2026-08-13T14:00:00.000Z",
+  "identity": {
+    "projectRef": "project_01",
+    "runtimeInstanceId": "runtime_01",
+    "sessionRef": "session_01",
+    "taskId": null,
+    "taskRunId": null,
+    "agentOperationId": "operation_smuggled",
+    "toolCallId": null
+  },
+  "revision": {
+    "runtimeRevision": "runtime_rev_01",
+    "taskRevision": null,
+    "controlRevision": null,
+    "workspaceRevision": null,
+    "indexRevision": null,
+    "approvalRevision": null,
+    "sessionOptionRevision": null,
+    "queueRevision": null
+  },
+  "eventCursor": "cursor_01",
+  "state": "unavailable",
+  "items": [{ "rawSessionMessage": "secret" }],
+  "page": {
+    "beforeCursor": null,
+    "nextBeforeCursor": "cursor_invented",
+    "hasOlder": false,
+    "limit": 50,
+    "truncated": false
+  },
+  "reasonCode": null
+}

package/evals/fixtures/piagent-webui/transcript-v1.valid.json

@@ -0,0 +1,55 @@
+{
+  "schemaVersion": 1,
+  "version": "piagent-webui-transcript-v1",
+  "generatedAt": "2026-08-13T14:00:00.000Z",
+  "identity": {
+    "projectRef": "project_01",
+    "runtimeInstanceId": "runtime_01",
+    "sessionRef": "session_01",
+    "taskId": null,
+    "taskRunId": null,
+    "agentOperationId": null,
+    "toolCallId": null
+  },
+  "revision": {
+    "runtimeRevision": "runtime_rev_01",
+    "taskRevision": null,
+    "controlRevision": null,
+    "workspaceRevision": null,
+    "indexRevision": null,
+    "approvalRevision": null,
+    "sessionOptionRevision": null,
+    "queueRevision": "queue_rev_01"
+  },
+  "eventCursor": "cursor_01",
+  "state": "ready",
+  "items": [
+    {
+      "messageRef": "message_01",
+      "parentMessageRef": null,
+      "role": "user",
+      "recordedAt": "2026-08-13T13:59:59.000Z",
+      "agentOperationId": "operation_01",
+      "turnIndex": 0,
+      "content": {
+        "state": "available",
+        "text": "Continue the current task.",
+        "textChars": 26,
+        "digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "truncated": false,
+        "redacted": false,
+        "imageCount": 0,
+        "reasonCode": null
+      },
+      "toolCalls": []
+    }
+  ],
+  "page": {
+    "beforeCursor": null,
+    "nextBeforeCursor": null,
+    "hasOlder": false,
+    "limit": 50,
+    "truncated": false
+  },
+  "reasonCode": null
+}

package/evals/fixtures/task-baseline-manifest.invalid.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 1,
+  "version": "piagent-task-baseline-manifest-v1",
+  "taskId": "task-01",
+  "taskRunId": "task-01-run-1",
+  "sessionIdentityHash": "raw-session-id",
+  "capturedAt": "2026-08-13",
+  "retentionUntil": "2026-09-12",
+  "baselineDigestAlgorithm": "sha1",
+  "baselineTreeDigest": "unknown",
+  "captureState": "current",
+  "reasonCode": "invented-current-error",
+  "limits": { "maxEntries": 3000, "maxFileBytes": 0, "maxTotalBytes": 0, "capturedBytes": -1 },
+  "roots": [],
+  "integrityDigest": "not-a-digest"
+}

package/evals/fixtures/task-baseline-manifest.valid.json

@@ -0,0 +1,41 @@
+{
+  "schemaVersion": 1,
+  "version": "piagent-task-baseline-manifest-v1",
+  "taskId": "task-01",
+  "taskRunId": "task-01-run-1",
+  "sessionIdentityHash": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
+  "capturedAt": "2026-08-13T12:00:00.000Z",
+  "retentionUntil": "2026-09-12T12:00:00.000Z",
+  "baselineDigestAlgorithm": "wt-content-v2",
+  "baselineTreeDigest": "wt-content-v2:2222222222222222222222222222222222222222222222222222222222222222",
+  "captureState": "current",
+  "reasonCode": null,
+  "limits": { "maxEntries": 2000, "maxFileBytes": 4194304, "maxTotalBytes": 67108864, "capturedBytes": 5 },
+  "roots": [
+    {
+      "repoRef": "repo.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "projectPath": ".",
+      "headState": "head",
+      "headOid": "3333333333333333333333333333333333333333",
+      "workspaceRevision": "workspace.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "indexRevision": "index.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "state": "current",
+      "reasonCode": null,
+      "entries": [
+        {
+          "pathRef": "path.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+          "pathDigest": "sha256:4444444444444444444444444444444444444444444444444444444444444444",
+          "repoPathBase64": "YS50eHQ",
+          "state": "blob",
+          "reasonCode": null,
+          "contentRef": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
+          "byteLength": 5,
+          "mode": "100644",
+          "headObject": "6666666666666666666666666666666666666666",
+          "indexObject": "7777777777777777777777777777777777777777"
+        }
+      ]
+    }
+  ],
+  "integrityDigest": "sha256:19a3c69ef5e5abeeb505725d52b481744c60d3fec4bd8c46ec19a4800f64e59d"
+}

package/evals/fixtures/verifier-file-snapshot.invalid.json

@@ -0,0 +1,21 @@
+{
+  "schemaVersion": 1,
+  "version": "piagent-verifier-file-snapshot-v1",
+  "attemptId": "verifier.invalid",
+  "attemptRef": "verifier-evidence.invalid",
+  "taskId": "task-01",
+  "taskRunId": "task-01-run-01",
+  "sessionIdentityHash": "raw-session",
+  "toolCallIdentityHash": "raw-tool",
+  "commandDigest": "raw-command",
+  "observedAt": "invalid",
+  "capturedAt": "invalid",
+  "retentionUntil": "invalid",
+  "exitCode": 1,
+  "outcome": "passed",
+  "treeDigest": "unknown",
+  "fileCount": 1,
+  "exposedPathCount": 1,
+  "files": [],
+  "integrityDigest": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
+}

package/evals/fixtures/verifier-file-snapshot.valid.json

@@ -0,0 +1,21 @@
+{
+  "schemaVersion": 1,
+  "version": "piagent-verifier-file-snapshot-v1",
+  "attemptId": "verifier.165224a1269311b35faa7c68a3285dec225f563a761d8984b3f0e5525a3837d9",
+  "attemptRef": "verifier-evidence.165224a1269311b35faa7c68a3285dec225f563a761d8984b3f0e5525a3837d9",
+  "taskId": "task-01",
+  "taskRunId": "task-01-run-01",
+  "sessionIdentityHash": "sha256:6e165fadbb274b7254278eadb81c25aaa7fda6b62c3f2c6f8ca393b34f90834e",
+  "toolCallIdentityHash": "sha256:4dd7feedf5ee29f32ee3a58080756f540d67d815fb658d836f77d959b6c33c49",
+  "commandDigest": "sha256:328e123c63857fd8473bd4bd3581e655b08b7440d7f5d2c31cc375607582f539",
+  "observedAt": "2026-08-13T16:00:00.000Z",
+  "capturedAt": "2026-08-13T16:00:01.000Z",
+  "retentionUntil": "2026-09-12T16:00:01.000Z",
+  "exitCode": 0,
+  "outcome": "passed",
+  "treeDigest": "wt-content-v2:19d7d78c84028ca50754225c92b10733bc8a5bf2fe4dbf89042aa14352159f46",
+  "fileCount": 0,
+  "exposedPathCount": 0,
+  "files": [],
+  "integrityDigest": "sha256:afcb27f99d5ba2c52410075f4c42a3bb00209354df9edb8349ee463579e1fc66"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/platform",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -43,12 +43,20 @@
     "packs/",
     "packages/piagent-core/",
     "!packages/piagent-core/extensions/core-services.js",
+    "packages/piagent-webui/package.json",
+    "packages/piagent-webui/server/",
+    "packages/piagent-webui/extension/",
+    "packages/piagent-webui/gateway/",
+    "packages/piagent-webui/ownership/",
+    "packages/piagent-webui/dist/client/",
     "schemas/",
     "scripts/",
     "templates/",
     "types/"
   ],
   "bin": {
+    "piagent": "scripts/piagent-cli.mjs",
+    "piagent-dashboard": "scripts/piagent-cli.mjs",
     "piagent-setup": "scripts/piagent-cli.mjs",
     "piagent-install": "scripts/piagent-cli.mjs",
     "piagent-update": "scripts/piagent-cli.mjs",
@@ -66,11 +74,13 @@
     "piagent-migrate": "scripts/piagent-cli.mjs",
     "piagent-import-instructions": "scripts/piagent-cli.mjs",
     "piagent-auto": "scripts/piagent-cli.mjs",
-    "piagent-context": "scripts/piagent-cli.mjs"
+    "piagent-context": "scripts/piagent-cli.mjs",
+    "piagent-webui": "scripts/piagent-cli.mjs"
   },
   "pi": {
     "extensions": [
-      "packages/piagent-core/extensions/piagent-guard.ts"
+      "packages/piagent-core/extensions/piagent-guard.ts",
+      "packages/piagent-webui/extension/piagent-webui.ts"
     ],
     "skills": [
       "packages/piagent-core/skills"
@@ -84,6 +94,13 @@
       ]
     }
   },
+  "piagent": {
+    "runtimeIntegrityEntrypoints": [
+      "packages/piagent-webui/server/sidecar-main.ts",
+      "scripts/register-typescript-loader.mjs",
+      "scripts/typescript-loader.mjs"
+    ]
+  },
   "peerDependencies": {
     "@earendil-works/pi-ai": "0.84.1",
     "@earendil-works/pi-coding-agent": "0.84.1",
@@ -100,8 +117,16 @@
       "optional": true
     }
   },
+  "dependencies": {
+    "ws": "8.21.3"
+  },
   "devDependencies": {
+    "@axe-core/playwright": "4.13.0",
+    "@playwright/test": "1.62.1",
     "@types/node": "^26.1.1",
+    "@types/ws": "8.18.1",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
     "typescript": "^7.0.2"
   },
   "workspaces": [
@@ -110,6 +135,7 @@
   "scripts": {
     "verify": "bash scripts/verify-local.sh",
     "test": "PIAGENT_NO_UPDATE_CHECK=1 node --test tests/*.test.mjs",
+    "test:webui:e2e": "playwright test --config playwright.webui.config.mjs",
     "test:policy": "node --test tests/policy-core.test.mjs",
     "test:golden": "node --test tests/golden-enforcement.test.mjs",
     "typecheck": "tsc --noEmit",
@@ -129,6 +155,7 @@
     "site:check": "node scripts/check-published-site.mjs",
     "architecture:check": "node scripts/check-architecture.mjs",
     "docs:check": "node scripts/check-doc-languages.mjs",
+    "docs:neutrality": "node scripts/check-third-party-neutrality.mjs",
     "smoke": "bash scripts/runtime-policy-smoke.sh",
     "usage": "bash scripts/pi-session-stats.sh",
     "auto": "bash scripts/pi-auto.sh",

package/packages/piagent-core/benchmark/benchmark-candidate.d.ts

@@ -0,0 +1 @@
+export function validBenchmarkCandidateProvenance(value: unknown): boolean;

package/packages/piagent-core/benchmark/benchmark-forensics.d.ts

@@ -0,0 +1 @@
+export function benchmarkCandidateProvenance(root: string): Record<string, unknown>;

package/packages/piagent-core/benchmark/benchmark-ledger.d.ts

@@ -0,0 +1,4 @@
+export type BenchmarkLedgerBinding = { schemaVersion: 1; algorithm: string; digest: string; records: number; bytes: number };
+export function inspectBenchmarkLedger(file: string): { binding: BenchmarkLedgerBinding; records: unknown[]; raw: Buffer };
+export function assertBenchmarkLedgerBinding(expected: unknown, observed: unknown, label?: string): BenchmarkLedgerBinding;
+export function validateBenchmarkLedgerPrefix(records: unknown[], order: unknown[], completedRecord: (record: unknown) => boolean): Set<string>;

package/packages/piagent-core/benchmark/benchmark-record-validation.d.ts

@@ -0,0 +1 @@
+export function completedBenchmarkRecord(record: unknown): boolean;

package/packages/piagent-core/benchmark/benchmark-runtime.d.ts

@@ -0,0 +1 @@
+export function benchmarkGitEnvironment(): NodeJS.ProcessEnv;

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

@@ -3,7 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { containsSensitiveText } from "../security/sensitive-data.js";
 import { resolveProjectProfileDocument } from "./project-profile.js";
-import { CORE_RUNTIME_INTEGRITY_FILES } from "./runtime-integrity.js";
+import { discoverRuntimeIntegrityFiles } from "./runtime-integrity.js";
 
 const API_VERSION = "piagent/v1";
 const CORE_API_VERSION = 1;
@@ -798,7 +798,7 @@ function buildCoreIntegrity(root) {
     "packages/piagent-core/capabilities/project-profile.js",
     "packages/piagent-core/security/sensitive-data.js",
     "packages/piagent-core/extensions/piagent-guard.ts",
-    ...CORE_RUNTIME_INTEGRITY_FILES,
+    ...discoverRuntimeIntegrityFiles(root),
     // context-engine.js decides which repository content enters the model
     // context and records the resulting telemetry, so it is part of the
     // runtime trust boundary enforced by the profile lock.

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