@piagent/platform 1.3.1 → 1.4.1

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,19 +1,30 @@
 {
   "name": "@piagent/platform",
-  "version": "1.3.1",
+  "version": "1.4.1",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
   "type": "module",
-  "description": "Reusable Pi agent platform, project adapters, MCP/tool policy, and coding workflow harness.",
+  "description": "Guardrails for AI coding agents: blocks secret reads, destructive commands, and unapproved MCP servers before the tool call runs. Ships project profiles, capability locks, a context engine, and task verification.",
   "homepage": "https://piagent.io.vn",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Vt-mmm/piagent.git"
   },
   "keywords": [
+    "ai-agent",
+    "coding-agent",
+    "agent-guardrails",
+    "agent-security",
+    "llm-tool-policy",
+    "prompt-injection",
+    "mcp",
+    "mcp-security",
+    "secret-redaction",
+    "context-engineering",
+    "developer-tools",
     "pi-package",
     "pi-extension",
     "pi-skill",
@@ -43,12 +54,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 +85,14 @@
     "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-explain": "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 +106,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 +129,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 +147,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 +167,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/README.md

@@ -179,8 +179,9 @@ Project-local state belongs in `.pi/.gitignore`.
 Task files use schema v2 and bind one unique `taskRunId` to one Pi `sessionId`.
 They record attempt/max-attempt history, dependency-safe work-plan progress,
 Git baseline/final digests, observed changes, all exact verify results and final
-trace. A terminal task is immutable; retry starts in a fresh session and carries
-the prior failure/ruled-out evidence. Legacy v1 state is migrated and archived
+trace. A terminal task is immutable; the same conversation may bind a new task
+or retry attempt after the prior task closes, while keeping only one task pending
+at a time and carrying prior failure/ruled-out evidence. Legacy v1 state is migrated and archived
 without requiring project onboarding again.
 
 Local state directories are owner-only. Task state, context telemetry, trace,

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

@@ -148,12 +148,21 @@ function lexicalAncestors(target) {
   return ancestors;
 }
 
-function metadataSignature(targets) {
+// The directories above every target, sorted, derived once per snapshot. The
+// set is a pure function of the target list, and a cached entry's target list
+// cannot change while the entry lives, so deriving it per call was repeating
+// work that could not produce a different answer -- and at 296 pinned files it
+// was the single most expensive part of a cache hit, more than every `lstat`
+// this function performs put together.
+function ancestorPaths(targets) {
+  return [...new Set(targets.flatMap((target) => lexicalAncestors(target.path)))].sort(compare);
+}
+
+function metadataSignature(targets, ancestors) {
   if (!targets) return undefined;
   const records = [];
-  const ancestors = new Set(targets.flatMap((target) => lexicalAncestors(target.path)));
   try {
-    for (const ancestor of [...ancestors].sort(compare)) {
+    for (const ancestor of ancestors ?? ancestorPaths(targets)) {
       const stat = fs.lstatSync(ancestor, { bigint: true });
       const symbolic = stat.isSymbolicLink();
       const identity = symbolic ? statIdentity(stat, true) : ancestorIdentity(stat);
@@ -194,13 +203,14 @@ function cacheIdentity(lockDocument, options = {}) {
 }
 
 function snapshotTargets(targets) {
-  const signature = metadataSignature(targets);
-  return signature ? { signature, targets } : undefined;
+  const ancestors = ancestorPaths(targets);
+  const signature = metadataSignature(targets, ancestors);
+  return signature ? { signature, targets, ancestors } : undefined;
 }
 
 function stableSnapshot(snapshot) {
   if (!snapshot) return false;
-  const current = metadataSignature(snapshot.targets);
+  const current = metadataSignature(snapshot.targets, snapshot.ancestors);
   return Boolean(current && current === snapshot.signature);
 }
 
@@ -209,7 +219,7 @@ export function verifyCapabilityLockCached(cache, root, profilePath, lockPath, l
   const identity = cacheIdentity(lockDocument, options);
   const cached = options.forceFull === true ? undefined : cache?.get(key);
   if (cached?.identity === identity) {
-    const signature = metadataSignature(cached.targets);
+    const signature = metadataSignature(cached.targets, cached.ancestors);
     if (signature && signature === cached.signature) return { ...cached.verification, cacheStatus: "hit" };
   }
   cache?.delete(key);

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

@@ -1,3 +1,6 @@
+import fs from "node:fs";
+import path from "node:path";
+
 export const CORE_RUNTIME_INTEGRITY_FILES = Object.freeze([
   "packages/piagent-core/runtime/context/adaptive-planner.ts",
   "packages/piagent-core/runtime/context/retrieval-route-policy.ts",
@@ -31,7 +34,53 @@ export const CORE_RUNTIME_INTEGRITY_FILES = Object.freeze([
   "packages/piagent-core/runtime/hooks/session-start-hook.ts",
   "packages/piagent-core/runtime/hooks/tool-call-hook.ts",
   "packages/piagent-core/runtime/hooks/tool-result-hook.ts",
+  "packages/piagent-core/runtime/hooks/tool-result-metadata.ts",
   "packages/piagent-core/runtime/input/chat-images.ts",
+  "packages/piagent-core/runtime/inspection/activity-event-adapter.ts",
+  "packages/piagent-core/runtime/inspection/approval-broker.ts",
+  "packages/piagent-core/runtime/inspection/criteria-links.ts",
+  "packages/piagent-core/runtime/inspection/commit-summary-projection.ts",
+  "packages/piagent-core/runtime/inspection/diff-projection.ts",
+  "packages/piagent-core/runtime/inspection/git-numstat-adapter.ts",
+  "packages/piagent-core/runtime/inspection/git-filter-safety.ts",
+  "packages/piagent-core/runtime/inspection/git-status-adapter.ts",
+  "packages/piagent-core/runtime/inspection/git-tree-adapter.ts",
+  "packages/piagent-core/runtime/inspection/mcp-control.ts",
+  "packages/piagent-core/runtime/inspection/mutation-provenance-contract.ts",
+  "packages/piagent-core/runtime/inspection/mutation-provenance-recorder.ts",
+  "packages/piagent-core/runtime/inspection/mutation-provenance-store.ts",
+  "packages/piagent-core/runtime/inspection/project-runtime-inspection.ts",
+  "packages/piagent-core/runtime/inspection/review-state-contract.ts",
+  "packages/piagent-core/runtime/inspection/review-state-projection.ts",
+  "packages/piagent-core/runtime/inspection/review-state-store.ts",
+  "packages/piagent-core/runtime/inspection/runtime-event-store.ts",
+  "packages/piagent-core/runtime/inspection/same-process-bridge-proof.ts",
+  "packages/piagent-core/runtime/inspection/zero-turn-conformance.ts",
+  "packages/piagent-core/runtime/inspection/source-evidence-contract.ts",
+  "packages/piagent-core/runtime/inspection/source-evidence-store.ts",
+  "packages/piagent-core/runtime/inspection/source-inspection-plan.ts",
+  "packages/piagent-core/runtime/inspection/source-mutation-projection.ts",
+  "packages/piagent-core/runtime/inspection/source-mutation-store.ts",
+  "packages/piagent-core/runtime/inspection/source-revert-projection.ts",
+  "packages/piagent-core/runtime/inspection/source-handoff-store.ts",
+  "packages/piagent-core/runtime/inspection/source-open-target.ts",
+  "packages/piagent-core/runtime/inspection/task-run-index.ts",
+  "packages/piagent-core/runtime/inspection/task-recovery-timeline.ts",
+  "packages/piagent-core/runtime/inspection/task-compaction-history.ts",
+  "packages/piagent-core/runtime/inspection/context-telemetry-inspection.ts",
+  "packages/piagent-core/runtime/inspection/task-handoff-history.ts",
+  "packages/piagent-core/runtime/inspection/task-subagent-tree.ts",
+  "packages/piagent-core/runtime/inspection/task-baseline-start-capture.ts",
+  "packages/piagent-core/runtime/inspection/task-control-journal.ts",
+  "packages/piagent-core/runtime/inspection/task-source-projection.ts",
+  "packages/piagent-core/runtime/inspection/task-provenance-projection.ts",
+  "packages/piagent-core/runtime/inspection/verifier-snapshot-contract.ts",
+  "packages/piagent-core/runtime/inspection/verifier-snapshot-store.ts",
+  "packages/piagent-core/runtime/inspection/webui-snapshot.ts",
+  "packages/piagent-core/runtime/inspection/text-diff.ts",
+  "packages/piagent-core/runtime/inspection/source-change-projection.ts",
+  "packages/piagent-core/runtime/inspection/workspace-file-reader.ts",
+  "packages/piagent-core/runtime/inspection/workspace-source-projection.ts",
   "packages/piagent-core/runtime/model/capabilities.ts",
   "packages/piagent-core/runtime/model/authenticated-catalog.ts",
   "packages/piagent-core/runtime/model/model-route-policy.ts",
@@ -42,6 +91,10 @@ export const CORE_RUNTIME_INTEGRITY_FILES = Object.freeze([
   "packages/piagent-core/runtime/model/snapshot-telemetry.ts",
   "packages/piagent-core/runtime/policy/authority-manifest.ts",
   "packages/piagent-core/runtime/policy/authority-resume-policy.ts",
+  "packages/piagent-core/runtime/policy/source-index-transaction.ts",
+  "packages/piagent-core/runtime/policy/source-mutation-guard-binding.ts",
+  "packages/piagent-core/runtime/policy/source-mutation-guard.ts",
+  "packages/piagent-core/runtime/policy/source-worktree-transaction.ts",
   "packages/piagent-core/runtime/policy/task-authority-runtime.ts",
   "packages/piagent-core/runtime/orchestration/role-policy.ts",
   "packages/piagent-core/runtime/orchestration/role-binder.ts",
@@ -106,3 +159,140 @@ export const CORE_RUNTIME_INTEGRITY_FILES = Object.freeze([
   "scripts/register-typescript-loader.mjs",
   "scripts/typescript-loader.mjs"
 ]);
+
+const EXECUTABLE_SOURCE = /\.(?:[cm]?js|ts|json|sh)$/;
+const IMPORT_SPECIFIER = /(?:\bimport\s*(?:type\s+)?(?:[^"'`]*?\s+from\s*)?|\bexport\s+(?:type\s+)?[^"'`]*?\s+from\s*)["']([^"']+)["']/g;
+const DYNAMIC_IMPORT = /\bimport\(\s*["']([^"']+)["']\s*\)/g;
+const RUNTIME_LITERAL = /["']((?:packages|scripts)\/[A-Za-z0-9_./-]+\.(?:[cm]?js|ts|json|sh))["']/g;
+// A shell entrypoint reaches a sibling program through the directory it computed
+// for itself -- `"$SCRIPT_DIR/pi-usage-history.mjs"` -- so the repository-relative
+// literal the scanner above looks for never appears in the source. `piagent-usage`
+// is a pinned command that ran a 567-line unpinned program this way.
+const SHELL_SIBLING = /\$(?:\{)?(?:SCRIPT_DIR|ROOT|REPO_ROOT|PLATFORM_ROOT)(?:\})?\/([A-Za-z0-9_./-]+\.(?:[cm]?js|ts|json|sh))/g;
+const MAX_INTEGRITY_FILES = 5_000;
+
+function normalizedRelative(root, absolute) {
+  const relative = path.relative(root, absolute);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) return undefined;
+  return relative.split(path.sep).join("/");
+}
+
+// A served bundle is more than its scripts: the document names which script runs,
+// so pinning the JavaScript while leaving the HTML free would leave the choice of
+// program unpinned.
+const SERVED_BUNDLE_ASSET = /\.(?:[cm]?js|css|html|json|svg|woff2)$/;
+
+function bundleFilesBelow(root, relativeDirectory) {
+  return executableFilesBelow(root, relativeDirectory, SERVED_BUNDLE_ASSET);
+}
+
+function executableFilesBelow(root, relativeDirectory, accept = EXECUTABLE_SOURCE) {
+  const directory = path.join(root, relativeDirectory);
+  if (!fs.existsSync(directory)) return [];
+  const files = [];
+  const visit = (absolute) => {
+    const entries = fs.readdirSync(absolute, { withFileTypes: true });
+    for (const entry of entries) {
+      const target = path.join(absolute, entry.name), stat = fs.lstatSync(target);
+      if (stat.isSymbolicLink()) throw new Error(`runtime-integrity-symlink:${normalizedRelative(root, target) ?? "outside-root"}`);
+      if (stat.isDirectory()) visit(target);
+      else if (stat.isFile() && accept.test(entry.name)) files.push(normalizedRelative(root, target));
+    }
+  };
+  visit(directory);
+  return files.filter(Boolean);
+}
+
+function localImportTarget(root, importer, specifier) {
+  if (!specifier.startsWith(".")) return undefined;
+  const base = path.resolve(path.dirname(path.join(root, importer)), specifier);
+  // TypeScript sources import a sibling module by its emitted name, so `./x.js`
+  // is how a `.ts` file refers to `x.ts`. Without that rewrite the specifier
+  // resolves to nothing and the reference is dropped in silence -- a module
+  // that decides what the guard enforces would then sit outside the lock while
+  // this list still claimed to cover the whole import graph.
+  const rewritten = base.endsWith(".js") ? [`${base.slice(0, -3)}.ts`] : [];
+  const candidates = [base, ...rewritten, `${base}.ts`, `${base}.js`, `${base}.mjs`, path.join(base, "index.ts"), path.join(base, "index.js")];
+  for (const candidate of candidates) {
+    const relative = normalizedRelative(root, candidate);
+    if (!relative || !fs.existsSync(candidate)) continue;
+    const stat = fs.lstatSync(candidate);
+    if (stat.isSymbolicLink()) throw new Error(`runtime-integrity-symlink:${relative}`);
+    if (stat.isFile() && EXECUTABLE_SOURCE.test(candidate)) return relative;
+  }
+  return undefined;
+}
+
+function sourceReferences(root, relativeFile) {
+  // Shell entrypoints are scanned too. They were skipped here, so a pinned
+  // command could execute an unpinned program and the lock reported a complete
+  // graph while missing it.
+  const shell = relativeFile.endsWith(".sh");
+  if (!shell && !/\.(?:[cm]?js|ts)$/.test(relativeFile)) return [];
+  const source = fs.readFileSync(path.join(root, relativeFile), "utf8"), references = new Set();
+  if (shell) {
+    const directory = path.posix.dirname(relativeFile);
+    for (const pattern of [RUNTIME_LITERAL, SHELL_SIBLING]) {
+      pattern.lastIndex = 0;
+      for (let match = pattern.exec(source); match; match = pattern.exec(source)) {
+        const candidate = pattern === SHELL_SIBLING ? path.posix.join(directory, match[1]) : match[1];
+        const absolute = path.join(root, candidate), relative = normalizedRelative(root, absolute);
+        if (relative && fs.existsSync(absolute) && fs.lstatSync(absolute).isFile()) references.add(relative);
+      }
+    }
+    return [...references];
+  }
+  for (const pattern of [IMPORT_SPECIFIER, DYNAMIC_IMPORT]) {
+    pattern.lastIndex = 0;
+    for (let match = pattern.exec(source); match; match = pattern.exec(source)) {
+      const target = localImportTarget(root, relativeFile, match[1]);
+      if (target) references.add(target);
+    }
+  }
+  RUNTIME_LITERAL.lastIndex = 0;
+  for (let match = RUNTIME_LITERAL.exec(source); match; match = RUNTIME_LITERAL.exec(source)) {
+    const target = path.join(root, match[1]), relative = normalizedRelative(root, target);
+    if (relative && fs.existsSync(target) && fs.lstatSync(target).isFile()) references.add(relative);
+  }
+  return [...references];
+}
+
+export function discoverRuntimeIntegrityFiles(root) {
+  const packageDocument = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+  const declaredExtensions = Array.isArray(packageDocument.pi?.extensions) ? packageDocument.pi.extensions : [];
+  const declaredBins = packageDocument.bin && typeof packageDocument.bin === "object" ? Object.values(packageDocument.bin) : [];
+  const declaredEntrypoints = Array.isArray(packageDocument.piagent?.runtimeIntegrityEntrypoints)
+    ? packageDocument.piagent.runtimeIntegrityEntrypoints : [];
+  const seeds = new Set([
+    ...CORE_RUNTIME_INTEGRITY_FILES,
+    "packages/piagent-core/extensions/piagent-guard.ts",
+    ...executableFilesBelow(root, "packages/piagent-core/runtime"),
+    // The browser bundle the WebUI serves. The published package ships the built
+    // assets and not the sources they came from, so on an installed platform
+    // this code cannot be regenerated or cross-checked against anything -- and it
+    // runs inside the origin that holds the session cookie and the CSRF token,
+    // with the authority to drive session commands, source mutation and provider
+    // auth. The server that serves it was pinned; what it serves was not.
+    //
+    // The tree is absent in a source checkout until the workspace is built, and
+    // absence is not a failure here: a lock recorded with these entries still
+    // fails verification if they later disappear.
+    ...bundleFilesBelow(root, "packages/piagent-webui/dist/client"),
+    ...declaredExtensions,
+    ...declaredBins,
+    ...declaredEntrypoints
+  ].filter((entry) => typeof entry === "string" && !path.isAbsolute(entry)));
+  const files = new Set(), pending = [...seeds];
+  while (pending.length) {
+    if (files.size >= MAX_INTEGRITY_FILES) throw new Error("runtime-integrity-file-limit");
+    const relative = pending.pop();
+    if (files.has(relative)) continue;
+    const absolute = path.join(root, relative), contained = normalizedRelative(root, absolute);
+    if (!contained || !fs.existsSync(absolute)) continue;
+    const stat = fs.lstatSync(absolute);
+    if (stat.isSymbolicLink() || !stat.isFile()) throw new Error(`runtime-integrity-file-unsafe:${relative}`);
+    files.add(contained);
+    for (const reference of sourceReferences(root, contained)) if (!files.has(reference)) pending.push(reference);
+  }
+  return [...files].sort((left, right) => left.localeCompare(right, "en"));
+}