@piagent/platform 1.5.5 → 1.6.1

package/packages/piagent-core/runtime/recovery/resume-state.ts

@@ -2,7 +2,6 @@ import path from "node:path";
 
 import type { TaskContract } from "../../extensions/guard-types.ts";
 import { allVerifyCommandsPassCurrentTree } from "../../extensions/task-contract-view.js";
-import { criterionGraphGuidance } from "../../extensions/criterion-graph.js";
 import { replayTaskCheckpoints, taskRecoveryDecision } from "../../extensions/task-journal.js";
 import { taskDigestMigrationArchiveStatus, workingTreeSnapshot, workingTreeSnapshotHasUnavailableEvidence } from "../../extensions/task-state.js";
 import { workingTreeEvidenceDigest } from "../../extensions/task-lifecycle.js";
@@ -10,12 +9,21 @@ import { hashEvidenceCommand } from "../../extensions/runtime-evidence.js";
 import { WORKING_TREE_DIGEST_ALGORITHM, isCurrentWorkingTreeDigest, workingTreeSnapshotUsesCurrentAlgorithm } from "../../extensions/working-tree-digest.js";
 import { handoffProjectionPath, readHandoffProjection } from "./handoff-projection.ts";
 import { inspectTaskAuthorityResumePolicy, type AuthorityResumeDecision } from "../policy/authority-resume-policy.ts";
+import { presentedAcceptanceCriteria, presentedCriterionGraphGuidance } from "../session/task-contract-presentation.ts";
+import { operatorRequestCarryLines } from "../session/operator-request-carry.ts";
 import { readTrajectoryStore } from "../trajectory/trajectory-store.ts";
 import { findVerifierFileSnapshot, inspectVerifierStaleness, readVerifierFileSnapshots } from "../inspection/verifier-snapshot-store.ts";
 
 export const RESUME_STATE_VERSION = "resume-v1" as const;
 export const RESUME_CONTEXT_VERSION = "resume-context-v1" as const;
