@piagent/platform 1.5.5 → 1.6.1

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

@@ -1,4 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { durableContextEvidenceEntries, isRuntimeOwnedContextEvidenceEntry } from "../../extensions/context-evidence.js";
+import { mergeObservedTaskContext } from "../../extensions/task-contract-view.js";
 import { buildHandoffProjection, writeHandoffProjection } from "../recovery/handoff-projection.ts";
 import { buildCompletionReceiptView } from "../product/operator-projections.ts";
 import { semanticRepairProvenance } from "../recovery/semantic-repair-handshake.ts";
@@ -7,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 {
@@ -39,15 +44,52 @@ 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) {
+        return {
+          content: [{ type: "text", text: `Context evidence rejected for ${task.taskId}: the active runtime task identity does not match this session task.` }],
+          details: { reasonCode: "context-evidence-task-identity-mismatch" },
+          isError: true
+        };
+      }
+      const observedPaths = new Set(runtimeState.observedContext(ctx)
+        .map((entry: { path: string }) => normalizeRelative(ctx.cwd, entry.path))
+        .filter((filePath: string | undefined): filePath is string => Boolean(filePath)));
+      const qualifiedByPath = new Map<string, { path: string; reason: string }>();
+      for (const entry of runtimeState.qualifiedContextEvidence(ctx, task.taskRunId)) {
+        const filePath = normalizeRelative(ctx.cwd, entry.path);
+        if (filePath && isRuntimeOwnedContextEvidenceEntry(entry)) qualifiedByPath.set(filePath, entry);
+      }
+      const qualifiedFiles = new Map<string, { path: string; reason: string }>();
+      const unprovenPaths: string[] = [];
+      for (const file of params.files) {
+        const filePath = normalizeRelative(ctx.cwd, file.path);
+        const evidence = filePath ? qualifiedByPath.get(filePath) : undefined;
+        if (!filePath || !observedPaths.has(filePath) || !evidence) {
+          unprovenPaths.push(redactText(file.path));
+          continue;
+        }
+        qualifiedFiles.set(filePath, { path: filePath, reason: evidence.reason });
+      }
+      if (unprovenPaths.length > 0) {
+        return {
+          content: [{ type: "text", text: `Context evidence rejected for ${task.taskId}: no runtime-observed read or host-confirmed delivery exists in this task/session for ${unprovenPaths.join(", ")}. Read the exact file successfully in this task or rely on automatic delivery confirmation.` }],
+          details: { reasonCode: "context-evidence-unproven", paths: unprovenPaths },
+          isError: true
+        };
       }
-      if (runtime.contextBudget !== "off" && task.contextManifest.length + params.files.length > budget.maxManifestFiles) {
+      const safeFiles = [...qualifiedFiles.values()];
+      const evidencePaths = new Set(durableContextEvidenceEntries(task).map((item) => item.path));
+      const projectedManifestFiles = evidencePaths.size + new Set(safeFiles.map((item) => item.path).filter((filePath) => !evidencePaths.has(filePath))).size;
+      if (runtime.contextBudget !== "off" && projectedManifestFiles > budget.maxManifestFiles) {
         return {
-          content: [{ type: "text", text: `Context manifest budget exceeded: ${task.contextManifest.length + params.files.length} files > ${budget.maxManifestFiles}` }],
+          content: [{ type: "text", text: `Context manifest budget exceeded: ${projectedManifestFiles} files > ${budget.maxManifestFiles}` }],
           isError: true
         };
       }
-      const fileBudget = params.files.map((file) => candidateFileBudget(ctx.cwd, file.path, budget));
+      const fileBudget = safeFiles.map((file) => candidateFileBudget(ctx.cwd, file.path, budget));
       const overLimit = fileBudget.filter((item) => item.overLimit);
       if (runtime.contextBudget === "enforce" && overLimit.length > 0) {
         return {
@@ -56,17 +98,8 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
           isError: true
         };
       }
-
-      const safeFiles = params.files.map((file) => ({
-        path: file.path,
-        reason: redactText(file.reason)
-      }));
-      const seen = new Set(task.contextManifest.map((item) => `${item.path}\u0000${item.reason}`));
-      for (const file of safeFiles) {
-        const key = `${file.path}\u0000${file.reason}`;
-        if (!seen.has(key)) task.contextManifest.push(file);
-      }
-      const lifecycle = task.changeMode === "read-only"
+      mergeObservedTaskContext(task, safeFiles, budget.maxManifestFiles, (value) => value);
+      const lifecycle = task.changeMode === "read-only" || task.mutationPolicy === "forbidden"
         ? applyRuntimeLifecycleObservation(task, "context-complete", nowIso())
         : { changed: false, mode: runtimeLifecycleMode(task) };
       const written = writeTask(ctx.cwd, task);
@@ -74,7 +107,7 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
       appendSessionTrace(pi, { taskId: task.taskId, taskRunId: task.taskRunId, sessionId: task.sessionId, event: "context_record", files: safeFiles, lifecycleMode: lifecycle.mode, lifecycleAdvanced: lifecycle.changed });
 
       return {
-        content: [{ type: "text", text: `Context recorded for ${task.taskId}: ${params.files.length} file(s)` }],
+        content: [{ type: "text", text: `Context recorded for ${task.taskId}: ${safeFiles.length} runtime-qualified file(s)` }],
         details: compactTaskDetails(written)
       };
     }
