@piagent/platform 1.5.5 → 1.6.1

package/packages/piagent-core/extensions/task-contract-view.js

@@ -1,4 +1,5 @@
 import { acceptanceReceiptProvenanceSummary, acceptanceReceiptSummary } from "./acceptance-receipt.js";
+import { isDurableContextEvidenceEntry } from "./context-evidence.js";
 import { runtimeLifecycleMode } from "./task-lifecycle.js";
 import { latestObservedVerificationEvidence, meaningfulVerificationCommands, verificationEvidenceProvesStableTree } from "./verification-intelligence.js";
 import { isCurrentWorkingTreeDigest, WORKING_TREE_DIGEST_ALGORITHM } from "./working-tree-digest.js";
@@ -25,6 +26,7 @@ export function compactTaskDetails(task) {
     sessionId: task.sessionId,
     sessionName: task.sessionName,
     changeMode: task.changeMode,
+    mutationPolicy: task.mutationPolicy ?? (task.changeMode === "read-only" ? "forbidden" : "required"),
     attempt: task.attempt,
     maxAttempts: task.maxAttempts,
     previousAttempts: task.previousAttempts,
@@ -51,12 +53,24 @@ export function compactTaskDetails(task) {
 }
 
 export function mergeObservedTaskContext(task, entries, maxManifestFiles, redact = (value) => String(value ?? "")) {
-  const known = new Set((task.contextManifest ?? []).map((item) => item.path));
+  const known = new Map((task.contextManifest ?? []).map((item, index) => [item.path, index]));
+  let durableCount = (task.contextManifest ?? []).filter(isDurableContextEvidenceEntry).length;
   const added = [];
   for (const entry of entries ?? []) {
-    if (task.contextManifest.length >= maxManifestFiles || known.has(entry.path)) continue;
+    const existingIndex = known.get(entry.path);
+    if (existingIndex !== undefined) {
+      const existing = task.contextManifest[existingIndex];
+      if (isDurableContextEvidenceEntry(existing) || !isDurableContextEvidenceEntry(entry)) continue;
+      if (durableCount >= maxManifestFiles) continue;
+      task.contextManifest[existingIndex] = { path: entry.path, reason: redact(entry.reason) };
+      durableCount += 1;
+      added.push(entry.path);
+      continue;
+    }
+    if (durableCount >= maxManifestFiles || !isDurableContextEvidenceEntry(entry)) continue;
     task.contextManifest.push({ path: entry.path, reason: redact(entry.reason) });
-    known.add(entry.path);
+    durableCount += 1;
+    known.set(entry.path, task.contextManifest.length - 1);
     added.push(entry.path);
   }
   return added;

package/packages/piagent-core/extensions/task-lifecycle.js

@@ -31,16 +31,20 @@ const ASSISTED_READ_ONLY_PLAN = [
   { id: "review", role: "piagent-reviewer", mode: "review", dependsOn: ["scout"] }
 ];
 
+function mutationForbidden(task) {
+  return task?.changeMode === "read-only" || task?.mutationPolicy === "forbidden";
+}
+
 export function runtimeLifecycleMode(task) {
   if (!Array.isArray(task?.workPlan)) return "manual";
   if (
-    task.changeMode === "read-only"
+    mutationForbidden(task)
     && (task.riskLane === "tiny" || (task.intakeMode === "runtime" && task.riskLane === "normal"))
     && task.workPlan.length === AUTOMATIC_READ_ONLY_PLAN.length
     && task.workPlan.every((step, index) => matchesStep(step, AUTOMATIC_READ_ONLY_PLAN[index]))
   ) return "automatic-readonly";
   if (
-    task.changeMode === "read-only"
+    mutationForbidden(task)
     && task.riskLane === "normal"
     && task.workPlan.length === ASSISTED_READ_ONLY_PLAN.length
     && task.workPlan.every((step, index) => matchesStep(step, ASSISTED_READ_ONLY_PLAN[index]))
@@ -68,6 +72,7 @@ function nonEmptyStrings(value) {
 function sourceContractReady(task) {
   return task?.schemaVersion === 2
     && task.changeMode === "source-change"
+    && task.mutationPolicy !== "forbidden"
     && task.trace?.outcome === "pending"
     && nonEmptyStrings(task.acceptanceCriteria)
     && nonEmptyStrings(task.scope)
@@ -190,3 +195,35 @@ export function applyRuntimeLifecycleObservation(task, observation, recordedAt =
   }
   return { changed, mode };
 }
+
+/**
+ * A default assisted read-only review is a presentation checkpoint, not a
+ * second reasoning pass. Once runtime-owned read evidence exists and the model
+ * emits its final handoff, completing this one exact checkpoint preserves the
+ * substantive answer instead of forcing a token-heavy retry. Custom/manual
+ * plans and every source-change review remain explicit.
+ */
+export function applyAssistedReadOnlyFinalHandoff(
+  task,
+  { durableReadEvidence = false, finalHandoffObserved = false } = {},
+  recordedAt = new Date().toISOString()
+) {
+  const mode = runtimeLifecycleMode(task);
+  if (mode !== "assisted-readonly" || !durableReadEvidence || !finalHandoffObserved) {
+    return { changed: false, mode };
+  }
+  const scout = task.workPlan.find((step) => step.id === "scout");
+  const review = task.workPlan.find((step) => step.id === "review");
+  if (scout?.status !== "done" || review?.status !== "in-progress") {
+    return { changed: false, mode };
+  }
+  return {
+    changed: setStep(
+      review,
+      "done",
+      "Runtime observed a final handoff grounded in durable read-only evidence.",
+      recordedAt
+    ),
+    mode
+  };
+}

package/packages/piagent-core/extensions/task-state.js

@@ -1,7 +1,6 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { execFileSync } from "node:child_process";
 import { ensurePrivateStateDirectory, resolveLocalStatePath } from "./local-state-path.js";
 import { appendTaskJournalEvent, readTaskJournal } from "./task-journal.js";
 import {
@@ -21,6 +20,7 @@ import {
 } from "./task-digest-state.js";
 export { taskDigestMigrationArchiveStatus } from "./task-digest-state.js";
 import { acceptanceReceiptWithoutWorkingTreeProof, normalizedTaskDigestFields, taskDigestContractValidationErrors } from "./task-digest-contract.js";
+import { unicodeCodePointLength } from "./verification-intelligence.js";
 import {
   WORKING_TREE_DIGEST_ALGORITHM,
   isCurrentWorkingTreeDigest,
@@ -28,13 +28,31 @@ import {
   unavailableWorkingTreeHash,
   versionWorkingTreeHash
 } from "./working-tree-digest.js";
+import {
+  directChildGitEvidenceRoots,
+  gitEvidenceRootDetails,
+  gitEvidenceRoots,
+  gitOutput,
+  isGitWorkingTree,
+  nonGitWorkspaceFileDetails,
+  nonGitWorkspaceFiles,
+  normalizedGitPath,
+  pathWithinNonGitWorkspaceEvidenceRoot,
+  prefixedGitPath
+} from "./workspace-evidence-roots.js";
+export { isGitWorkingTree } from "./workspace-evidence-roots.js";
 
 export const TASK_CONTRACT_SCHEMA_VERSION = 2; export const DEFAULT_MAX_TASK_ATTEMPTS = 3;
+export const OPERATOR_REQUEST_MAX_CHARS = 8_000;
+export const TASK_SUMMARY_MAX_CHARS = 2_000;
+export const TASK_EXPECTED_OUTPUT_MAX_CHARS = 2_000;
+export const TASK_ACCEPTANCE_CRITERION_MAX_CHARS = 1_000;
+export const TASK_ACCEPTANCE_CRITERIA_MAX = 12;
 const TASK_OUTCOMES = ["pending", "completed", "blocked", "partial", "failed"], TERMINAL_TASK_OUTCOMES = new Set(["completed", "blocked", "partial", "failed"]);
 const REVIEW_LENSES = ["correctness", "tests", "scope", "security", "docs", "release", "package"];
 const TASK_CONTRACT_FIELDS = new Set([
-  "schemaVersion", "taskRunId", "taskId", "sessionId", "sessionName", "changeMode", "attempt", "maxAttempts",
-  "previousAttempts", "summary", "riskLane", "intakeMode", "expectedOutput", "acceptanceCriteria", "criterionGraph", "scope", "outOfScope",
+  "schemaVersion", "taskRunId", "taskId", "sessionId", "sessionName", "changeMode", "mutationPolicy", "attempt", "maxAttempts",
+  "previousAttempts", "summary", "operatorRequest", "operatorRequestDigest", "riskLane", "intakeMode", "expectedOutput", "acceptanceCriteria", "criterionGraph", "scope", "outOfScope",
   "protectedPaths", "requiredContext", "contextManifest", "memoryCitations", "mcpCapabilities", "verifyGroup",
   "verifyCommands", "workPlan", "reviewLenses", "orchestration", "acceptanceReceipt", "authoritySnapshot", "workingTreeDigestAlgorithm", "workingTreeDigestMigration", "baselineChangedFiles", "baselineFileDigests",
   "observedChangedFiles", "finalWorkingTreeFiles", "finalFileDigests", "changedFiles", "verifyEvidence", "trace",
@@ -47,14 +65,6 @@ const ORCHESTRATION_FIELDS = new Set(["mode", "subagents", "reason", "fieldGuide
 const MODEL_ROLE_FIELDS = new Set(["planner", "worker", "reviewer", "watchdog"]);
 const VERIFY_EVIDENCE_FIELDS = new Set(["command", "exitCode", "summary", "recordedAt", "observed", "observedAt", "isError", "matchedProfileCommand", "preWorkingTreeDigest", "workingTreeDigest"]);
 const TRACE_FIELDS = new Set(["outcome", "friction", "notes", "recordedAt"]);
-const WORKSPACE_EVIDENCE_MAX_FILES = 2000;
-const WORKSPACE_EVIDENCE_SKIP_NAMES = new Set([
-  ".git", ".hg", ".svn", ".pi", "node_modules", "dist", "build", ".next", "coverage"
-]);
-const WORKSPACE_EVIDENCE_PRIORITY_NAMES = new Map([
-  ["plans", 0]
-]);
-
 export function safeTaskId(value) {
   const normalized = String(value ?? "")
     .trim()
@@ -132,6 +142,10 @@ function stringArray(value) {
   return Array.isArray(value) ? [...new Set(value.filter((item) => typeof item === "string" && item.trim()).map((item) => item.trim()))] : [];
 }
 
+function exactCommandArray(value) {
+  return Array.isArray(value) ? [...new Set(value.filter((item) => typeof item === "string" && item.trim()))] : [];
+}
+
 function stringRecord(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return {};
   return Object.fromEntries(Object.entries(value)
@@ -147,6 +161,10 @@ function validTimestamp(value) {
   return typeof value === "string" && value.trim().length > 0 && Number.isFinite(Date.parse(value));
 }
 
+export function operatorRequestDigest(value) {
+  return `operator-request-v1:${crypto.createHash("sha256").update(String(value ?? "")).digest("hex")}`;
+}
+
 function normalizedTimestamp(value, fallback) {
   return validTimestamp(value) ? value : fallback;
 }
@@ -187,6 +205,16 @@ export function taskContractValidationErrors(input) {
   if (typeof input.taskId === "string" && safeTaskId(input.taskId) !== input.taskId) errors.push("taskId must be normalized");
   if (typeof input.summary === "string" && input.summary.trim().length < 10) errors.push("summary must be at least 10 characters");
   if (typeof input.expectedOutput === "string" && input.expectedOutput.trim().length < 10) errors.push("expectedOutput must be at least 10 characters");
+  const hasOperatorRequest = input.operatorRequest !== undefined;
+  const hasOperatorRequestDigest = input.operatorRequestDigest !== undefined;
+  if (hasOperatorRequest !== hasOperatorRequestDigest) errors.push("operatorRequest and operatorRequestDigest must be present together");
+  if (hasOperatorRequest) {
+    if (typeof input.operatorRequest !== "string" || !input.operatorRequest.trim()) errors.push("operatorRequest must be a non-empty string");
+    else {
+      if (unicodeCodePointLength(input.operatorRequest) > OPERATOR_REQUEST_MAX_CHARS) errors.push(`operatorRequest must contain at most ${OPERATOR_REQUEST_MAX_CHARS} Unicode characters`);
+      if (input.operatorRequestDigest !== operatorRequestDigest(input.operatorRequest)) errors.push("operatorRequestDigest does not match operatorRequest");
+    }
+  }
   for (const field of ["createdAt", "updatedAt"]) {
     if (typeof input[field] === "string" && !validTimestamp(input[field])) errors.push(`${field} must be a valid timestamp`);
   }
@@ -198,6 +226,8 @@ export function taskContractValidationErrors(input) {
   }
   if (input.failedAt !== undefined && !["research", "plan", "execute", "verify", "review"].includes(input.failedAt)) errors.push("failedAt is invalid");
   if (!["source-change", "read-only"].includes(input.changeMode)) errors.push("changeMode is invalid");
+  if (input.mutationPolicy !== undefined && !["required", "forbidden"].includes(input.mutationPolicy)) errors.push("mutationPolicy is invalid");
+  if (input.changeMode === "read-only" && input.mutationPolicy === "required") errors.push("read-only tasks cannot require mutation");
   if (!["tiny", "normal", "high-risk"].includes(input.riskLane)) errors.push("riskLane is invalid");
   if (input.intakeMode !== undefined && !["model", "runtime"].includes(input.intakeMode)) errors.push("intakeMode is invalid");
   errors.push(...taskDigestContractValidationErrors(input));
@@ -227,6 +257,7 @@ export function taskContractValidationErrors(input) {
   }
   if (Array.isArray(input.acceptanceCriteria) && input.acceptanceCriteria.length === 0) errors.push("acceptanceCriteria must not be empty");
   if (Array.isArray(input.scope) && input.scope.length === 0) errors.push("scope must not be empty");
+  if (Array.isArray(input.scope) && input.scope.length > 2000) errors.push("scope must contain at most 2000 entries");
   if (Array.isArray(input.previousAttempts) && input.previousAttempts.length > 10) errors.push("previousAttempts must contain at most 10 entries");
   if (Array.isArray(input.workPlan) && input.workPlan.length > 12) errors.push("workPlan must contain at most 12 entries");
   if (Array.isArray(input.reviewLenses)) {
@@ -390,10 +421,13 @@ export function normalizeTaskContract(input, options = {}) {
     sessionId,
     sessionName: String(input.sessionName ?? options.sessionName ?? "").trim() || undefined,
     changeMode: input.changeMode === "read-only" ? "read-only" : "source-change",
+    mutationPolicy: input.changeMode === "read-only" || input.mutationPolicy === "forbidden" ? "forbidden" : "required",
     attempt: positiveInteger(input.attempt, 1, 100),
     maxAttempts: positiveInteger(input.maxAttempts, DEFAULT_MAX_TASK_ATTEMPTS, 10),
     previousAttempts: Array.isArray(input.previousAttempts) ? input.previousAttempts.slice(-10).map((item) => pickFields(item, PREVIOUS_ATTEMPT_FIELDS)) : [],
     summary: typeof input.summary === "string" ? input.summary : "",
+    operatorRequest: typeof input.operatorRequest === "string" && input.operatorRequest.trim() ? input.operatorRequest : undefined,
+    operatorRequestDigest: typeof input.operatorRequestDigest === "string" && input.operatorRequestDigest.trim() ? input.operatorRequestDigest : undefined,
     riskLane: ["tiny", "normal", "high-risk"].includes(input.riskLane) ? input.riskLane : "normal",
     intakeMode: ["model", "runtime"].includes(input.intakeMode) ? input.intakeMode : "model",
     expectedOutput: typeof input.expectedOutput === "string" ? input.expectedOutput : "", acceptanceCriteria: stringArray(input.acceptanceCriteria),
@@ -405,7 +439,7 @@ export function normalizeTaskContract(input, options = {}) {
     memoryCitations: Array.isArray(input.memoryCitations) ? input.memoryCitations.map((item) => pickFields(item, CITATION_FIELDS)) : [],
     mcpCapabilities: stringArray(input.mcpCapabilities),
     verifyGroup: typeof input.verifyGroup === "string" && input.verifyGroup.trim() ? input.verifyGroup.trim() : undefined,
-    verifyCommands: stringArray(input.verifyCommands),
+    verifyCommands: exactCommandArray(input.verifyCommands),
     workPlan: Array.isArray(input.workPlan) ? input.workPlan.map((item) => pickFields(item, WORK_PLAN_FIELDS)) : [],
     reviewLenses: stringArray(input.reviewLenses),
     acceptanceReceipt: normalizeAcceptanceReceipt(legacyDigestContract
@@ -576,13 +610,6 @@ export function summarizeAttempt(task) {
   };
 }
 
-function gitOutput(cwd, args, options = {}) {
-  return execFileSync("git", ["-C", cwd, ...args], {
-    encoding: options.encoding ?? "utf8",
-    maxBuffer: options.maxBuffer ?? 16 * 1024 * 1024,
-    stdio: ["ignore", "pipe", "ignore"]
-  });
-}
 function gitHasHead(cwd) {
   try {
     gitOutput(cwd, ["rev-parse", "--verify", "HEAD"]);
@@ -591,20 +618,6 @@ function gitHasHead(cwd) {
     return false;
   }
 }
-export function isGitWorkingTree(cwd) {
-  try {
-    return gitOutput(cwd, ["rev-parse", "--is-inside-work-tree"]).trim() === "true";
-  } catch {
-    return false;
-  }
-}
-function normalizedGitPath(value) {
-  return String(value ?? "").replaceAll("\\", "/").replace(/^\/+/, "");
-}
-function prefixedGitPath(prefix, file) {
-  const normalized = normalizedGitPath(file);
-  return prefix ? `${prefix}/${normalized}` : normalized;
-}
 
 function workingTreeFilesForGitRoot(cwd, observeRename) {
   if (!isGitWorkingTree(cwd)) return [];
@@ -615,90 +628,8 @@ function workingTreeFilesForGitRoot(cwd, observeRename) {
   return [...new Set([...changed, ...untracked].map(normalizedGitPath).filter((item) => item && !item.startsWith(".pi/piagent-state/")))].sort();
 }
 
-function directChildGitEvidenceRoots(cwd) {
-  const roots = [];
-  let entries;
-  try {
-    entries = fs.readdirSync(cwd, { withFileTypes: true });
-  } catch {
-    return roots;
-  }
-  for (const entry of entries) {
-    if (!entry.isDirectory() || entry.name.startsWith(".") || entry.name === "node_modules") continue;
-    const child = path.join(cwd, entry.name);
-    try {
-      if (fs.lstatSync(child).isSymbolicLink()) continue;
-      if (!isGitWorkingTree(child)) continue;
-      const topLevel = gitOutput(child, ["rev-parse", "--show-toplevel"]).trim();
-      if (fs.realpathSync(topLevel) !== fs.realpathSync(child)) continue;
-      roots.push({ cwd: child, prefix: normalizedGitPath(entry.name) });
-    } catch {
-      // Ignore unreadable or non-standard child folders; source-change start
-      // only needs at least one reliable evidence root.
-    }
-  }
-  return roots.sort((left, right) => left.prefix.localeCompare(right.prefix));
-}
-
-function gitEvidenceRoots(cwd) {
-  if (isGitWorkingTree(cwd)) return [{ cwd, prefix: "" }];
-  return directChildGitEvidenceRoots(cwd);
-}
-
-function nonGitWorkspaceFiles(cwd, gitRootPrefixes) {
-  const files = [];
-  const gitRoots = new Set(gitRootPrefixes.filter(Boolean));
-  function orderedEntries(entries) {
-    return [...entries].sort((left, right) => {
-      const leftPriority = WORKSPACE_EVIDENCE_PRIORITY_NAMES.get(left.name.toLowerCase()) ?? 10;
-      const rightPriority = WORKSPACE_EVIDENCE_PRIORITY_NAMES.get(right.name.toLowerCase()) ?? 10;
-      if (leftPriority !== rightPriority) return leftPriority - rightPriority;
-      return left.name.localeCompare(right.name, "en-US");
-    });
-  }
-  function visit(directory, relativeDirectory) {
-    if (files.length >= WORKSPACE_EVIDENCE_MAX_FILES) return;
-    let entries;
-    try {
-      entries = fs.readdirSync(directory, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const entry of orderedEntries(entries)) {
-      if (files.length >= WORKSPACE_EVIDENCE_MAX_FILES) return;
-      if (WORKSPACE_EVIDENCE_SKIP_NAMES.has(entry.name)) continue;
-      const relative = relativeDirectory ? `${relativeDirectory}/${entry.name}` : entry.name;
-      const topSegment = relative.split("/")[0];
-      if (gitRoots.has(topSegment)) continue;
-      const absolute = path.join(directory, entry.name);
-      try {
-        if (fs.lstatSync(absolute).isSymbolicLink()) continue;
-      } catch {
-        continue;
-      }
-      if (entry.isDirectory()) {
-        visit(absolute, relative);
-      } else if (entry.isFile()) {
-        files.push(normalizedGitPath(relative));
-      }
-    }
-  }
-  visit(cwd, "");
-  return files.sort();
-}
-
 function nonGitWorkspaceFileDigest(cwd, file, protectedProjectPath = null) { return streamedWorkingTreeFileDigest(cwd, file, false, protectedProjectPath); }
 
-function pathWithinNonGitWorkspaceEvidenceRoot(candidate, gitRootPrefixes) {
-  const topSegment = candidate.split("/")[0];
-  return Boolean(
-    topSegment
-    && !WORKSPACE_EVIDENCE_SKIP_NAMES.has(topSegment)
-    && !topSegment.startsWith(".")
-    && !gitRootPrefixes.includes(topSegment)
-  );
-}
-
 export function hasGitEvidenceRoot(cwd) {
   return gitEvidenceRoots(cwd).length > 0;
 }
@@ -739,35 +670,36 @@ export function workingTreeFiles(cwd) {
     return [];
   }
 }
-
-export function repositoryFileManifest(cwd, maxFiles = 10_000) {
-  const limit = Number.isInteger(maxFiles) ? Math.max(1, Math.min(50_000, maxFiles)) : 10_000;
-  const files = [];
+export function repositoryFileManifestDetails(cwd, maxFiles = 10_000) {
+  const limit = Number.isInteger(maxFiles) ? Math.max(1, Math.min(50_000, maxFiles)) : 10_000, files = new Set();
   try {
-    for (const root of gitEvidenceRoots(cwd)) {
-      const listed = gitOutput(root.cwd, ["ls-files", "--cached", "--others", "--exclude-standard", "-z"])
-        .split("\0")
-        .filter(Boolean);
+    const rootDetails = gitEvidenceRootDetails(cwd), roots = rootDetails.roots;
+    const add = (candidate) => {
+      if (!candidate || candidate.startsWith(".pi/") || candidate.startsWith(".git/") || candidate.split("/").includes("node_modules")
+        || /(?:^|\/)\.env(?:\.|$)/i.test(candidate) || /(?:^|\/)(?:auth|credentials?|secrets?|tokens?)\.json$/i.test(candidate)) return true;
+      files.add(candidate);
+      return files.size <= limit;
+    };
+    for (const root of roots) {
+      const listed = gitOutput(root.cwd, ["ls-files", "--cached", "--others", "--exclude-standard", "-z"]).split("\0").filter(Boolean);
       for (const file of listed) {
         const candidate = prefixedGitPath(root.prefix, file);
-        if (
-          !candidate
-          || candidate.startsWith(".pi/")
-          || candidate.startsWith(".git/")
-          || candidate.split("/").includes("node_modules")
-          || /(?:^|\/)\.env(?:\.|$)/i.test(candidate)
-          || /(?:^|\/)(?:auth|credentials?|secrets?|tokens?)\.json$/i.test(candidate)
-        ) continue;
-        files.push(candidate);
-        if (files.length >= limit) return [...new Set(files)].sort();
+        if (!add(candidate)) return { files: [...files].slice(0, limit).sort(), complete: false, candidateCount: files.size };
       }
     }
+    if (!isGitWorkingTree(cwd) && roots.length > 0) {
+      const looseDetails = nonGitWorkspaceFileDetails(cwd, roots.map((root) => root.prefix));
+      const looseFiles = looseDetails.files;
+      for (const file of looseFiles) if (!add(file)) return { files: [...files].slice(0, limit).sort(), complete: false, candidateCount: files.size };
+      if (!looseDetails.complete) return { files: [...files].sort(), complete: false, candidateCount: files.size };
+    }
+    if (!rootDetails.complete) return { files: [...files].sort(), complete: false, candidateCount: files.size };
   } catch {
-    return [];
+    return { files: [], complete: false, candidateCount: 0 };
   }
-  return [...new Set(files)].sort();
+  return { files: [...files].sort(), complete: true, candidateCount: files.size };
 }
-
+export function repositoryFileManifest(cwd, maxFiles = 10_000) { return repositoryFileManifestDetails(cwd, maxFiles).files; }
 function changedPathsFromNameStatus(output, observeRename) {
   const fields = String(output ?? "").split("\0").filter(Boolean);
   const files = [];
@@ -785,6 +717,10 @@ function changedPathsFromNameStatus(output, observeRename) {
 }
 
 const WORKING_TREE_STREAM_CHUNK_BYTES = 1024 * 1024;
+// This path cannot collide with enumerated project evidence because `.pi` is
+// intentionally excluded from workspace discovery. Its unavailable digest
+// turns a partial inventory into an explicitly non-proof-capable snapshot.
+const WORKING_TREE_ENUMERATION_EVIDENCE_PATH = ".pi/piagent-state/.working-tree-enumeration-unavailable";
 function unavailableWorkingTreeDigest(file, reason, stat) {
   return unavailableWorkingTreeHash(crypto.createHash("sha256")
     .update(`${file}\0${reason}\0${stat?.mode ?? ""}\0${stat?.size ?? ""}\0${stat?.mtimeMs ?? ""}\0${stat?.ctimeMs ?? ""}`)
@@ -864,7 +800,18 @@ function streamedWorkingTreeFileDigest(root, file, hasHead, protectedProjectPath
 export function workingTreeSnapshot(cwd, options = {}) {
   const snapshot = {};
   const isProtectedProjectPath = typeof options.isProtectedProjectPath === "function" ? options.isProtectedProjectPath : () => false;
-  const roots = gitEvidenceRoots(cwd);
+  let rootDetails;
+  try {
+    rootDetails = gitEvidenceRootDetails(cwd);
+  } catch (error) {
+    snapshot[WORKING_TREE_ENUMERATION_EVIDENCE_PATH] = unavailableWorkingTreeDigest(
+      WORKING_TREE_ENUMERATION_EVIDENCE_PATH,
+      `root-enumeration:${error?.code ?? "failed"}`
+    );
+    return snapshot;
+  }
+  const roots = rootDetails.roots;
+  const incompleteReasons = rootDetails.complete ? [] : ["root-enumeration-incomplete"];
   for (const root of roots) {
     const protectedAliases = new Set();
     const observeRename = (source, destination) => {
@@ -872,13 +819,33 @@ export function workingTreeSnapshot(cwd, options = {}) {
       if (paths.some((file) => file === ".pi/piagent-state" || file.startsWith(".pi/piagent-state/") || isProtectedProjectPath(prefixedGitPath(root.prefix, file))))
         paths.forEach((file) => protectedAliases.add(file));
     };
-    const hasHead = gitHasHead(root.cwd); for (const file of workingTreeFilesForGitRoot(root.cwd, observeRename)) {
-      const projectPath = prefixedGitPath(root.prefix, file);
-      snapshot[projectPath] = streamedWorkingTreeFileDigest(root.cwd, file, hasHead, isProtectedProjectPath(projectPath) || protectedAliases.has(file) ? projectPath : null);
+    try {
+      const hasHead = gitHasHead(root.cwd); for (const file of workingTreeFilesForGitRoot(root.cwd, observeRename)) {
+        const projectPath = prefixedGitPath(root.prefix, file);
+        snapshot[projectPath] = streamedWorkingTreeFileDigest(root.cwd, file, hasHead, isProtectedProjectPath(projectPath) || protectedAliases.has(file) ? projectPath : null);
+      }
+    } catch {
+      incompleteReasons.push(`git-root-enumeration-incomplete:${root.prefix || "."}`);
     }
-  } if (!isGitWorkingTree(cwd) && roots.length > 0) for (const file of nonGitWorkspaceFiles(cwd, roots.map((root) => root.prefix))) {
+  }
+  if (!roots.some((root) => root.prefix === "") && roots.length > 0) {
+    const looseDetails = nonGitWorkspaceFileDetails(
+      cwd,
+      roots.map((root) => root.prefix),
+      options.maxNonGitWorkspaceFiles
+    );
+    for (const file of looseDetails.files) {
       snapshot[file] = nonGitWorkspaceFileDigest(cwd, file, isProtectedProjectPath(file) ? file : null);
-  } return snapshot;
+    }
+    if (!looseDetails.complete) incompleteReasons.push("non-git-enumeration-incomplete");
+  }
+  if (incompleteReasons.length > 0) {
+    snapshot[WORKING_TREE_ENUMERATION_EVIDENCE_PATH] = unavailableWorkingTreeDigest(
+      WORKING_TREE_ENUMERATION_EVIDENCE_PATH,
+      incompleteReasons.sort().join(",")
+    );
+  }
+  return snapshot;
 }
 
 export function taskStateMigrationStatus(cwd) {

package/packages/piagent-core/extensions/verification-intelligence.js

@@ -13,8 +13,22 @@ import {
 } from "./failure-types.ts";
 import { isCurrentWorkingTreeDigest } from "./working-tree-digest.js";
 
+export const MAX_VERIFY_COMMANDS = 2;
+export const MAX_VERIFY_COMMAND_CHARS = 900;
+export const MAX_VERIFY_COMMAND_BYTES = 900;
+export const MAX_VERIFY_COMMAND_TOTAL_BYTES = MAX_VERIFY_COMMANDS * MAX_VERIFY_COMMAND_BYTES;
+export const MAX_VERIFY_COMMAND_TOTAL_CHARS = MAX_VERIFY_COMMANDS * MAX_VERIFY_COMMAND_CHARS;
+
+export function unicodeCodePointLength(value) {
+  return Array.from(String(value ?? "")).length;
+}
+
+export function utf8ByteLength(value) {
+  return Buffer.byteLength(String(value ?? ""), "utf8");
+}
+
 function uniqueStrings(values) {
-  return [...new Set((Array.isArray(values) ? values : []).filter((value) => typeof value === "string" && value.trim()).map((value) => value.trim()))];
+  return [...new Set((Array.isArray(values) ? values : []).filter((value) => typeof value === "string" && value.trim()))];
 }
 
 export function meaningfulVerificationCommands(commands = []) {
@@ -27,6 +41,25 @@ export function meaningfulVerificationCommands(commands = []) {
   });
 }
 
+export function verifierCommandBoundsError(commands = []) {
+  const supplied = (Array.isArray(commands) ? commands : []).filter((command) => typeof command === "string");
+  if (supplied.some((command) => /[\r\n]/.test(command))) {
+    return "Exact verify commands must be single-line values without CR or LF characters; move multiline logic into a checked-in script before task intake.";
+  }
+  const normalized = uniqueStrings(supplied);
+  if (normalized.length > MAX_VERIFY_COMMANDS) {
+    return `Verify plans support at most ${MAX_VERIFY_COMMANDS} exact commands; consolidate or shorten the project verifier before task intake.`;
+  }
+  const oversized = normalized.find((command) => unicodeCodePointLength(command) > MAX_VERIFY_COMMAND_CHARS);
+  if (oversized) return `An exact verify command exceeds ${MAX_VERIFY_COMMAND_CHARS} characters; shorten it or move verifier logic into a checked-in script before task intake.`;
+  const oversizedTraffic = normalized.find((command) => utf8ByteLength(command) > MAX_VERIFY_COMMAND_BYTES);
+  if (oversizedTraffic) return `An exact verify command exceeds ${MAX_VERIFY_COMMAND_BYTES} UTF-8 bytes; shorten it or move verifier logic into a checked-in script before task intake.`;
+  if (normalized.reduce((total, command) => total + utf8ByteLength(command), 0) > MAX_VERIFY_COMMAND_TOTAL_BYTES) {
+    return `Exact verify commands exceed the ${MAX_VERIFY_COMMAND_TOTAL_BYTES}-byte aggregate limit; consolidate or shorten the project verifier before task intake.`;
+  }
+  return undefined;
+}
+
 /** Return the last durably recorded observed execution for each exact command. */
 export function latestObservedVerificationEvidence(evidence = []) {
   const latest = new Map();
@@ -100,7 +133,10 @@ function parsedSignals(text, exitCode, structuredEvents) {
   const lower = text.toLowerCase();
   const signals = structuredEvents.map((event) => STRUCTURED_SIGNALS[event]).filter(Boolean);
   const add = (signal, pattern) => { if (pattern.test(lower)) signals.push(signal); };
-  add("scope-diagnostic", /\b(outside (?:its |the )?declared scope|scope violation|protected path|symlink escape)\b/);
+  // Task scope is advisory. Only concrete filesystem-safety wording may be
+  // inferred from unstructured output; scope policy must arrive as a trusted
+  // structured event so ordinary assertion text cannot stop recovery.
+  add("scope-diagnostic", /\b(protected path|symlink escape)\b/);
   add("policy-diagnostic", /\b(policy (?:blocked|denied|violation)|capability lock|guard blocked)\b/);
   add("permission-diagnostic", /\b(eacces|eperm|permission denied|not authorized|unauthorized|forbidden)\b/);
   add("provider-rate-limit", /\b(?:http\s*)?429\b|\brate[ -]?limit(?:ed|ing)?\b/);
@@ -191,7 +227,7 @@ const RECORDED_CATEGORY_HINTS = Object.freeze({
   environment: "command not found in runtime environment",
   "provider-network": "provider API request timed out",
   "permission-policy": "permission denied by policy",
-  "scope-protected-path": "outside declared scope",
+  "scope-protected-path": "protected path is forbidden",
   "flaky-infrastructure": "EADDRINUSE: port is already in use"
 });
 
@@ -202,16 +238,15 @@ export function classifyRecordedVerificationFailure(summary, exitCode = 1) {
   return classifyVerificationFailure(hint ? `${text}\n${hint}` : text, exitCode);
 }
 
-const COMPLETION_SCOPE_BOUNDARY = /(?:^changes within task scope\b|^read-only task has observed changes\b|\boutside (?:(?:its|the|task) )?(?:declared )?scope\b|\bscope violation\b|\bprotected(?:\/read-only| or read-only)? paths?\b|\bread-only path\b)/i;
+const COMPLETION_POLICY_BOUNDARY = /(?:^read-only task has observed changes\b|^mutation-forbidden task has observed changes\b|\bprotected(?:\/read-only| or read-only)? paths?\b|\bread-only path\b)/i;
 
 export function classifyCompletionGateFailure(missing = [], summary = "", exitCode = 1) {
   const missingItems = Array.isArray(missing) ? missing.map((item) => String(item)) : [];
-  // Scope, protected-path, and read-only mutation boundaries are structural
-  // completion failures. They must outrank verifier/acceptance diagnostics and
-  // remain non-retryable even when the latest exact verifier exited zero.
-  if (missingItems.some((item) => COMPLETION_SCOPE_BOUNDARY.test(item))) {
-    return classifyVerificationFailure("Completion gate rejected a scope or protected-path boundary.", 1, {
-      structuredEvents: ["scope-violation"]
+  // Protected-path and read-only mutation boundaries are structural
+  // completion failures. Task scope is advisory and never enters this path.
+  if (missingItems.some((item) => COMPLETION_POLICY_BOUNDARY.test(item))) {
+    return classifyVerificationFailure("Completion gate rejected a protected-path or read-only boundary.", 1, {
+      structuredEvents: ["protected-path"]
     });
   }
   if (missingItems.some((item) => /^critical acceptance evidence\b/i.test(item))) {
@@ -235,8 +270,8 @@ export function chooseVerificationScope(profileVerifyCommands = {}, changedFiles
     || /^(?:README|CHANGELOG|CONTRIBUTING|SECURITY)(?:\.|$)/i.test(file);
   const hasDocs = files.some(isDocumentationFile);
   const hasDocsOnly = files.length > 0 && files.every(isDocumentationFile);
-  const hasFrontend = files.some((file) => /(^|\/)(?:app|pages|components|frontend|web|client)(\/|$)|\.(?:tsx|jsx|css|scss|vue|svelte)$/i.test(file));
-  const hasBackend = files.some((file) => /(^|\/)(?:api|server|backend|services)(\/|$)|\.(?:go|py|rs|java|kt|cs|rb|php|sql)$/i.test(file));
+  const hasFrontend = files.some((file) => /(^|[\/_-])(?:app|pages|components|frontend|web|client)(?=[\/_-]|$)|\.(?:tsx|jsx|css|scss|vue|svelte)$/i.test(file));
+  const hasBackend = files.some((file) => /(^|[\/_-])(?:api|server|backend|services)(?=[\/_-]|$)|\.(?:go|py|rs|java|kt|cs|rb|php|sql)$/i.test(file));
   const selectedGroups = [];
   if (hasDocsOnly && groups.docs) {
     selectedGroups.push("docs");
@@ -295,7 +330,9 @@ export function selectVerificationPlan(profile, requestedGroup, changeMode, cwd,
         const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
         const scripts = manifest.scripts && typeof manifest.scripts === "object" ? manifest.scripts : {};
         const selected = ["type-check", "typecheck", "lint", "test"].filter((name) => typeof scripts[name] === "string");
-        if (selected.length > 0) commands = selected.map((name) => name === "test" ? "npm test" : `npm run ${name}`);
+        if (selected.length > 0) {
+          commands = [selected.map((name) => name === "test" ? "npm test" : `npm run ${name}`).join(" && ")];
+        }
       }
     } catch {
       // Preserve the profile's fail-closed verifier when package metadata is absent or invalid.
@@ -308,5 +345,7 @@ export function selectVerificationPlan(profile, requestedGroup, changeMode, cwd,
       error: `Verify group ${group ?? "(none)"} has no meaningful command. Configure .pi/piagent-profile.json before source changes.`
     };
   }
+  const boundsError = verifierCommandBoundsError(commands);
+  if (boundsError) return { group, commands, error: boundsError };
   return { group, commands };
 }