-export const RESUME_CONTEXT_MAX_CHARS = 6_000;
+export const RESUME_CONTEXT_MAX_CHARS = 12_000;
+// Validated task text is bounded in Unicode code points by JSON Schema. Astral
+// characters occupy two UTF-16 code units, so the exceptional resume ceiling
+// must cover the worst valid lossless task even though the normal target stays
+// at 12k. This overflow is explicit and is never used for routine compaction.
+export const RESUME_CONTEXT_LOSSLESS_MAX_CHARS = 40_000;
+export const RESUME_CONTEXT_LOSSLESS_OVERFLOW_MARKER = `[Piagent lossless resume overflow: the ${RESUME_CONTEXT_MAX_CHARS}-character target was exceeded; complete authoritative task truth is retained.]`;
+export const LEGACY_TASK_TRUTH_OVERFLOW_MARKER = `[Piagent legacy-task-truth-overflow: automatic continuation is paused because lossless task truth exceeds the ${RESUME_CONTEXT_LOSSLESS_MAX_CHARS}-character exceptional ceiling.]`;
 type ResumePlanStep = {
   id: string;
   title: string;
@@ -153,44 +161,129 @@ function limitedLines(values: unknown[], maximumItems: number, maximumChars: num
   return selected;
 }
 
+function losslessManualResumeContent(task: TaskContract): string {
+  return [
+    "[Piagent durable task resume]",
+    RESUME_CONTEXT_LOSSLESS_OVERFLOW_MARKER,
+    `Task: ${compact(task.taskId, 120)} (${compact(task.taskRunId, 120)})`,
+    `Goal: ${task.summary}`,
+    `Expected output: ${task.expectedOutput}`,
+    "Acceptance focus:", ...presentedAcceptanceCriteria(task).map((value, index) => `- C${index + 1}: ${value}`),
+    "Exact verifier commands:", ...task.verifyCommands.map((value, index) => `${index + 1}. ${value}`),
+    "Continue only under the current runtime-enforced task state and every durable task clause above; do not infer progress from transcript memory."
+  ].join("\n");
+}
+
+/** Exact UTF-16 traffic size for the smallest lossless automatic legacy resume. */
+export function legacyTaskResumeTruthChars(task: TaskContract): number {
+  return operatorRequestCarryLines(task).length > 0 ? 0 : losslessManualResumeContent(task).length;
+}
+
+function legacyTaskTruthOverflowsAutomaticResume(task: TaskContract): boolean {
+  const chars = legacyTaskResumeTruthChars(task);
+  return chars > RESUME_CONTEXT_LOSSLESS_MAX_CHARS;
+}
+
+function legacyOverflowResumeContent(task: TaskContract): string {
+  return [
+    "[Piagent durable task resume]",
+    LEGACY_TASK_TRUTH_OVERFLOW_MARKER,
+    `Task: ${compact(task.taskId, 120)} (${compact(task.taskRunId, 120)})`,
+    "The durable task remains byte-for-byte intact, but its complete acceptance truth cannot be injected safely in one automatic resume.",
+    "Do not mutate or auto-continue this task. Ask the operator to re-intake the original request as a new bounded task or provide an explicit compact handoff."
+  ].join("\n");
+}
+
 export function buildTaskResumeContext(task: TaskContract, resume: ResumeState): {
   customType: "piagent-runtime-task-resume";
   content: string;
   details: Record<string, unknown>;
 } {
-  const criteria = limitedLines(task.acceptanceCriteria, 8, 180, (value, index) => `- C${index + 1}: ${value}`);
+  if (legacyTaskTruthOverflowsAutomaticResume(task)) {
+    return {
+      customType: "piagent-runtime-task-resume",
+      content: legacyOverflowResumeContent(task),
+      details: {
+        resumeContextVersion: RESUME_CONTEXT_VERSION, taskId: task.taskId, taskRunId: task.taskRunId,
+        phase: resume.phase, checkpointId: resume.latestCheckpoint?.checkpointId ?? null,
+        decision: "blocked", enforcementSafe: false, verifierEvidenceCurrent: resume.verifierEvidenceCurrent,
+        staleVerifierEvidence: resume.staleVerifierEvidence, losslessOverflow: true,
+        legacyTaskTruthOverflow: true, nextAction: resume.reconstruction.nextAction
+      }
+    };
+  }
+  const operatorTruth = operatorRequestCarryLines(task);
+  const presentedCriteria = presentedAcceptanceCriteria(task);
+  const criteria = operatorTruth.length > 0
+    ? limitedLines(presentedCriteria, 8, 180, (value, index) => `- C${index + 1}: ${value}`)
+    : presentedCriteria.map((value, index) => `- C${index + 1}: ${value}`);
   const scope = limitedLines(task.scope, 8, 100, (value) => `- ${value}`);
   const plan = resume.reconstruction.plan.slice(0, 12).map((step) => (
     `- ${step.id}: ${step.status}; ${compact(step.title, 140)}${step.dependsOn.length > 0 ? `; after=${step.dependsOn.join(",")}` : ""}`
   ));
   if (resume.reconstruction.plan.length > 12) plan.push(`- [${resume.reconstruction.plan.length - 12} more steps retained in the Task Contract]`);
-  const verifiers = limitedLines(task.verifyCommands, 8, 180, (value, index) => `${index + 1}. ${value}`);
-  const executionMap = criterionGraphGuidance(task.criterionGraph, 8).map((line: string) => `- ${line}`);
+  const verifiers = task.verifyCommands.map((value, index) => `${index + 1}. ${value}`);
+  const executionMap = presentedCriterionGraphGuidance(task, 8).map((line: string) => `- ${line}`);
   const next = resume.reconstruction.nextAction;
   const lines = [
     "[Piagent durable task resume]",
     "This brief is reconstructed from the current Task Contract, journal, trajectory, handoff and working tree. Durable files remain authoritative.",
     `Task: ${compact(task.taskId, 160)} (${compact(task.taskRunId, 160)})`,
-    `Goal: ${compact(task.summary, 500)}`,
-    `Expected output: ${compact(task.expectedOutput, 400)}`,
+    `Goal: ${operatorTruth.length > 0 ? compact(task.summary, 500) : task.summary}`,
+    ...operatorTruth,
+    `Expected output: ${operatorTruth.length > 0 ? compact(task.expectedOutput, 400) : task.expectedOutput}`,
     "Acceptance focus:", ...criteria,
-    "Scope:", ...scope,
+    "Initial focus (advisory):", ...scope,
+    "Initial focus guides retrieval/review and neither authorizes nor forbids mutation.",
     "Work plan/progress:", ...plan,
     ...(executionMap.length > 0 ? ["Execution map (planning only):", ...executionMap] : []),
     `Current phase/checkpoint: ${resume.phase ?? "unknown"} / ${resume.latestCheckpoint?.checkpointId ?? "none"}`,
     `Verifier state: current=${resume.verifierEvidenceCurrent}; stale=${resume.staleVerifierEvidence}; tree=${resume.currentTreeDigest}`,
     "Exact verifier commands:", ...verifiers,
     `Next safe action: ${next.action}${next.stepId ? ` (${next.stepId})` : ""}. ${compact(next.reason, 500)}`,
-    ...(next.exactCommands.length > 0 ? ["Required commands for that action:", ...limitedLines(next.exactCommands, 8, 180, (value, index) => `${index + 1}. ${value}`)] : []),
+    ...(next.exactCommands.length > 0 ? ["Required commands for that action:", ...next.exactCommands.map((value, index) => `${index + 1}. ${value}`)] : []),
     `Resume safety: decision=${resume.decision}; enforcementSafe=${resume.enforcementSafe}; handoff=${resume.handoff.exists ? resume.handoff.path : "none"}.`,
     "Do not infer progress from transcript memory, reopen completed steps, or mutate when the next action is inspect-handoff, wait-paused, or terminal."
   ];
   let content = lines.join("\n");
   if (content.length > RESUME_CONTEXT_MAX_CHARS) {
-    const marker = "\n[Middle details shortened; complete task truth remains in the Task Contract.]\n";
-    const available = RESUME_CONTEXT_MAX_CHARS - marker.length;
-    const head = Math.floor(available * 0.7);
-    content = `${content.slice(0, head).trimEnd()}${marker}${content.slice(-(available - head)).trimStart()}`;
+    const boundedOperatorTruth = operatorRequestCarryLines(task);
+    content = boundedOperatorTruth.length > 0 ? [
+      "[Piagent durable task resume]",
+      `Task: ${compact(task.taskId, 160)} (${compact(task.taskRunId, 160)})`,
+      ...boundedOperatorTruth,
+      "Acceptance focus:", ...limitedLines(presentedAcceptanceCriteria(task), 8, 160, (value, index) => `- C${index + 1}: ${value}`),
+      `Current phase/checkpoint: ${resume.phase ?? "unknown"} / ${resume.latestCheckpoint?.checkpointId ?? "none"}`,
+      "Exact verifier commands:", ...verifiers,
+      `Next safe action: ${next.action}${next.stepId ? ` (${next.stepId})` : ""}. ${compact(next.reason, 400)}`,
+      `Resume safety: decision=${resume.decision}; enforcementSafe=${resume.enforcementSafe}.`,
+      "Continue from current source. Preserve every operator clause exactly; do not infer progress from transcript memory."
+    ].join("\n") : losslessManualResumeContent(task);
+    if (content.length > RESUME_CONTEXT_MAX_CHARS && boundedOperatorTruth.length > 0) {
+      content = [
+        "[Piagent durable task resume]",
+        RESUME_CONTEXT_LOSSLESS_OVERFLOW_MARKER,
+        `Task: ${compact(task.taskId, 120)} (${compact(task.taskRunId, 120)})`,
+        ...boundedOperatorTruth,
+        "Acceptance focus:", ...limitedLines(presentedAcceptanceCriteria(task), 12, 220, (value, index) => `- C${index + 1}: ${value}`),
+        "Exact verifier commands:", ...verifiers,
+        `Next safe action: ${next.action}${next.stepId ? ` (${next.stepId})` : ""}. ${compact(next.reason, 300)}`,
+        `Resume safety: decision=${resume.decision}; enforcementSafe=${resume.enforcementSafe}.`,
+        "Continue only from current source, the complete operator request, exact verifiers, and durable atomic acceptance facts."
+      ].join("\n");
+      if (content.length > RESUME_CONTEXT_LOSSLESS_MAX_CHARS) {
+        content = [
+          "[Piagent durable task resume]",
+          RESUME_CONTEXT_LOSSLESS_OVERFLOW_MARKER,
+          `Task: ${compact(task.taskId, 120)} (${compact(task.taskRunId, 120)})`,
+          ...boundedOperatorTruth,
+          "Exact verifier commands:", ...verifiers,
+          `Next safe action: ${next.action}${next.stepId ? ` (${next.stepId})` : ""}. ${compact(next.reason, 240)}`,
+          `Resume safety: decision=${resume.decision}; enforcementSafe=${resume.enforcementSafe}.`,
+          "The complete operator request above is the acceptance source of truth. Continue only from current source and these exact verifiers."
+        ].join("\n");
+      }
+    }
   }
   return {
     customType: "piagent-runtime-task-resume",
@@ -205,6 +298,7 @@ export function buildTaskResumeContext(task: TaskContract, resume: ResumeState):
       enforcementSafe: resume.enforcementSafe,
       verifierEvidenceCurrent: resume.verifierEvidenceCurrent,
       staleVerifierEvidence: resume.staleVerifierEvidence,
+      losslessOverflow: content.length > RESUME_CONTEXT_MAX_CHARS,
       nextAction: resume.reconstruction.nextAction
     }
   };
@@ -220,6 +314,7 @@ export function inspectTaskResumeState(
   const currentTreeDigest = workingTreeEvidenceDigest(currentDigests);
   const authorityPolicy = inspectTaskAuthorityResumePolicy(cwd, task);
   const archive = taskDigestMigrationArchiveStatus(cwd, task);
+  const legacyTruthOverflow = task.trace.outcome === "pending" && legacyTaskTruthOverflowsAutomaticResume(task);
   const algorithmReady = task.workingTreeDigestAlgorithm === WORKING_TREE_DIGEST_ALGORITHM
     && isCurrentWorkingTreeDigest(currentTreeDigest)
     && workingTreeSnapshotUsesCurrentAlgorithm(currentDigests)
@@ -265,8 +360,9 @@ export function inspectTaskResumeState(
   if (!trajectory.enforcementSafe) warnings.push(`trajectory state is unsafe: ${trajectory.warnings[0] ?? "unknown error"}`);
   if (!algorithmReady) warnings.push("working-tree digest algorithm/evidence is not current and proof-capable");
   if (!archive.valid) warnings.push(archive.reason);
+  if (legacyTruthOverflow) warnings.push("legacy-task-truth-overflow requires explicit operator re-intake or compact handoff");
   if (refreshRequired) warnings.push("legacy evidence was archived; run each exact configured verifier once against the current wt-content-v2 tree");
-  const enforcementSafe = authorityReady && !identityConflict && algorithmReady && archive.valid && journal.corruptions.length === 0 && trajectory.enforcementSafe && handoffValid;
+  const enforcementSafe = authorityReady && !identityConflict && !legacyTruthOverflow && algorithmReady && archive.valid && journal.corruptions.length === 0 && trajectory.enforcementSafe && handoffValid;
   const recovery = refreshRequired ? { decision: "resume", reason: "Digest migration requires current exact verifier evidence." } : taskRecoveryDecision(task, journal);
   const decision: ResumeState["decision"] = terminal
     ? "terminal"
@@ -281,6 +377,8 @@ export function inspectTaskResumeState(
             : "resume";
   const reason = terminal
     ? `Task contract is immutable after ${task.trace.outcome}.`
+    : legacyTruthOverflow
+      ? "legacy-task-truth-overflow: automatic continuation is paused; ask the operator to re-intake the original request or provide a compact handoff."
     : journal.corruptions.length > 0
       ? `task journal is corrupt: ${journal.corruptions[0]}`
     : !authorityReady

package/packages/piagent-core/runtime/recovery/semantic-repair-handshake.ts

@@ -11,12 +11,12 @@ import { safeTaskId } from "../../extensions/task-state.js";
 import { isCurrentWorkingTreeDigest } from "../../extensions/working-tree-digest.js";
 
 const HASH = /^[a-f0-9]{64}$/;
-const GLOB = /[?*[\]{}]/;
 const MAX_FILE_BYTES = 256 * 1024;
 export const MAX_SEMANTIC_REPAIR_PATHS = 12;
 export const MAX_SEMANTIC_REPAIR_REVISIONS = 2;
 export const MAX_SEMANTIC_REPAIR_MUTATIONS = 8;
 export const MAX_SEMANTIC_REPAIR_UNSUCCESSFUL_CALLS = 3;
+export const BOUNDED_RECOVERY_CONFLICT_CODE = "post-verifier-model-omission";
 
 type RepairStatus = "reserved" | "authorized" | "active" | "retry-ready" | "verifier-pending" | "passed" | "cancelled" | "locked";
 type RepairPendingCall = {
@@ -105,13 +105,6 @@ function tokenHash(token: string): string {
   return crypto.createHash("sha256").update(token).digest("hex");
 }
 
-function exactDeclaredPath(task: TaskContract, target: string): boolean {
-  return (task.scope ?? []).some((candidate) => {
-    const normalized = normalizePathCandidate(candidate);
-    return Boolean(normalized && !GLOB.test(normalized) && normalized === target);
-  });
-}
-
 function isTestPath(file: string): boolean {
   return /(^|\/)(?:test|tests|spec|__tests__)(\/|$)|[._-](?:test|spec)\.[cm]?[jt]sx?$/i.test(file);
 }
@@ -145,12 +138,13 @@ export function decideSemanticRepairHandshake(input: {
   verifierCurrent: boolean;
 }): SemanticRepairHandshakeDecision {
   const targets = uniquePaths(input.mutationTargets), delta = new Set(uniquePaths(input.currentDeltaPaths));
+  const targetSet = new Set(targets);
   const empty = { authorized: false, conflictCodes: [], eligibleTargets: [], eligiblePaths: [], pathConflictCodes: {} };
   if (!input.verifierCurrent || targets.length === 0 || delta.size === 0) return empty;
-  const candidates = uniquePaths([...delta, ...(input.task.scope ?? []).filter((item) => !GLOB.test(item))]);
+  const candidates = uniquePaths([...delta, ...targets]);
   const pathConflictCodes: Record<string, string[]> = {}, sourceTexts = new Map<string, string>();
   for (const file of candidates) {
-    if (isTestPath(file) || (!delta.has(file) && !exactDeclaredPath(input.task, file))) continue;
+    if (isTestPath(file) || (!delta.has(file) && !targetSet.has(file))) continue;
     const source = readSmallFile(input.cwd, file), conflicts = contentLinkedConflictCodes(input.task, source);
     if (conflicts.length === 0) continue;
     pathConflictCodes[file] = conflicts;
@@ -160,7 +154,7 @@ export function decideSemanticRepairHandshake(input: {
   if (sourcePaths.length === 0) return empty;
   const relatedTests = candidates.filter((file) => (
     isTestPath(file)
-    && (delta.has(file) || exactDeclaredPath(input.task, file))
+    && (delta.has(file) || targetSet.has(file))
     && sourcePaths.some((sourcePath) => acceptanceExecutableTestBinding({
       sourceEntry: { path: sourcePath, text: sourceTexts.get(sourcePath) ?? "" },
       testEntry: { path: file, text: readSmallFile(input.cwd, file) }
@@ -173,6 +167,47 @@ export function decideSemanticRepairHandshake(input: {
   return { authorized: includesConflictingSource && targets.length === eligibleTargets.length, conflictCodes, eligibleTargets, eligiblePaths, pathConflictCodes };
 }
 
+/**
+ * Grant a single fail-closed recovery entry when the model notices an omission
+ * after a current exact verifier has already moved the task into verify.
+ *
+ * This is intentionally narrower than semantic repair: every target must be
+ * an actual current task delta, must have been observed in this task, and must
+ * still carry successful structured-mutation authorship for the exact task,
+ * run, and session. The caller separately enforces CAP-09/12/13 and every
+ * normal protected-path, permission, approval, and exact-target guard before
+ * persisting the reservation; task scope is advisory.
+ */
+export function decideBoundedRecoveryHandshake(input: {
+  task: TaskContract;
+  mutationTargets: string[];
+  currentDeltaPaths: string[];
+  observedChangedPaths: string[];
+  authoredFileDigests: Record<string, string>;
+  verifierCurrent: boolean;
+}): SemanticRepairHandshakeDecision {
+  const targets = uniquePaths(input.mutationTargets);
+  const empty = { authorized: false, conflictCodes: [], eligibleTargets: [], eligiblePaths: [], pathConflictCodes: {} };
+  if (!input.verifierCurrent || targets.length === 0 || targets.length > MAX_SEMANTIC_REPAIR_PATHS) return empty;
+
+  const delta = new Set(uniquePaths(input.currentDeltaPaths));
+  const observed = new Set(uniquePaths(input.observedChangedPaths));
+  const authored = new Set(uniquePaths(Object.entries(input.authoredFileDigests)
+    .filter(([, digest]) => typeof digest === "string" && digest.length > 0)
+    .map(([file]) => file)));
+  const eligibleTargets = targets.filter((file) => delta.has(file) && observed.has(file) && authored.has(file));
+  if (eligibleTargets.length !== targets.length) return empty;
+
+  const pathConflictCodes = Object.fromEntries(targets.map((file) => [file, [BOUNDED_RECOVERY_CONFLICT_CODE]]));
+  return {
+    authorized: true,
+    conflictCodes: [BOUNDED_RECOVERY_CONFLICT_CODE],
+    eligibleTargets: targets,
+    eligiblePaths: targets,
+    pathConflictCodes
+  };
+}
+
 export function semanticRepairStatePath(cwd: string, taskRunId: string): string {
   return path.join(cwd, ".pi", "piagent-state", "semantic-repair", `${safeTaskId(taskRunId)}.json`);
 }
@@ -364,6 +399,7 @@ export function authorizeSemanticRepairCall(input: {
     return { handled: true, allowed: true, bypassPhase: false, state: writeState(input.cwd, state) };
   }
   if (state.status !== "active") return { handled: true, allowed: false, bypassPhase: false, reason: `semantic repair is ${state.status}` };
+  const boundedRecovery = state.conflictCodes.includes(BOUNDED_RECOVERY_CONFLICT_CODE);
   if (input.exactVerifier) {
     if (state.successfulMutationsInRevision < 1) return denyActiveCall(input.cwd, state, "semantic repair verifier requires a successful mutation in this revision", input.recordedAt);
     state.status = "verifier-pending";
@@ -372,6 +408,7 @@ export function authorizeSemanticRepairCall(input: {
     return { handled: true, allowed: true, bypassPhase: false, state: writeState(input.cwd, state) };
   }
   if (input.projectMutation) {
+    if (boundedRecovery) return denyActiveCall(input.cwd, state, "bounded recovery permits exactly one successful mutation before the exact verifier", input.recordedAt);
     const targets = uniquePaths(input.targetPaths);
     if (input.targetExtractionComplete === false) return denyActiveCall(input.cwd, state, "semantic repair mutation targets are not statically complete", input.recordedAt);
     if (targets.length === 0 || targets.some((file) => !state.eligiblePaths.includes(file))) return denyActiveCall(input.cwd, state, "semantic repair mutation is outside the exact persisted grant", input.recordedAt);
@@ -402,6 +439,7 @@ export function pendingSemanticRepairCall(cwd: string, taskRunId: string, toolCa
 export function completeSemanticRepairCall(input: {
   cwd: string; taskRunId: string; toolCallId: string; success: boolean; exitCode?: number;
   currentDigest: string; changedPaths: string[]; retryableFailure?: boolean; correctiveFailure?: boolean; recordedAt?: string;
+  authoredChangedPaths?: string[];
 }): { result: "unmatched" | "opened" | "recorded" | "retry" | "correction" | "passed" | "cancelled" | "locked"; state?: SemanticRepairState } {
   const view = readSemanticRepairState(input.cwd, input.taskRunId), state = view.state;
   if (!view.enforcementSafe || !state?.pending || state.pending.toolCallId !== input.toolCallId) return { result: "unmatched", state };
@@ -410,6 +448,7 @@ export function completeSemanticRepairCall(input: {
     return { result: "locked", state: writeState(input.cwd, state) };
   }
   const pending = state.pending, changed = uniquePaths(input.changedPaths), treeChanged = input.currentDigest !== pending.preDigest;
+  const boundedRecovery = state.conflictCodes.includes(BOUNDED_RECOVERY_CONFLICT_CODE);
   const now = input.recordedAt ?? new Date().toISOString();
   if (!pending.authorized) { state.status = "locked"; state.pending = null; state.updatedAt = now; return { result: "locked", state: writeState(input.cwd, state) }; }
   if (pending.kind === "verifier") {
@@ -418,12 +457,20 @@ export function completeSemanticRepairCall(input: {
     state.failedCalls += 1;
     if (treeChanged || unsuccessful(state) >= MAX_SEMANTIC_REPAIR_UNSUCCESSFUL_CALLS) state.status = "locked";
     else if (input.retryableFailure && !state.transientRetryUsed) { state.transientRetryUsed = true; state.status = "retry-ready"; }
-    else if (input.correctiveFailure && state.revision < MAX_SEMANTIC_REPAIR_REVISIONS) { state.revision += 1; state.successfulMutationsInRevision = 0; state.status = "active"; }
+    else if (!boundedRecovery && input.correctiveFailure && state.revision < MAX_SEMANTIC_REPAIR_REVISIONS) { state.revision += 1; state.successfulMutationsInRevision = 0; state.status = "active"; }
     else state.status = "locked";
     const result = state.status === "retry-ready" ? "retry" : state.status === "active" ? "correction" : "locked";
     return { result, state: writeState(input.cwd, state) };
   }
-  const unexpected = changed.length === 0 || changed.some((file) => !pending.targetPaths.includes(file) || !state.eligiblePaths.includes(file));
+  const authoredChanged = uniquePaths(input.authoredChangedPaths ?? []);
+  const boundedTargetMismatch = boundedRecovery
+    && (changed.length !== pending.targetPaths.length || changed.some((file, index) => pending.targetPaths[index] !== file));
+  const boundedAuthorshipMissing = boundedRecovery
+    && (authoredChanged.length !== changed.length || changed.some((file, index) => authoredChanged[index] !== file));
+  const unexpected = changed.length === 0
+    || changed.some((file) => !pending.targetPaths.includes(file) || !state.eligiblePaths.includes(file))
+    || boundedTargetMismatch
+    || boundedAuthorshipMissing;
   if (treeChanged && (!input.success || unexpected)) { state.status = "locked"; state.pending = null; state.updatedAt = now; return { result: "locked", state: writeState(input.cwd, state) }; }
   if (input.success && treeChanged) {
     if (pending.opensRepair) writeSemanticRepairOrigin(input.cwd, state, input.currentDigest, now);

package/packages/piagent-core/runtime/recovery/semantic-repair-runtime.ts

@@ -3,8 +3,10 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { TaskContract } from "../../extensions/guard-types.ts";
 import type { TrajectorySyncResult } from "../trajectory/trajectory-runtime.ts";
 import {
+  BOUNDED_RECOVERY_CONFLICT_CODE,
   authorizeSemanticRepairCall,
   completeSemanticRepairCall,
+  decideBoundedRecoveryHandshake,
   decideSemanticRepairHandshake,
   pendingSemanticRepairCall,
   readSemanticRepairState,
@@ -31,6 +33,7 @@ export type SemanticRepairCompletionMetadata = {
   exitCode: number;
   currentWorkingTreeDigest: string;
   changedPaths: string[];
+  authoredChangedPaths?: string[];
   retryableFailure: boolean; correctiveFailure: boolean;
 };
 
@@ -100,6 +103,52 @@ export class SemanticRepairRuntime {
     return true;
   }
 
+  prepareBoundedRecovery(input: {
+    ctx: ExtensionContext; task: TaskContract; event: ToolEvent; currentDigest: string;
+    currentDeltaPaths: string[]; observedChangedPaths: string[];
+    authoredFileDigests: Record<string, string>; targetPaths: string[]; verifierCurrent: boolean;
+  }): boolean {
+    // This path is a one-shot CAP-12 bridge, not CAP-13's multi-revision
+    // semantic-repair protocol. Any durable state, including a cancelled or
+    // interrupted reservation, consumes the task-run grant and fails closed.
+    if (readSemanticRepairState(input.ctx.cwd, input.task.taskRunId).status !== "missing"
+      || semanticRepairStateRequired(input.ctx.cwd, input.task.taskRunId)) return false;
+    const decision = decideBoundedRecoveryHandshake({
+      task: input.task,
+      mutationTargets: input.targetPaths,
+      currentDeltaPaths: input.currentDeltaPaths,
+      observedChangedPaths: input.observedChangedPaths,
+      authoredFileDigests: input.authoredFileDigests,
+      verifierCurrent: input.verifierCurrent
+    });
+    if (!decision.authorized) return false;
+    const toolCallId = String(input.event.toolCallId);
+    const reserved = reserveSemanticRepairCall({
+      cwd: input.ctx.cwd,
+      task: input.task,
+      sessionId: input.ctx.sessionManager.getSessionId(),
+      toolCallId,
+      toolName: input.event.toolName,
+      currentDigest: input.currentDigest,
+      decision,
+      targetPaths: input.targetPaths,
+      recordedAt: this.dependencies.now()
+    });
+    if (!reserved.reserved) return false;
+    this.reservationTokens.set(
+      this.reservationKey(input.ctx.cwd, input.task.taskRunId, toolCallId),
+      reserved.reservationToken!
+    );
+    this.dependencies.trace(input.ctx, input.task, {
+      event: "bounded_recovery_repair_reserved",
+      workingTreeDigest: input.currentDigest,
+      reasonCode: BOUNDED_RECOVERY_CONFLICT_CODE,
+      eligiblePaths: decision.eligiblePaths,
+      targetCount: input.targetPaths.length
+    });
+    return true;
+  }
+
   reservedCallMatches(input: {
     cwd: string; taskRunId: string; sessionId: string; toolCallId: string;
     toolName: string; currentDigest: string; targetPaths: string[];
@@ -131,7 +180,8 @@ export class SemanticRepairRuntime {
     if (view.state.successfulMutations > 0 && !semanticRepairOriginMatches(cwd, view.state)) return "semantic repair durable origin is missing or invalid";
     if (view.state.status === "passed") return;
     if (view.state.successfulMutations === 0 && view.state.pending === null && !semanticRepairStateRequired(cwd, taskRunId)) return;
-    return `semantic repair exact final verifier is not satisfied (${view.state.status})`;
+    const label = view.state.conflictCodes.includes(BOUNDED_RECOVERY_CONFLICT_CODE) ? "bounded recovery" : "semantic repair";
+    return `${label} exact final verifier is not satisfied (${view.state.status})`;
   }
 
   complete(
@@ -148,13 +198,16 @@ export class SemanticRepairRuntime {
       exitCode: metadata.exitCode,
       currentDigest: metadata.currentWorkingTreeDigest,
       changedPaths: metadata.changedPaths,
+      authoredChangedPaths: metadata.authoredChangedPaths,
       retryableFailure: metadata.retryableFailure,
       correctiveFailure: metadata.correctiveFailure,
       recordedAt: this.dependencies.now()
     });
     if (completion.result === "unmatched") return;
     this.dependencies.trace(ctx, task, {
-      event: completion.result === "opened" ? "semantic_contradiction_repair_opened" : `semantic_repair_${completion.result}`,
+      event: completion.state?.conflictCodes.includes(BOUNDED_RECOVERY_CONFLICT_CODE)
+        ? `bounded_recovery_repair_${completion.result}`
+        : completion.result === "opened" ? "semantic_contradiction_repair_opened" : `semantic_repair_${completion.result}`,
       toolName: event.toolName,
       revision: completion.state?.revision,
       successfulMutations: completion.state?.successfulMutations,