@@ -97,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 = [
@@ -209,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) => ({
@@ -227,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)
       };
     }
   });
@@ -254,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;
@@ -296,7 +329,10 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
         currentDigests: finalFileDigests,
         currentWorkingTreeDigest: workingTreeEvidenceDigest(finalFileDigests)
       });
-      const semanticBlock = taskAuthorityDecision(nextTask, "CAP-13", "block").allowed ? semanticRepairCompletionBlock?.(ctx.cwd, nextTask.taskRunId) : undefined;
+      const semanticBlock = (taskAuthorityDecision(nextTask, "CAP-13", "block").allowed
+        || taskAuthorityDecision(nextTask, "CAP-12", "mutate").allowed)
+        ? semanticRepairCompletionBlock?.(ctx.cwd, nextTask.taskRunId)
+        : undefined;
       if (semanticBlock) gate = { ...gate, decision: "fail", missing: [...new Set([...gate.missing, semanticBlock])] };
       if (params.outcome === "completed" && (semanticBlock || (runtime.finalGate === "enforce" && gate.decision === "fail"))) {
         const blockedTrace = {
@@ -330,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
         };
       }
@@ -393,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

@@ -0,0 +1,169 @@
+type CriterionNode = {
+  id?: string;
+  obligation?: string;
+  kind?: string;
+  proofKinds?: string[];
+  targetHints?: string[];
+};
+
+type CriterionGraph = { mode?: string; nodes?: CriterionNode[] } | undefined;
+
+export type FocusedTestCandidate = {
+  criterionId: string;
+  path: string;
+};
+
+export type CriterionProofGuidance = {
+  criterionId: string;
+  guidance: string[];
+};
+
+type ProofTask = {
+  changeMode?: string;
+  mutationPolicy?: string;
+  criterionGraph?: CriterionGraph;
+};
+
+export const RUNTIME_SOURCE_REUSE_GUIDANCE = "Use runtime-delivered source; do not reread it. On edit drift/oldText mismatch, use attached recovery; otherwise reread the affected region once. Never retry guessed anchors. Otherwise read only missing source or a named criterion-focused test. Globs/directories grant scope, not file targets.";
+
+export const EXACT_VERIFIER_EXECUTION_GUIDANCE = "Keep each exact verifier command separate and unmodified. Run the set once on the final tree; rerun only after a later mutation or a runtime-authorized same-tree infrastructure retry.";
+
+function normalizedPath(value: string): string {
+  return value.trim().replaceAll("\\", "/");
+}
+
+function exactNameMentioned(obligation: string, file: string): boolean {
+  const text = obligation.toLowerCase().replaceAll("\\", "/");
+  const normalized = normalizedPath(file).toLowerCase();
+  const basename = normalized.split("/").pop() ?? "";
+  return [normalized, basename].filter(Boolean).some((candidate) => {
+    let offset = text.indexOf(candidate);
+    while (offset >= 0) {
+      const before = text[offset - 1] ?? "";
+      const after = text[offset + candidate.length] ?? "";
+      const afterNext = text[offset + candidate.length + 1] ?? "";
+      const nameContinuesAfter = /[a-z0-9_/-]/i.test(after) || (after === "." && /[a-z0-9_-]/i.test(afterNext));
+      if (!/[a-z0-9_./-]/i.test(before) && !nameContinuesAfter) return true;
+      offset = text.indexOf(candidate, offset + candidate.length);
+    }
+    return false;
+  });
+}
+
+function behavioralNodes(criterionGraph: CriterionGraph): CriterionNode[] {
+  return (criterionGraph?.nodes ?? []).filter((node) => (
+    typeof node?.id === "string"
+    && typeof node?.obligation === "string"
+    && Array.isArray(node?.proofKinds)
+    && node.proofKinds.includes("behavioral-check")
+  ));
+}
+
+export function concretePlannedAcceptanceTests(
+  plannedContext: Array<{ path: string; reason: string }>,
+  repositoryFiles: string[],
+  criterionGraph: CriterionGraph,
+  isAcceptanceTestPath: (file: string) => boolean,
+  acceptanceLanguageAdapterForPath: (file: string) => { disposition?: string }
+): FocusedTestCandidate[] {
+  const concreteFiles = new Set(repositoryFiles.map(normalizedPath));
+  const nodes = behavioralNodes(criterionGraph);
+  const candidates: FocusedTestCandidate[] = [];
+  for (const entry of plannedContext) {
+    const file = normalizedPath(entry.path);
+    if (!file || /[?*[\]{}]/.test(file) || !concreteFiles.has(file)) continue;
+    if (!isAcceptanceTestPath(file) || acceptanceLanguageAdapterForPath(file)?.disposition !== "supported") continue;
+    if (/\.d\.[cm]?ts$/i.test(file)) continue;
+    for (const node of nodes) {
+      if (exactNameMentioned(node.obligation!, file)) candidates.push({ criterionId: node.id!, path: file });
+    }
+  }
+  const seen = new Set<string>();
+  return candidates.filter((candidate) => {
+    const identity = `${candidate.criterionId}\0${candidate.path}`;
+    if (seen.has(identity)) return false;
+    seen.add(identity);
+    return true;
+  });
+}
+
+export function behavioralCriterionProofGuidance(
+  criterionGraph: CriterionGraph,
+  acceptanceProofGuidance: (text: string) => string[]
+): CriterionProofGuidance[] {
+  return behavioralNodes(criterionGraph).map((node) => ({
+    criterionId: node.id!,
+    guidance: acceptanceProofGuidance(node.obligation!)
+  }));
+}
+
+export function criticalProofSection(
+  proofGuidance: string[],
+  acceptanceTests: FocusedTestCandidate[],
+  criterionProofs: CriterionProofGuidance[]
+): string[] {
+  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))
+      .map((entry) => entry.criterionId))];
+    if (criterionIds.length === 0) {
+      return [`- [fallback] ${proof}`];
+    }
+    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 && genericTags.length === 0 ? ["No concrete criterion-linked focused test was selected."] : []),
+    ...proofLines,
+    ...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")];
+}
+
+export function automaticTaskExecutionGuidance(task: ProofTask): string {
+  if (task.changeMode === "read-only" || task.mutationPolicy === "forbidden") {
+    return task.changeMode === "source-change"
+      ? "Stay mutation-free. Runtime permits bounded inspection and the exact configured verifier, records completion evidence, and requires a zero task delta."
+      : "Stay read-only. Runtime records targeted reads and completion evidence; do not call task-management tools.";
+  }
+  return task.criterionGraph?.mode === "criterion-graph"
+    ? "Follow the execution map and implement dependency-ready criteria. The map plans work but never overrides the operator request or exact verifiers. Runtime records evidence and completion; do not call task-management tools."
+    : "Privately map every operator criterion to implementation and durable focused-test coverage before mutating. Finish intended edits and a criterion-by-criterion self-review. Runtime records evidence and completion; do not call task-management tools.";
+}
+
+export function taskCriticalProofSection(
+  task: ProofTask,
+  plannedContext: Array<{ path: string; reason: string }>,
+  repositoryFiles: string[],
+  acceptanceProofGuidance: (taskOrText: unknown) => string[],
+  isAcceptanceTestPath: (file: string) => boolean,
+  acceptanceLanguageAdapterForPath: (file: string) => { disposition?: string },
+  requireGenericFallback = true
+): string[] {
+  const proofGuidance = task.changeMode === "source-change" && task.mutationPolicy !== "forbidden"
+    ? acceptanceProofGuidance(task)
+    : [];
+  const acceptanceTests = concretePlannedAcceptanceTests(
+    plannedContext, repositoryFiles, task.criterionGraph, isAcceptanceTestPath, acceptanceLanguageAdapterForPath
+  );
+  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" };
+    }
+  };
+}

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

