refactor(policy): name the Pi trust boundary in the project's own terms

Documentation review found the new text drifting from repository
vocabulary. The check reported failures with "denies" where every
neighbouring case says "rejects", used "writable" where the controlled
term for a path that also permits reads is "read-write", and justified
two manifest rules by an unnamed "v1 surface". The module summary listed
four of the eight boundaries the check binds.

The endpoint enforcement mode and the device-pairing rule now have the
cases they were missing, and the endpoint-count rule is asserted rather
than merely reached.

Signed-off-by: Tinson Lai <tinsonl@nvidia.com>

Author: laitingsheng

scripts/checks/pi-candidate-artifacts.mts

@@ -12,11 +12,17 @@
  * candidate contract artifact name stays outside the all-agent cohort download
  * pattern.
  *
- * It also binds the accepted Pi trust boundary: the baseline permits only the
- * managed inference route from root-owned image binaries, writable paths stay
- * on the declared sandbox state, non-interactive runs keep passing the flag
- * that ignores project-local resources, and neither the project-trust store nor
- * the project-trust setting can travel through backup and restore.
+ * It also binds the accepted Pi trust boundary:
+ *
+ * - The baseline network policy permits only the managed inference route, and
+ *   only root-owned image binaries carry network capability.
+ * - The read-write paths stay /dev/null, /sandbox, /sandbox/.pi, and /tmp, and
+ *   Landlock stays strict so filesystem policy fails closed.
+ * - Pi runs as the sandbox user and group.
+ * - The headless command passes the flag that ignores project-local resources,
+ *   MCP stays disabled, and device pairing stays off.
+ * - Neither the project-trust store nor the project-trust setting is declared
+ *   in the manifest state that backup and restore carry.
  */
 
 import { createHash } from "node:crypto";
@@ -324,7 +330,7 @@ function verifyFilesystemBoundary(policy: LooseRecord): string[] {
   const readWrite = sortedStrings(filesystem.read_write);
   if (!sameSet(readWrite, APPROVED_READ_WRITE_PATHS)) {
     failures.push(
-      `${PI_POLICY_PATH}: writable paths must stay ${APPROVED_READ_WRITE_PATHS.join(", ")}, found ${readWrite.join(", ") || "none"}`,
+      `${PI_POLICY_PATH}: read-write paths must stay ${APPROVED_READ_WRITE_PATHS.join(", ")}, found ${readWrite.join(", ") || "none"}`,
     );
   }
   if (asRecord(policy.landlock).compatibility !== REQUIRED_LANDLOCK_COMPATIBILITY) {
@@ -352,10 +358,10 @@ function verifyApprovalBoundary(manifest: LooseRecord): string[] {
     );
   }
   if (asRecord(manifest.mcp).support !== "disabled") {
-    failures.push(`${PI_MANIFEST_PATH}: mcp.support must stay disabled for the accepted v1 surface`);
+    failures.push(`${PI_MANIFEST_PATH}: mcp.support must stay disabled`);
   }
   if (manifest.device_pairing !== false) {
-    failures.push(`${PI_MANIFEST_PATH}: device_pairing must stay false for the accepted v1 surface`);
+    failures.push(`${PI_MANIFEST_PATH}: device_pairing must stay false`);
   }
   return failures;
 }

src/lib/policy/agent-base-preset.test.ts

@@ -67,7 +67,7 @@ describe("agent base preset detection", () => {
     expect(isAgentBasePreset("hermes", "pypi")).toBe(true);
   });
 
