@piagent/platform 1.6.1 → 1.7.1

package/packages/piagent-core/runtime/policy/source-worktree-transaction.ts

@@ -6,25 +6,26 @@ import path from "node:path";
 
 import { collectExactGitPatchAuthority } from "../inspection/diff-projection.ts";
 import { collectGitStatusForPaths, runReadOnlyGit } from "../inspection/git-status-adapter.ts";
-import { localFilterDisableArgs } from "../inspection/git-filter-safety.ts";
 import { collectIndexPreimage, collectSelectedWorkspacePreimage } from "../inspection/source-mutation-projection.ts";
+import { readWorkspaceFile } from "../inspection/workspace-file-reader.ts";
 import type { SourceRevertAuthority } from "../inspection/source-revert-projection.ts";
 import type { SourceIndexTransactionResult } from "./source-index-transaction.ts";
 
 function result(value: Omit<SourceIndexTransactionResult, "executor" | "directExecution">): SourceIndexTransactionResult {
   return { ...value, executor: "pi-guard", directExecution: false };
 }
-function environment(): NodeJS.ProcessEnv {
+function environment(extra: NodeJS.ProcessEnv = {}): NodeJS.ProcessEnv {
   return { PATH: process.env.PATH, LC_ALL: "C", LANG: "C", GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: os.devNull,
     GIT_OPTIONAL_LOCKS: "0", GIT_PAGER: "cat", PAGER: "cat", GIT_TERMINAL_PROMPT: "0", GIT_ASKPASS: "",
-    ...(process.platform === "win32" ? { SystemRoot: process.env.SystemRoot, ComSpec: process.env.ComSpec } : {}) };
+    ...(process.platform === "win32" ? { SystemRoot: process.env.SystemRoot, ComSpec: process.env.ComSpec } : {}), ...extra };
 }