@@ -0,0 +1,37 @@
+type AuthoritySnapshot = {
+  profile: string;
+  capabilities: Array<{ id: string; authority: string }>;
+};
+
+type AuthorityReplacementTask = {
+  authoritySnapshot?: AuthoritySnapshot;
+};
+
+type AuthorityReplacementState = {
+  reason?: string;
+  killedCapabilities: string[];
+};
+
+export function sameStringRecord(left: Record<string, string>, right: Record<string, string>): boolean {
+  const leftEntries = Object.entries(left).sort(([a], [b]) => a.localeCompare(b));
+  const rightEntries = Object.entries(right).sort(([a], [b]) => a.localeCompare(b));
+  return leftEntries.length === rightEntries.length
+    && leftEntries.every(([key, value], index) => rightEntries[index]?.[0] === key && rightEntries[index]?.[1] === value);
+}
+
+export function satisfiesAuthorityReplacement(
+  task: AuthorityReplacementTask,
+  state: AuthorityReplacementState
+): boolean {
+  if (!task.authoritySnapshot) return false;
+  const authoritySnapshot = task.authoritySnapshot;
+  if (state.reason === "mechanical-rollback-requested") {
+    return authoritySnapshot.profile === "mechanical-only";
+  }
+  if (state.reason === "capability-kill-switch-requested") {
+    return state.killedCapabilities.length > 0 && state.killedCapabilities.every((capabilityId) => (
+      authoritySnapshot.capabilities.some((entry) => entry.id === capabilityId && entry.authority === "off")
+    ));
+  }
+  return true;
+}