@piagent/platform 1.6.1 → 1.8.0

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.";

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

@@ -4,10 +4,11 @@ import { WORKING_TREE_DIGEST_ALGORITHM } from "../../extensions/working-tree-dig
 import { TASK_ACCEPTANCE_CRITERIA_MAX, TASK_ACCEPTANCE_CRITERION_MAX_CHARS, TASK_EXPECTED_OUTPUT_MAX_CHARS, TASK_SUMMARY_MAX_CHARS, operatorRequestDigest } from "../../extensions/task-state.js";
 import { createEnvironmentBoundTaskAuthority } from "../policy/task-authority-runtime.ts";
 import { authorityReplacementState } from "../policy/authority-resume-policy.ts";
+import { uncertainSendRuntimeIntake } from "../session/uncertain-send-continuation.ts";
 import { compileCriterionGraph, criterionGraphContextSelection, criterionGraphContextSelectionDetails, criterionGraphGuidance, criterionGraphMode } from "../../extensions/criterion-graph.js";
 import { captureTaskStartBaseline } from "../inspection/task-baseline-start-capture.ts";
 import { sameStringRecord, satisfiesAuthorityReplacement } from "./task-start-retry-helpers.ts"; import { automaticTaskExecutionGuidance, EXACT_VERIFIER_EXECUTION_GUIDANCE, RUNTIME_SOURCE_REUSE_GUIDANCE, taskCriticalProofSection } from "./task-start-guidance.ts";
