@piagent/platform 1.6.1 → 1.7.1

package/scripts/check-public-wording.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(import.meta.dirname, "..");
+const surfaces = ["README.md", "docs", "docs-site/content", "scripts/build-docs-site.mjs",
+  "packages/piagent-core/README.md", "packages/piagent-core/prompts", "packages/piagent-core/mcp",
+  "packages/piagent-core/extensions", "packages/piagent-core/runtime", "templates/project/AGENTS.md"];
+// Explicit reviewed research records, never a marker supplied by arbitrary docs.
+const researchRecords = new Set(["docs/piagent-core-improvement-plan.md",
+  "docs/piagent-core-reasoning-research-2026-09-06.md", "docs/piagent-core-research-sources-2026-09-06.json"]);
+const sourceNames = ["Codex CLI", "Claude CLI", "Claude Code"];
+const prohibited = ["platform-migration", "codex-migration", "codex-parity", "benchmark-parity",
+  "harness-migration", "agent-stuff", "mitsuhiko", "claude mcp", "codex mcp",
+  "Codex-inspired", "Codex-grade", "Pi vs Codex", "vs Claude", "reference repo",
+  "repo tham khảo", "nguồn tham khảo", "tham khảo"];
+const escaped = value => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+export function publicWordingViolations(file, text) {
+  const terms = researchRecords.has(file) ? prohibited : [...prohibited, ...sourceNames];
+  const pattern = new RegExp(terms.map(escaped).join("|"), "gi");
+  return [...text.matchAll(pattern)].map(match => ({ file,
+    line: text.slice(0, match.index).split("\n").length, keyword: match[0] }));
+}
+
+function filesIn(repositoryRoot, relative) {
+  const absolute = path.join(repositoryRoot, relative);
+  if (!fs.statSync(absolute).isDirectory()) return [relative];
+  return fs.readdirSync(absolute).flatMap(name => filesIn(repositoryRoot, path.join(relative, name)));
+}
+
+export function inspectPublicWording(repositoryRoot = root) {
+  const files = surfaces.flatMap(surface => filesIn(repositoryRoot, surface));
+  const violations = files.flatMap(file => publicWordingViolations(file, fs.readFileSync(path.join(repositoryRoot, file), "utf8")));
+  return { ok: violations.length === 0, checkedFiles: files.length, violations };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const result = inspectPublicWording();
+  if (!result.ok) {
+    process.stderr.write(`Public docs contain non-neutral platform wording\n${result.violations
+      .map(item => `- ${item.file}:${item.line} ${item.keyword}`).join("\n")}\n`);
+    process.exitCode = 1;
+  } else process.stdout.write(`PASS: ${result.checkedFiles} public surfaces preserve neutral copy and research provenance\n`);
+}

package/scripts/fs4-readiness-evaluation.mjs

@@ -6,6 +6,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { evaluateFs4Readiness } from "../packages/piagent-core/benchmark/fs4-readiness-gates.js";
+import { verifyPublicExposure } from "./public-evaluation-exposure.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 let matrixPath = path.join(root, "evals", "fs4-readiness-matrix.v1.json");
@@ -37,6 +38,9 @@ const artifactManifest = matrix.artifacts.map((artifact) => {
   return { id: artifact.id, path: artifact.path, sha256: actual, bytes: bytes.byteLength };
 });
 const byId = new Map(matrix.artifacts.map((artifact) => [artifact.id, artifact]));
+// The retained v1 matrix describes historical inputs. Current readiness also
+// requires the complete current exposure inventory, even before running tests.
+const currentPublicExposure = verifyPublicExposure(root);
 const artifactJson = (id) => readJson(byId.get(id).path);
 const core = artifactJson("e0-core-suite");
 const production = artifactJson("e1-public-suite");
@@ -67,7 +71,8 @@ function executeTestGroup(id, files) {
     durationMs: Number((performance.now() - started).toFixed(3))
   };
 }
