@piagent/platform 1.6.0 → 1.6.1

package/packages/piagent-core/runtime/registration/knowledge-tools.ts

@@ -11,11 +11,11 @@ export function registerKnowledgeTools(pi: ExtensionAPI, deps: Record<string, an
   registerPiagentTool(pi, {
     name: "piagent_orchestration_policy",
     label: "Piagent Orchestration Policy",
-    description: "Return solo-first subagent, review lens, model-role, and Field Guide policy for the current project.",
-    promptSnippet: "Use this before planning medium/large tasks so orchestration stays single-agent-first and token-aware.",
+    description: "Return parent-direct helper limits, review lenses, model-role, and Field Guide policy for the current project.",
+    promptSnippet: "Use this before planning medium/large tasks so the parent stays direct and helper use remains a measured token optimization.",
     promptGuidelines: [
-      "Default to the parent agent plus bounded subagents only when they reduce context risk or improve review quality.",
-      "Use review lenses instead of spawning a broad swarm.",
+      "Default to the parent model working directly; review quality alone does not justify another model run.",
+      "Use at most one fresh read-only helper only with two independent lanes and at least 30% projected total token savings; never delegate implementation or retry a deterministic failure.",
       "Treat Field Guide memory as advisory and verify it against current repository files."
     ],
     parameters: Type.Object({
@@ -45,7 +45,9 @@ export function registerKnowledgeTools(pi: ExtensionAPI, deps: Record<string, an
           path: fieldGuidePath,
           exists: fieldGuideExists
         },
-        stance: "single-agent-first; subagents are opt-in tools for bounded scout, planning, and review"
+        helperBudget: "1-readonly-total/0-retries/0-writers",
+        minimumProjectedNetSaving: 0.3,
+        stance: "parent-direct; one fresh read-only helper only when runtime-measured net token savings justify it"
       };
       const text = params.detail === "full"
         ? JSON.stringify(payload, null, 2)
@@ -53,6 +55,8 @@ export function registerKnowledgeTools(pi: ExtensionAPI, deps: Record<string, an
           `mode: ${payload.defaultMode}`,
           `maxConcurrentSubagents: ${payload.maxConcurrentSubagents}`,
           `helpersMode: ${payload.helpersMode}`,
+          `helperBudget: ${payload.helperBudget}`,
+          `minimumProjectedNetSaving: ${Math.round(payload.minimumProjectedNetSaving * 100)}%`,
           `reviewLenses: ${payload.defaultReviewLenses.join(", ")}`,
           `fieldGuide: ${payload.fieldGuide.enabled ? `${payload.fieldGuide.path} (${payload.fieldGuide.exists ? "exists" : "missing"})` : "off"}`,
           `fieldGuidePolicy: ${payload.fieldGuide.writePolicy}, maxLines=${payload.fieldGuide.maxLines}`,

package/packages/piagent-core/runtime/registration/operator-request-intake.ts

@@ -0,0 +1,49 @@
+import { OPERATOR_REQUEST_MAX_CHARS } from "../../extensions/task-state.js";
+
+type SessionContext = {
+  sessionManager: {
+    getBranch?: () => unknown;
+    getEntries?: () => unknown;
+  };
+};
+
+function userMessageText(message: unknown): string {
+  if (!message || typeof message !== "object" || (message as Record<string, unknown>).role !== "user") return "";
+  const content = (message as Record<string, unknown>).content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  // The host stores the exact operator prose in the first text block. Later
+  // text blocks may contain extracted attachment bodies and must not be copied
+  // into private task truth as if the operator typed them.
+  const first = content.find((block) => block && typeof block === "object"
+    && (block as Record<string, unknown>).type === "text"
+    && typeof (block as Record<string, unknown>).text === "string") as Record<string, unknown> | undefined;
+  return typeof first?.text === "string" ? first.text : "";
+}
+
+export function latestOperatorRequest(ctx: SessionContext): string | undefined {
+  let entries: unknown[] = [];
+  try {
+    const branch = ctx.sessionManager.getBranch?.();
+    entries = Array.isArray(branch) ? branch : [];
+    if (entries.length === 0) {
+      const all = ctx.sessionManager.getEntries?.();
+      entries = Array.isArray(all) ? all : [];
+    }
+  } catch {
+    return undefined;
+  }
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const entry = entries[index] as Record<string, any> | undefined;
+    if (entry?.type !== "message") continue;
+    const text = userMessageText(entry.message);
+    if (text.trim()) return text;
+  }
+  return undefined;
+}
+
+export function boundedOperatorRequest(value: unknown, redactText: (value: string) => string): string | undefined {
+  if (typeof value !== "string" || !value.trim()) return undefined;
+  const redacted = redactText(value);
+  return Array.from(redacted).length <= OPERATOR_REQUEST_MAX_CHARS ? redacted : undefined;
+}

package/packages/piagent-core/runtime/registration/policy-tools.ts

@@ -30,7 +30,7 @@ export function registerPolicyTools(pi: ExtensionAPI, deps: Record<string, any>)
       "When recovery is necessary, load only the smallest group that resolves the reported missing evidence."
     ],
     parameters: Type.Object({
-      groups: Type.Array(StringEnum(["intake", "governance", "task", "recovery", "policy", "retrieval", "knowledge", "onboarding", "usage"] as const), { minItems: 1 })
+      groups: Type.Array(StringEnum(["intake", "governance", "task", "recovery", "policy", "retrieval", "source", "knowledge", "onboarding", "usage"] as const), { minItems: 1 })
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const groups = [...new Set(params.groups)] as PiagentToolGroup[];
@@ -429,8 +429,8 @@ export function registerPolicyTools(pi: ExtensionAPI, deps: Record<string, any>)
   registerPiagentTool(pi, {
     name: "piagent_task_gate_check",
     label: "Piagent Task Gate Check",
-    description: "Check whether a governed task has enough context, verify evidence, and trace before claiming done.",
-    promptSnippet: "Use this before final on source-changing tasks.",
+    description: "Check whether a governed task has enough context, current-tree exact verifier evidence, and trace before claiming done or rerunning verification.",
+    promptSnippet: "Use before final and before repeating an exact verifier; run only commands listed as missing for the current tree.",
     parameters: Type.Object({
       taskId: Type.String({ minLength: 1 }),
       changedFiles: Type.Optional(Type.Array(Type.String()))
@@ -451,7 +451,7 @@ export function registerPolicyTools(pi: ExtensionAPI, deps: Record<string, any>)
         ...verifierCommandInstructions(result.missingVerifyCommands),
         `warnings: ${result.warnings.join("; ") || "none"}`
       ].join("\n");
-      return { content: [{ type: "text", text }], details: { ...result, task: projected } };
+      return { content: [{ type: "text", text }], details: { ...result, task: projected ? { taskId: projected.taskId, taskRunId: projected.taskRunId } : undefined } };
     }
   });
 

package/packages/piagent-core/runtime/registration/session-commands.ts

@@ -334,7 +334,7 @@ export function registerSessionCommands(pi: ExtensionAPI, deps: Record<string, a
       const approvals = feature ? [feature.externalAction ? "external-action" : "", feature.destructiveAction ? "destructive-action" : "", feature.permissionExpansion ? "permission-expansion" : ""].filter(Boolean) : [];
       const modelRoute = feature ? await evaluateModelRoute?.(ctx, feature, snapshot) : undefined;
       const retrievalRoute = feature ? await evaluateRetrievalRoute?.(ctx, feature) : undefined;
-      return { runtime: snapshot, modelRoute: modelRoute?.status === "ok" ? modelRoute.decision : null, retrievalRoute: retrievalRoute ?? null, scope: task?.scope ?? [], protectedPaths: effectiveProtectedPaths(policy, profile).readProtectedPaths, activeToolGroups: pi.getActiveTools(), helperMode: helpersMode(), helperBudget: "2-concurrent/3-total", executionBackend: "host", executionBoundary: "host execution is not a sandbox", approvals, blockers: feature?.protectedTarget ? ["protected-target"] : [], controlMode: evaluation.status === "ok" && evaluation.decision.mode === "shadow" ? "shadow" : resolveRuntimePolicy(profile).finalGate === "enforce" ? "enforce" : "assist" };
+      return { runtime: snapshot, modelRoute: modelRoute?.status === "ok" ? modelRoute.decision : null, retrievalRoute: retrievalRoute ?? null, scope: task?.scope ?? [], protectedPaths: effectiveProtectedPaths(policy, profile).readProtectedPaths, activeToolGroups: pi.getActiveTools(), helperMode: helpersMode(), helperBudget: "1-readonly-total/0-retries/0-writers", executionBackend: "host", executionBoundary: "host execution is not a sandbox", approvals, blockers: feature?.protectedTarget ? ["protected-target"] : [], controlMode: evaluation.status === "ok" && evaluation.decision.mode === "shadow" ? "shadow" : resolveRuntimePolicy(profile).finalGate === "enforce" ? "enforce" : "assist" };
     }
   });
 

package/packages/piagent-core/runtime/registration/task-completion-tools.ts

@@ -9,6 +9,9 @@ import { readTrajectoryStore } from "../trajectory/trajectory-store.ts";
 
 type TaskContract = any;
 
+function taskErrorDetails(task: TaskContract, reasonCode: string): Record<string, unknown> {
+  return { reasonCode, taskId: task.taskId, taskRunId: task.taskRunId, outcome: task.trace?.outcome, attempt: task.attempt };
+}
 
 export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<string, any>): void {
   const {
@@ -41,7 +44,7 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
         return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], isError: true };
       }
       if (task.trace.outcome !== "pending") {
-        return { content: [{ type: "text", text: `Task ${task.taskId} is immutable after ${task.trace.outcome}; context evidence was not changed.` }], details: task, isError: true };
+        return { content: [{ type: "text", text: `Task ${task.taskId} is immutable after ${task.trace.outcome}; context evidence was not changed.` }], details: taskErrorDetails(task, "task-immutable"), isError: true };
       }
       const activeIdentity = runtimeState.taskIdentity(ctx);
       if (!activeIdentity || activeIdentity.taskId !== task.taskId || activeIdentity.taskRunId !== task.taskRunId) {
@@ -127,7 +130,7 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
         return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], isError: true };
       }
       if (task.trace.outcome !== "pending") {
-        return { content: [{ type: "text", text: `Task ${task.taskId} is immutable after ${task.trace.outcome}; verify evidence was not changed.` }], details: task, isError: true };
+        return { content: [{ type: "text", text: `Task ${task.taskId} is immutable after ${task.trace.outcome}; verify evidence was not changed.` }], details: taskErrorDetails(task, "task-immutable"), isError: true };
       }
 
       const observedEntries = [
@@ -239,7 +242,7 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
         return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], isError: true };
       }
       if (task.trace.outcome !== "pending") {
-        return { content: [{ type: "text", text: `Task ${task.taskId} is immutable after ${task.trace.outcome}; memory evidence was not changed.` }], details: task, isError: true };
+        return { content: [{ type: "text", text: `Task ${task.taskId} is immutable after ${task.trace.outcome}; memory evidence was not changed.` }], details: taskErrorDetails(task, "task-immutable"), isError: true };
       }
 
       const safeFiles = params.files.map((file) => ({
@@ -257,7 +260,7 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
 
       return {
         content: [{ type: "text", text: `Memory citations recorded for ${task.taskId}: ${params.files.length} file(s)` }],
-        details: task
+        details: compactTaskDetails(task)
       };
     }
   });