-import { resolveTaskStartRepositoryManifestProvider } from "./task-start-manifest.ts"; import { boundedOperatorRequest, latestOperatorRequest } from "./operator-request-intake.ts";
+import { resolveTaskStartRepositoryManifestProvider } from "./task-start-manifest.ts"; import { boundedOperatorRequest, latestOperatorRequest } from "./operator-request-intake.ts"; import { automaticTaskExpectedOutput, conditionalMutationPreTaskContext, taskStartLifecycleGuidance } from "./task-start-conditional-mutation.ts";
 type ExtensionContext = any; type TaskContract = any; type TaskStartParameters = Record<string, any> & { operatorRequest?: string }; function taskReferenceDetails(task: TaskContract, reasonCode: string): Record<string, unknown> { const scope = Array.isArray(task.scope) ? task.scope.slice(0, 50) : []; return { reasonCode, taskId: task.taskId, taskRunId: task.taskRunId, outcome: task.trace?.outcome, attempt: task.attempt, ...(reasonCode === "task-already-active" ? { scope, scopeTruncated: scope.length < task.scope.length } : {}) }; }
 export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any>): any {
   const {
@@ -16,7 +17,7 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
     applyRuntimeLifecycleObservation, automaticAcceptanceCriteria, automaticReadOnlyTaskScope, automaticReviewLenses, automaticTaskIntakeMode, automaticTaskMutationPolicy, automaticTaskRiskLane, automaticTaskScope,
     acceptanceBaselineGuidance, acceptanceLanguageAdapterForPath, acceptanceProofGuidance, bindSessionTask, buildAcceptanceReceipt, compactTaskDetails, contextBudgetConfig, createTaskRunId,
     currentSessionName, defaultWorkPlan, effectiveProtectedPaths, hasGitEvidenceRoot, hasOperatorSessionName,
-    isAcceptanceTestPath, loadProfileFromContext, matchesProtectedPath, normalizeReviewLenses, normalizeWorkPlanSteps, nowIso, policy,
+    isAcceptanceTestPath, loadProfileFromContext, matchesAnyPath, matchesProtectedPath, normalizeReviewLenses, normalizeWorkPlanSteps, nowIso, policy,
     priorTaskAttempts, recordTaskStartCheckpoint, redactText, redactTextArray, registerRuntimeTool,
     repositoryFileManifest, resolveOrchestrationPolicy, resolveTaskScopePatterns, runtimeLifecycleMode, runtimeState, safeTaskId, selectVerificationPlan,
     summarizeAttempt, telemetry, validTaskScopePattern, validateNewWorkPlan, verifierCommandInstructions, workingTreeEvidenceDigest, workingTreeSnapshot, workingTreeSnapshotHasUnavailableEvidence,
@@ -30,7 +31,7 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
     promptSnippet: "Start a governed project task and persist the task contract.",
     promptGuidelines: [
       "Call this exactly once before source edits in a project managed by Pi Agent Platform.",
-      "Use source-change for project verifier execution or edits. For an assessment, report, or plan with no source changes, set mutationPolicy=forbidden; use read-only when no project verifier needs to execute.",
+      "Use source-change for project verifier execution or edits. Set mutationPolicy=required when a task-local diff is mandatory, allowed when verification/review may conditionally repair findings but zero delta is valid, and forbidden when source mutation is prohibited; use read-only when no project verifier needs to execute.",
       "Do not call context, status, policy, evidence-recording, trace, or gate tools first; runtime hooks provide those checks automatically.",
       "Use tiny for a bounded low-risk change, normal for ordinary multi-file work, and high-risk for security, data, release, migration, or external-impact work.",
       "Every scope entry is an initial retrieval/review focus and must be a project-relative path or glob such as src/file.ts, src/**, or test/**; it is not a source-mutation boundary.",
@@ -44,7 +45,7 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
       changeMode: Type.Optional(StringEnum(["source-change", "read-only"] as const, {
         description: "Use source-change for project verifier execution or edits; use read-only for bounded inspection."
       })),
-      mutationPolicy: Type.Optional(StringEnum(["required", "forbidden"] as const, { description: "Required demands a final diff; forbidden allows exact verification, rejects source mutation, and requires a zero task delta." })),
+      mutationPolicy: Type.Optional(StringEnum(["required", "allowed", "forbidden"] as const, { description: "Required demands a final diff; allowed accepts zero or scoped source changes while retaining exact verification and mutation guards; forbidden rejects source mutation and requires a zero task delta." })),
       maxAttempts: Type.Optional(Type.Number({ minimum: 1, maximum: 10 })),
       expectedOutput: Type.String({ minLength: 10, maxLength: TASK_EXPECTED_OUTPUT_MAX_CHARS }),
       acceptanceCriteria: Type.Array(Type.String({ minLength: 1, maxLength: TASK_ACCEPTANCE_CRITERION_MAX_CHARS }), { minItems: 1, maxItems: TASK_ACCEPTANCE_CRITERIA_MAX }),
@@ -227,8 +228,10 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
       }
       const orchestration = resolveOrchestrationPolicy(profile, policy);
       const changeMode = params.changeMode === "read-only" ? "read-only" : "source-change";
-      const mutationPolicy = changeMode === "read-only" || params.mutationPolicy === "forbidden" ? "forbidden" : "required";
-      if (changeMode === "read-only" && params.mutationPolicy === "required") return { content: [{ type: "text", text: "Task start refused: read-only tasks cannot require source mutation." }], isError: true };
+      const mutationPolicy = changeMode === "read-only" || params.mutationPolicy === "forbidden"
+        ? "forbidden"
+        : params.mutationPolicy === "allowed" ? "allowed" : "required";
+      if (changeMode === "read-only" && params.mutationPolicy !== undefined && params.mutationPolicy !== "forbidden") return { content: [{ type: "text", text: "Task start refused: read-only tasks must forbid source mutation." }], isError: true };
       if (changeMode === "source-change" && !hasGitEvidenceRoot(ctx.cwd)) {
         return {
           content: [{ type: "text", text: "Task start refused: source-change tasks require a Git working tree, or a workspace parent with direct child Git repositories, so changed-file evidence cannot silently disappear. Initialize Git, open the parent that contains the repos, or use read-only mode." }],
@@ -288,7 +291,8 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
       const maxManifestFiles = contextBudgetConfig(policy).maxManifestFiles;
       const plannedSelection = criterionGraphContextSelectionDetails(criterionGraph, projectFiles, [], maxManifestFiles, projectManifest.complete, resolvedScope);
       const plannedContext = plannedSelection.entries;
-      const observedContext = criterionGraphContextSelection(undefined, [], runtimeState.preTaskContext(ctx), maxManifestFiles);
+      const observedContext = criterionGraphContextSelection(undefined, [], conditionalMutationPreTaskContext(runtimeState.preTaskContext(ctx), resolvedScope,
+        params.intakeMode === "runtime" && mutationPolicy === "allowed", matchesAnyPath), maxManifestFiles);
       const task: TaskContract = {
         schemaVersion: 2,
         taskRunId,
@@ -396,16 +400,7 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
             ...(baselineGuidance.length > 0
               ? [["Existing public contract:", ...baselineGuidance.map((item: string) => `- ${item}`)].join("\n")]
               : []),
-            lifecycleMode === "automatic-readonly"
-              ? "Runtime records targeted reads and final completion automatically. Stay read-only and report cited evidence."
-              : lifecycleMode === "assisted-readonly"
-                ? "Runtime records read-only evidence automatically; complete only the explicit evidence-review step before handoff."
-                : mutationPolicy === "forbidden" ? "Runtime permits bounded inspection and exact configured verifier commands only. Source mutation is blocked, and completion requires a zero task delta."
-                : lifecycleMode === "automatic"
-              ? "Runtime will record reads, changes, exact verifier results, and final completion automatically. Continue with ordinary read/edit/bash work."
-                  : lifecycleMode === "assisted"
-                    ? `Runtime records objective evidence automatically; after verification, complete only step \`review\` with piagent_task_progress using taskId \`${written.taskId}\` and stepId \`review\`.`
-                    : "Use the active progress/recovery tools for the custom or high-risk checkpoints."
+            taskStartLifecycleGuidance(lifecycleMode, mutationPolicy, written.taskId)
           ].join("\n")
         }],
         details: compactTaskDetails(written)
@@ -413,19 +408,25 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
     }
   };
   registerRuntimeTool(pi, taskStartTool);
