@piagent/platform 1.4.0 → 1.4.1

package/package.json

@@ -1,19 +1,30 @@
 {
   "name": "@piagent/platform",
-  "version": "1.4.0",
+  "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",
@@ -75,6 +86,7 @@
     "piagent-import-instructions": "scripts/piagent-cli.mjs",
     "piagent-auto": "scripts/piagent-cli.mjs",
     "piagent-context": "scripts/piagent-cli.mjs",
+    "piagent-explain": "scripts/piagent-cli.mjs",
     "piagent-webui": "scripts/piagent-cli.mjs"
   },
   "pi": {

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/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

@@ -164,6 +164,11 @@ 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) {
@@ -172,7 +177,16 @@ function normalizedRelative(root, absolute) {
   return relative.split(path.sep).join("/");
 }
 
-function executableFilesBelow(root, relativeDirectory) {
+// 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 = [];
@@ -182,7 +196,7 @@ function executableFilesBelow(root, relativeDirectory) {
       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() && EXECUTABLE_SOURCE.test(entry.name)) files.push(normalizedRelative(root, target));
+      else if (stat.isFile() && accept.test(entry.name)) files.push(normalizedRelative(root, target));
     }
   };
   visit(directory);
@@ -192,7 +206,13 @@ function executableFilesBelow(root, relativeDirectory) {
 function localImportTarget(root, importer, specifier) {
   if (!specifier.startsWith(".")) return undefined;
   const base = path.resolve(path.dirname(path.join(root, importer)), specifier);
-  const candidates = [base, `${base}.ts`, `${base}.js`, `${base}.mjs`, path.join(base, "index.ts"), path.join(base, "index.js")];
+  // 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;
@@ -204,8 +224,24 @@ function localImportTarget(root, importer, specifier) {
 }
 
 function sourceReferences(root, relativeFile) {
-  if (!/\.(?:[cm]?js|ts)$/.test(relativeFile)) return [];
+  // 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)) {
@@ -231,6 +267,17 @@ export function discoverRuntimeIntegrityFiles(root) {
     ...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

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

@@ -11,6 +11,11 @@ import {
   evaluateExecPolicyCore, extractShellGlobCandidates, extractShellPathCandidates, findProtectedPathInCommand, unresolvedPathExpansions,
   globMatchesPath, matchesProtectedPath, normalizePathCandidate, matchesAnyPath
 } from "./policy-core.js";
+import {
+  expandSimpleGlobAlternatives, findResolvedProtectedPathInCommand, normalizeRelative, protectedPatternExamples,
+  resolveRepositoryPathCandidate, shellGlobMatchesPath, shellGlobSegmentMatches, shellGlobTargetsProtectedPath,
+  unresolvedExpansionReason
+} from "./shell-reach.ts";
 import { extractShellWritePathCandidates, shellHasFileWriteRedirection } from "./shell-write-targets.js";
 import { commandMatchesVerifyPlan, createBashResultLedger, findMatchingObservedBashResult, readObservedBashResults } from "./runtime-evidence.js";
 import { findPackageRoot, findPlatformRoot, readJsonFile } from "./guard-io.js";
@@ -374,10 +379,16 @@ const SHELL_TOOL_NAMES = new Set(["bash", "shell", "exec"]);
 const MAX_MCP_PROXY_ARGS_CHARS = 131_072;
 const SESSION_PERMISSION_OVERRIDES = new Map<string, PermissionProfileMode>();
 
+// The policy used when `policies/base-policy.json` cannot be read. It runs in
+// exactly the case where something is already wrong, so it must never be the
+// looser of the two: this copy had drifted behind the file and silently dropped
+// `.pi/piagent-state/**` -- the guard's own state -- along with the `sudo ` and
+// `chmod -R 777` blocks. A missing policy file is a reason to be stricter, not a
+// quiet downgrade. `tests/policy-core.test.mjs` fails if this drifts again.
 const DEFAULT_POLICY: BasePolicy = {
-  protectedPaths: [".git/**", "**/auth.json", "**/.env", "**/.env.*", ".pi/settings.json", ".pi/piagent-profile.json", ".pi/piagent-profile.lock.json", CONTEXT_INDEX_FILE],
-  shellProtectedPaths: [".git/**", "**/auth.json", "**/.env", "**/.env.*", ".pi/settings.json", ".pi/piagent-profile.json", ".pi/piagent-profile.lock.json", CONTEXT_INDEX_FILE],
-  blockedCommandPatterns: ["rm -rf /", "rm -rf ~", "rm -rf $HOME", "git reset --hard", "git clean -fd"],
+  protectedPaths: [".git/**", "**/auth.json", "**/.env", "**/.env.*", "**/node_modules/**", "**/dist/**", ".pi/piagent-state/**", ".pi/settings.json", ".pi/piagent-profile.json", ".pi/piagent-profile.lock.json", CONTEXT_INDEX_FILE],
+  shellProtectedPaths: [".git/**", "**/auth.json", "**/.env", "**/.env.*", ".pi/piagent-state/**", ".pi/settings.json", ".pi/piagent-profile.json", ".pi/piagent-profile.lock.json", CONTEXT_INDEX_FILE],
+  blockedCommandPatterns: ["rm -rf /", "rm -rf ~", "rm -rf $HOME", "git reset --hard", "git clean -fd", "sudo ", "chmod -R 777"],
   requireConfirmationPatterns: ["deploy", "release", "publish", "migration", "gh pr merge", "git push"],
   defaultRequiredContext: ["AGENTS.md", "README.md"],
   permissionProfiles: {
@@ -646,26 +657,6 @@ function legacyProjectStateWarning(cwd: string): string | undefined {
     : `${detail} No .pi/piagent-profile.json exists, so this project is running unprofiled and its protected paths and verify commands are NOT enforced. Convert it with \`piagent-migrate . --apply\`.`;
 }
 
-function normalizeRelative(cwd: string, candidate: unknown): string | undefined {
-  if (typeof candidate !== "string" || candidate.trim().length === 0) return undefined;
-  let raw = candidate.trim();
-  try {
-    raw = decodeURIComponent(raw);
-  } catch {
-    return undefined;
-  }
-  if (/^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(raw)) {
-    if (!raw.toLowerCase().startsWith("file://")) return undefined;
-    try {
-      raw = fileURLToPath(raw);
-    } catch {
-      return undefined;
-    }
-  }
-  const absolute = path.isAbsolute(raw) ? raw : path.resolve(cwd, raw);
-  return path.relative(cwd, absolute).split(path.sep).join("/");
-}
-
 function slugify(input: string): string {
   return input
     .trim()
@@ -957,60 +948,6 @@ function inspectRepositoryPathBoundary(cwd: string, candidate: string): { reason
   return {};
 }
 
-function resolveRepositoryPathCandidate(cwd: string, candidate: string): string | undefined {
-  const normalized = normalizePathCandidate(candidate);
-  if (normalized === ".." || normalized.startsWith("../")) return undefined;
-
-  const relative = path.posix.isAbsolute(normalized)
-    ? path.relative(cwd, normalized).split(path.sep).join("/")
-    : normalized;
-  if (relative === ".." || relative.startsWith("../")) return undefined;
-
-  const pending = relative.split("/").filter((item) => item && item !== ".");
-  let current = cwd;
-  let resolvedDepth = 0;
-  for (let index = 0; index < pending.length; index += 1) {
-    const next = path.join(current, pending[index]);
-    try {
-      fs.lstatSync(next);
-      current = next;
-      resolvedDepth = index + 1;
-    } catch (error) {
-      const code = error && typeof error === "object" && "code" in error ? String((error as { code?: unknown }).code) : "";
-      if (code !== "ENOENT") return undefined;
-      break;
-    }
-  }
-
-  let canonicalBase: string;
-  try {
-    canonicalBase = fs.realpathSync.native(current);
-  } catch {
-    return undefined;
-  }
-  const canonical = path.resolve(canonicalBase, ...pending.slice(resolvedDepth));
-  const canonicalRoot = fs.realpathSync.native(cwd);
-  const canonicalRelative = path.relative(canonicalRoot, canonical).split(path.sep).join("/");
-  if (canonicalRelative === ".." || canonicalRelative.startsWith("../") || path.isAbsolute(canonicalRelative)) return undefined;
-  return canonicalRelative || ".";
-}
-
-function findResolvedProtectedPathInCommand(
-  cwd: string,
-  command: string,
-  protectedPatterns: string[]
-): { candidate: string; resolved: string; pattern: string } | undefined {
-  for (const candidate of extractShellPathCandidates(command)) {
-    const relative = normalizeRelative(cwd, candidate);
-    if (!relative) continue;
-    const resolved = resolveRepositoryPathCandidate(cwd, relative);
-    if (!resolved || resolved === relative) continue;
-    const pattern = matchesProtectedPath(resolved, protectedPatterns);
-    if (pattern) return { candidate, resolved, pattern };
-  }
-  return undefined;
-}
-
 const MAX_TOOL_INPUT_INSPECTION_DEPTH = 32;
 
 type StringInputWalkResult = {
@@ -1088,130 +1025,6 @@ function extractLikelyPathFromInput(cwd: string, input: Record<string, unknown>)
   return extractPathInputsFromInput(cwd, input)[0]?.path;
 }
 
-function expandSimpleGlobAlternatives(pattern: string, max = 24): { values: string[]; complete: boolean } {
-  let results = [pattern];
-  let changed = true;
-  let complete = true;
-
-  while (changed) {
-    changed = false;
-    const expanded: string[] = [];
-    for (const item of results) {
-      const match = item.match(/\{([^{}]+)\}/);
-      if (!match) {
-        expanded.push(item);
-        continue;
-      }
-      changed = true;
-      const options = match[1].split(",").map((option) => option.trim());
-      for (const option of options) {
-        expanded.push(`${item.slice(0, match.index)}${option}${item.slice((match.index ?? 0) + match[0].length)}`);
-        if (expanded.length >= max) {
-          complete = false;
-          break;
-        }
-      }
-      if (expanded.length >= max) break;
-    }
-    results = expanded.slice(0, max);
-  }
-
-  return { values: results, complete };
-}
-
-function shellGlobSegmentMatches(patternSegment: string, candidateSegment: string): boolean {
-  if (candidateSegment.startsWith(".") && !patternSegment.startsWith(".")) return false;
-  let source = "";
-  for (let index = 0; index < patternSegment.length; index += 1) {
-    const char = patternSegment[index];
-    if (char === "*") {
-      source += "[^/]*";
-      continue;
-    }
-    if (char === "?") {
-      source += "[^/]";
-      continue;
-    }
-    if (char === "[") {
-      const end = patternSegment.indexOf("]", index + 1);
-      const body = end > index + 1 ? patternSegment.slice(index + 1, end) : "";
-      if (body && /^[!^A-Za-z0-9_-]+$/.test(body)) {
-        const negated = body.startsWith("!") ? `^${body.slice(1)}` : body;
-        source += `[${negated}]`;
-        index = end;
-        continue;
-      }
-    }
-    source += char.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
-  }
-  return new RegExp(`^${source}$`, "i").test(candidateSegment);
-}
-
-function shellGlobMatchesPath(pattern: string, candidate: string): boolean {
-  const patternSegments = normalizePathCandidate(pattern).split("/").filter(Boolean);
-  const candidateSegments = normalizePathCandidate(candidate).split("/").filter(Boolean);
-
-  function match(patternIndex: number, candidateIndex: number): boolean {
-    if (patternIndex === patternSegments.length) return candidateIndex === candidateSegments.length;
-    const patternSegment = patternSegments[patternIndex];
-    if (patternSegment === "**") {
-      if (match(patternIndex + 1, candidateIndex)) return true;
-      for (let next = candidateIndex; next < candidateSegments.length; next += 1) {
-        if (match(patternIndex + 1, next + 1)) return true;
-      }
-      return false;
-    }
-    if (candidateIndex >= candidateSegments.length) return false;
-    return shellGlobSegmentMatches(patternSegment, candidateSegments[candidateIndex])
-      && match(patternIndex + 1, candidateIndex + 1);
-  }
-
-  return patternSegments.length > 0 && candidateSegments.length > 0 && match(0, 0);
-}
-
-function protectedPatternExamples(pattern: string): string[] {
-  const normalized = normalizePathCandidate(pattern);
-  if (!normalized) return [];
-
-  const examples = new Set<string>();
-  const add = (value: string | undefined) => {
-    const normalizedValue = normalizePathCandidate(value ?? "");
-    if (normalizedValue) examples.add(normalizedValue);
-  };
-
-  add(normalized);
-
-  if (normalized.endsWith("/**")) {
-    const base = normalized.slice(0, -3);
-    add(base);
-    add(`${base}/probe`);
-  }
-
-  if (normalized.startsWith("**/")) {
-    const tail = normalized.slice(3);
-    const concreteTail = tail
-      .replace(/\*\*/g, "nested")
-      .replace(/\*/g, tail.includes(".env.") ? "local" : "probe");
-    add(tail);
-    add(concreteTail);
-    add(`nested/${concreteTail}`);
-  }
-
-  const concrete = normalized
-    .replace(/^\*\*\//, "")
-    .replace(/\/\*\*$/, "/probe")
-    .replace(/\*\*/g, "nested")
-    .replace(/\*/g, normalized.includes(".env.") ? "local" : "probe");
-  add(concrete);
-
-  for (const example of [...examples]) {
-    const base = path.posix.basename(example);
-    if (base && base !== "probe") examples.add(base);
-  }
-
-  return [...examples];
-}
-
 function protectedLiteralHints(pattern: string): string[] {
   const normalized = normalizePathCandidate(pattern).toLowerCase();
   if (!normalized) return [];
@@ -1271,32 +1084,6 @@ function globTargetsProtectedPath(glob: unknown, protectedPatterns: string[]): {
   return undefined;
 }
 
-function shellGlobTargetsProtectedPath(
-  command: string,
-  protectedPatterns: string[]
-): { glob: string; pattern: string; example: string } | undefined {
-  for (const candidate of extractShellGlobCandidates(command)) {
-    if (!/[*?{\[]/.test(candidate)) continue;
-    const expanded = expandSimpleGlobAlternatives(candidate);
-    if (!expanded.complete) return { glob: candidate, pattern: "bounded glob expansion", example: "a protected path" };
-    for (const candidateGlob of expanded.values) {
-      for (const pattern of protectedPatterns) {
-        for (const example of protectedPatternExamples(pattern)) {
-          if (/[*?{\[\]]/.test(example)) continue;
-          if (
-            shellGlobMatchesPath(candidateGlob, example)
-            || shellGlobMatchesPath(`**/${candidateGlob}`, example)
-            || shellGlobMatchesPath(candidateGlob, path.posix.basename(example))
-          ) {
-            return { glob: candidate, pattern, example };
-          }
-        }
-      }
-    }
-  }
-  return undefined;
-}
-
 function isPlainRecord(value: unknown): value is Record<string, unknown> {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const prototype = Object.getPrototypeOf(value);
@@ -2550,13 +2337,6 @@ function evaluateMcpApproval(
 // running the substitution. Matching the literal half against the protected
 // patterns answers a different question than the one being asked, so refuse
 // rather than let an unknown filename through unchecked.
-function unresolvedExpansionReason(subject: string, words: string[]): string {
-  const listed = words.map((word) => `\`${word}\``).join(", ");
-  return `${subject} builds a filename this guard cannot resolve: ${listed}. `
-    + "The literal text around the expansion makes it a path, but its value is only known at run time, "
-    + "so it cannot be checked against the protected paths. Write the path out, or put the expansion in its own argument.";
-}
-
 function evaluateMcpProxyShellProtectedAccess(
   cwd: string,
   prepared: PreparedToolInput,
@@ -4829,7 +4609,10 @@ export default function piagentGuard(pi: ExtensionAPI) {
     if (!sessionTask && taskContractRequired && (shellProjectMutation || directProjectMutation)) {
       return {
         block: true,
-        reason: "A session-bound Task Implementation Contract is required before project files can be mutated. Start the task first."
+        // Naming the tool matters: this is the first wall a new operator hits,
+        // and "start the task first" does not say with what.
+        reason: "A session-bound Task Implementation Contract is required before project files can be mutated."
+          + " Call `piagent_task_start` once with explicit project-relative scope, then retry."
       };
     }
     if (sessionTask?.trace.outcome === "pending" && sessionTask.changeMode === "source-change") {

package/packages/piagent-core/extensions/runtime-evidence.js

@@ -58,11 +58,22 @@ function numericExitCode(value) {
   return undefined;
 }
 
+// `isError: false` is Pi stating that the command succeeded, so it is evidence
+// and a claim of zero matches it. An observation that states neither an exit code
+// nor an error flag says nothing at all, and nothing is not evidence of success:
+// without this an empty record satisfied a claim of zero, which is the one
+// direction a ledger built to catch forged verification must never fail in.
+//
+// Both shapes are unreachable through `observedBashResultFromToolResultEvent` and
+// `readObservedBashResults`, which always set a boolean flag. The guard is here
+// because a reader of this function should not have to prove that to know the
+// answer is safe.
 export function claimedExitMatchesObserved(exitCode, observed) {
   const claimed = numericExitCode(exitCode);
   if (claimed === undefined) return false;
   if (typeof observed?.exitCode === "number") return observed.exitCode === claimed;
-  return observed?.isError === true ? claimed !== 0 : claimed === 0;
+  if (typeof observed?.isError !== "boolean") return false;
+  return observed.isError ? claimed !== 0 : claimed === 0;
 }
 
 export function extractBashCommandFromToolResultEvent(event) {