-const testGroups = Object.fromEntries(Object.entries(matrix.deterministicTests).map(([id, files]) => [id, executeTestGroup(id, files)]));
+const testGroups = Object.fromEntries(Object.entries(matrix.deterministicTests).map(([id, files]) => [id,
+  executeTestGroup(id, id === "e3" ? [...new Set([...files, "tests/public-evaluation-exposure.test.mjs"])] : files)]));
 const evaluation = evaluateFs4Readiness({
   artifactBindingsCurrent: true,
   e0: { testsPassed: testGroups.e0.passed, suiteId: core.id, scenarioCount: core.scenarios?.length },
@@ -120,6 +125,7 @@ const report = {
   generatedAt: new Date().toISOString(),
   workItem: "CF-FS4-05",
   matrix: { path: path.relative(root, matrixPath), sha256: digest(matrixBytes), artifactManifestSha256: digest(JSON.stringify(artifactManifest)), artifacts: artifactManifest },
+  currentPublicExposure,
   tests: Object.values(testGroups),
   evaluation,
   claimBoundary: matrix.claimBoundary,

package/scripts/phase-tools-evaluation.mjs

@@ -27,6 +27,7 @@ async function registeredTools() {
   try {
     writeRuntimeStubs(root);
     fs.cpSync(path.join(repoRoot, "packages", "piagent-core"), path.join(root, "packages", "piagent-core"), { recursive: true });
+    fs.cpSync(path.join(repoRoot, "adapters", "common"), path.join(root, "adapters", "common"), { recursive: true });
     fs.copyFileSync(path.join(repoRoot, "package.json"), path.join(root, "package.json"));
     const moduleUrl = pathToFileURL(path.join(root, "packages", "piagent-core", "extensions", "piagent-guard.ts")).href;
     const guard = (await import(`${moduleUrl}?evaluation=${Date.now()}`)).default;

package/scripts/pi-auto.sh

@@ -73,7 +73,13 @@ if ! command -v pi >/dev/null 2>&1; then
 fi
 
 if [[ "$PERMISSION_PROFILE" == "read-only" ]]; then
-  exec env PIAGENT_PERMISSION_PROFILE="$PERMISSION_PROFILE" pi "$APPROVE_FLAG" --exclude-tools bash,write,edit "${ARGS[@]}"
+  # Grep, find, and ls are built-in read tools but Pi leaves them disabled by
+  # default. Use an allowlist so a read-only scout can discover paths before
+  # reading them instead of guessing with `read`. Keep this option before the
+  # caller's arguments: an explicit --tools/--exclude-tools/--no-tools choice
+  # remains authoritative for that invocation, while Piagent's guard still
+  # enforces the read-only permission profile independently.
+  exec env PIAGENT_PERMISSION_PROFILE="$PERMISSION_PROFILE" pi "$APPROVE_FLAG" --tools read,grep,find,ls "${ARGS[@]}"
 fi
 
 exec env PIAGENT_PERMISSION_PROFILE="$PERMISSION_PROFILE" pi "$APPROVE_FLAG" "${ARGS[@]}"

package/scripts/pi-usage-history.mjs

@@ -202,20 +202,102 @@ function emptyTotals() {
   };
 }
 
+function emptyExecutionAggregate(source = "pi-session-jsonl") {
+  return {
+    schemaVersion: 1,
+    source,
+    completeness: {
+      tools: "unverified",
+      retries: "unavailable",
+      compactions: "partial",
+      subagents: "unverified"
+    },
+    providerStartedAttempts: 0,
+    toolCalls: 0,
+    toolResults: 0,
+    toolFailures: 0,
+    blockedToolCalls: 0,
+    declinedToolCalls: 0,
+    explicitRetries: 0,
+    retryFailures: 0,
+    compactions: 0,
+    abortedCompactions: 0,
+    summarizationRetries: 0,
+    repeatedToolCalls: 0,
+    subagentAttempts: 0,
+    subagentFailures: 0
+  };
+}
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stableValue(value[key])]));
+}
+
+function toolFingerprint(block) {
+  let args = block?.arguments ?? null;
+  if (typeof args === "string") {
+    try { args = JSON.parse(args); } catch { /* The opaque string remains useful for equality. */ }
+  }
+  try { return JSON.stringify([String(block?.name ?? "tool"), stableValue(args)]); }
+  catch { return String(block?.name ?? "tool"); }
+}
+
+function isSubagentAttempt(block) {
+  const name = String(block?.name ?? "").toLowerCase();
+  if (["spawn_agent", "create_agent", "delegate_task", "subagent"].includes(name)) return true;
+  return false;
+}
+
+function structuredToolStatus(message) {
+  const candidates = [message?.status, message?.details?.status, message?.result?.status];
+  return candidates.find((value) => typeof value === "string")?.toLowerCase() ?? "";
+}
+
+function exactPricingRequest(usage) {
+  const fields = ["input", "output", "cacheRead", "cacheWrite"];
+  if (!usage || fields.some((field) => !Number.isSafeInteger(usage[field]) || usage[field] < 0)) return null;
+  const reasoningReported = Object.hasOwn(usage, "reasoning") && usage.reasoning !== undefined;
+  const reasoning = reasoningReported ? usage.reasoning : 0;
+  if (!Number.isSafeInteger(reasoning) || reasoning < 0) return null;
+  const total = usage.totalTokens;
+  if (!Number.isSafeInteger(total) || total !== usage.input + usage.output + usage.cacheRead + usage.cacheWrite
+    || reasoning > usage.output) return null;
+  return {
+    input: usage.input,
+    output: usage.output,
+    cacheRead: usage.cacheRead,
+    cacheWrite: usage.cacheWrite,
+    reasoning,
+    total,
+    promptTokens: usage.input + usage.cacheRead + usage.cacheWrite,
+    ...(!reasoningReported && usage.output > 0 ? { reasoningCompleteness: "lower-bound" } : {})
+  };
+}
+
 function exactToken(raw, label) {
   if (!Number.isSafeInteger(raw) || raw < 0) throw new Error(`${label} must be a non-negative safe integer`);
   return raw;
 }
 
 function addTotals(target, usage, { strict = false, label = "usage" } = {}) {
-  const values = strict ? {
-    input: exactToken(usage?.input, `${label}.input`),
-    output: exactToken(usage?.output, `${label}.output`),
-    cacheRead: exactToken(usage?.cacheRead, `${label}.cacheRead`),
-    cacheWrite: exactToken(usage?.cacheWrite, `${label}.cacheWrite`),
-    reasoning: exactToken(usage?.reasoning, `${label}.reasoning`),
-    total: exactToken(usage?.totalTokens, `${label}.totalTokens`)
-  } : {
+  const reasoningReported = Boolean(usage && Object.hasOwn(usage, "reasoning") && usage.reasoning !== undefined);
+  const values = strict ? (() => {
+    const output = exactToken(usage?.output, `${label}.output`);
+    return {
+      input: exactToken(usage?.input, `${label}.input`),
+      output,
+      cacheRead: exactToken(usage?.cacheRead, `${label}.cacheRead`),
+      cacheWrite: exactToken(usage?.cacheWrite, `${label}.cacheWrite`),
+      // Pi's upstream usage shape makes reasoning optional. Its absence does
+      // not make the additive input/output totals unknown: reasoning is a
+      // subset of output. A zero-output response proves zero reasoning; for a
+      // non-zero output we retain zero only as an explicit lower bound.
+      reasoning: reasoningReported ? exactToken(usage.reasoning, `${label}.reasoning`) : 0,
+      total: exactToken(usage?.totalTokens, `${label}.totalTokens`)
+    };
+  })() : {
     input: numberValue(usage.input), output: numberValue(usage.output), cacheRead: numberValue(usage.cacheRead),
     cacheWrite: numberValue(usage.cacheWrite), reasoning: numberValue(usage.reasoning),
     total: numberValue(usage.totalTokens) || numberValue(usage.input) + numberValue(usage.output) + numberValue(usage.cacheRead) + numberValue(usage.cacheWrite)
@@ -229,6 +311,11 @@ function addTotals(target, usage, { strict = false, label = "usage" } = {}) {
   target.cost += typeof cost === "object" && cost !== null
     ? numberValue(cost.total)
     : numberValue(cost);
+  return {
+    reasoningReported,
+    reasoningCompleteness: reasoningReported || values.output === 0 ? "exact" : "lower-bound",
+    reasoningInferredZero: !reasoningReported && values.output === 0
+  };
 }
 
 function numberValue(raw) {
@@ -253,6 +340,7 @@ function summarizeSession(file, options) {
     return undefined;
   }
 
+  const execution = emptyExecutionAggregate();
   const summary = {
     id: path.basename(file, ".jsonl"),
     name: "",
@@ -269,13 +357,29 @@ function summarizeSession(file, options) {
     messages: { user: 0, assistant: 0, toolCalls: 0, toolResults: 0, total: 0 },
     promptChars: 0,
     tokens: emptyTotals(),
-    usageIntegrity: { exact: options.strictUsage === true, source: "pi-session-jsonl", assistantMessages: 0, usageMessages: 0 },
+    usageIntegrity: {
+      exact: options.strictUsage === true,
+      source: "pi-session-jsonl",
+      assistantMessages: 0,
+      usageMessages: 0,
+      reasoningMessages: 0,
+      reasoningInferredZeroMessages: 0,
+      reasoningLowerBoundMessages: 0,
+      reasoningCompleteness: "exact"
+    },
+    pricingBuckets: { schemaVersion: 1, source: "provider-request-usage", completeness: "unverified", requests: [] },
+    execution,
     toolNames: {},
     sizeBytes: stat.size,
     mtime: stat.mtime
   };
 
   let hasCountedActivity = false;
+  let parsedRecordCount = 0;
+  let sessionHeaderCount = 0;
+  const toolCallsById = new Map();
+  const toolResultIds = new Set();
+  const toolCallFingerprints = new Set();
   const lines = fs.readFileSync(file, "utf8").split(/\n/);
   for (const [lineIndex, line] of lines.entries()) {
     if (!line) continue;
@@ -287,6 +391,12 @@ function summarizeSession(file, options) {
       continue;
     }
 
+    const isFirstParsedRecord = parsedRecordCount === 0;
+    parsedRecordCount += 1;
+    if (options.strictUsage && isFirstParsedRecord && entry?.type !== "session") {
+      throw new Error("Pi session JSONL is missing its session header as the first record");
+    }
+
     const ts = parseIso(entry.timestamp ?? entry.message?.timestamp);
     if (ts) {
       if (!summary.firstTimestamp || ts < summary.firstTimestamp) summary.firstTimestamp = ts;
@@ -294,6 +404,14 @@ function summarizeSession(file, options) {
     }
 
     if (entry.type === "session") {
+      sessionHeaderCount += 1;
+      if (options.strictUsage && (sessionHeaderCount !== 1 || !isFirstParsedRecord)) {
+        throw new Error("Pi session JSONL must contain exactly one session header as the first record");
+      }
+      if (options.strictUsage && (typeof entry.id !== "string" || !entry.id.trim()
+        || typeof entry.cwd !== "string" || !entry.cwd.trim())) {
+        throw new Error("Pi session JSONL session header must contain non-empty id and cwd strings");
+      }
       if (entry.id) summary.id = String(entry.id);
       if (entry.cwd) summary.cwd = String(entry.cwd);
       continue;
@@ -311,6 +429,13 @@ function summarizeSession(file, options) {
       summary.name = String(entry.name);
       continue;
     }
+
+    const countedControl = inRange(ts ?? stat.mtime, options);
+    if (countedControl && entry.type === "auto_retry_start") execution.explicitRetries += 1;
+    else if (countedControl && entry.type === "auto_retry_end" && entry.success === false) execution.retryFailures += 1;
+    else if (countedControl && entry.type === "compaction_start") execution.compactions += 1;
+    else if (countedControl && entry.type === "compaction_end" && entry.aborted === true) execution.abortedCompactions += 1;
+    else if (countedControl && entry.type === "summarization_retry_scheduled") execution.summarizationRetries += 1;
     if (entry.type !== "message" || !entry.message) continue;
 
     const counted = inRange(ts ?? stat.mtime, options);
@@ -324,6 +449,10 @@ function summarizeSession(file, options) {
     const role = message.role;
     summary.messages.total += 1;
     if (role === "user") {
+      // A repeated call means duplicate work inside one operator turn. The
+      // same verifier or read requested again by a later user turn is fresh
+      // work, not a retry loop, even when the session itself is preserved.
+      toolCallFingerprints.clear();
       summary.messages.user += 1;
       summary.promptChars += extractTextLength(message.content);
     } else if (role === "assistant") {
@@ -335,21 +464,52 @@ function summarizeSession(file, options) {
         throw new Error(`Pi assistant message at line ${lineIndex + 1} is missing usage`);
       }
       if (message.usage) {
-        addTotals(summary.tokens, message.usage, { strict: options.strictUsage === true, label: `Pi session JSONL line ${lineIndex + 1} usage` });
+        const usageReceipt = addTotals(summary.tokens, message.usage, {
+          strict: options.strictUsage === true,
+          label: `Pi session JSONL line ${lineIndex + 1} usage`
+        });
         summary.usageIntegrity.usageMessages += 1;
+        if (usageReceipt.reasoningReported) summary.usageIntegrity.reasoningMessages += 1;
+        if (usageReceipt.reasoningInferredZero) summary.usageIntegrity.reasoningInferredZeroMessages += 1;
+        if (usageReceipt.reasoningCompleteness === "lower-bound") {
+          summary.usageIntegrity.reasoningLowerBoundMessages += 1;
+          summary.usageIntegrity.reasoningCompleteness = "lower-bound";
+        }
+        execution.providerStartedAttempts += 1;
+        const request = exactPricingRequest(message.usage);
+        if (request) summary.pricingBuckets.requests.push(request);
       }
       if (Array.isArray(message.content)) {
         for (const block of message.content) {
           if (block?.type !== "toolCall") continue;
           summary.messages.toolCalls += 1;
+          execution.toolCalls += 1;
           const name = String(block.name ?? "tool");
           summary.toolNames[name] = (summary.toolNames[name] ?? 0) + 1;
+          const id = typeof block.id === "string" && block.id ? block.id : null;
+          const subagentAttempt = isSubagentAttempt(block);
+          if (id) toolCallsById.set(id, { name, subagentAttempt });
+          if (subagentAttempt) execution.subagentAttempts += 1;
+          const fingerprint = toolFingerprint(block);
+          if (toolCallFingerprints.has(fingerprint)) execution.repeatedToolCalls += 1;
+          else toolCallFingerprints.add(fingerprint);
         }
       }
     } else if (role === "toolResult") {
       summary.messages.toolResults += 1;
+      execution.toolResults += 1;
       const name = String(message.toolName ?? "tool");
       summary.toolNames[name] = summary.toolNames[name] ?? 0;
+      const status = structuredToolStatus(message);
+      const failed = message.isError === true || status === "failed" || status === "error";
+      if (failed) execution.toolFailures += 1;
+      if (status === "blocked") execution.blockedToolCalls += 1;
+      if (status === "declined") execution.declinedToolCalls += 1;
+      const call = typeof message.toolCallId === "string" ? toolCallsById.get(message.toolCallId) : undefined;
+      if (typeof message.toolCallId === "string") toolResultIds.add(message.toolCallId);
+      if (call?.subagentAttempt && (failed || status === "blocked" || status === "declined")) execution.subagentFailures += 1;
+      const compacted = message.details?.piagentCompactedToolResults;
+      if (Number.isSafeInteger(compacted) && compacted > 0) execution.compactions += compacted;
     }
   }
 
@@ -360,9 +520,21 @@ function summarizeSession(file, options) {
   if (!summary.countedLastTimestamp) summary.countedLastTimestamp = summary.lastTimestamp;
 
   if (!hasCountedActivity && (options.since || options.until)) return undefined;
+  if (options.strictUsage && sessionHeaderCount !== 1) {
+    throw new Error("Pi session JSONL is missing its session header");
+  }
   if (options.strictUsage && summary.usageIntegrity.assistantMessages !== summary.usageIntegrity.usageMessages) {
     throw new Error("Pi session JSONL usage coverage is incomplete");
   }
+  summary.pricingBuckets.completeness = summary.usageIntegrity.assistantMessages > 0
+    && summary.pricingBuckets.requests.length === summary.usageIntegrity.assistantMessages
+    ? "exact"
+    : "unverified";
+  const identifiedToolResults = [...toolCallsById.keys()].filter((id) => toolResultIds.has(id)).length;
+  execution.completeness.tools = execution.toolCalls === execution.toolResults && identifiedToolResults === execution.toolCalls
+    ? "exact"
+    : "partial";
+  execution.completeness.subagents = execution.completeness.tools;
   return summary;
 }
 
@@ -388,7 +560,9 @@ function buildReport(options, sessions) {
     subagentSessions: sessions.filter((s) => s.isSubagent).length,
     messages: { user: 0, assistant: 0, toolCalls: 0, toolResults: 0, total: 0 },
     promptChars: 0,
-    tokens: emptyTotals()
+    tokens: emptyTotals(),
+    execution: emptyExecutionAggregate(),
+    pricingBuckets: { schemaVersion: 1, source: "provider-request-usage", completeness: "exact", requests: [] }
   };
   const projects = new Map();
   const tools = {};
@@ -396,6 +570,12 @@ function buildReport(options, sessions) {
     for (const key of Object.keys(totals.messages)) totals.messages[key] += session.messages[key];
     totals.promptChars += session.promptChars;
     for (const key of Object.keys(totals.tokens)) totals.tokens[key] += session.tokens[key];
+    for (const key of ["providerStartedAttempts", "toolCalls", "toolResults", "toolFailures", "blockedToolCalls",
+      "declinedToolCalls", "explicitRetries", "retryFailures", "compactions", "abortedCompactions",
+      "summarizationRetries", "repeatedToolCalls", "subagentAttempts", "subagentFailures"]) {
+      totals.execution[key] += Number(session.execution?.[key] ?? 0);
+    }
+    totals.pricingBuckets.requests.push(...(session.pricingBuckets?.requests ?? []));
     const project = projects.get(session.cwd) ?? {
       cwd: session.cwd,
       sessions: 0,
@@ -420,6 +600,16 @@ function buildReport(options, sessions) {
     .map(([name, count]) => ({ name, count }))
     .sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
 
+  const completenessRank = { exact: 0, partial: 1, unverified: 2, unavailable: 3 };
+  for (const field of ["tools", "retries", "compactions", "subagents"]) {
+    totals.execution.completeness[field] = sessions.reduce((worst, session) => {
+      const value = session.execution?.completeness?.[field] ?? "unavailable";
+      return completenessRank[value] > completenessRank[worst] ? value : worst;
+    }, "exact");
+  }
+  totals.pricingBuckets.completeness = sessions.length > 0
+    && sessions.every((session) => session.pricingBuckets?.completeness === "exact") ? "exact" : "unverified";
+
   return {
     generatedAt: new Date().toISOString(),
     scope: {

package/scripts/piagent-cli.mjs

@@ -42,6 +42,12 @@ if (invokedAs === "piagent") {
   } else if (subcommand === "explain") {
     script = "scripts/explain-command.mjs";
     forwardedArgs = forwardedArgs.slice(1);
+  } else if (subcommand === "approve-verification") {
+    script = "scripts/approve-independent-verification.mjs";
+    forwardedArgs = forwardedArgs.slice(1);
+  } else if (subcommand === "select-verification") {
+    script = "scripts/select-independent-verification.mjs";
+    forwardedArgs = forwardedArgs.slice(1);
   } else if ([undefined, "help", "--help", "-h"].includes(subcommand)) {
     // Subcommands are listed, their flags are not. Restating them here meant a
     // second copy that drifts: this line still advertised the dashboard without
@@ -51,6 +57,8 @@ if (invokedAs === "piagent") {
     console.log("Commands:");
     console.log("  dashboard   Open and manage the local session hub");
     console.log("  explain     Say why the guard would allow or block a shell command");
+    console.log("  approve-verification  Preview or approve an independent verification plan");
+    console.log("  select-verification   Preview reusable contracts for exact task criteria");
     console.log("");
     console.log("Run `piagent <command> --help` for that command's options.");
     process.exit(0);

package/scripts/private-holdout-readiness.mjs

@@ -5,6 +5,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { benchmarkAssuranceEvidenceValidationErrors } from "../packages/piagent-core/benchmark/benchmark-assurance.js";
+import { verifyPublicExposure } from "./public-evaluation-exposure.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const usage = "Usage: node scripts/private-holdout-readiness.mjs --evidence /secure/path/assurance.json";
@@ -46,11 +47,15 @@ const errors = benchmarkAssuranceEvidenceValidationErrors(evidence);
 if (errors.length > 0) refuse(errors.join("; "));
 if (evidence.schemaVersion !== 2) refuse("legacy assurance evidence is historical-only and cannot establish E3 readiness");
 
+let publicExposure;
+try { publicExposure = verifyPublicExposure(root); }
+catch { refuse("current public exposure inventory is unavailable, stale or incomplete"); }
+
 const bindings = {
   accessPolicyDigest: digestFile("evals/private-holdout-v1/access-policy.v1.json"),
   humanRubricDigest: digestFile("evals/private-holdout-v1/human-rubric.v1.json"),
   taxonomyDigest: digestFile("evals/real-task-taxonomy.v1.json"),
-  publicExposureDigest: digestFile("evals/private-holdout-v1/public-exposure.v1.json")
+  publicExposureDigest: publicExposure.sha256
 };
 for (const [field, expected] of Object.entries(bindings)) {
   const actual = field in evidence ? evidence[field] : evidence.disjointness?.[field];
@@ -64,6 +69,7 @@ const receipt = {
   protocolVersion: "e3-custody-v1",
   ready: true,
   evidenceManifestDigest: crypto.createHash("sha256").update(buffer).digest("hex"),
+  publicExposure,
   claimTier: evidence.claimTier,
   visibility: evidence.visibility,
   access: {

package/scripts/public-evaluation-exposure.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { fileURLToPath } from "node:url";
+
+export const EXPOSURE_PATH = "evals/private-holdout-v1/public-exposure.v2.json";
+const PREVIOUS_PATH = "evals/private-holdout-v1/public-exposure.v1.json";
+const TAXONOMY_PATH = "evals/real-task-taxonomy.v1.json";
+const PUBLIC_TREES = [
+  "adapters", "benchmarks", "evals/architecture-conformance-v1", "evals/golden",
+  "evals/harness-next", "evals/long-horizon-v1", "evals/runtime-conformance-v1",
+  "evals/scenarios", "tests"
+];
+const sha256 = (bytes) => crypto.createHash("sha256").update(bytes).digest("hex");
+const MAX_FILES = 10_000, MAX_FILE_BYTES = 4 * 1024 * 1024, MAX_TOTAL_BYTES = 64 * 1024 * 1024;
+const DEFAULT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+function reader(root) {
+  let total = 0, count = 0;
+  const cache = new Map();
+  function checked(relative) {
+    let current = root;
+    for (const part of relative.split("/")) {
+      if (!part || part === "." || part === ".." || part.includes("\\")) throw new Error("Invalid public exposure path");
+      current = path.join(current, part);
+      if (fs.lstatSync(current).isSymbolicLink()) throw new Error("Public exposure inputs must not be symlinks");
+    }
+    return current;
+  }
+  function bytes(relative) {
+    if (cache.has(relative)) return cache.get(relative);
+    const target = checked(relative), descriptor = fs.openSync(target, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    let value;
+    try {
+      const stat = fs.fstatSync(descriptor);
+      if (!stat.isFile() || stat.size > MAX_FILE_BYTES) throw new Error("Public exposure input is not a bounded regular file");
+      value = fs.readFileSync(descriptor);
+    } finally { fs.closeSync(descriptor); }
+    total += value.length;
+    if (value.length > MAX_FILE_BYTES || ++count > MAX_FILES || total > MAX_TOTAL_BYTES) throw new Error("Public exposure inventory exceeds its limits");
+    cache.set(relative, value);
+    return value;
+  }
+  function files(relative) {
+    const target = checked(relative);
+    if (!fs.statSync(target).isDirectory()) throw new Error("Public exposure tree is not a directory");
+    const result = [];
+    for (const name of fs.readdirSync(target).sort()) {
+      const child = `${relative}/${name}`, stat = fs.lstatSync(checked(child));
+      if (stat.isDirectory()) result.push(...files(child));
+      else if (stat.isFile()) { bytes(child); result.push(child); }
+      else throw new Error("Public exposure tree contains a non-regular input");
+    }
+    return result;
+  }
+  return { bytes, files, json: (relative) => JSON.parse(bytes(relative).toString("utf8")) };
+}
+
+// Inventory public files only. Never load a private suite or execute an oracle.
+// The predecessor is retained rather than silently erasing earlier exposure.
+export function buildPublicExposure(root = DEFAULT_ROOT) {
+  const read = reader(root), allFiles = new Map();
+  const visibleTrees = PUBLIC_TREES.map((relative) => {
+    const entries = read.files(relative).sort().map((file) => {
+      const bytes = read.bytes(file), digest = sha256(bytes);
+      allFiles.set(file, bytes);
+      return [file, digest];
+    });
+    return { path: relative, fileCount: entries.length, sha256: sha256(JSON.stringify(entries)) };
+  });
+  const visibleSuites = [...allFiles.keys()].filter((file) => /^benchmarks\/[^/]+\/suite\.json$/.test(file)).map((file) => {
+    const suite = read.json(file);
+    if (!/^[a-z0-9-]+$/.test(suite.id ?? "") || file !== `benchmarks/${suite.id}/suite.json`
+      || !Array.isArray(suite.scenarios) || suite.scenarios.length === 0) throw new Error("Invalid public suite identity");
+    const scenarioIds = suite.scenarios.map((scenario) => scenario.id);
+    if (scenarioIds.some((id) => !/^[a-z0-9-]+$/.test(id ?? "")) || new Set(scenarioIds).size !== scenarioIds.length) throw new Error("Invalid public scenario identities");
+    return { id: suite.id, path: file, manifestSha256: sha256(read.bytes(file)), scenarioIds };
+  });
+  const contractLibraries = [...allFiles.keys()].filter((file) => /^adapters\/[^/]+\/contract-families\.json$/.test(file)).map((file) => {
+    const library = read.json(file);
+    if (library.schemaVersion !== 1 || !Array.isArray(library.families)) throw new Error("Invalid public contract library");
+    const families = library.families.map(({ id, version }) => {
+      if (!/^[a-z0-9-]+$/.test(id ?? "") || !Number.isSafeInteger(version) || version < 1) throw new Error("Invalid public contract family identity");
+      return { id, version };
+    });
+    if (new Set(families.map(({ id, version }) => `${id}@${version}`)).size !== families.length) throw new Error("Duplicate public contract family identity");
+    return { path: file, sha256: sha256(read.bytes(file)), families };
+  });
+  return {
+    schemaVersion: 2,
+    id: "author-visible-evaluation-exposure-v2",
+    previousExposure: { path: PREVIOUS_PATH, sha256: sha256(read.bytes(PREVIOUS_PATH)) },
+    taxonomy: { path: TAXONOMY_PATH, sha256: sha256(read.bytes(TAXONOMY_PATH)) },
+    visibleSuites,
+    contractLibraries,
+    visibleTrees,
+    custodianComparisonRules: {
+      familyKey: "Compare private task and acceptance-mechanism lineage against every listed suite, contract family, public tree and predecessor exposure; renamed, generated or structurally varied descendants are not disjoint.",
+      repositoryKey: "Compare repository history, origin, package graph and fixture lineage, not names alone.",
+      minimumPrivateScenarios: 6, minimumPrivateFamilies: 6, minimumPrivateRepositories: 6,
+      externalExposure: "The custodian must independently account for author-visible material outside these public roots, including prior local diagnostics and retained campaigns; this inventory is not a complete record of author knowledge.",
+      publicOutput: "Export only the closed schema-v2 assurance receipt and independent custody attestation."
+    },
+    claimBoundary: "Current public-input inventory only, not independent evaluation, approval, generalization or release evidence. Public-tree digests bind [relative path, file SHA-256] pairs globally sorted by the slash-separated path's UTF-16 code units, serialized as compact JSON and hashed as UTF-8; no private artifacts are loaded."
+  };
+}
+
+export function verifyPublicExposure(root = DEFAULT_ROOT) {
+  const read = reader(root), bytes = read.bytes(EXPOSURE_PATH), actual = JSON.parse(bytes.toString("utf8"));
+  if (!isDeepStrictEqual(actual, buildPublicExposure(root))) throw new Error("Current public exposure inventory is stale or incomplete; regenerate and obtain a new independent custody receipt");
+  return { path: EXPOSURE_PATH, sha256: sha256(bytes), suiteCount: actual.visibleSuites.length,
+    scenarioCount: actual.visibleSuites.reduce((sum, suite) => sum + suite.scenarioIds.length, 0),
+    contractFamilyVersionCount: actual.contractLibraries.reduce((sum, library) => sum + library.families.length, 0),
+    publicTreeCount: actual.visibleTrees.length };
+}
+
+// Node resolves module URLs through filesystem aliases. Compare actual files,
+// otherwise /var versus /private/var (or a global-bin symlink) can skip the CLI.
+const invokedDirectly = process.argv[1] && fs.existsSync(process.argv[1])
+  && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+if (invokedDirectly) {
+  if (process.argv.length === 3 && ["--help", "-h"].includes(process.argv[2])) {
+    process.stdout.write("Usage: node scripts/public-evaluation-exposure.mjs --check|--write\nRequires the complete public source tree, including development tests. Generation does not grant custody or provider authority.\n");
+    process.exit(0);
+  }
+  try {
+    if (process.argv.length !== 3 || !["--check", "--write"].includes(process.argv[2])) throw new Error("Usage: node scripts/public-evaluation-exposure.mjs --check|--write");
+    if (process.argv[2] === "--write") {
+      const destination = path.join(DEFAULT_ROOT, EXPOSURE_PATH);
+      if (fs.existsSync(destination) && fs.lstatSync(destination).isSymbolicLink()) throw new Error("Refusing a symlinked public exposure destination");
+      fs.writeFileSync(destination, `${JSON.stringify(buildPublicExposure(), null, 2)}\n`);
+    }
+    process.stdout.write(`${JSON.stringify(verifyPublicExposure())}\n`);
+  } catch {
+    process.stderr.write("REFUSED: current public exposure inventory is unavailable, stale or incomplete; inspect public inputs and regenerate before independent custody review\n");
+    process.exitCode = 1;
+  }
+}