@piagent/platform 1.6.0 → 1.7.1

package/packages/piagent-core/runtime/orchestration/subagent-tool-policy.ts

@@ -0,0 +1,329 @@
+import crypto from "node:crypto";
+import path from "node:path";
+
+import type { TaskContract } from "../../extensions/guard-types.js";
+import { taskAuthorityMode } from "../policy/task-authority-runtime.ts";
+import { MINIMAL_DELEGATION_LIMITS } from "./minimal-delegation-policy.ts";
+
+const SUBAGENT_TOOL = /(?:^|[_-])subagents?(?:[_-]|$)/i;
+const NON_DISPATCH_ACTIONS = new Set(["cancel", "kill", "list", "status", "stop", "wait"]);
+const READ_ONLY_AGENTS = new Set([
+  "piagent-oracle",
+  "piagent-planner",
+  "piagent-reviewer",
+  "piagent-scout"
+]);
+const URL = /\bhttps?:\/\/[^\s<>)\]}]+/i;
+const PROVIDED_SOURCE = /\b(?:provided|supplied|attached|pasted)\s+(?:evidence|source|text)|\busing only (?:the )?(?:evidence|source|text) below|\bdo not (?:fetch|open|retrieve)|\bn[oộ]i dung (?:đ[aã] )?(?:cung c[aấ]p|d[aá]n|đ[ií]nh k[eè]m)/i;
+
+type PlainRecord = Record<string, unknown>;
+
+export type DirectSubagentDispatchPreflight = {
+  applicable: boolean;
+  dispatch: boolean;
+  allowed: boolean;
+  reasonCode: string | null;
+  reason: string | null;
+  role: string | null;
+  requestCount: number;
+};
+
+export type DirectSubagentResult = {
+  applicable: boolean;
+  spawned: boolean;
+  failed: boolean;
+  reasonCode: string | null;
+  disposition: string;
+  role: "retriever" | "scout" | "planner" | "worker" | "reviewer" | "oracle" | "researcher";
+  requestRef: string;
+  outputDigest: string | null;
+  calls: number;
+  tokens: number;
+};
+
+type DirectSubagentTaskPersistence = {
+  now: () => string;
+  persist: (task: TaskContract) => TaskContract;
+  trace: (payload: Record<string, unknown>) => void;
+  sessionTrace?: (payload: Record<string, unknown>) => void;
+};
+
+export function taskHelperUsageMode(task: TaskContract): "off" | "recommend" | "on" {
+  const boundMode = taskAuthorityMode(task, "CAP-14");
+  return boundMode === "on" || boundMode === "recommend" ? boundMode : "off";
+}
+
+export function reserveDirectSubagentDispatch(
+  task: TaskContract | undefined,
+  toolCallId: string,
+  persistence: DirectSubagentTaskPersistence
+): TaskContract | undefined {
+  if (!task || task.trace.outcome !== "pending" || task.orchestration?.subagents !== "not-used") return task;
+  task.orchestration = {
+    ...(task.orchestration ?? {
+      mode: "solo-first" as const,
+      subagents: "not-used" as const,
+      reason: "Parent works directly by default."
+    }),
+    subagents: "optional",
+    reason: "One bounded read-only helper dispatch is authorized and awaiting a durable result."
+  };
+  task.updatedAt = persistence.now();
+  const written = persistence.persist(task);
+  persistence.trace({
+    event: "helper_dispatch_reserved",
+    taskId: written.taskId,
+    taskRunId: written.taskRunId,
+    sessionId: written.sessionId,
+    toolCallId
+  });
+  return written;
+}
+
+export function recordDirectSubagentResult(
+  task: TaskContract | undefined,
+  event: { toolCallId?: string; toolName: string },
+  result: DirectSubagentResult,
+  persistence: DirectSubagentTaskPersistence
+): TaskContract | undefined {
+  if (!task || task.trace.outcome !== "pending") return task;
+  const existingUsage = task.acceptanceReceipt?.helperUsage;
+  const helper = {
+    role: result.role,
+    disposition: result.disposition,
+    requestRef: result.requestRef,
+    outputDigest: result.outputDigest,
+    calls: result.calls,
+    tokens: result.tokens
+  };
+  const helpers = result.spawned
+    ? [...(existingUsage?.helpers ?? []).filter((item) => item.requestRef !== result.requestRef), helper].slice(-3)
+    : existingUsage?.helpers ?? [];
+  const used = helpers.length > 0 || existingUsage?.used === true;
+  const reasonCodes = [...new Set([
+    ...(existingUsage?.reasonCodes ?? []),
+    result.reasonCode ?? (result.spawned ? "helper-result-accepted" : "helper-dispatch-rejected")
+  ])].slice(-16);
+  if (task.acceptanceReceipt) {
+    task.acceptanceReceipt.helperUsage = {
+      mode: taskHelperUsageMode(task),
+      used,
+      decision: result.spawned ? "dispatch" : "skip",
+      projectedSavingsRatio: existingUsage?.projectedSavingsRatio ?? null,
+      reasonCodes,
+      helpers,
+      recordedAt: persistence.now()
+    };
+  }
+  if (task.orchestration) {
+    task.orchestration.subagents = used ? "used" : "not-used";
+    task.orchestration.reason = result.spawned
+      ? `A bounded read-only helper ran with disposition ${result.disposition}; its digest-only usage is recorded in the acceptance receipt.`
+      : `Helper dispatch did not start (${result.reasonCode ?? "helper-dispatch-rejected"}); the parent remains the sole execution owner.`;
+  }
+  task.updatedAt = persistence.now();
+  const written = persistence.persist(task);
+  const trace = {
+    event: "helper_result_recorded",
+    taskId: written.taskId,
+    taskRunId: written.taskRunId,
+    sessionId: written.sessionId,
+    toolCallId: event.toolCallId,
+    toolName: event.toolName,
+    spawned: result.spawned,
+    disposition: result.disposition,
+    reasonCode: result.reasonCode,
+    calls: result.calls,
+    tokens: result.tokens
+  };
+  persistence.trace(trace);
+  persistence.sessionTrace?.(trace);
+  return written;
+}
+
+function record(value: unknown): PlainRecord {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as PlainRecord : {};
+}
+
+function finiteInteger(value: unknown, fallback = 0): number {
+  return typeof value === "number" && Number.isFinite(value)
+    ? Math.max(0, Math.trunc(value))
+    : fallback;
+}
+
+function helperRole(value: unknown): DirectSubagentResult["role"] {
+  const normalized = String(value ?? "").trim().toLowerCase().replace(/^piagent-/, "");
+  return ["retriever", "scout", "planner", "worker", "reviewer", "oracle", "researcher"].includes(normalized)
+    ? normalized as DirectSubagentResult["role"]
+    : "scout";
+}
+
+function dispatchRequests(input: PlainRecord): PlainRecord[] {
+  if (Array.isArray(input.tasks)) {
+    return input.tasks.filter((item): item is PlainRecord => Boolean(item && typeof item === "object" && !Array.isArray(item)))
+      .map((item) => ({ ...input, ...item, tasks: undefined }));
+  }
+  return typeof input.agent === "string" && input.agent.trim() ? [input] : [];
+}
+
+function boundedNumber(input: PlainRecord, nestedField: string, field: string): number | undefined {
+  const nested = record(input[nestedField]);
+  const value = nested[field];
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function sameProjectRoot(currentCwd: string, requested: unknown): boolean {
+  if (typeof requested !== "string" || !requested.trim()) return true;
+  return path.resolve(currentCwd) === path.resolve(currentCwd, requested);
+}
+
+function blocked(reasonCode: string, reason: string, role: string | null, requestCount: number): DirectSubagentDispatchPreflight {
+  return { applicable: true, dispatch: true, allowed: false, reasonCode, reason, role, requestCount };
+}
+
+/**
+ * The optional pi-subagents tool is a second execution backend. It must not be
+ * able to bypass the task-bound CAP-14 snapshot merely because the model knows
+ * the tool name. This preflight is deliberately conservative: one fresh,
+ * read-only, locally capable helper, with the same hard ceilings as Piagent's
+ * owned helper runtime.
+ */
+export function evaluateDirectSubagentDispatch(input: {
+  toolName: string;
+  toolInput: unknown;
+  cwd: string;
+  helpersMode: "off" | "recommend" | "on";
+  taskPending: boolean;
+  dispatchAuthority: boolean;
+  durableSubagentState?: "not-used" | "optional" | "used";
+}): DirectSubagentDispatchPreflight {
+  if (!SUBAGENT_TOOL.test(input.toolName)) {
+    return { applicable: false, dispatch: false, allowed: true, reasonCode: null, reason: null, role: null, requestCount: 0 };
+  }
+  const toolInput = record(input.toolInput);
+  const requests = dispatchRequests(toolInput);
+  const action = String(toolInput.action ?? "").trim().toLowerCase();
+  if (requests.length === 0 && NON_DISPATCH_ACTIONS.has(action)) {
+    return { applicable: true, dispatch: false, allowed: true, reasonCode: null, reason: null, role: null, requestCount: 0 };
+  }
+  if (requests.length === 0) return blocked("helper-dispatch-shape-invalid", "Subagent dispatch requires exactly one named read-only helper.", null, 0);
+  const role = String(requests[0].agent ?? "").trim();
+  if (requests.length !== 1) return blocked("helper-count-exceeds-one", `Piagent permits at most one helper for the entire task; ${requests.length} were requested.`, role || null, requests.length);
+  if (!input.taskPending) return blocked("helper-task-authority-missing", "A pending session-bound task is required before helper dispatch.", role || null, 1);
+  if (input.helpersMode !== "on" || !input.dispatchAuthority) {
+    return blocked("helper-dispatch-authority-disabled", "Task-bound helper authority is not on; continue in the parent model.", role || null, 1);
+  }
+  if (input.durableSubagentState === "optional" || input.durableSubagentState === "used") {
+    return blocked("helper-retry-forbidden", "This task already reserved or used its one helper; helper retries are disabled.", role || null, 1);
+  }
+  if (role === "piagent-worker" || !READ_ONLY_AGENTS.has(role)) {
+    return blocked("automatic-helper-role-disabled", `Automatic helper ${role || "(unknown)"} is not an enabled read-only Piagent role.`, role || null, 1);
+  }
+  const request = requests[0];
+  if (request.context !== undefined && request.context !== "fresh") {
+    return blocked("helper-parent-history-forbidden", "Helpers must use fresh isolated context and cannot fork the parent transcript.", role, 1);
+  }
+  if (!sameProjectRoot(input.cwd, request.cwd)) {
+    return blocked("helper-cwd-outside-project", "Helper cwd must remain the current project root.", role, 1);
+  }
+  const timeoutMs = typeof request.timeoutMs === "number" ? request.timeoutMs : undefined;
+  if (timeoutMs === undefined) {
+    return blocked("helper-time-budget-missing", "Helper dispatch requires an explicit timeoutMs no greater than 300 seconds.", role, 1);
+  }
+  if (!Number.isFinite(timeoutMs) || timeoutMs > 300_000 || timeoutMs < 1) {
+    return blocked("helper-time-budget-exceeded", "Helper timeout must be between 1 ms and the 300 second Piagent ceiling.", role, 1);
+  }
+  const maxTurns = boundedNumber(request, "turnBudget", "maxTurns");
+  if (maxTurns === undefined) {
+    return blocked("helper-turn-budget-missing", "Helper dispatch requires an explicit turnBudget.maxTurns no greater than 8.", role, 1);
+  }
+  if (maxTurns < 1 || maxTurns > 8) {
+    return blocked("helper-turn-budget-exceeded", "Helper maxTurns exceeds the bounded 8-turn ceiling.", role, 1);
+  }
+  const hardCalls = boundedNumber(request, "toolBudget", "hard");
+  if (hardCalls === undefined) {
+    return blocked("helper-call-budget-missing", `Helper dispatch requires an explicit toolBudget.hard no greater than ${MINIMAL_DELEGATION_LIMITS.maxHelperCalls}.`, role, 1);
+  }
+  if (hardCalls < 1 || hardCalls > MINIMAL_DELEGATION_LIMITS.maxHelperCalls) {
+    return blocked("helper-call-budget-exceeded", `Helper hard tool budget exceeds the ${MINIMAL_DELEGATION_LIMITS.maxHelperCalls}-call ceiling.`, role, 1);
+  }
+  const objective = String(request.task ?? "").trim();
+  if (!objective) return blocked("helper-objective-missing", "Helper dispatch requires a bounded objective.", role, 1);
+  if (URL.test(objective) && !PROVIDED_SOURCE.test(objective)) {
+    return blocked("helper-source-access-unavailable", "The selected helper has local read tools only and cannot retrieve the remote URL; inspect it in the parent or provide a local checkout/evidence bundle.", role, 1);
+  }
+  return { applicable: true, dispatch: true, allowed: true, reasonCode: null, reason: null, role, requestCount: 1 };
+}
+
+function textContent(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content.filter((item) => item && typeof item === "object" && (item as { type?: unknown }).type === "text")
+    .map((item) => String((item as { text?: unknown }).text ?? "")).join("\n");
+}
+
+function childAcceptanceFailed(result: PlainRecord): boolean {
+  const acceptance = record(result.acceptance);
+  const report = record(acceptance.childReport);
+  const criteria = Array.isArray(report.criteriaSatisfied) ? report.criteriaSatisfied : [];
+  return criteria.some((item) => record(item).status === "not-satisfied")
+    || ["failed", "rejected", "not-satisfied"].includes(String(acceptance.status ?? "").toLowerCase());
+}
+
+function totalUsage(details: PlainRecord, results: PlainRecord[]): number {
+  const aggregate = record(details.totalChildUsage);
+  const sources = Object.keys(aggregate).length > 0 ? [aggregate] : results.map((result) => record(result.usage));
+  return Math.min(100_000_000, sources.reduce((total, usage) => total
+    + finiteInteger(usage.input)
+    + finiteInteger(usage.output)
+    + finiteInteger(usage.cacheRead)
+    + finiteInteger(usage.cacheWrite), 0));
+}
+
+/** Convert a pi-subagents provider result into fail-closed, digest-only truth. */
+export function classifyDirectSubagentResult(input: {
+  toolName: string;
+  toolInput: unknown;
+  content: unknown;
+  details: unknown;
+  isError?: boolean;
+}): DirectSubagentResult | undefined {
+  if (!SUBAGENT_TOOL.test(input.toolName)) return undefined;
+  const toolInput = record(input.toolInput);
+  if (dispatchRequests(toolInput).length === 0) return undefined;
+  const details = record(input.details);
+  const results = Array.isArray(details.results)
+    ? details.results.filter((item): item is PlainRecord => Boolean(item && typeof item === "object" && !Array.isArray(item)))
+    : [];
+  const spawned = results.length > 0 || typeof details.runId === "string" && details.runId.length > 0;
+  const resultFailures = results.some((result) => finiteInteger(result.exitCode) !== 0 || childAcceptanceFailed(result));
+  const content = textContent(input.content);
+  const insufficientEvidence = results.some(childAcceptanceFailed)
+    || /\bscope inspected:\s*none\b|\bno source (?:content|evidence) (?:was|could be) (?:accessible|collected)|\bcriteria?[^\n]{0,80}not-satisfied\b/i.test(content);
+  const failed = input.isError === true || !spawned || resultFailures || insufficientEvidence;
+  const reasonCode = input.isError === true
+    ? "helper-tool-error"
+    : !spawned
+      ? "helper-dispatch-rejected"
+      : insufficientEvidence
+        ? "helper-insufficient-evidence"
+        : resultFailures
+          ? "helper-run-failed"
+          : null;
+  const firstResult = results[0] ?? {};
+  const agent = firstResult.agent ?? dispatchRequests(toolInput)[0]?.agent;
+  const finalOutput = results.map((result) => String(result.finalOutput ?? "")).filter(Boolean).join("\n");
+  const calls = Math.min(100, results.reduce((total, result) => total + finiteInteger(result.toolCount), 0));
+  return {
+    applicable: true,
+    spawned,
+    failed,
+    reasonCode,
+    disposition: failed ? reasonCode ?? "failed" : "succeeded",
+    role: helperRole(agent),
+    requestRef: crypto.createHash("sha256").update(JSON.stringify(toolInput)).digest("hex"),
+    outputDigest: !failed && finalOutput ? crypto.createHash("sha256").update(finalOutput).digest("hex") : null,
+    calls,
+    tokens: totalUsage(details, results)
+  };
+}

package/packages/piagent-core/runtime/policy/block-remedy.ts

@@ -43,10 +43,6 @@ const REMEDIES: Array<{ match: RegExp; remedy: string }> = [
     match: /outside resolved filesystem scope/i,
     remedy: "Work inside the project, or widen the filesystem scope in the active profile and reapply it."
   },
-  {
-    match: /cannot mutate paths outside its declared scope|semantic repair must stay inside its declared task scope/i,
-    remedy: "Start a new attempt with `piagent_task_start` listing this path in the scope; a running task cannot widen its own."
-  },
   {
     match: /Task Implementation Contract is required/i,
     remedy: "Call `piagent_task_start` once with explicit project-relative scope, then retry."

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,
@@ -112,6 +116,9 @@ export function buildTaskEfficiencyMetrics(
     helpers: {
       mode: helperUsage?.mode ?? "unknown",
       used: helperUsage?.used ?? false,
+      decision: helperUsage?.decision ?? (helperUsage?.used ? "dispatch" : "skip"),
+      projectedSavingsRatio: helperUsage?.projectedSavingsRatio ?? null,
+      reasonCodes: helperUsage?.reasonCodes ?? ["parent-direct-default"],
       entries: (helperUsage?.helpers ?? []).map((item) => ({
         role: item.role,
         model: null,
@@ -127,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;