@@ -284,13 +287,13 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
         return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], isError: true };
       }
       if (task.trace.outcome !== "pending") {
-        return { content: [{ type: "text", text: `Task ${task.taskId} is immutable after ${task.trace.outcome}; its final trace was not replaced.` }], details: task, isError: true };
+        return { content: [{ type: "text", text: `Task ${task.taskId} is immutable after ${task.trace.outcome}; its final trace was not replaced.` }], details: taskErrorDetails(task, "task-immutable"), isError: true };
       }
       if (params.outcome !== "completed" && !params.friction?.trim() && !task.failureReason?.trim()) {
-        return { content: [{ type: "text", text: `Trace ${params.outcome} requires a concrete friction/reason so the next attempt does not repeat the same work.` }], details: task, isError: true };
+        return { content: [{ type: "text", text: `Trace ${params.outcome} requires a concrete friction/reason so the next attempt does not repeat the same work.` }], details: taskErrorDetails(task, "trace-friction-required"), isError: true };
       }
       if (params.outcome === "failed" && !params.failedAt && !task.failedAt) {
-        return { content: [{ type: "text", text: "A failed trace requires failedAt to identify the lifecycle phase." }], details: task, isError: true };
+        return { content: [{ type: "text", text: "A failed trace requires failedAt to identify the lifecycle phase." }], details: taskErrorDetails(task, "trace-failure-phase-required"), isError: true };
       }
 
       const rawChangedFiles = params.changedFiles ?? task.changedFiles;
