@piagent/platform 1.6.1 → 1.7.1

package/packages/piagent-core/runtime/recovery/recovery-policy.ts

@@ -1,46 +1,15 @@
 import type { FailureClassification } from "../../extensions/failure-types.ts";
 import { failureClassificationValidationErrors } from "../../extensions/failure-types.ts";
+import {
+  RECOVERY_ACTIONS, RECOVERY_CEILINGS, RECOVERY_POLICY_VERSION, RECOVERY_REASON_CODES, recoveryDecisionValidationErrors
+} from "../../extensions/recovery-decision-validation.ts";
 import type { TrajectoryPhase } from "../trajectory/trajectory-types.ts";
 
-export const RECOVERY_POLICY_VERSION = "recovery-v1" as const;
-export const RECOVERY_ACTIONS = Object.freeze(["repair", "retry", "fresh-session", "ask-operator", "handoff", "blocked"] as const);
-export const RECOVERY_CEILINGS = Object.freeze({
-  sourceRepairPasses: 1,
-  transientVerifierRetries: 1,
-  unknownDiagnosticPasses: 1,
-  providerRetries: 1
-} as const);
+export { RECOVERY_ACTIONS, RECOVERY_CEILINGS, RECOVERY_POLICY_VERSION, RECOVERY_REASON_CODES, recoveryDecisionValidationErrors };
 
 export type RecoveryAction = typeof RECOVERY_ACTIONS[number];
 export type RecoveryDisposition = "scheduled" | "failed" | "succeeded" | "declined";