-  it("keeps a catalog preset outside the Pi baseline so external access stays an explicit choice (#7924)", () => {
+  it("reports pypi and github as non-baseline presets for the Pi policy (#7924)", () => {
     const piPolicy = fs.readFileSync(path.join(AGENTS_DIR, "pi", "policy-additions.yaml"), "utf8");
     const agent = createAgentFixture(piPolicy);
     vi.spyOn(registry, "getSandbox").mockReturnValue({ name: "pi", agent } as never);

test/pi-candidate-runtime-artifacts.test.ts

@@ -207,11 +207,11 @@ describe("Pi candidate contract validation", () => {
 });
 
 describe("Pi runtime boundaries", () => {
-  it("accepts the trust boundary committed in this repository (#7924)", () => {
+  it("accepts the Pi trust boundary committed in this repository (#7924)", () => {
     expect(verifyPiTrustBoundary(currentSources())).toEqual([]);
   });
 
-  it("denies a direct provider endpoint added beside the managed route (#7924)", () => {
+  it("rejects a direct provider endpoint added beside the managed route (#7924)", () => {
     const sources = withPolicy((policy) => {
       policy.network_policies.managed_inference.endpoints.push({
         host: "api.openai.com",
@@ -221,12 +221,13 @@ describe("Pi runtime boundaries", () => {
         rules: [{ allow: { method: "POST", path: "/v1/chat/completions" } }],
       });
     });
-    expect(verifyPiTrustBoundary(sources)).toContain(
+    expect(verifyPiTrustBoundary(sources)).toEqual([
+      "agents/pi/policy-additions.yaml: managed_inference must declare exactly one endpoint",
       "agents/pi/policy-additions.yaml: the baseline permits only inference.local:443",
-    );
+    ]);
   });
 
-  it("denies a package registry policy the baseline never selected (#7924)", () => {
+  it("rejects a package registry policy added to the Pi baseline (#7924)", () => {
     const sources = withPolicy((policy) => {
       policy.network_policies.npm_registry = {
         name: "npm_registry",
@@ -238,7 +239,7 @@ describe("Pi runtime boundaries", () => {
     );
   });
 
-  it("denies network capability to a binary the agent can write (#7924)", () => {
+  it("rejects an agent-writable binary in the network policy (#7924)", () => {
     const sources = withPolicy((policy) => {
       policy.network_policies.managed_inference.binaries.push({ path: "/sandbox/agent-proxy" });
     });
@@ -247,7 +248,7 @@ describe("Pi runtime boundaries", () => {
     );
   });
 
-  it("denies a rule that widens the managed route beyond its versioned paths (#7924)", () => {
+  it("rejects a managed inference rule that allows a path outside /v1/ (#7924)", () => {
     const sources = withPolicy((policy) => {
       policy.network_policies.managed_inference.endpoints[0].rules.push({
         allow: { method: "GET", path: "/**" },
@@ -258,16 +259,34 @@ describe("Pi runtime boundaries", () => {
     );
   });
 
-  it("denies a container-runtime socket added to the writable paths (#7924)", () => {
+  it("rejects a managed inference endpoint that is observed instead of enforced (#7924)", () => {
+    const sources = withPolicy((policy) => {
+      policy.network_policies.managed_inference.endpoints[0].enforcement = "observe";
+    });
+    expect(verifyPiTrustBoundary(sources)).toContain(
+      "agents/pi/policy-additions.yaml: inference.local must stay enforced, not observed",
+    );
+  });
+
+  it("rejects a manifest that enables device pairing (#7924)", () => {
+    const sources = withManifest((manifest) => {
+      manifest.device_pairing = true;
+    });
+    expect(verifyPiTrustBoundary(sources)).toContain(
+      "agents/pi/manifest.yaml: device_pairing must stay false",
+    );
+  });
+
+  it("rejects a container-runtime socket added to the read-write paths (#7924)", () => {
     const sources = withPolicy((policy) => {
       policy.filesystem_policy.read_write.push("/var/run/docker.sock");
     });
     expect(verifyPiTrustBoundary(sources).join("\n")).toContain(
-      "writable paths must stay /dev/null, /sandbox, /sandbox/.pi, /tmp",
+      "read-write paths must stay /dev/null, /sandbox, /sandbox/.pi, /tmp",
     );
   });
 
-  it("denies a relaxed Landlock compatibility that would start with policy unenforced (#7924)", () => {
+  it("rejects a Landlock compatibility that does not fail closed (#7924)", () => {
     const sources = withPolicy((policy) => {
       policy.landlock.compatibility = "best-effort";
     });
@@ -276,7 +295,7 @@ describe("Pi runtime boundaries", () => {
     );
   });
 
-  it("denies host control by refusing a privileged process identity (#7924)", () => {
+  it("rejects a root process identity in the Pi policy (#7924)", () => {
     const sources = withPolicy((policy) => {
       policy.process.run_as_user = "root";
     });
@@ -285,7 +304,7 @@ describe("Pi runtime boundaries", () => {
     );
   });
 
-  it("denies a non-interactive command that stops ignoring project-local resources (#7924)", () => {
+  it("rejects a headless command that omits --no-approve (#7924)", () => {
     const sources = withManifest((manifest) => {
       manifest.runtime.headless_command = "pi --print";
     });
@@ -294,16 +313,16 @@ describe("Pi runtime boundaries", () => {
     );
   });
 
-  it("denies an MCP surface the accepted v1 scope excludes (#7924)", () => {
+  it("rejects an enabled MCP surface in the Pi manifest (#7924)", () => {
     const sources = withManifest((manifest) => {
       manifest.mcp.support = "enabled";
     });
     expect(verifyPiTrustBoundary(sources)).toContain(
-      "agents/pi/manifest.yaml: mcp.support must stay disabled for the accepted v1 surface",
+      "agents/pi/manifest.yaml: mcp.support must stay disabled",
     );
   });
 
-  it("denies a project-trust store that a restore could carry into a new sandbox (#7924)", () => {
+  it("rejects a manifest that declares the trust.json project-trust store (#7924)", () => {
     const sources = withManifest((manifest) => {
       manifest.state_files.push({ path: "trust.json" });
     });
@@ -312,7 +331,7 @@ describe("Pi runtime boundaries", () => {
     );
   });
 
-  it("denies a restore allowlist that could widen project trust (#7924)", () => {
+  it("rejects defaultProjectTrust in the restore allowlist (#7924)", () => {
     const sources = withManifest((manifest) => {
       manifest.state_files[0].restore.user_keys.push({
         key: "defaultProjectTrust",