@@ -363,7 +366,7 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
               ...verifierCommandInstructions(gate.missingVerifyCommands)
             ].join("\n")
           }],
-          details: { gate, task: nextTask },
+          details: { gate, task: taskErrorDetails(nextTask, "completion-gate-blocked") },
           isError: true
         };
       }
@@ -426,7 +429,7 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
 
       return {
         content: [{ type: "text", text: `Trace recorded for ${nextTask.taskId}: ${params.outcome}${gate.decision === "fail" ? ` (gate warning: missing ${gate.missing.join(", ")})` : ""}` }],
-        details: { task: written, gate, completionReceipt: buildCompletionReceiptView(written, { cwd: ctx.cwd, gate }) }
+        details: { task: compactTaskDetails(written), gate, completionReceipt: buildCompletionReceiptView(written, { cwd: ctx.cwd, gate }) }
       };
     }
   });

package/packages/piagent-core/runtime/registration/task-evidence-tools.ts

@@ -2,6 +2,9 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 type WorkPlanStep = any;
 
+function taskErrorDetails(task: any, reasonCode: string): Record<string, unknown> {
+  return { reasonCode, taskId: task.taskId, taskRunId: task.taskRunId, outcome: task.trace?.outcome, attempt: task.attempt };
+}
 
 export function registerTaskEvidenceTools(pi: ExtensionAPI, deps: Record<string, any>): void {
   const {
@@ -9,7 +12,7 @@ export function registerTaskEvidenceTools(pi: ExtensionAPI, deps: Record<string,
     compactTaskDetails, effectiveProtectedPaths, extensionDir, extractDocument, loadProfileFromContext,
     matchesAnyPath, matchesProtectedPath, nowIso, path, permissionOverrideFromContext,
     policy, readTask, recordTaskProgressCheckpoints, redactText, registerPiagentTool,
-    resolveDocumentPath, resolveDocumentRoots, resolvePermissionProfile, safeTaskId, verifyProjectCapabilityState,
+    resolveDocumentPath, resolveDocumentRoots, resolvePermissionProfile, runtimeState, safeTaskId, verifyProjectCapabilityState,
     writeTask
   } = deps;
   registerPiagentTool(pi, {
@@ -37,24 +40,26 @@ export function registerTaskEvidenceTools(pi: ExtensionAPI, deps: Record<string,
         return { content: [{ type: "text", text: `Task not found in this session: ${params.taskId}` }], isError: true };
       }
       if (task.trace.outcome !== "pending") {
-        return { content: [{ type: "text", text: `Task ${task.taskId} is immutable after ${task.trace.outcome}; start a fresh session for another attempt.` }], details: task, isError: true };
+        return { content: [{ type: "text", text: `Task ${task.taskId} is immutable after ${task.trace.outcome}; start a fresh session for another attempt.` }], details: taskErrorDetails(task, "task-immutable"), isError: true };
       }
       const stepId = safeTaskId(params.stepId).slice(0, 40);
       const step = task.workPlan.find((item) => item.id === stepId);
       if (!step) {
-        const valid = task.workPlan.map((item) => `${item.id} (${item.status})`).join(", ");
+        const validSteps = task.workPlan.slice(0, 20).map((item) => ({ id: item.id, status: item.status }));
+        const valid = validSteps.map((item) => `${item.id} (${item.status})`).join(", ");
         const actionable = task.workPlan
           .filter((item) => item.status === "in-progress" || (
             item.status === "pending"
             && (item.dependsOn ?? []).every((dependency) => task.workPlan.some((candidate) => candidate.id === dependency && ["done", "skipped"].includes(candidate.status)))
           ))
-          .map((item) => item.id);
+          .map((item) => item.id)
+          .slice(0, 20);
         return {
           content: [{
             type: "text",
             text: `Work-plan step not found: ${stepId}. Valid step IDs: ${valid || "none"}. Currently actionable: ${actionable.join(", ") || "none"}.`
           }],
-          details: task.workPlan,
+          details: { ...taskErrorDetails(task, "work-plan-step-not-found"), stepId, validSteps, actionable },
           isError: true
         };
       }
@@ -66,7 +71,7 @@ export function registerTaskEvidenceTools(pi: ExtensionAPI, deps: Record<string,
       if ((params.status === "in-progress" || params.status === "done") && unresolved.length > 0) {
         return {
           content: [{ type: "text", text: `Step ${stepId} is blocked by unfinished dependencies: ${unresolved.join(", ")}` }],
-          details: { step, unresolved },
+          details: { ...taskErrorDetails(task, "work-plan-step-blocked"), stepId, unresolved: unresolved.slice(0, 20) },
           isError: true
         };
       }
@@ -75,13 +80,13 @@ export function registerTaskEvidenceTools(pi: ExtensionAPI, deps: Record<string,
         return { content: [{ type: "text", text: `A concrete note is required when step ${stepId} fails.` }], isError: true };
       }
       if ((step.status === "done" || step.status === "skipped") && params.status !== step.status) {
-        return { content: [{ type: "text", text: `Work-plan step ${stepId} is already ${step.status} and cannot be reopened in the same attempt.` }], details: step, isError: true };
+        return { content: [{ type: "text", text: `Work-plan step ${stepId} is already ${step.status} and cannot be reopened in the same attempt.` }], details: { ...taskErrorDetails(task, "work-plan-step-immutable"), stepId, status: step.status }, isError: true };
       }
       if (step.status === params.status) {
-        return { content: [{ type: "text", text: `Work-plan step ${stepId} is already ${params.status}; no state change was recorded.` }], details: step, isError: true };
+        return { content: [{ type: "text", text: `Work-plan step ${stepId} is already ${params.status}; no state change was recorded.` }], details: { ...taskErrorDetails(task, "work-plan-step-unchanged"), stepId, status: step.status }, isError: true };
       }
       if (step.status === "failed" && params.status === "in-progress" && !note) {
-        return { content: [{ type: "text", text: `A concrete note is required to reopen failed step ${stepId} within this attempt.` }], details: step, isError: true };
+        return { content: [{ type: "text", text: `A concrete note is required to reopen failed step ${stepId} within this attempt.` }], details: { ...taskErrorDetails(task, "work-plan-step-reopen-note-required"), stepId, status: step.status }, isError: true };
       }
 
       const recordedAt = nowIso();
@@ -254,7 +259,7 @@ export function registerTaskEvidenceTools(pi: ExtensionAPI, deps: Record<string,
   registerPiagentTool(pi, {
     name: "piagent_source_checkout",
     label: "Piagent Source Checkout",
-    description: "Cache and refresh an external Git repository for targeted local inspection.",
+    description: "Prepare an external Git repository for bounded, read-only local inspection.",
     promptSnippet: "Use this before reading a user-provided external source repository.",
     promptGuidelines: [
       "Use for GitHub/GitLab/Bitbucket source repositories supplied by the user.",
@@ -264,15 +269,19 @@ export function registerTaskEvidenceTools(pi: ExtensionAPI, deps: Record<string,
       repoRef: Type.String({ minLength: 3, description: "owner/repo, host/owner/repo, https URL, or git@host:owner/repo.git" }),
       forceUpdate: Type.Optional(Type.Boolean({ description: "Fetch immediately even if the cache was refreshed recently." }))
     }),
-    async execute(_toolCallId, params) {
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       try {
         const repo = checkoutReferenceRepo(params.repoRef, params.forceUpdate === true);
+        const grantedPath = runtimeState.grantSourceCheckoutReadRoot(ctx, repo.checkoutPath);
+        repo.checkoutPath = grantedPath;
         const text = [
           "Source cache ready:",
           `path: ${repo.checkoutPath}`,
           `url: ${repo.cloneUrl}`,
           `commit: ${repo.commit ?? "unknown"}`,
-          `fetched: ${repo.fetched ? "yes" : "no"}`
+          `fetched: ${repo.fetched ? "yes" : "no"}`,
+          "access: read-only for this session via read, grep, find, or ls",
+          "Do not run a checkout script or use shell mutation against this shared cache."
         ].join("\n");
         return {
           content: [{ type: "text", text }],

package/packages/piagent-core/runtime/registration/task-start-guidance.ts

@@ -102,12 +102,18 @@ export function criticalProofSection(
   acceptanceTests: FocusedTestCandidate[],
   criterionProofs: CriterionProofGuidance[]
 ): string[] {
-  if (proofGuidance.length === 0) return [];
+  if (proofGuidance.length === 0 && criterionProofs.length === 0) return [];
   const candidateMap = new Map<string, string[]>();
   for (const candidate of acceptanceTests) {
     candidateMap.set(candidate.criterionId, [...new Set([...(candidateMap.get(candidate.criterionId) ?? []), candidate.path])]);
   }
   let mappedCandidate = false;
+  const criterionTag = (criterionId: string): string => {
+    const candidates = candidateMap.get(criterionId) ?? [];
+    if (candidates.length === 0) return `[${criterionId}:fallback]`;
+    mappedCandidate = true;
+    return `[${criterionId}:candidate=${candidates.join("|")}]`;
+  };
   const proofLines = proofGuidance.flatMap((proof) => {
     const criterionIds = [...new Set(criterionProofs
       .filter((entry) => entry.guidance.includes(proof))
@@ -115,21 +121,19 @@ export function criticalProofSection(
     if (criterionIds.length === 0) {
       return [`- [fallback] ${proof}`];
     }
-    const tags = criterionIds.map((criterionId) => {
-      const candidates = candidateMap.get(criterionId) ?? [];
-      if (candidates.length === 0) {
-        return `[${criterionId}:fallback]`;
-      }
-      mappedCandidate = true;
-      return `[${criterionId}:candidate=${candidates.join("|")}]`;
-    });
+    const tags = criterionIds.map(criterionTag);
     return [`- ${tags.join("")} ${proof}`];
   });
+  const genericTags = criterionProofs.filter((entry) => entry.guidance.length === 0).map((entry) => criterionTag(entry.criterionId));
+  const genericLines = genericTags.length > 0
+    ? [`- ${genericTags.join("")} Prove every tagged observable clause with linked live assertions; the generic verifier alone is insufficient.`]
+    : [];
   return [[
     "Critical behavioral proof:",
-    ...(!mappedCandidate ? ["No concrete criterion-linked focused test was selected."] : []),
+    ...(!mappedCandidate && genericTags.length === 0 ? ["No concrete criterion-linked focused test was selected."] : []),
     ...proofLines,
-    "Candidate tags are locations, not proof; add/update durable scoped tests with live assertions and changed-test evidence. Each fallback tag requires adding/updating a durable scoped focused test with live assertions. If test scope is unavailable, report missing durable proof and do not claim completion. Run proof after the criterion's final intended mutation and before exact verifiers; rerun after later target mutation or a runtime-authorized same-tree infrastructure retry. Transient/print-only probes and prose are insufficient."
+    ...genericLines,
+    "Candidate tags are locations, not proof; add/update durable scoped tests with live assertions and changed-test evidence. Each fallback tag requires adding/updating a durable scoped focused test with live assertions. If test scope is unavailable, report missing durable proof and do not claim completion. Run proof after the criterion's final intended mutation and before exact verifiers; rerun after later target mutation or a runtime-authorized same-tree infrastructure retry. Transient/print-only probes and prose are insufficient. Claims must match diff/tests; never claim unproved behavior."
   ].join("\n")];
 }
 
@@ -150,7 +154,8 @@ export function taskCriticalProofSection(
   repositoryFiles: string[],
   acceptanceProofGuidance: (taskOrText: unknown) => string[],
   isAcceptanceTestPath: (file: string) => boolean,
-  acceptanceLanguageAdapterForPath: (file: string) => { disposition?: string }
+  acceptanceLanguageAdapterForPath: (file: string) => { disposition?: string },
+  requireGenericFallback = true
 ): string[] {
   const proofGuidance = task.changeMode === "source-change" && task.mutationPolicy !== "forbidden"
     ? acceptanceProofGuidance(task)
@@ -158,6 +163,7 @@ export function taskCriticalProofSection(
   const acceptanceTests = concretePlannedAcceptanceTests(
     plannedContext, repositoryFiles, task.criterionGraph, isAcceptanceTestPath, acceptanceLanguageAdapterForPath
   );
-  const criterionProofs = behavioralCriterionProofGuidance(task.criterionGraph, acceptanceProofGuidance);
+  const criterionProofs = behavioralCriterionProofGuidance(task.criterionGraph, acceptanceProofGuidance)
+    .filter((entry) => requireGenericFallback || entry.guidance.length > 0);
   return criticalProofSection(proofGuidance, acceptanceTests, criterionProofs);
 }

package/packages/piagent-core/runtime/registration/task-start-manifest.ts

@@ -0,0 +1,54 @@
+type RepositoryManifestCompatibilityReason = "missing-details-provider" | "nonfunction-details-provider" | "invalid-details-result";
+
+type TaskStartRepositoryManifest = {
+  files: string[];
+  complete: boolean;
+  candidateCount: number;
+  provider: "details" | "legacy-array-fallback";
+  compatibilityReason?: RepositoryManifestCompatibilityReason;
+};
+
+function normalizedManifestFiles(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(value.filter((item): item is string => typeof item === "string" && item.trim().length > 0))];
+}
+
+/**
+ * Keep rolling upgrades safe when a long-lived host has the legacy extension
+ * entrypoint cached but imports a newer task-start registration module. The
+ * legacy array provider cannot prove whether its result was truncated, so the
+ * compatibility path deliberately reports `complete: false` and records the
+ * provider/reason in the durable task trace.
+ */
+export function resolveTaskStartRepositoryManifestProvider(deps: Record<string, any>): {
+  read(cwd: string, maxFiles?: number): TaskStartRepositoryManifest;
+} {
+  const legacyProvider = deps.repositoryFileManifest;
+  if (typeof legacyProvider !== "function") {
+    throw new TypeError("Piagent task-start registration requires repositoryFileManifest to be a function.");
+  }
+  const detailsProvider = deps.repositoryFileManifestDetails;
+  const compatibilityReason: RepositoryManifestCompatibilityReason | undefined = detailsProvider === undefined
+    ? "missing-details-provider"
+    : typeof detailsProvider !== "function"
+      ? "nonfunction-details-provider"
+      : undefined;
+  const legacyManifest = (cwd: string, maxFiles?: number,
+    reason: RepositoryManifestCompatibilityReason = compatibilityReason ?? "invalid-details-result"): TaskStartRepositoryManifest => {
+    const files = normalizedManifestFiles(legacyProvider(cwd, maxFiles));
+    return { files, complete: false, candidateCount: files.length, provider: "legacy-array-fallback", compatibilityReason: reason };
+  };
+  if (compatibilityReason) return { read: legacyManifest };
+  return {
+    read(cwd: string, maxFiles?: number): TaskStartRepositoryManifest {
+      const details = detailsProvider(cwd, maxFiles);
+      if (!details || typeof details !== "object" || !Array.isArray(details.files)) {
+        return legacyManifest(cwd, maxFiles, "invalid-details-result");
+      }
+      const files = normalizedManifestFiles(details.files);
+      return { files, complete: details.complete === true,
+        candidateCount: Number.isInteger(details.candidateCount) ? Math.max(files.length, details.candidateCount) : files.length,
+        provider: "details" };
+    }
+  };
+}