-async function runGit(repoRoot: string, args: string[], input: Buffer, timeoutMs: number): Promise<void> {
-  const filterArgs = await localFilterDisableArgs(repoRoot, timeoutMs);
+async function runGitInTemporaryTree(treeRoot: string, args: string[], input: Buffer, timeoutMs: number): Promise<void> {
   const argv = ["--no-pager", "--literal-pathspecs", "-c", "color.ui=false", "-c", "core.fsmonitor=false", "-c", `core.hooksPath=${os.devNull}`,
-    "-c", "diff.external=", "-c", "submodule.recurse=false", ...filterArgs, "-C", repoRoot, ...args];
+    "-c", "diff.external=", "-c", "submodule.recurse=false", "-C", treeRoot, ...args];
   await new Promise<void>((resolve, reject) => {
-    const child = spawn("git", argv, { cwd: repoRoot, env: environment(), shell: false, stdio: ["pipe", "ignore", "pipe"], windowsHide: true });
+    const child = spawn("git", argv, { cwd: treeRoot,
+      env: environment({ GIT_CEILING_DIRECTORIES: path.dirname(treeRoot), GIT_ATTR_NOSYSTEM: "1" }),
+      shell: false, stdio: ["pipe", "ignore", "pipe"], windowsHide: true });
     let stderr = 0, settled = false; child.stderr.on("data", (chunk: Buffer) => { stderr += chunk.length; if (stderr > 64 * 1024) child.kill("SIGKILL"); });
     child.stdin.on("error", () => undefined); child.stdin.end(input);
     const timer = setTimeout(() => child.kill("SIGKILL"), timeoutMs); timer.unref?.();
@@ -52,12 +53,59 @@ async function restoreWholeFile(authority: SourceRevertAuthority, recheck: () =>
   finally { fs.rmSync(temporary, { force: true }); }
   const actual = fs.readFileSync(target); if (!actual.equals(bytes)) throw new Error("revert-postcondition-failed");
 }
-async function restoreSelectedHunk(authority: SourceRevertAuthority, hunkRef: string, timeoutMs: number): Promise<void> {
+type PreparedSelectedHunk = { stagingPath: string; target: string; initialMode: number };
+function inside(root: string, candidate: string): boolean {
+  const relative = path.relative(root, candidate);
+  return relative === "" || relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+function cleanupScratchRoot(scratchRoot: string): void {
+  try { fs.rmSync(scratchRoot, { recursive: true, force: true }); } catch {}
+}
+function cleanupStagingFile(stagingPath: string | null): void {
+  if (stagingPath) try { fs.rmSync(stagingPath, { force: true }); } catch {}
+}
+async function prepareSelectedHunk(authority: SourceRevertAuthority, hunkRef: string, timeoutMs: number): Promise<PreparedSelectedHunk | null> {
   const block = authority.patchAuthority.hunks.find((hunk) => hunk.hunkRef === hunkRef);
   if (!block) throw new Error("revert-hunk-stale");
   const patch = Buffer.concat([authority.patchAuthority.header, block.bytes]);
   if (patch.length > 2 * 1024 * 1024) throw new Error("revert-patch-oversized");
-  await runGit(authority.repoRoot, ["apply", "--reverse", "--recount", "--whitespace=nowarn", "-"], patch, timeoutMs);
+  const repoRoot = fs.realpathSync.native(authority.repoRoot), target = path.resolve(repoRoot, authority.repoPath);
+  const parent = fs.realpathSync.native(path.dirname(target));
+  if (parent !== path.dirname(target) || !inside(repoRoot, target)) throw new Error("revert-target-unsafe");
+  const current = fs.lstatSync(target);
+  if (!current.isFile() || current.isSymbolicLink() || fs.realpathSync.native(target) !== target) throw new Error("revert-target-unsafe");
+  const scratchRoot = fs.realpathSync.native(fs.mkdtempSync(path.join(os.tmpdir(), `piagent-revert-tree.${process.pid}.`)));
+  fs.chmodSync(scratchRoot, 0o700);
+  const scratchTarget = path.resolve(scratchRoot, ...authority.repoPath.split("/"));
+  let stagingPath: string | null = null;
+  try {
+    if (!inside(scratchRoot, scratchTarget)) throw new Error("revert-target-unsafe");
+    fs.mkdirSync(path.dirname(scratchTarget), { recursive: true, mode: 0o700 });
+    const descriptor = fs.openSync(scratchTarget,
+      fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW ?? 0), 0o600);
+    try {
+      fs.writeFileSync(descriptor, readWorkspaceFile(repoRoot, authority.repoPath, 16 * 1024 * 1024));
+      fs.fchmodSync(descriptor, current.mode & 0o777); fs.fsyncSync(descriptor);
+    } finally { fs.closeSync(descriptor); }
+    if (collectSelectedWorkspacePreimage(scratchRoot, [authority.repoPath]) !== authority.target.workspacePreimage) return null;
+    await runGitInTemporaryTree(scratchRoot, ["apply", "--reverse", "--recount", "--whitespace=nowarn", "-"], patch, timeoutMs);
+    const result = fs.lstatSync(scratchTarget);
+    if (!result.isFile() || result.isSymbolicLink() || fs.realpathSync.native(scratchTarget) !== scratchTarget)
+      throw new Error("revert-target-unsafe");
+    const candidate = readWorkspaceFile(scratchRoot, authority.repoPath, 16 * 1024 * 1024);
+    stagingPath = path.join(parent, `.${path.basename(target)}.piagent-revert.${process.pid}.${randomBytes(8).toString("hex")}`);
+    const stagingDescriptor = fs.openSync(stagingPath,
+      fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW ?? 0), 0o600);
+    try {
+      fs.writeFileSync(stagingDescriptor, candidate);
+      fs.fchmodSync(stagingDescriptor, result.mode & 0o777);
+      fs.fsyncSync(stagingDescriptor);
+    } finally { fs.closeSync(stagingDescriptor); }
+    return { stagingPath, target, initialMode: current.mode & 0o777 };
+  } catch (error) {
+    cleanupStagingFile(stagingPath);
+    throw error;
+  } finally { cleanupScratchRoot(scratchRoot); }
 }
 
 export async function executeGuardedSourceWorktreeRevert(options: { authority: SourceRevertAuthority; expectedIndexPreimage: string;
@@ -74,13 +122,26 @@ export async function executeGuardedSourceWorktreeRevert(options: { authority: S
     if (!options.recheck() || lockedIndex !== options.expectedIndexPreimage || lockedWorkspace !== options.expectedWorkspacePreimage)
       return result({ state: "rejected", reasonCode: "mutation-preimage-stale", ...before,
         afterIndexPreimage: lockedIndex, afterWorkspacePreimage: lockedWorkspace });
-    const finalRecheck = async () => options.recheck()
-      && await collectIndexPreimage(options.authority.repoRoot) === options.expectedIndexPreimage
-      && collectSelectedWorkspacePreimage(options.authority.repoRoot, [options.authority.repoPath]) === options.expectedWorkspacePreimage;
+    const finalRecheck = async () => {
+      if (!options.recheck()) return false;
+      const index = await collectIndexPreimage(options.authority.repoRoot);
+      const workspace = collectSelectedWorkspacePreimage(options.authority.repoRoot, [options.authority.repoPath]);
+      return index === options.expectedIndexPreimage && workspace === options.expectedWorkspacePreimage && options.recheck();
+    };
     if (options.authority.target.hunkRefs.length) {
-      if (!await finalRecheck()) return result({ state: "rejected", reasonCode: "mutation-preimage-stale", ...before,
+      const prepared = await prepareSelectedHunk(options.authority, options.authority.target.hunkRefs[0],
+        Math.max(100, Math.min(60_000, options.timeoutMs ?? 5_000)));
+      if (!prepared) return result({ state: "rejected", reasonCode: "mutation-preimage-stale", ...before,
         afterIndexPreimage: null, afterWorkspacePreimage: null });
-      await restoreSelectedHunk(options.authority, options.authority.target.hunkRefs[0], Math.max(100, Math.min(60_000, options.timeoutMs ?? 5_000)));
+      try {
+        if (!await finalRecheck()) return result({ state: "rejected", reasonCode: "mutation-preimage-stale", ...before,
+          afterIndexPreimage: null, afterWorkspacePreimage: null });
+        const current = fs.lstatSync(prepared.target);
+        if (!current.isFile() || current.isSymbolicLink() || (current.mode & 0o777) !== prepared.initialMode)
+          return result({ state: "rejected", reasonCode: "mutation-preimage-stale", ...before,
+            afterIndexPreimage: null, afterWorkspacePreimage: null });
+        fs.renameSync(prepared.stagingPath, prepared.target);
+      } finally { cleanupStagingFile(prepared.stagingPath); }
     } else await restoreWholeFile(options.authority, finalRecheck);
     committed = true;
     const afterIndexPreimage = await collectIndexPreimage(options.authority.repoRoot);

package/packages/piagent-core/runtime/product/activity-inspector.ts

@@ -57,7 +57,7 @@ function commandProjection(events: ActivityInspectorEvent[]) {
     const decision = decisions.get(call.toolCallId), result = results.get(call.toolCallId);
     const blocked = decision?.decision === "blocked";
     const recovered = Boolean(call.toolCallId && recoveries.has(call.toolCallId));
-    const failed = !blocked && !recovered && !handledToolFailure(result?.reasonCode) && Boolean(result && failedToolResult(result));
+    const failed = !blocked && !recovered && !handledToolFailure(result?.reasonCode, result?.toolName ?? call.toolName) && Boolean(result && failedToolResult(result));
     return { toolCallId: call.toolCallId ?? "unknown", command: call.command ?? "[redacted or unavailable]",
       status: blocked ? "blocked" : !result ? "running" : failed ? "failed" : "passed",
       exitCode: result?.exitCode ?? null, exitCodeExact: result?.exitCodeExact === true,
@@ -114,9 +114,12 @@ export async function buildActivityInspector(input: {
   eventCursor?: string;
   resyncRequired?: boolean;
   eventReplay?: { eventRetentionCount: number; eventRetentionSeconds: number };
+  operationLiveness?: "idle" | "running" | "unknown";
 }) {
   const projection = await buildWebUiInspectionProjection(input);
   const events = projection.scopedEvents, snapshot = projection.snapshot;
+  const current = snapshot.activity.running.length > 0 ? input.current ?? []
+    : (input.current ?? []).filter((activity) => (activity.status ?? "running") !== "running");
   const calls = events.filter((event) => event.event === "tool_call"), results = events.filter((event) => event.event === "tool_result");
   const byName = Object.fromEntries([...new Set(calls.map((event) => event.toolName ?? "unknown"))].sort().map((name) => [name, calls.filter((event) => (event.toolName ?? "unknown") === name).length]));
   const commands = commandProjection(events), files = sourceFiles(projection, input.task), safety = safetyProjection(events);
@@ -124,9 +127,9 @@ export async function buildActivityInspector(input: {
     schemaVersion: 2, version: ACTIVITY_INSPECTOR_VERSION, snapshot,
     state: { taskId: snapshot.identity.taskId, taskRunId: snapshot.identity.taskRunId,
       phase: snapshot.session.operation.hostPhase.state === "known" && snapshot.session.operation.hostPhase.value !== "idle" ? snapshot.session.operation.hostPhase.value : null,
-      outcome: snapshot.task?.outcome ?? "idle", running: snapshot.activity.running.length, current: input.current ?? [] },
+      outcome: snapshot.task?.outcome ?? "idle", running: snapshot.activity.running.length, current },
     criteria: snapshot.task?.criteria ?? [], sourceChanges: snapshot.sourceChanges, files,
-    tools: { calls: calls.length, results: results.length, failed: results.filter((event) => failedToolResult(event) && !handledToolFailure(event.reasonCode)).length,
+    tools: { calls: calls.length, results: results.length, failed: results.filter((event) => failedToolResult(event) && !handledToolFailure(event.reasonCode, event.toolName)).length,
       blocked: events.filter((event) => event.event === "tool_decision" && event.decision === "blocked").length, byName,
       perToolTokens: null, perToolTokensReason: "Pi reports model usage by response/turn; built-in tool calls do not carry attributable model-token totals." },
     commands, safety,

package/packages/piagent-core/runtime/product/edit-verifier-timing.ts

@@ -0,0 +1,26 @@
+import type { TaskContract } from "../../extensions/guard-types.ts";
+import { latestObservedVerificationEvidence, verificationEvidenceProvesStableTree } from "../../extensions/verification-intelligence.js";
+
+export type CompletionSource = { approved: boolean; treeDigest: string | null; revisionDigest: string | null };
+
+// A report consumes an existing gate result. It cannot approve completion.
+// This metric means first observed edit reaching the accepted final source,
+// not proof that an individual hunk alone solved the task.
+export function firstCorrectEditTiming(task: TaskContract, records: Record<string, any>[],
+  completeTelemetry: boolean, source?: CompletionSource) {
+  const unavailable = { timeToFirstCorrectEditMs: null, timeToFirstCorrectEditReason: "edit-to-current-verifier-and-completion-evidence-unavailable" };
+  if (!completeTelemetry || !source?.approved || !source.treeDigest || !source.revisionDigest
+    || task.trace.outcome !== "completed" || !task.verifyCommands.length) return unavailable;
+  const latest = latestObservedVerificationEvidence(task.verifyEvidence);
+  const verifiers = task.verifyCommands.map((command) => latest.get(command.trim()));
+  if (!verifiers.every((entry) => verificationEvidenceProvesStableTree(entry, source.treeDigest, source.revisionDigest))) return unavailable;
+  const startedAt = Date.parse(task.createdAt);
+  const earliestVerifier = Math.min(...verifiers.map((entry: any) => Date.parse(entry.observedAt)));
+  const candidates = records.filter((event) => event.event === "tool_result" && event.taskUsageVersion === 1
+    && event.taskId === task.taskId && event.taskRunId === task.taskRunId && event.sessionId === task.sessionId
+    && event.mutationObserved === true && event.isError === false && typeof event.toolCallId === "string"
+    && event.postWorkingTreeDigest === source.treeDigest && event.postWorkspaceRevisionDigest === source.revisionDigest)
+    .map((event) => Date.parse(event.recordedAt)).filter((time) => Number.isFinite(time) && time >= startedAt && time < earliestVerifier);
+  return candidates.length ? { timeToFirstCorrectEditMs: Math.min(...candidates) - startedAt,
+    timeToFirstCorrectEditReason: "observed-edit-to-accepted-source; same-tree-and-revision-verifiers" } : unavailable;
+}

package/packages/piagent-core/runtime/product/efficiency-metrics.ts

@@ -5,6 +5,8 @@ import type { TaskContract } from "../../extensions/guard-types.ts";
 import { readSolverShadowEvents } from "../solver/solver-shadow.ts";
 import { readTrajectoryStore } from "../trajectory/trajectory-store.ts";
 import type { TrajectoryPhase } from "../trajectory/trajectory-types.ts";
+import { readTaskUsage } from "./task-usage.ts";
+import type { CompletionSource } from "./edit-verifier-timing.ts";
 
 export const TASK_EFFICIENCY_METRICS_VERSION = "task-efficiency-v1" as const;
 
@@ -44,12 +46,14 @@ function phaseDurations(task: TaskContract, trajectory: ReturnType<typeof readTr
 export function buildTaskEfficiencyMetrics(
   cwd: string,
   task: TaskContract,
-  input: { activeToolGroups?: string[]; exactUsage?: ExactUsage } = {}
+  input: { activeToolGroups?: string[]; exactUsage?: ExactUsage; completionSource?: CompletionSource } = {}
 ) {
   const sessionHash = hash(task.sessionId);
   const solverStore = readSolverShadowEvents(cwd);
-  const solverEvent = [...solverStore.records].reverse().find((event) => event.sessionHash === sessionHash);
   const trajectory = readTrajectoryStore(cwd, task.taskRunId);
+  const recommendation = trajectory.status === "ok" ? trajectory.state?.recommendationRef : null;
+  const solverEvent = recommendation ? [...solverStore.records].reverse().find((event) => event.sessionHash === sessionHash
+    && event.featureHash === recommendation.featureHash && hash(JSON.stringify(event.decision)) === recommendation.decisionDigest) : undefined;
   const decision = solverEvent?.decision;
   const helperUsage = task.acceptanceReceipt?.helperUsage;
   const provenance = task.acceptanceReceipt?.provenance;
@@ -58,9 +62,10 @@ export function buildTaskEfficiencyMetrics(
   const relevantFileMs = relevantEvent && contextEvidence.length > 0 ? duration(task.createdAt, relevantEvent.observedAt) : null;
   const recommendedTools = decision?.toolGroups ?? [];
   const activeTools = [...new Set(input.activeToolGroups ?? [])].sort();
+  const usage = readTaskUsage(cwd, task, input.completionSource);
   const exactUsage = input.exactUsage && (input.exactUsage.tokens !== null || input.exactUsage.cost !== null)
     ? input.exactUsage
-    : { tokens: null, cost: null, currency: null, source: "unavailable" as const };
+    : { tokens: usage.tokens, cost: null, currency: null, source: usage.tokens === null ? "unavailable" as const : "pi-runtime" as const, scope: usage.scope };
 
   return {
     schemaVersion: 1,
@@ -95,12 +100,11 @@ export function buildTaskEfficiencyMetrics(
       recommendedGroups: recommendedTools,
       activeGroups: activeTools,
       activeRecommendedGroups: activeTools.filter((group) => recommendedTools.includes(group)),
-      actualInvocationCounts: null
+      actualInvocationCounts: usage.actualInvocationCounts
     },
     timing: {
       taskDurationMs: duration(task.createdAt, task.updatedAt),
-      timeToFirstCorrectEditMs: null,
-      timeToFirstCorrectEditReason: "no persisted edit-to-verifier causal marker"
+      ...usage.editTiming
     },
     verification: {
       attempts: task.verifyEvidence.length,
@@ -130,6 +134,7 @@ export function buildTaskEfficiencyMetrics(
       acceptance: task.acceptanceReceipt?.criteria.map((item) => ({ id: item.id, status: item.status })) ?? [],
       recoveryDisposition: provenance?.finalRecoveryDisposition ?? "unknown"
     },
-    exactUsage
+    exactUsage,
+    usageAccounting: usage
   };
 }

package/packages/piagent-core/runtime/product/operator-projections.ts

@@ -1,7 +1,8 @@
+import { currentWorkspaceRevisionDigest } from "../../extensions/workspace-revision.js";
 import type { TaskContract } from "../../extensions/guard-types.ts";
 import { replayTaskCheckpoints } from "../../extensions/task-journal.js";
 import { taskContractValidationErrors, taskDigestMigrationArchiveStatus } from "../../extensions/task-state.js";
-import { latestObservedVerificationEvidence, verificationEvidenceProvesStableTree } from "../../extensions/verification-intelligence.js";
+import { latestObservedVerificationEvidence, verificationEvidenceProvesCurrentWorkspace } from "../../extensions/verification-intelligence.js";
 import {
   isCurrentWorkingTreeDigest,
   WORKING_TREE_DIGEST_ALGORITHM,
@@ -79,7 +80,9 @@ export function buildLiveTaskStatus(cwd: string, task: TaskContract | undefined,
   const currentTreeDigest = isCurrentWorkingTreeDigest(resume.currentTreeDigest) ? resume.currentTreeDigest : null;
   const migrationRefresh = task.workingTreeDigestMigration?.status === "verification-refresh-required";
   const latestVerifiers = latestObservedVerificationEvidence(task.verifyEvidence);
-  return { schemaVersion: 1, version: LIVE_TASK_STATUS_VERSION, state: task.trace.outcome === "pending" ? resume.enforcementSafe ? "active" : "corrupt" : "terminal", task: { taskId: task.taskId, taskRunId: task.taskRunId, sessionHash: resume.sessionId === task.sessionId ? "matched" : "conflict", attempt: task.attempt, maxAttempts: task.maxAttempts, phase: input.trajectory?.phase ?? resume.phase, outcome: task.trace.outcome, pendingVerifiers: task.verifyCommands.filter((command) => !currentTreeDigest || !verificationEvidenceProvesStableTree(latestVerifiers.get(command.trim()), currentTreeDigest)), pendingReview: task.workPlan.some((step) => step.id === "review" && step.status !== "done") }, tree: { ...digestMigration(task), currentDigest: currentTreeDigest }, runtime: input.runtime ?? null, modelRouting: input.modelRoute ?? null, activeToolGroups: input.activeToolGroups ?? [], recovery: { classification: evidence.failureClassification?.category ?? null, action: evidence.recovery?.action ?? null }, helpers: input.helpers ?? task.acceptanceReceipt?.helperUsage?.helpers ?? [], checkpoint: latest ? { id: latest.checkpointId, phase: latest.phase, status: latest.status, sequence: latest.sequence } : null, resume: { decision: resume.decision, safe: resume.enforcementSafe, staleVerifier: resume.staleVerifierEvidence, authorityPolicy: resume.authorityPolicy }, blockers: resume.warnings, nextSafeAction: task.trace.outcome !== "pending" ? "none-terminal" : migrationRefresh ? "rerun-exact-verifier" : resume.enforcementSafe ? resume.staleVerifierEvidence ? "rerun-exact-verifier" : "continue-current-phase" : "inspect-handoff-and-recover", receipt: task.trace.outcome === "pending" ? null : buildCompletionReceiptView(task, { cwd, gate: input.completionGate, modelRoute: input.modelRoute }), efficiency: buildTaskEfficiencyMetrics(cwd, task, { activeToolGroups: input.activeToolGroups }) };
+  const receipt = task.trace.outcome === "pending" ? null : buildCompletionReceiptView(task, { cwd, gate: input.completionGate, modelRoute: input.modelRoute });
+  const completionSource = { approved: receipt?.completionApproved === true && resume.enforcementSafe, treeDigest: currentTreeDigest, revisionDigest: receipt?.completionApproved ? currentWorkspaceRevisionDigest(cwd) : null };
+  return { schemaVersion: 1, version: LIVE_TASK_STATUS_VERSION, state: task.trace.outcome === "pending" ? resume.enforcementSafe ? "active" : "corrupt" : "terminal", task: { taskId: task.taskId, taskRunId: task.taskRunId, sessionHash: resume.sessionId === task.sessionId ? "matched" : "conflict", attempt: task.attempt, maxAttempts: task.maxAttempts, phase: input.trajectory?.phase ?? resume.phase, outcome: task.trace.outcome, pendingVerifiers: task.verifyCommands.filter((command) => !currentTreeDigest || !verificationEvidenceProvesCurrentWorkspace(latestVerifiers.get(command.trim()), currentTreeDigest, cwd)), pendingReview: task.workPlan.some((step) => step.id === "review" && step.status !== "done") }, tree: { ...digestMigration(task), currentDigest: currentTreeDigest }, runtime: input.runtime ?? null, modelRouting: input.modelRoute ?? null, activeToolGroups: input.activeToolGroups ?? [], recovery: { classification: evidence.failureClassification?.category ?? null, action: evidence.recovery?.action ?? null }, helpers: input.helpers ?? task.acceptanceReceipt?.helperUsage?.helpers ?? [], checkpoint: latest ? { id: latest.checkpointId, phase: latest.phase, status: latest.status, sequence: latest.sequence } : null, resume: { decision: resume.decision, safe: resume.enforcementSafe, staleVerifier: resume.staleVerifierEvidence, authorityPolicy: resume.authorityPolicy }, blockers: resume.warnings, nextSafeAction: task.trace.outcome !== "pending" ? "none-terminal" : migrationRefresh ? "rerun-exact-verifier" : resume.decision === "blocked" ? "inspect-handoff-and-recover" : resume.enforcementSafe ? resume.staleVerifierEvidence ? "rerun-exact-verifier" : "continue-current-phase" : "inspect-handoff-and-recover", receipt, efficiency: buildTaskEfficiencyMetrics(cwd, task, { activeToolGroups: input.activeToolGroups, completionSource }) };
 }
 
 export function formatLiveTaskStatus(view: ReturnType<typeof buildLiveTaskStatus>): string { if (!view.task) return `task: none\nmodelRoute: ${view.modelRouting ? `${view.modelRouting.disposition}/${view.modelRouting.capabilityBand}` : "none"}\nnext: start-or-resume-task`; const task = view.task; return [`task: ${task.taskId} (${task.taskRunId}); attempt=${task.attempt}/${task.maxAttempts}`, `state: ${view.state}; phase=${task.phase ?? "unknown"}; outcome=${task.outcome}`, `modelRoute: ${view.modelRouting ? `${view.modelRouting.disposition}; band=${view.modelRouting.capabilityBand}; target=${view.modelRouting.modelId ?? "none"}:${view.modelRouting.effort ?? "none"}; enforced=${view.modelRouting.enforced}` : "none"}`, `pending: verify=${task.pendingVerifiers.join(",") || "none"}; review=${task.pendingReview}`, `recovery: ${view.recovery.classification ?? "none"}/${view.recovery.action ?? "none"}`, `helpers: ${view.helpers.length}; checkpoint=${view.checkpoint?.id ?? "none"}`, `resume: ${view.resume.decision}; safe=${view.resume.safe}; staleVerifier=${view.resume.staleVerifier}; authority=${view.resume.authorityPolicy.disposition}/${view.resume.authorityPolicy.reason}`, `blockers: ${view.blockers.join("; ") || "none"}`, `next: ${view.nextSafeAction}`].join("\n"); }
@@ -92,7 +95,9 @@ export function buildCompletionReceiptView(task: TaskContract, input: { cwd?: st
   const recovery = task.acceptanceReceipt?.provenance;
   const helpers = task.acceptanceReceipt?.helperUsage;
   const latestVerifiers = latestObservedVerificationEvidence(task.verifyEvidence);
-  const acceptanceSatisfied = task.acceptanceReceipt?.criteria.every((item) => item.status === "satisfied") === true;
+  const acceptanceRequired = task.changeMode === "source-change" && task.changedFiles.length > 0;
+  const acceptanceSatisfied = !acceptanceRequired
+    || task.acceptanceReceipt?.criteria.every((item) => item.status === "satisfied") === true;
   const treeEvidenceCurrent = taskTreeEvidenceIsCurrent(input.cwd, task, baselineDigest, currentDigest);
   const gateTreeCurrent = isCurrentWorkingTreeDigest(gate?.currentWorkingTreeDigest)
     && gate?.currentWorkingTreeDigest === currentDigest;

package/packages/piagent-core/runtime/product/task-usage-hooks.ts

@@ -0,0 +1,78 @@
+import crypto from "node:crypto";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { TaskContract } from "../../extensions/guard-types.ts";
+
+type Request = { requestId: string; taskId?: string; taskRunId?: string; sessionId: string; providerRequests: number };
+
+// Metadata only, written to the existing telemetry stream. SDK turns are not
+// provider billing receipts; missing terminals and internal retries stay unknown.
+export function registerTaskUsageHooks(pi: ExtensionAPI, input: {
+  activeTask: (ctx: ExtensionContext) => TaskContract | undefined;
+  telemetry: (ctx: ExtensionContext, event: Record<string, unknown>) => void;
+}): void {
+  const requests = new Map<string, Request>();
+  const messages = new WeakMap<object, Request>();
+  const calls = new Map<string, { request: Request; invoked: boolean }>();
+  const key = (ctx: ExtensionContext) => `${ctx.cwd}\u0000${ctx.sessionManager.getSessionId()}`;
+  const emit = (ctx: ExtensionContext, request: Request, event: string, data = {}) => input.telemetry(ctx, {
+    ...request, event, taskUsageVersion: 1, ...data
+  });
+  pi.on("turn_start", (_event, ctx) => {
+    const task = input.activeTask(ctx);
+    const request: Request = { requestId: crypto.randomUUID(), taskId: task?.taskId,
+      taskRunId: task?.taskRunId, sessionId: ctx.sessionManager.getSessionId(), providerRequests: 0 };
+    requests.set(key(ctx), request);
+    emit(ctx, request, "task_usage_request");
+  });
+  pi.on("before_provider_request", (_event, ctx) => {
+    const request = requests.get(key(ctx));
+    if (request) {
+      request.providerRequests += 1;
+      emit(ctx, request, "task_usage_dispatch");
+    }
+  });
+  const observe = (message: any, ctx: ExtensionContext, allowBind: boolean) => {
+    if (message?.role !== "assistant") return;
+    const request = messages.get(message) ?? (allowBind ? requests.get(key(ctx)) : undefined);
+    if (!request) return;
+    messages.set(message, request);
+    // Only numeric usage metadata crosses this boundary. No content, arguments,
+    // headers, opaque reasoning, or error text is retained.
+    const usage = message.usage;
+    const numeric = (value: unknown) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+    emit(ctx, request, "task_usage_terminal", {
+      usageSemantics: "request-cumulative", usageRevision: "terminal",
+      stopReason: ["stop", "length", "toolUse", "error", "aborted"].includes(message.stopReason) ? message.stopReason : "unknown",
+      usage: Object.fromEntries(["input", "output", "cacheRead", "cacheWrite", "totalTokens"].map((field) => [field, numeric(usage?.[field])])),
+      cost: numeric(usage?.cost?.total), costBasis: "sdk-rate-estimate", currency: "USD"
+    });
+  };
+  pi.on("message_end", (event, ctx) => observe(event.message, ctx, true));
+  // The pinned SDK emits the same final message at both boundaries. An unknown
+  // replay object must not inherit the identity of a newer task at turn_end.
+  pi.on("turn_end", (event, ctx) => observe(event.message, ctx, false));
+  const callKey = (ctx: ExtensionContext, id: string) => `${key(ctx)}\u0000${id}`;
+  pi.on("tool_execution_start", (event, ctx) => {
+    const request = requests.get(key(ctx));
+    if (!request) return;
+    calls.set(callKey(ctx, event.toolCallId), { request, invoked: false });
+    emit(ctx, request, "task_tool_attempted", { toolCallId: event.toolCallId, toolName: event.toolName });
+  });
+  // SDK start events also cover blocked/invalid/truncated calls. Only the
+  // afterToolCall-backed tool_result hook proves execute was actually entered.
+  pi.on("tool_result", (event, ctx) => {
+    const call = calls.get(callKey(ctx, event.toolCallId));
+    if (!call) return;
+    call.invoked = true;
+    emit(ctx, call.request, "task_tool_invoked", { toolCallId: event.toolCallId, toolName: event.toolName });
+  });
+  pi.on("tool_execution_end", (event, ctx) => {
+    const id = callKey(ctx, event.toolCallId), call = calls.get(id);
+    if (call && !call.invoked) emit(ctx, call.request, "task_tool_not_executed", { toolCallId: event.toolCallId, toolName: event.toolName });
+    calls.delete(id);
+  });
+  pi.on("session_shutdown", (_event, ctx) => {
+    requests.delete(key(ctx));
+    for (const id of calls.keys()) if (id.startsWith(`${key(ctx)}\u0000`)) calls.delete(id);
+  });
+}

package/packages/piagent-core/runtime/product/task-usage.ts

@@ -0,0 +1,104 @@
+import { inspectContextTelemetry } from "../../extensions/context-engine.js";
+import type { TaskContract } from "../../extensions/guard-types.ts";
+import { firstCorrectEditTiming, type CompletionSource } from "./edit-verifier-timing.ts";
+
+type Event = Record<string, any>;
+type Inspection = { records: Event[]; exists: boolean; integrityFailures: number; recoverableTailBytes: number; inputTruncated: boolean };
+const FIELDS = ["input", "output", "cacheRead", "cacheWrite", "totalTokens"] as const;
+const validNumber = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value) && value >= 0;
+
+export function projectTaskUsage(task: Pick<TaskContract, "taskId" | "taskRunId" | "sessionId">, inspection: Inspection) {
+  const records = inspection.records.filter((event) => event.taskUsageVersion === 1
+    && event.sessionId === task.sessionId && event.taskId === task.taskId && event.taskRunId === task.taskRunId);
+  const warnings = new Set<string>();
+  if (!inspection.exists) warnings.add("telemetry-unavailable");
+  if (inspection.inputTruncated || inspection.integrityFailures || inspection.recoverableTailBytes) warnings.add("telemetry-incomplete");
+  const requests = new Map<string, { start: boolean; terminal?: Event; conflict: boolean; dispatches: number }>();
+  const tools = new Map<string, string>();
+  const attempts = new Map<string, { name: string; attempted: boolean; invoked: boolean; rejected: boolean }>();
+  for (const event of records) {
+    if (event.event === "task_tool_started") warnings.add("legacy-tool-start-is-not-execution-proof");
+    if (["task_tool_attempted", "task_tool_invoked", "task_tool_not_executed"].includes(event.event)) {
+      if (typeof event.toolCallId !== "string" || !event.toolCallId || typeof event.toolName !== "string"
+        || typeof event.requestId !== "string" || !event.requestId) { warnings.add("tool-identity-unavailable"); continue; }
+      const id = `${event.requestId}\u0000${event.toolCallId}`;
+      const call = attempts.get(id) ?? { name: event.toolName, attempted: false, invoked: false, rejected: false };
+      if (call.name !== event.toolName) warnings.add("tool-identity-conflict");
+      call.attempted ||= event.event === "task_tool_attempted";
+      call.invoked ||= event.event === "task_tool_invoked";
+      call.rejected ||= event.event === "task_tool_not_executed";
+      attempts.set(id, call);
+      if (call.invoked) tools.set(id, call.name);
+      continue;
+    }
+    if (!["task_usage_request", "task_usage_dispatch", "task_usage_terminal"].includes(event.event)) continue;
+    if (typeof event.requestId !== "string" || !event.requestId) { warnings.add("request-identity-unavailable"); continue; }
+    const request = requests.get(event.requestId) ?? { start: false, conflict: false, dispatches: 0 };
+    requests.set(event.requestId, request);
+    if (event.event === "task_usage_request") request.start = true;
+    if (Number.isSafeInteger(event.providerRequests)) request.dispatches = Math.max(request.dispatches, event.providerRequests);
+    if (event.event !== "task_usage_terminal") continue;
+    if (event.usageSemantics !== "request-cumulative") { request.conflict = true; continue; }
+    const material = (value: Event) => JSON.stringify([FIELDS.map((field) => value.usage?.[field] ?? null), value.cost ?? null, value.stopReason]);
+    if (request.terminal && material(request.terminal) !== material(event)) {
+      // Late totals may fill missing fields, but cannot rewrite known terminal
+      // amounts. Deltas/session cumulative snapshots are never summed here.
+      const previous = request.terminal;
+      if (FIELDS.some((field) => previous.usage?.[field] != null && event.usage?.[field] != null && previous.usage[field] !== event.usage[field])
+        || (previous.cost != null && event.cost != null && previous.cost !== event.cost) || previous.stopReason !== event.stopReason) request.conflict = true;
+      request.terminal = { ...event, cost: previous.cost ?? event.cost,
+        usage: Object.fromEntries(FIELDS.map((field) => [field, previous.usage?.[field] ?? event.usage?.[field]])) };
+      continue;
+    }
+    request.terminal = event;
+  }
+  const sums = Object.fromEntries(FIELDS.map((field) => [field, 0])) as Record<typeof FIELDS[number], number>;
+  let unknownRequests = 0, failedAttempts = 0, estimatedCost = 0, costKnown = true;
+  for (const request of requests.values()) {
+    const event = request.terminal;
+    if (event && ["error", "aborted"].includes(event.stopReason)) failedAttempts += 1;
+    if (!request.start || !event || request.conflict || request.dispatches > 1) {
+      unknownRequests += 1; costKnown = false; continue;
+    }
+    const usage = event.usage;
+    const numeric = FIELDS.every((field) => validNumber(usage?.[field]) && Number.isSafeInteger(usage[field]));
+    const consistent = numeric && usage.totalTokens === usage.input + usage.output + usage.cacheRead + usage.cacheWrite;
+    // SDK error messages may contain synthetic all-zero usage after a billed
+    // abort. Zero on these paths is not proof that nothing was charged.
+    if (!consistent || (["error", "aborted", "unknown"].includes(event.stopReason) && usage.totalTokens === 0)) unknownRequests += 1;
+    else for (const field of FIELDS) sums[field] += usage[field];
+    if (validNumber(event.cost) && event.costBasis === "sdk-rate-estimate") estimatedCost += event.cost;
+    else costKnown = false;
+  }
+  if (Object.values(sums).some((sum) => !Number.isSafeInteger(sum))) warnings.add("usage-overflow");
+  if (!requests.size) warnings.add("request-coverage-unavailable");
+  if (unknownRequests) warnings.add("request-usage-unknown");
+  if ([...attempts.values()].some((call) => !call.attempted || call.invoked === call.rejected)) warnings.add("tool-execution-unconfirmed");
+  const complete = warnings.size === 0;
+  const counts: Record<string, number> = {};
+  for (const name of tools.values()) Object.defineProperty(counts, name, { value: (Object.hasOwn(counts, name) ? counts[name] : 0) + 1, enumerable: true, configurable: true });
+  return {
+    scope: "observed-sdk-requests" as const,
+    status: complete ? "observed" as const : "unknown" as const,
+    requests: requests.size, unknownRequests, failedAttempts: complete ? failedAttempts : null, observedFailedAttempts: failedAttempts,
+    tokens: complete ? sums.totalTokens : null,
+    components: complete ? sums : null,
+    knownTokenSubtotal: sums.totalTokens,
+    sdkEstimatedCost: complete && costKnown ? estimatedCost : null,
+    billedCost: null, currency: null,
+    actualInvocationCounts: complete ? counts : null,
+    observedInvocationCounts: counts,
+    attemptedToolCalls: attempts.size,
+    notExecutedToolCalls: [...attempts.values()].filter((call) => call.rejected && !call.invoked).length,
+    warnings: [...warnings],
+    limitations: ["SDK reported usage; not an end-to-end billing receipt", "Coverage limited to instrumented requests; pre-instrumentation and hidden provider retries unavailable"]
+  };
+}
+
+export function readTaskUsage(cwd: string, task: TaskContract, source?: CompletionSource) {
+  let inspection: Inspection;
+  try { inspection = inspectContextTelemetry(cwd); }
+  catch { inspection = { records: [], exists: false, integrityFailures: 1, recoverableTailBytes: 0, inputTruncated: false }; }
+  const complete = inspection.exists && !inspection.integrityFailures && !inspection.recoverableTailBytes && !inspection.inputTruncated;
+  return { ...projectTaskUsage(task, inspection), editTiming: firstCorrectEditTiming(task, inspection.records, complete, source) };
+}

package/packages/piagent-core/runtime/quality/protected-refusal-handoff.ts

@@ -0,0 +1,35 @@
+import { hasProtectedRefusalBoundary } from "../workflows/task-intake.ts";
+
+const MARKER = /(?:^|[\s`])(REFUSAL|SAFE_ALTERNATIVE)=([a-z0-9][a-z0-9._:-]{0,127})(?=[\s`]|$)/gi;
+const SAFE_EXPLANATION = /\b(?:cannot|can't|declin(?:e|ed|ing)|non-secret|redact(?:ed|ion)|refus(?:e|ed|ing|al)|safe\s+alternative|won't|will\s+not)\b/i;
+
+function expectedMarkers(prompt: string): string[] | undefined {
+  const found = new Map<string, string>();
+  for (const match of String(prompt ?? "").matchAll(new RegExp(MARKER.source, MARKER.flags))) {
+    const key = match[1].toUpperCase(), value = match[2];
+    if (found.has(key)) return undefined;
+    found.set(key, `${key}=${value}`);
+  }
+  if (found.size !== 2 || !found.has("REFUSAL") || !found.has("SAFE_ALTERNATIVE")) return undefined;
+  return [found.get("REFUSAL")!, found.get("SAFE_ALTERNATIVE")!];
+}
+
+/** A narrow native fallback for a task that explicitly requires refusal. It
+ * recognizes only operator-declared durable markers; it never evaluates or
+ * grants access to the protected material itself. */
+export function protectedRefusalHandoffMatches(prompt: string, response: string): boolean {
+  if (!hasProtectedRefusalBoundary(String(prompt ?? ""))) return false;
+  const expected = expectedMarkers(prompt);
+  if (!expected || typeof response !== "string" || !response.trim() || !(response as any).isWellFormed()
+    || Buffer.byteLength(response) > 65_536) return false;
+  const observed = [...response.matchAll(new RegExp(MARKER.source, MARKER.flags))]
+    .map((match) => `${match[1].toUpperCase()}=${match[2]}`);
+  if (observed.length !== expected.length
+    || observed.some((marker) => !expected.includes(marker))
+    || expected.some((marker) => observed.filter((candidate) => candidate === marker).length !== 1)) return false;
+  const lines = response.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  if (expected.some((marker) => lines.filter((line) => line === marker).length !== 1)) return false;
+  if (lines.some((line) => /^(?:REFUSAL|SAFE_ALTERNATIVE)=/i.test(line) && !expected.includes(line))) return false;
+  const explanation = lines.filter((line) => !expected.includes(line)).join(" ");
+  return !explanation || SAFE_EXPLANATION.test(explanation);
+}

package/packages/piagent-core/runtime/recovery/acceptance-recovery-guidance.ts

@@ -0,0 +1,21 @@
+export type CriticalRecoveryProjection = { criterionText: string; targets: string[]; missingDimensions: string[]; proofHints: string[]; diagnosticHints?: string[] };
+
+function compactRecoveryField(value: unknown, maximum: number): string {
+  const text = String(value ?? "").replace(/\s+/g, " ").trim();
+  return text.length > maximum ? `${text.slice(0, Math.max(0, maximum - 1)).trimEnd()}…` : text;
+}
+export function criticalAcceptanceRecoveryGuidance(projections: CriticalRecoveryProjection[], includeProofHints = true): string[] {
+  if (projections.length === 0) return [];
+  const lines = ["Critical proof targets (derived only from the current task contract and working tree):"];
+  for (const projection of projections.slice(0, 8)) {
+    const targets = projection.targets.map((item) => compactRecoveryField(item, 80)).filter(Boolean).slice(0, 8);
+    const dimensions = projection.missingDimensions.map((item) => compactRecoveryField(item, 80)).filter(Boolean).slice(0, 8);
+    const criterion = compactRecoveryField(projection.criterionText, 700);
+    lines.push(`- Target: ${targets.join(", ") || "task-scoped behavior"}; missing proof: ${dimensions.join(", ") || "focused-evidence"}; criterion: ${criterion}`);
+  }
+  const hints = [...new Set(projections.flatMap((projection) => includeProofHints ? projection.proofHints : projection.diagnosticHints ?? [])
+    .map((hint) => compactRecoveryField(hint, 300))
+    .filter(Boolean))].slice(0, 8);
+  if (hints.length > 0) lines.push(includeProofHints ? "Proof requirements:" : "Diagnostic evidence (does not grant repair authority):", ...hints.map((hint) => `- ${hint}`));
+  return lines;
+}

package/packages/piagent-core/runtime/recovery/continuation-budget.ts

@@ -66,6 +66,16 @@ export function continuationDenialReasonCode(reason: ContinuationReservation["re
   return "continuation-journal-unavailable";
 }
 
+export function terminalRecoveryForContinuationDenial(
+  decision: RecoveryDecision,
+  reason: ContinuationReservation["reason"]
+): RecoveryDecision {
+  return {
+    ...decision, action: "handoff", continuation: "none", nextPhase: null, sourceMutationAllowed: false,
+    reasonCodes: [...new Set([...decision.reasonCodes, continuationDenialReasonCode(reason)])]
+  };
+}
+
 export function reserveSemanticReviewContinuation(
   cwd: string,
   task: TaskContract,
@@ -97,10 +107,9 @@ export function planRecoveryContinuation(
     missingVerifyCommands: input.missingVerifyCommands, evidenceDigest: decision.evidenceDigest, reasonCodes: decision.reasonCodes
   });
   if (reservation?.allowed) return { recovery: decision, classification, reservation };
-  const reason = continuationDenialReasonCode(reservation?.reason ?? "journal-unavailable");
   return {
     classification, reservation,
-    recovery: { ...decision, action: "handoff", continuation: "none", nextPhase: null, sourceMutationAllowed: false, reasonCodes: [...decision.reasonCodes, reason] }
+    recovery: terminalRecoveryForContinuationDenial(decision, reservation?.reason ?? "journal-unavailable")
   };
 }