-export type RecoveryReasonCode =
-  | "feature-disabled"
-  | "invalid-input"
-  | "terminal-phase"
-  | "handoff-already-observed"
-  | "no-failure"
-  | "stale-verifier-evidence"
-  | "source-repair-eligible"
-  | "dependency-mutation-not-authorized"
-  | "read-only-task"
-  | "repair-ceiling-reached"
-  | "repeated-hypothesis"
-  | "operator-environment-action"
-  | "provider-transient-retry"
-  | "provider-retry-exhausted"
-  | "permission-expansion-forbidden"
-  | "protected-path-forbidden"
-  // Legacy persisted recovery records may still carry this value. New runtime
-  // decisions never emit it because task scope is advisory.
-  | "scope-replan-required"
-  | "transient-verifier-retry"
-  | "transient-retry-unavailable"
-  | "unknown-diagnostic-pass"
-  | "unknown-diagnostic-exhausted"
-  | "global-continuation-budget-exhausted"
-  | "repeated-progress-signature"
-  | "continuation-journal-unavailable"
-  | "manual-lifecycle-handoff";
+export type RecoveryReasonCode = typeof RECOVERY_REASON_CODES[number];
 
 export type RecoveryHistoryEntry = {
   taskId: string;
@@ -71,6 +40,7 @@ export type RecoveryPolicyInput = {
   exactVerifierAvailable?: boolean;
   currentTreeMatchesEvidence?: boolean;
   dependencyMutationAuthorized?: boolean;
+  independentDisposition?: "cancelled" | "reconcile" | "unsupported" | "halt" | "approval";
 };
 
 export type RecoveryDecision = {
@@ -96,10 +66,20 @@ export type RecoveryDecision = {
   hypothesisRef: string | null;
 };
 
-const HASH = /^[a-f0-9]{64}$/;
 const REF = /^[a-z0-9][a-z0-9:._-]{0,255}$/i;
 const COUNTED_DISPOSITIONS = new Set<RecoveryDisposition>(["scheduled", "failed", "succeeded"]);
 
+export function applyProofCapabilityHandoff(selected: RecoveryDecision, missing: string[] = [], hasIndependentRecovery = false): RecoveryDecision {
+  let reason: RecoveryReasonCode | undefined;
+  if (selected.failureCategory === "unknown" && !hasIndependentRecovery && selected.action !== "blocked"
+    && missing.some(item => /^critical acceptance evidence independent-required\b/i.test(item))) reason = "independent-acceptance-proof-required";
+  else if (selected.failureCategory === "unknown" && !hasIndependentRecovery && selected.action !== "blocked"
+    && missing.some(item => /^critical acceptance evidence source-proof-required\b/i.test(item))) reason = "source-acceptance-proof-required";
+  else if (missing.some(item => /^critical acceptance evidence adapter-unresolved\b/i.test(item))) reason = "deterministic-adapter-proof-required";
+  return reason ? { ...selected, action: "handoff", continuation: "none", nextPhase: null,
+    sourceMutationAllowed: false, reasonCodes: [reason] } : selected;
+}
+
 function validIdentity(input: RecoveryPolicyInput): boolean {
   return Boolean(
     input.task?.taskId?.trim()
@@ -181,8 +161,7 @@ function repairDecision(input: RecoveryPolicyInput): RecoveryDecision {
 }
 
 export function selectRecoveryDecision(input: RecoveryPolicyInput): RecoveryDecision {
-  const invalidClassification = failureClassificationValidationErrors(input.classification).length > 0
-    || !HASH.test(String(input.classification?.evidenceDigest ?? ""));
+  const invalidClassification = failureClassificationValidationErrors(input.classification).length > 0;
   if (!validIdentity(input) || invalidClassification) return decision(input, "blocked", ["invalid-input"]);
   if (!input.featureEnabled) return decision(input, "handoff", ["feature-disabled"]);
   if (input.currentPhase === "terminal") return decision(input, "blocked", ["terminal-phase"]);
@@ -194,6 +173,15 @@ export function selectRecoveryDecision(input: RecoveryPolicyInput): RecoveryDeci
   if (input.classification.category === "scope-protected-path") {
     return decision(input, "handoff", ["protected-path-forbidden"]);
   }
+  const independentCategories = { cancelled: "unknown", reconcile: "environment", unsupported: "unknown", halt: "unknown", approval: "environment" };
+  if (input.independentDisposition !== undefined && (typeof input.independentDisposition !== "string"
+    || !Object.hasOwn(independentCategories, input.independentDisposition)
+    || independentCategories[input.independentDisposition] !== input.classification.category)) return decision(input, "blocked", ["invalid-input"]);
+  if (input.independentDisposition === "cancelled") return decision(input, "handoff", ["independent-execution-cancelled"]);
+  if (input.independentDisposition === "reconcile") return decision(input, "ask-operator", ["independent-execution-reconciliation-required"], { continuation: "operator" });
+  if (input.independentDisposition === "unsupported") return decision(input, "handoff", ["independent-verifier-unsupported"]);
+  if (input.independentDisposition === "halt") return decision(input, "handoff", ["independent-verification-halted"]);
+  if (input.independentDisposition === "approval") return decision(input, "ask-operator", ["operator-environment-action"], { continuation: "operator" });
 
   const counts = countsFor(input);
   if (input.currentTreeMatchesEvidence === false && input.exactVerifierAvailable === true) {

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

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { currentWorkspaceRevisionDigest } from "../../extensions/workspace-revision.js";
 
 import type { TaskContract } from "../../extensions/guard-types.ts";
 import { allVerifyCommandsPassCurrentTree } from "../../extensions/task-contract-view.js";
@@ -7,7 +8,7 @@ import { taskDigestMigrationArchiveStatus, workingTreeSnapshot, workingTreeSnaps
 import { workingTreeEvidenceDigest } from "../../extensions/task-lifecycle.js";
 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 { handoffIdentityMatchesTask, 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";
@@ -312,6 +313,7 @@ export function inspectTaskResumeState(
   options: { protectedPaths?: string[] } = {}
 ): ResumeState {
   const currentTreeDigest = workingTreeEvidenceDigest(currentDigests);
+  const workspaceRevisionDigest = currentWorkspaceRevisionDigest(cwd);
   const authorityPolicy = inspectTaskAuthorityResumePolicy(cwd, task);
   const archive = taskDigestMigrationArchiveStatus(cwd, task);
   const legacyTruthOverflow = task.trace.outcome === "pending" && legacyTaskTruthOverflowsAutomaticResume(task);
@@ -328,7 +330,7 @@ export function inspectTaskResumeState(
   try {
     const handoff = readHandoffProjection(cwd, task.taskRunId);
     handoffExists = Boolean(handoff);
-    if (handoff && (handoff.identity.taskId !== task.taskId || handoff.identity.taskRunId !== task.taskRunId)) {
+    if (handoff && !handoffIdentityMatchesTask(handoff.identity, task)) {
       handoffValid = false;
       warnings.push("handoff identity conflicts with the task contract");
     }
@@ -337,13 +339,14 @@ export function inspectTaskResumeState(
     warnings.push(`handoff projection is invalid: ${error instanceof Error ? error.message : String(error)}`);
   }
   const passingEvidence = task.verifyEvidence.filter((evidence) => evidence.observed === true && evidence.matchedProfileCommand === true && evidence.exitCode === 0);
-  const invalidatedVerifierCommands = strings(passingEvidence.filter((evidence) => !isCurrentWorkingTreeDigest(evidence.workingTreeDigest) || evidence.workingTreeDigest !== currentTreeDigest).map((evidence) => evidence.command), 50);
-  const verifierEvidenceCurrent = algorithmReady && !refreshRequired && (task.changeMode === "read-only" || allVerifyCommandsPassCurrentTree(task, currentTreeDigest));
+  const invalidatedVerifierCommands = strings(passingEvidence.filter((evidence) => !isCurrentWorkingTreeDigest(evidence.workingTreeDigest) || evidence.workingTreeDigest !== currentTreeDigest
+    || !workspaceRevisionDigest || evidence.preWorkspaceRevisionDigest !== workspaceRevisionDigest || evidence.workspaceRevisionDigest !== workspaceRevisionDigest).map((evidence) => evidence.command), 50);
+  const verifierEvidenceCurrent = algorithmReady && !refreshRequired && (task.changeMode === "read-only" || allVerifyCommandsPassCurrentTree(task, currentTreeDigest, workspaceRevisionDigest));
   const staleVerifierEvidence = refreshRequired || (invalidatedVerifierCommands.length > 0 && !verifierEvidenceCurrent);
   const invalidatedFiles = staleVerifierEvidence
     ? staleVerifierFiles(cwd, task, passingEvidence, currentDigests, currentTreeDigest, options.protectedPaths ?? null)
     : { files: [], known: true };
-  if (staleVerifierEvidence) warnings.push("working tree changed after the latest passing verifier; prior evidence is stale");
+  if (staleVerifierEvidence) warnings.push("working tree or workspace baseline changed, or the prior verifier lacks baseline binding; prior evidence is stale");
   const latest = journal.checkpoints.at(-1);
   const latestCheckpoint = latest ? {
     checkpointId: String(latest.checkpointId ?? "checkpoint"),

package/packages/piagent-core/runtime/registration/activity-inspector-command.ts

@@ -143,7 +143,8 @@ export function registerActivityInspector(pi: ExtensionAPI, dependencies: Inspec
       runtimeInstanceId: WEBUI_RUNTIME_INSTANCE_REF,
       eventCursor: events.currentCursor(),
       resyncRequired: events.resyncRequired(),
-      eventReplay: events.retention()
+      eventReplay: events.retention(),
+      operationLiveness: typeof ctx.isIdle === "function" ? ctx.isIdle() ? "idle" : "running" : "unknown"
     });
     cached.set(key, { at: Date.now(), view });
     return view;

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

@@ -1,8 +1,15 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { stageContextDelivery } from "../context/context-delivery.ts";
 import { semanticCompactionCancelled } from "../session/system-prompt.ts";
+import { WORKFLOW_IDS, resolveWorkflowId, type WorkflowId } from "../workflows/webui-workflow.ts";
 
 type ExtensionContext = any;
+const WORKFLOW_USAGE = WORKFLOW_IDS.join("|");
+
+export function parsePreflightWorkflow(raw: string): WorkflowId {
+  const first = String(raw ?? "").trim().split(/\s+/)[0];
+  return resolveWorkflowId(first) ?? "task";
+}
 
 export function registerContextCommands(pi: ExtensionAPI, deps: Record<string, any>): any {
   const {
@@ -226,14 +233,11 @@ export function registerContextCommands(pi: ExtensionAPI, deps: Record<string, a
       `lowConfidencePacks: ${report.metrics.lowConfidencePacks}/${report.sample.contextPacks}`,
       `editRecovery: ${report.metrics.editRecoveryContextCount}/${report.metrics.editRecoveryFailures} failures returned context; ${report.metrics.editRecoverySuppressedFailures} suppressed; ${report.metrics.editRecoveryEstimatedTokens} estimated tokens; classification coverage ${formatPercent(report.metrics.editRecoveryFailureEvidenceCoverage)}`,
       `taskEfficiency: ${taskEfficiency ? `${taskEfficiency.solver.route}; verify=${taskEfficiency.verification.attempts}; outcome=${taskEfficiency.outcome.task}` : "no active task"}`,
+      ...(taskEfficiency ? [`taskUsage: ${taskEfficiency.usageAccounting.status}; observed SDK tokens=${formatCount(taskEfficiency.exactUsage.tokens)}; billed cost=unknown; requests=${taskEfficiency.usageAccounting.requests}`] : []),
       ...report.recommendations.map((recommendation) => `- ${recommendation}`)
     ].join("\n"), { ...report, taskEfficiency });
   }
 
-  function parsePreflightWorkflow(raw: string): string {
-    return raw.match(/\b(?:scout|be-to-fe|review|plan|platform-improve|task)\b/i)?.[0]?.toLowerCase() ?? "task";
-  }
-
   function compactCurrentSession(ctx: ExtensionContext): void {
     const sessionId = ctx.sessionManager.getSessionId();
     const instructions = semanticCompactionInstructions(ctx.cwd, sessionId);
@@ -328,8 +332,8 @@ export function registerContextCommands(pi: ExtensionAPI, deps: Record<string, a
         "pack: /context pack <task or symbol>",
         "impact: /context impact [changed files]",
         "efficiency: /context efficiency",
-        "preflight: /context preflight [task|scout|be-to-fe|review|plan]",
-        "compact: /context compact [task|scout|be-to-fe]",
+        `preflight: /context preflight [${WORKFLOW_USAGE}]`,
+        `compact: /context compact [${WORKFLOW_USAGE}]`,
         "legacy: /piagent-context | /context-index | /task-preflight"
       ].join("\n"));
       return;
@@ -380,8 +384,8 @@ export function registerContextCommands(pi: ExtensionAPI, deps: Record<string, a
         "pack: /context pack <task or symbol>",
         "impact: /context impact [changed files]",
         "efficiency: /context efficiency",
-        "preflight: /context preflight [task|scout|be-to-fe|review|plan]",
-        "compact: /context compact [task|scout|be-to-fe]",
+        `preflight: /context preflight [${WORKFLOW_USAGE}]`,
+        `compact: /context compact [${WORKFLOW_USAGE}]`,
         "legacy: /piagent-context | /context-index | /task-preflight"
       ].join("\n"));
       return;

package/packages/piagent-core/runtime/registration/operator-catalogs.ts

@@ -1,3 +1,5 @@
+import { WORKFLOW_IDS, WORKFLOW_OPTIONS } from "../workflows/webui-workflow.ts";
+
 export const WORKFLOW_COMMAND_EXCLUSIONS = Object.freeze([
   "implement",
   "audit",
@@ -15,16 +17,9 @@ export const ONBOARDING_COMMAND_ACTIONS = Object.freeze([
   "help"
 ]);
 
-export const FRESH_COMMAND_ACTIONS = Object.freeze([
-  "task",
-  "scout",
-  "be-to-fe",
-  "help"
-]);
+export const FRESH_COMMAND_ACTIONS = Object.freeze([...WORKFLOW_IDS, "help"]);
 
 export const FRESH_COMMAND_HELP = Object.freeze([
   "namespace: /fresh",
-  "/fresh task <request>",
-  "/fresh scout <read-only request>",
-  "/fresh be-to-fe <BE spec/change + FE outcome>"
+  ...WORKFLOW_OPTIONS.map((option) => `/fresh ${option.id} ${option.argumentHint}`)
 ]);

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

@@ -1,11 +1,12 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { stageContextDelivery } from "../context/context-delivery.ts";
 import { formatContextEfficiencyReport } from "../context/context-efficiency-format.ts";
+import { WORKFLOW_IDS } from "../workflows/webui-workflow.ts";
+import { registerSessionWaitTool } from "./session-wait-tool.ts";
 
 type PiagentToolGroup = any;
 type TechStackManifest = any;
 
-
 export function registerPolicyTools(pi: ExtensionAPI, deps: Record<string, any>): void {
   const {
     PIAGENT_TOOL_NAMES, READ_ONLY_TOOL_NAMES, StringEnum, Type, activateToolGroups, activeSessionTask,
@@ -20,6 +21,7 @@ export function registerPolicyTools(pi: ExtensionAPI, deps: Record<string, any>)
     resolvePermissionProfile, resolveRuntimePolicy, retrievalKey, runtimeState, searchContextIndexV2,
     techStackPath, telemetry, toolRegistryConfig, verifierCommandInstructions
   } = deps;
+  registerSessionWaitTool(pi, Type);
   registerPiagentTool(pi, {
     name: "piagent_tools",
     label: "Piagent Tool Loader",
@@ -30,7 +32,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", "source", "knowledge", "onboarding", "usage"] as const), { minItems: 1 })
+      groups: Type.Array(StringEnum(["intake", "governance", "task", "waiting", "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[];
@@ -481,7 +483,7 @@ export function registerPolicyTools(pi: ExtensionAPI, deps: Record<string, any>)
       "Do not paste mandatory-flow boilerplate into the task request; use platform workflow commands instead."
     ],
     parameters: Type.Object({
-      workflow: Type.Optional(StringEnum(["task", "scout", "be-to-fe", "review", "plan", "platform-improve"] as const)),
+      workflow: Type.Optional(StringEnum(WORKFLOW_IDS)),
       inputChars: Type.Optional(Type.Number({ minimum: 0 }))
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {

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

@@ -1,7 +1,9 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { WORKFLOW_IDS, resolveWorkflowId } from "../workflows/webui-workflow.ts";
 
 type ExtensionContext = any;
 type TaskContract = any;
+const WORKFLOW_USAGE = WORKFLOW_IDS.join("|");
 
 export function registerSessionCommands(pi: ExtensionAPI, deps: Record<string, any>): any {
   const {
@@ -89,8 +91,8 @@ export function registerSessionCommands(pi: ExtensionAPI, deps: Record<string, a
         "namespace: /usage",
         "live: /usage live",
         "history: /usage history",
-        "preflight: /usage preflight [task|scout|be-to-fe]",
-        "compact: /usage compact [task|scout|be-to-fe]",
+        `preflight: /usage preflight [${WORKFLOW_USAGE}]`,
+        `compact: /usage compact [${WORKFLOW_USAGE}]`,
         "logs: /usage logs",
         "efficiency: /usage efficiency",
         "native exact session: /session",
@@ -186,8 +188,7 @@ export function registerSessionCommands(pi: ExtensionAPI, deps: Record<string, a
         { value: "current", label: "Current session", description: "Name, id, file, model", recommended: true },
         { value: "name", label: "Set name", description: "Use Pi native /name <task name>" },
         { value: "resume", label: "Resume help", description: "Commands for continuing old sessions" },
-        { value: "fresh-task", label: "Fresh task", description: "Use /fresh task <request>" },
-        { value: "fresh-scout", label: "Fresh scout", description: "Use /fresh scout <request>" },
+        { value: "fresh", label: "Fresh workflow", description: "Use /fresh <workflow> <request>" },
         { value: "usage", label: "Usage", description: "Current context/session usage" },
         { value: "help", label: "Help", description: "Show typed forms" }
       ], "current");
@@ -207,7 +208,7 @@ export function registerSessionCommands(pi: ExtensionAPI, deps: Record<string, a
         "session helpers:",
         "current: /usage live or Pi native /session",
         "name: Pi native /name <task/session name>",
-        "fresh: /fresh task|scout|be-to-fe <request>",
+        `fresh: /fresh ${WORKFLOW_USAGE} <request>`,
         "resume: Pi native /resume or /session",
         "legacy: /piagent-session | /setname | /fresh-task | /fresh-scout | /fresh-be-to-fe"
       ].join("\n"));
@@ -231,8 +232,9 @@ export function registerSessionCommands(pi: ExtensionAPI, deps: Record<string, a
     }
     if (["fresh", "new"].includes(action)) {
       const next = commandArgs(rest);
-      const workflow = next.action === "be-to-fe" ? "be-to-fe" : next.action === "scout" ? "scout" : "task";
-      await startFreshWorkflow(workflow, next.rest, ctx);
+      const workflow = resolveWorkflowId(next.action);
+      const request = workflow ? next.rest : [next.action, next.rest].filter(Boolean).join(" ");
+      await startFreshWorkflow(workflow ?? "task", request, ctx);
       return;
     }
     if (["fresh-task", "task"].includes(action)) {

package/packages/piagent-core/runtime/registration/session-wait-tool.ts

@@ -0,0 +1,54 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { registerPiagentTool } from "./extension-registration.ts";
+import { MAX_SESSION_WAIT_SECONDS, SESSION_WAIT_ENTRY, SessionWaitRuntime } from "../tools/session-wait.ts";
+
+/** Reuse the host session journal; pending waits never schedule work on resume. */
+export function registerSessionWaitTool(pi: ExtensionAPI, Type: any): void {
+  const waits = new SessionWaitRuntime();
+  const key = (ctx: ExtensionContext) => `${ctx.cwd}\0${ctx.sessionManager.getSessionId()}`;
+  for (const event of ["session_before_switch", "session_before_fork", "session_before_tree", "session_shutdown"] as const) {
+    pi.on(event, async (_event: unknown, ctx: ExtensionContext) => { waits.interrupt(key(ctx)); });
+  }
+  registerPiagentTool(pi, {
+    name: "piagent_wait",
+    label: "Wait until the next check",
+    description: "Wait 1–3600 seconds within this open session without polling or calling a model. Use when the next useful check is later. No background scheduling, condition monitoring, command execution, or completion evidence. Cancel to interrupt.",
+    promptSnippet: "For a future check, wait once until it is useful; avoid repeated unchanged status checks.",
+    promptGuidelines: [
+      "Use a process/event wait tool when it can wake on completion; otherwise choose the next useful check time within the task deadline. Call this tool alone so cancellation can stop its batch.",
+      "Do independent work first. Keep the next check explicit; waiting never completes a task or proves an external action succeeded.",
+      "This requires an open running session. After interruption or restart, reconcile pending work before deciding to wait again; never replay uncertain external actions."
+    ],
+    parameters: Type.Object({
+      seconds: Type.Number({ minimum: 1, maximum: MAX_SESSION_WAIT_SECONDS, multipleOf: 1 }),
+      nextCheck: Type.String({ minLength: 1, maxLength: 240, description: "The specific observation to make when the wait ends, not a command to execute automatically." })
+    }),
+    async execute(toolCallId: string, params: { seconds: number; nextCheck: string }, signal: AbortSignal | undefined,
+      _onUpdate: unknown, ctx: ExtensionContext) {
+      if (!Number.isInteger(params.seconds) || params.seconds < 1 || params.seconds > MAX_SESSION_WAIT_SECONDS
+        || typeof params.nextCheck !== "string" || !params.nextCheck.trim() || params.nextCheck.length > 240) {
+        throw new Error("Use a bounded wait of 1–3600 seconds and a nonempty next check of at most 240 characters.");
+      }
+      const sessionId = ctx.sessionManager.getSessionId();
+      const prior = ctx.sessionManager.getBranch().some((entry: any) => entry.type === "custom"
+        && entry.customType === SESSION_WAIT_ENTRY && entry.data?.toolCallId === toolCallId);
+      if (prior) throw new Error("This wait call is already journaled. Reconcile its result; do not replay it after resume.");
+      if (signal?.aborted) throw new Error("Wait interrupted before starting; no follow-up was scheduled.");
+      const startedAt = new Date().toISOString();
+      const identity = { toolCallId, sessionId, startedAt, seconds: params.seconds };
+      pi.appendEntry(SESSION_WAIT_ENTRY, { ...identity, outcome: "pending" });
+      const result = await waits.wait(key(ctx), params.seconds, signal);
+      // Never append a receipt to a different session after a switch.
+      if (ctx.sessionManager.getSessionId() === sessionId) {
+        pi.appendEntry(SESSION_WAIT_ENTRY, { ...identity, ...result });
+      }
+      return {
+        terminate: result.outcome === "interrupted",
+        content: [{ type: "text", text: result.outcome === "elapsed"
+          ? `Wait elapsed. Next check: ${params.nextCheck}. No condition was checked; task completion and external outcomes remain unverified.`
+          : `Wait interrupted. Pending next check: ${params.nextCheck}. No follow-up was scheduled; reconcile current state before continuing.` }],
+        details: { ...identity, ...result, conditionChecked: false, followUpScheduled: false }
+      };
+    }
+  });
+}

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

@@ -1,4 +1,8 @@
+import { retainFocusedVerification } from "../../extensions/acceptance-focused-verification.js";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { completionPreparationCurrent } from "../verification/completion-preparation.ts";
+import { apiBaselineCriterionEvidence as apiBaselineEvidence } from "../verification/acceptance-api-baseline.js";
+import { currentWorkspaceRevisionDigest } from "../../extensions/workspace-revision.js";
 import { durableContextEvidenceEntries, isRuntimeOwnedContextEvidenceEntry } from "../../extensions/context-evidence.js";
 import { mergeObservedTaskContext } from "../../extensions/task-contract-view.js";
 import { buildHandoffProjection, writeHandoffProjection } from "../recovery/handoff-projection.ts";
@@ -20,7 +24,7 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
     compactTaskDetails, contextBudgetConfig, evaluateTaskGate, findMatchingObservedBashResult, loadProfileFromContext,
     normalizeRelative, nowIso, observedBashLedgerPath, policy, readObservedBashResults,
     readTask, recordCompletionAudit, recordVerificationCheckpoint, redactForStorage, redactText, runtimeState,
-    refreshAcceptanceReceipt, registerPiagentTool, resolveRuntimePolicy, runtimeLifecycleMode, semanticRepairCompletionBlock, taskChangedFileEvidence,
+    refreshAcceptanceReceipt, registerPiagentTool, resolveRuntimePolicy, runtimeLifecycleMode, semanticRepairCompletionBlock, taskAcceptanceEvidenceFiles, taskChangedFileEvidence,
     uniqueStrings, verifierCommandInstructions, workingTreeEvidenceDigest, workingTreeSnapshot, writeTask
   } = deps;
   registerPiagentTool(pi, {
@@ -174,16 +178,19 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
           matchedProfileCommand,
           workingTreeDigest
         });
-        task.verifyEvidence = task.verifyEvidence.slice(-100);
+        task.verifyEvidence = policy?.finalGate?.acceptanceProofMode === "diagnostic"
+          ? retainFocusedVerification(task.verifyEvidence, workingTreeDigest, currentWorkspaceRevisionDigest(ctx.cwd))
+          : task.verifyEvidence.slice(-100);
       }
-      const hasChanges = taskChangedFileEvidence(ctx.cwd, task, currentDigests).expected.length > 0;
-      const allPassing = matchedProfileCommand && hasChanges && allVerifyCommandsPassCurrentTree(task, workingTreeDigest);
-      if (matchedProfileCommand && hasChanges) {
+      const taskLocalDelta = taskChangedFileEvidence(ctx.cwd, task, currentDigests).expected;
+      const verificationCanSettleSourceTask = taskLocalDelta.length > 0 || task.mutationPolicy === "allowed";
+      const allPassing = matchedProfileCommand && verificationCanSettleSourceTask && allVerifyCommandsPassCurrentTree(task, workingTreeDigest, currentWorkspaceRevisionDigest(ctx.cwd));
+      if (matchedProfileCommand && verificationCanSettleSourceTask) {
         applyRuntimeLifecycleObservation(task, allPassing ? "verification-complete" : "verification-pending", nowIso());
       }
       const acceptance = refreshAcceptanceReceipt(task, {
-        cwd: ctx.cwd,
-        changedFiles: taskChangedFileEvidence(ctx.cwd, task, currentDigests).expected,
+        cwd: ctx.cwd, apiBaselineEvidence,
+        changedFiles: taskAcceptanceEvidenceFiles(ctx.cwd, task, currentDigests, taskLocalDelta),
         currentWorkingTreeDigest: workingTreeDigest
       });
       task.acceptanceReceipt = acceptance.task.acceptanceReceipt;
@@ -304,6 +311,9 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
           isError: true
         };
       }
+      if (params.outcome === "completed" && !completionPreparationCurrent(await deps.prepareIndependentAcceptance?.(ctx, task))) {
+        return { content: [{ type: "text", text: "Trace refused: independent verification stopped with the session." }], isError: true };
+      }
       const finalFileDigests = workingTreeSnapshot(ctx.cwd) as Record<string, string>;
       let nextTask: TaskContract = {
         ...task,
@@ -321,8 +331,8 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
         }
       };
       nextTask = refreshAcceptanceReceipt(nextTask, {
-        cwd: ctx.cwd,
-        changedFiles: nextTask.changedFiles,
+        cwd: ctx.cwd, apiBaselineEvidence,
+        changedFiles: taskAcceptanceEvidenceFiles(ctx.cwd, nextTask, finalFileDigests, nextTask.changedFiles),
         currentWorkingTreeDigest: workingTreeEvidenceDigest(finalFileDigests)
       }).task as TaskContract;
       let gate = evaluateTaskGate(ctx.cwd, nextTask, policy, {
@@ -334,7 +344,7 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
         ? 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"))) {
+      if (params.outcome === "completed" && (semanticBlock || ((runtime.finalGate === "enforce" || gate.acceptanceProof?.mode === "diagnostic") && gate.decision === "fail"))) {
         const blockedTrace = {
           taskId: nextTask.taskId,
           taskRunId: nextTask.taskRunId,
@@ -371,6 +381,10 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
         };
       }
 
+      if (gate.acceptanceProof?.mode === "diagnostic" && gate.acceptanceProof.pendingCriterionIds.length > 0) {
+        nextTask.trace.notes = [nextTask.trace.notes,
+          `Diagnostic acceptance: ${gate.acceptanceProof.pendingCriterionIds.length} criteria remain unproved; no quality claim.`].filter(Boolean).join("\n");
+      }
       let handoffPreview: any;
       try {
         handoffPreview = buildHandoffProjection(ctx.cwd, nextTask, {
@@ -398,6 +412,7 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
         taskRunId: nextTask.taskRunId,
         sessionId: nextTask.sessionId,
         event: "trace_record",
+        ...(gate.acceptanceProof?.mode === "diagnostic" ? { acceptanceProof: gate.acceptanceProof } : {}),
         outcome: params.outcome,
         changedFiles: nextTask.changedFiles,
         friction: nextTask.trace.friction,
@@ -412,6 +427,7 @@ export function registerTaskCompletionTools(pi: ExtensionAPI, deps: Record<strin
         phase: params.failedAt ?? "review",
         evidence: {
           outcome: params.outcome,
+          ...(gate.acceptanceProof?.mode === "diagnostic" ? { acceptanceProof: gate.acceptanceProof } : {}),
           changedFiles: written.changedFiles,
           failedAt: written.failedAt,
           ruledOut: written.ruledOut
@@ -428,7 +444,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(", ")})` : ""}` }],
+        content: [{ type: "text", text: `Trace recorded for ${nextTask.taskId}: ${params.outcome}${gate.acceptanceProof?.mode === "diagnostic" && gate.acceptanceProof.pendingCriterionIds.length > 0 ? " (diagnostic acceptance; no quality claim)" : ""}${gate.decision === "fail" ? ` (gate warning: missing ${gate.missing.join(", ")})` : ""}` }],
         details: { task: compactTaskDetails(written), gate, completionReceipt: buildCompletionReceiptView(written, { cwd: ctx.cwd, gate }) }
       };
     }

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

@@ -0,0 +1,45 @@
+export function conditionalMutationPreTaskContext<ContextEntry extends { path?: string }>(
+  context: ContextEntry[],
+  scope: string[],
+  enabled: boolean,
+  matchesAnyPath: (candidate: string, patterns: string[]) => boolean
+): ContextEntry[] {
+  if (!enabled) return context;
+  return context.filter((item) => typeof item.path === "string" && matchesAnyPath(item.path, scope));
+}
+
+export function taskStartLifecycleGuidance(
+  lifecycleMode: string,
+  mutationPolicy: string,
+  taskId: string
+): string {
+  if (lifecycleMode === "automatic-readonly") {
+    return "Runtime records targeted reads and final completion automatically. Stay read-only and report cited evidence.";
+  }
+  if (lifecycleMode === "assisted-readonly") {
+    return "Runtime records read-only evidence automatically; complete only the explicit evidence-review step before handoff.";
+  }
+  if (mutationPolicy === "forbidden") {
+    return "Runtime permits bounded inspection and exact configured verifier commands only. Source mutation is blocked, and completion requires a zero task delta.";
+  }
+  if (mutationPolicy === "allowed") {
+    return "Verify and review first. Repair only findings supported by evidence; zero delta is valid, while any mutation remains guarded and every exact verifier must pass.";
+  }
+  if (lifecycleMode === "automatic") {
+    return "Runtime will record reads, changes, exact verifier results, and final completion automatically. Continue with ordinary read/edit/bash work.";
+  }
+  if (lifecycleMode === "assisted") {
+    return `Runtime records objective evidence automatically; after verification, complete only step \`review\` with piagent_task_progress using taskId \`${taskId}\` and stepId \`review\`.`;
+  }
+  return "Use the active progress/recovery tools for the custom or high-risk checkpoints.";
+}
+
+export function automaticTaskExpectedOutput(mutationPolicy: string): string {
+  if (mutationPolicy === "forbidden") {
+    return "The requested read-only investigation is answered from observed project evidence without mutating files.";
+  }
+  if (mutationPolicy === "allowed") {
+    return "The current implementation is verified and any evidence-backed failure is repaired; zero task delta remains valid when no repair is needed.";
+  }
+  return "The requested bounded change is implemented and passes the configured verification.";
+}

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

@@ -24,9 +24,9 @@ type ProofTask = {
   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 RUNTIME_SOURCE_REUSE_GUIDANCE = "Use runtime-delivered source; do not reread it. When the operator names an exact file, work from its delivered/current contents; do not list or search the repository merely to rediscover 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.";
+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. Do not warm up with an unfocused command already contained in that exact set; use a genuinely criterion-focused test or run the exact set directly.";
 
 function normalizedPath(value: string): string {
   return value.trim().replaceAll("\\", "/");
@@ -143,6 +143,9 @@ export function automaticTaskExecutionGuidance(task: ProofTask): string {
       ? "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.";
   }
+  if (task.mutationPolicy === "allowed") {
+    return "Verify and review the referenced implementation first. Mutate only when observed evidence identifies a repair; zero task delta is valid. Any repair remains subject to the normal mutation guards, and every exact configured verifier must pass against the final working tree. Runtime records evidence and completion; 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.";