-  async function maybeStartAutomaticTask(prompt: string, ctx: ExtensionContext): Promise<{ started: boolean; text: string; task?: TaskContract; plannedContext?: Array<{ path: string; reason: string }>; plannedContextComplete?: boolean } | undefined> {
+  async function maybeStartAutomaticTask(prompt: string, ctx: ExtensionContext): Promise<{ started: boolean; text: string; task?: TaskContract; plannedContext?: Array<{ path: string; reason: string }>; plannedContextComplete?: boolean; continuation?: "terminal-uncertain-send" } | undefined> {
+    const active = activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined,
+      uncertainSend = uncertainSendRuntimeIntake(ctx.cwd, active, prompt, ctx.sessionManager.getSessionId());
+    if (uncertainSend) {
+      if (uncertainSend.task) { appendTrace(ctx.cwd, uncertainSend.trace); appendSessionTrace(pi, uncertainSend.trace); }
+      telemetry(ctx, uncertainSend.trace); return uncertainSend.intake;
+    }
     const profile = loadProfileFromContext(ctx);
     const readProtectedPaths = effectiveProtectedPaths(policy, profile).readProtectedPaths;
     const intakeMode = automaticTaskIntakeMode(prompt, readProtectedPaths);
     if (!intakeMode) return undefined;
-    const mutationPolicy = automaticTaskMutationPolicy(prompt, intakeMode), active = activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined;
+    const mutationPolicy = automaticTaskMutationPolicy(prompt, intakeMode);
     if (active?.trace.outcome === "pending") return undefined;
     const summary = redactText(automaticTaskSummary(prompt));
     const sessionName = currentSessionName(ctx);
     const projectManifest = repositoryManifestProvider.read(ctx.cwd), projectFiles = projectManifest.files;
     const scope = intakeMode === "read-only"
       ? automaticReadOnlyTaskScope(prompt, runtimeState.preTaskContext(ctx))
-      : automaticTaskScope(prompt, runtimeState.preTaskContext(ctx), projectFiles);
+      : automaticTaskScope(prompt, runtimeState.preTaskContext(ctx), projectFiles, active);
     const started = await taskStartTool.execute(
       `runtime-intake-${ctx.sessionManager.getSessionId()}`,
       {
@@ -435,9 +436,8 @@ export function registerTaskStartTool(pi: ExtensionAPI, deps: Record<string, any
         intakeMode: "runtime",
         changeMode: intakeMode,
         mutationPolicy,
-        expectedOutput: mutationPolicy === "forbidden" ? "The requested read-only investigation is answered from observed project evidence without mutating files."
-          : "The requested bounded change is implemented and passes the configured verification.",
-        acceptanceCriteria: automaticAcceptanceCriteria(prompt, mutationPolicy === "forbidden" ? "read-only" : intakeMode),
+        expectedOutput: automaticTaskExpectedOutput(mutationPolicy),
+        acceptanceCriteria: automaticAcceptanceCriteria(prompt, mutationPolicy === "forbidden" ? "read-only" : intakeMode, mutationPolicy),
         scope,
         outOfScope: ["Unrelated files and behavior outside the operator request."],
         reviewLenses: automaticReviewLenses(prompt)