@piagent/platform 1.3.1 → 1.4.1

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

@@ -0,0 +1,139 @@
+// What to do about a refusal.
+//
+// A blocked tool call is the only conversation most operators ever have with
+// this policy, and for most of them it was one-sided: the guard states 74
+// distinct refusals and three of them said what to do next. The rest ended at
+// "no", which leaves the reader guessing at a rule they cannot see.
+//
+// Remedies are attached in one place rather than at the 29 sites that build a
+// refusal, for the reason this codebase keeps arriving at: a rule applied at
+// every call site is a rule that will be missed at the next one. Every decision
+// leaves through `registerToolCallHook`, so it is enough to answer there, and a
+// refusal added tomorrow is answered without anyone remembering to.
+
+// Matched against the refusal text in order; the first match wins, so put the
+// narrower phrase above the broader one it would otherwise be swallowed by.
+const REMEDIES: Array<{ match: RegExp; remedy: string }> = [
+  {
+    // `grep glob targeting` and `find pattern targeting` are the same refusal
+    // reached through a different tool, and matching only the shell wording left
+    // two thirds of this family answering nothing.
+    match: /glob can target protected path|glob targeting protected path|pattern targeting protected path/i,
+    remedy: "Name the exact file instead of a pattern: a pattern is refused when any name it can match is protected."
+      + " `piagent explain '<command>'` shows which name it matched."
+  },
+  {
+    match: /builds a filename this guard cannot resolve/i,
+    // This refusal already carries its own guidance, so it only gains the
+    // pointer to the tool that shows the whole chain.
+    remedy: "`piagent explain '<command>'` shows every step that ran and what each one saw."
+  },
+  {
+    match: /(touches|resolves to) protected path|access to protected path|write to protected path/i,
+    remedy: "Use an approved `piagent-context` projection if one is available. Direct access requires the operator"
+      + " to change the protected-path policy; task scope alone does not override it."
+      + " `piagent explain '<command>'` shows which pattern matched."
+  },
+  {
+    match: /write to read-only path/i,
+    remedy: "The active profile marks this path read-only. Change `readOnlyPaths` in `.pi/piagent-profile.json`"
+      + " if the project really should allow writes here, then reapply the profile."
+  },
+  {
+    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."
+  },
+  {
+    match: /Capability lock is (missing|unreadable)|does not match what this project agreed to/i,
+    remedy: "Reapply the project profile to rebuild the lock: `piagent-init <project> --force-profile`."
+  },
+  {
+    match: /runtime changed during this session/i,
+    remedy: "Restart the Pi session. The lock is re-verified and re-pinned at session start, never mid-session."
+  },
+  {
+    match: /Permission profile read-only blocked/i,
+    remedy: "This session is read-only. Change the access level in Settings, or start it with a writable permission profile."
+  },
+  {
+    match: /Tool (is not registered|registry is disabled|registry blocked)/i,
+    remedy: "Enable the tool group for this profile, or use a tool the profile already allows."
+  },
+  {
+    match: /lifecycle control blocks tool start|resume is blocked|could not enter an audited repair phase/i,
+    remedy: "Resolve the task lifecycle first — resume, repair, or close the current attempt — then retry."
+  },
+  {
+    match: /path traverses symbolic link|path resolves outside the project|path component cannot be inspected/i,
+    remedy: "Use the real path inside the project. A link that leaves the project is refused rather than followed."
+  },
+  {
+    match: /requires confirmation|requires explicit operator approval/i,
+    remedy: "Approve it in the session when prompted; this is a decision the operator makes, not a defect."
+  },
+  {
+    // The whole session is refused here, so this is the refusal most in need of
+    // a next step -- and the one the narrower MCP wording used to miss.
+    match: /Blocked every tool call/i,
+    remedy: "Every tool call is refused while a repository config can reach an ungated server."
+      + " Run `piagent-mcp doctor` to see which config stopped the session, then approve or remove those servers."
+  },
+  {
+    match: /MCP (proxy|shell carrier|command|server)/i,
+    remedy: "Check the server with `piagent-mcp doctor`, and approve it explicitly if the project should reach it."
+  },
+  {
+    match: /is read-only; .*cannot mutate|read-only inspection allowlist/i,
+    remedy: "This task was started read-only. Start a source-change task with `piagent_task_start` when the work needs to write."
+  },
+  {
+    match: /opaque shell mutation whose write target is not statically bounded/i,
+    remedy: "Use the edit, write, or apply-patch tools so the target is named, instead of a shell command that computes it."
+  },
+  {
+    match: /Context budget blocked editing large file/i,
+    remedy: "Edit a narrower range of the file, or split the change, so the edit stays inside the context budget."
+  },
+  {
+    match: /Approval became stale/i,
+    remedy: "Ask for the action again; an approval is bound to the state it was granted for and does not survive a change to it."
+  },
+  {
+    match: /Missing capability|Capability validation failed/i,
+    remedy: "Add the pack that provides it to the project profile, then reapply the profile."
+  },
+  {
+    match: /nesting exceeds inspection depth|unsafe scope pattern/i,
+    remedy: "Flatten the tool input or narrow the scope pattern: anything the guard cannot finish inspecting is refused rather than guessed at."
+  },
+  {
+    match: /start a new attempt or a fresh task/i,
+    remedy: "Start the next attempt with `piagent_task_start`; a closed attempt cannot keep mutating the project."
+  }
+];
+
+// Kept out of the appended text when the refusal already ends by saying what to
+// do, so a reader is never given the same instruction twice in one line.
+const ALREADY_GUIDED = /Write the path out|Reapply the project profile|Restart the session|then retry\.$|Start the task first/i;
+
+export function remedyForReason(reason: string): string | undefined {
+  if (typeof reason !== "string" || reason.trim().length === 0) return undefined;
+  const found = REMEDIES.find((entry) => entry.match.test(reason));
+  if (!found) return undefined;
+  if (ALREADY_GUIDED.test(reason) && !/glob can target|cannot resolve/i.test(reason)) return undefined;
+  return found.remedy;
+}
+
+export function withRemedy<T extends { block: true; reason: string }>(decision: T): T {
+  const remedy = remedyForReason(decision.reason);
+  if (!remedy || decision.reason.includes(remedy)) return decision;
+  return { ...decision, reason: `${decision.reason.replace(/\s+$/, "")} → ${remedy}` };
+}

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

@@ -0,0 +1,173 @@
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { runReadOnlyGit } from "../inspection/git-status-adapter.ts";
+import {
+  collectIndexPreimage,
+  collectSelectedWorkspacePreimage,
+  type SourceMutationAuthority
+} from "../inspection/source-mutation-projection.ts";
+import { localFilterDisableArgs } from "../inspection/git-filter-safety.ts";
+
+const MAX_INDEX_BYTES = 64 * 1024 * 1024;
+
+export type SourceIndexTransactionResult = {
+  state: "settled" | "rejected" | "uncertain";
+  reasonCode: string | null;
+  beforeIndexPreimage: string;
+  afterIndexPreimage: string | null;
+  beforeWorkspacePreimage: string;
+  afterWorkspacePreimage: string | null;
+  executor: "pi-guard";
+  directExecution: false;
+};
+
+function result(value: Omit<SourceIndexTransactionResult, "executor" | "directExecution">): SourceIndexTransactionResult {
+  return { ...value, executor: "pi-guard", directExecution: false };
+}
+
+function gitEnvironment(indexFile: string): NodeJS.ProcessEnv {
+  return { PATH: process.env.PATH, LC_ALL: "C", LANG: "C", GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: os.devNull,
+    GIT_PAGER: "cat", PAGER: "cat", GIT_TERMINAL_PROMPT: "0", GIT_ASKPASS: "", GIT_INDEX_FILE: indexFile,
+    ...(process.platform === "win32" ? { SystemRoot: process.env.SystemRoot, ComSpec: process.env.ComSpec } : {}) };
+}
+
+async function runGitMutation(repoRoot: string, indexFile: string, args: string[], timeoutMs: number, input?: Buffer): Promise<Buffer> {
+  const filterArgs = await localFilterDisableArgs(repoRoot, timeoutMs);
+  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", "-C", repoRoot, ...args];
+  argv.splice(argv.indexOf("-C"), 0, ...filterArgs);
+  return new Promise<Buffer>((resolve, reject) => {
+    const child = spawn("git", argv, { cwd: repoRoot, env: gitEnvironment(indexFile), shell: false, stdio: [input ? "pipe" : "ignore", "pipe", "pipe"], windowsHide: true });
+    const stdout: Buffer[] = []; let stdoutBytes = 0, stderrBytes = 0, settled = false;
+    child.stdout.on("data", (chunk: Buffer) => { stdoutBytes += chunk.length; if (stdoutBytes <= 64 * 1024) stdout.push(chunk); else child.kill("SIGKILL"); });
+    child.stderr.on("data", (chunk: Buffer) => { stderrBytes += chunk.length; if (stderrBytes > 64 * 1024) child.kill("SIGKILL"); });
+    if (input) { child.stdin.on("error", () => undefined); child.stdin.end(input); }
+    const timer = setTimeout(() => child.kill("SIGKILL"), timeoutMs); timer.unref?.();
+    child.once("error", () => { clearTimeout(timer); if (!settled) { settled = true; reject(new Error("git-mutation-start-failed")); } });
+    child.once("close", (code) => { clearTimeout(timer); if (settled) return; settled = true;
+      if (code === 0 && stdoutBytes <= 64 * 1024 && stderrBytes <= 64 * 1024) resolve(Buffer.concat(stdout)); else reject(new Error("git-mutation-failed")); });
+  });
+}
+
+async function stageExactPaths(repoRoot: string, indexFile: string, repoPaths: string[], timeoutMs: number, objectLengthHint: number): Promise<void> {
+  const entries: Array<{ mode: string; object: string | null; repoPath: string }> = [];
+  let objectLength: 40 | 64 | null = null;
+  for (const repoPath of repoPaths) {
+    const absolute = path.resolve(repoRoot, repoPath);
+    try {
+      const stat = fs.lstatSync(absolute);
+      if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("unsupported-workspace-entry");
+      const object = (await runGitMutation(repoRoot, indexFile, ["hash-object", "-w", "--no-filters", "--", repoPath], timeoutMs)).toString("ascii").trim();
+      if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(object)) throw new Error("git-object-id-invalid");
+      objectLength = object.length as 40 | 64;
+      const mode = stat.mode & 0o111 ? "100755" : "100644";
+      entries.push({ mode, object, repoPath });
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      entries.push({ mode: "0", object: null, repoPath });
+    }
+  }
+  const length = objectLength ?? (objectLengthHint === 64 ? 64 : 40);
+  const input = Buffer.concat(entries.map((entry) => Buffer.from(`${entry.mode} ${entry.object ?? "0".repeat(length)}\t${entry.repoPath}\0`)));
+  await runGitMutation(repoRoot, indexFile, ["update-index", "-z", "--index-info"], timeoutMs, input);
+}
+
+async function applySelectedHunks(authority: SourceMutationAuthority, indexFile: string, selectedHunkRefs: string[], timeoutMs: number): Promise<void> {
+  const patch = authority.patchAuthority;
+  if (!patch || selectedHunkRefs.length === 0 || selectedHunkRefs.length > 128) throw new Error("hunk-patch-unavailable");
+  const selected = new Set(selectedHunkRefs), blocks = patch.hunks.filter((hunk) => selected.has(hunk.hunkRef));
+  if (blocks.length !== selected.size) throw new Error("hunk-patch-stale");
+  const bytes = Buffer.concat([patch.header, ...blocks.map((hunk) => hunk.bytes)]);
+  if (bytes.length === 0 || bytes.length > 2 * 1024 * 1024) throw new Error("hunk-patch-oversized");
+  await runGitMutation(authority.repoRoot, indexFile, ["apply", "--cached", "--recount", "--whitespace=nowarn",
+    ...(authority.target.view === "staged" ? ["--reverse"] : []), "-"], timeoutMs, bytes);
+}
+
+async function gitDirectory(repoRoot: string): Promise<string> {
+  const output = await runReadOnlyGit(repoRoot, ["rev-parse", "--absolute-git-dir"], { maxBytes: 16 * 1024 });
+  const candidate = output.toString("utf8").trim();
+  if (!path.isAbsolute(candidate) || candidate.includes("\0")) throw new Error("git-directory-invalid");
+  const resolved = fs.realpathSync.native(candidate), stat = fs.lstatSync(resolved);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("git-directory-invalid");
+  return resolved;
+}
+
+function copyIndex(indexPath: string, temporary: string): void {
+  try {
+    const stat = fs.lstatSync(indexPath);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_INDEX_BYTES) throw new Error("git-index-invalid");
+    fs.copyFileSync(indexPath, temporary, fs.constants.COPYFILE_EXCL); fs.chmodSync(temporary, 0o600);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+}
+
+function publishIndex(lockDescriptor: number, lockPath: string, temporary: string, indexPath: string): void {
+  const stat = fs.lstatSync(temporary);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_INDEX_BYTES) throw new Error("temporary-index-invalid");
+  const bytes = fs.readFileSync(temporary); fs.ftruncateSync(lockDescriptor, 0);
+  let offset = 0;
+  while (offset < bytes.length) offset += fs.writeSync(lockDescriptor, bytes, offset, bytes.length - offset, offset);
+  fs.fsyncSync(lockDescriptor); fs.fchmodSync(lockDescriptor, 0o600); fs.closeSync(lockDescriptor); fs.renameSync(lockPath, indexPath);
+  try { const directory = fs.openSync(path.dirname(indexPath), "r"); try { fs.fsyncSync(directory); } finally { fs.closeSync(directory); } } catch {}
+}
+
+export async function executeGuardedSourceIndexTransaction(options: {
+  authority: SourceMutationAuthority;
+  expectedIndexPreimage: string;
+  expectedWorkspacePreimage: string;
+  selectedHunkRefs?: string[];
+  recheck: () => boolean;
+  timeoutMs?: number;
+}): Promise<SourceIndexTransactionResult> {
+  const before = { beforeIndexPreimage: options.expectedIndexPreimage, beforeWorkspacePreimage: options.expectedWorkspacePreimage };
+  let directory: string;
+  try { directory = await gitDirectory(options.authority.repoRoot); }
+  catch { return result({ state: "rejected", reasonCode: "git-directory-unavailable", ...before, afterIndexPreimage: null, afterWorkspacePreimage: null }); }
+  const indexPath = path.join(directory, "index"), lockPath = path.join(directory, "index.lock");
+  const temporary = path.join(directory, `piagent-guard-index.${process.pid}.${randomBytes(12).toString("hex")}`);
+  let lockDescriptor: number | null = null, ownsLock = false, committed = false;
+  try {
+    lockDescriptor = fs.openSync(lockPath, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY | (fs.constants.O_NOFOLLOW ?? 0), 0o600);
+    ownsLock = true;
+    const lockedIndex = await collectIndexPreimage(options.authority.repoRoot);
+    const lockedWorkspace = collectSelectedWorkspacePreimage(options.authority.repoRoot, options.authority.repoPaths);
+    if (!options.recheck() || lockedIndex !== options.expectedIndexPreimage || lockedWorkspace !== options.expectedWorkspacePreimage) {
+      return result({ state: "rejected", reasonCode: "mutation-preimage-stale", ...before,
+        afterIndexPreimage: lockedIndex, afterWorkspacePreimage: lockedWorkspace });
+    }
+    copyIndex(indexPath, temporary);
+    const timeoutMs = Math.max(100, Math.min(60_000, options.timeoutMs ?? 5_000));
+    if ((options.selectedHunkRefs?.length ?? 0) > 0) await applySelectedHunks(options.authority, temporary, options.selectedHunkRefs!, timeoutMs);
+    else if (options.authority.target.view === "working-tree") await stageExactPaths(options.authority.repoRoot, temporary,
+      options.authority.repoPaths, timeoutMs, options.authority.headOid?.length ?? 40);
+    else if (options.authority.headOid) await runGitMutation(options.authority.repoRoot, temporary,
+      ["restore", "--staged", "--source=HEAD", "--", ...options.authority.repoPaths], timeoutMs);
+    else await runGitMutation(options.authority.repoRoot, temporary,
+      ["rm", "--cached", "-f", "--ignore-unmatch", "--", ...options.authority.repoPaths], timeoutMs);
+    const finalWorkspace = collectSelectedWorkspacePreimage(options.authority.repoRoot, options.authority.repoPaths);
+    const finalRealIndex = await collectIndexPreimage(options.authority.repoRoot);
+    if (!options.recheck() || finalWorkspace !== options.expectedWorkspacePreimage || finalRealIndex !== options.expectedIndexPreimage) {
+      return result({ state: "rejected", reasonCode: "mutation-preimage-stale", ...before,
+        afterIndexPreimage: finalRealIndex, afterWorkspacePreimage: finalWorkspace });
+    }
+    publishIndex(lockDescriptor, lockPath, temporary, indexPath); lockDescriptor = null; ownsLock = false; committed = true;
+    const afterIndexPreimage = await collectIndexPreimage(options.authority.repoRoot);
+    const afterWorkspacePreimage = collectSelectedWorkspacePreimage(options.authority.repoRoot, options.authority.repoPaths);
+    if (afterWorkspacePreimage !== options.expectedWorkspacePreimage || afterIndexPreimage === options.expectedIndexPreimage) {
+      return result({ state: "uncertain", reasonCode: "mutation-postcondition-unknown", ...before, afterIndexPreimage, afterWorkspacePreimage });
+    }
+    return result({ state: "settled", reasonCode: null, ...before, afterIndexPreimage, afterWorkspacePreimage });
+  } catch (error) {
+    const reasonCode = (error as NodeJS.ErrnoException).code === "EEXIST" ? "git-index-locked" : committed ? "mutation-postcondition-unknown" : "git-mutation-failed";
+    return result({ state: committed ? "uncertain" : "rejected", reasonCode, ...before, afterIndexPreimage: null, afterWorkspacePreimage: null });
+  } finally {
+    if (lockDescriptor !== null) try { fs.closeSync(lockDescriptor); } catch {}
+    try { fs.rmSync(temporary, { force: true }); } catch {}
+    if (ownsLock) try { fs.rmSync(lockPath, { force: true }); } catch {}
+  }
+}

package/packages/piagent-core/runtime/policy/source-mutation-guard-binding.ts

@@ -0,0 +1,42 @@
+import { randomBytes } from "node:crypto";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { effectiveProtectedPaths } from "../../extensions/context-index-policy.js";
+import type { BasePolicy, ProjectProfile, TaskContract } from "../../extensions/guard-types.js";
+import { matchesProtectedPath } from "../../extensions/policy-core.js";
+import { activeSessionTask } from "../../extensions/task-state.js";
+import { inspectTaskControlState } from "../inspection/task-control-journal.ts";
+import { webUiTaskRevision } from "../inspection/webui-snapshot.ts";
+import { piSourceMutationGuard } from "./source-mutation-guard.ts";
+
+export type SourceMutationGuardBindings = {
+  bind(ctx: ExtensionContext): void;
+  unbind(ctx: ExtensionContext): void;
+};
+
+export function createSourceMutationGuardBindings(policy: BasePolicy,
+  loadProfile: (ctx: ExtensionContext) => ProjectProfile): SourceMutationGuardBindings {
+  const guardInstanceId = `guard.${randomBytes(32).toString("hex")}`, bindings = new Map<string, () => void>();
+  const key = (ctx: ExtensionContext) => `${ctx.cwd}\0${ctx.sessionManager.getSessionId()}`;
+  return {
+    bind(ctx) {
+      const bindingKey = key(ctx); bindings.get(bindingKey)?.();
+      bindings.set(bindingKey, piSourceMutationGuard.bind({ cwd: ctx.cwd, rawSessionId: ctx.sessionManager.getSessionId(), guardInstanceId,
+        facts: () => {
+          const task = activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined;
+          if (!task) return null;
+          const control = inspectTaskControlState(ctx.cwd, task);
+          const taskState = task.trace.outcome !== "pending" || control.state === "terminal" ? "terminal"
+            : control.state === "active" ? "active" : "unknown";
+          const protectedPaths = effectiveProtectedPaths(policy, loadProfile(ctx)).readProtectedPaths;
+          return { taskId: task.taskId, taskRunId: task.taskRunId, taskRevision: webUiTaskRevision(task), controlRevision: control.controlRevision,
+            taskState, idle: ctx.isIdle(), isProtectedPath: (candidate: string) => matchesProtectedPath(candidate, protectedPaths) };
+        } }));
+    },
+    unbind(ctx) {
+      const bindingKey = key(ctx), unbind = bindings.get(bindingKey);
+      if (!unbind) return;
+      bindings.delete(bindingKey); unbind();
+    }
+  };
+}

package/packages/piagent-core/runtime/policy/source-mutation-guard.ts

@@ -0,0 +1,184 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  validateSourceMutationTarget,
+  type SourceMutationAction,
+  type SourceMutationAuthority
+} from "../inspection/source-mutation-projection.ts";
+import { validateSourceRevertTarget, type SourceRevertAuthority } from "../inspection/source-revert-projection.ts";
+import {
+  executeGuardedSourceIndexTransaction,
+  type SourceIndexTransactionResult
+} from "./source-index-transaction.ts";
+import { executeGuardedSourceWorktreeRevert } from "./source-worktree-transaction.ts";
+
+const REF = /^[A-Za-z0-9][A-Za-z0-9._:@~-]{0,159}$/;
+const REVISION = /^[A-Za-z0-9][A-Za-z0-9._:~-]{0,159}$/;
+const DIGEST = /^sha256:[a-f0-9]{64}$/;
+const WORKSPACE = /^wt-content-v2:[a-f0-9]{64}$/;
+
+export type SourceMutationGuardFacts = {
+  taskId: string;
+  taskRunId: string;
+  taskRevision: string;
+  controlRevision: string;
+  taskState: "active" | "terminal" | "unknown";
+  idle: boolean;
+  isProtectedPath(projectRelativePath: string): boolean;
+};
+
+export type SourceMutationGuardRequest = {
+  cwd: string;
+  rawSessionId: string;
+  identity: { projectRef: string; runtimeInstanceId: string; sessionRef: string; taskId: string; taskRunId: string };
+  action: SourceMutationAction;
+  expectedTaskRevision: string;
+  expectedControlRevision: string;
+  expectedIndexPreimage: string;
+  expectedWorkspacePreimage: string;
+  selectedHunkRefs: string[];
+  authority: SourceMutationAuthority;
+};
+export type SourceRevertGuardRequest = {
+  cwd: string; rawSessionId: string;
+  identity: { projectRef: string; runtimeInstanceId: string; sessionRef: string; taskId: string; taskRunId: string };
+  action: "source.revert"; expectedTaskRevision: string; expectedControlRevision: string; expectedIndexPreimage: string;
+  expectedWorkspacePreimage: string; previewRef: string; confirmedPreviewDigest: string; authority: SourceRevertAuthority;
+};
+
+type Binding = {
+  cwd: string;
+  rawSessionId: string;
+  guardInstanceId: string;
+  facts(): SourceMutationGuardFacts | null;
+};
+
+function bindingKey(cwd: string, rawSessionId: string): string { return `${fs.realpathSync.native(cwd)}\0${rawSessionId}`; }
+function inside(root: string, candidate: string): boolean {
+  const relative = path.relative(root, candidate);
+  return relative === "" || relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+
+function rejected(request: SourceMutationGuardRequest, reasonCode: string): SourceIndexTransactionResult {
+  return { state: "rejected", reasonCode, beforeIndexPreimage: request.expectedIndexPreimage, afterIndexPreimage: null,
+    beforeWorkspacePreimage: request.expectedWorkspacePreimage, afterWorkspacePreimage: null, executor: "pi-guard", directExecution: false };
+}
+function revertRejected(request: SourceRevertGuardRequest, reasonCode: string): SourceIndexTransactionResult {
+  return { state: "rejected", reasonCode, beforeIndexPreimage: request.expectedIndexPreimage, afterIndexPreimage: null,
+    beforeWorkspacePreimage: request.expectedWorkspacePreimage, afterWorkspacePreimage: null, executor: "pi-guard", directExecution: false };
+}
+
+export class PiSourceMutationGuard {
+  readonly #bindings = new Map<string, Binding>();
+
+  bind(input: Binding): () => void {
+    const key = bindingKey(input.cwd, input.rawSessionId);
+    this.#bindings.set(key, { ...input, cwd: fs.realpathSync.native(input.cwd) });
+    return () => {
+      const current = this.#bindings.get(key);
+      if (current?.guardInstanceId === input.guardInstanceId) this.#bindings.delete(key);
+    };
+  }
+
+  available(cwd: string, rawSessionId: string): boolean {
+    try {
+      const binding = this.#bindings.get(bindingKey(cwd, rawSessionId)), facts = binding?.facts();
+      return Boolean(facts && facts.taskState === "active" && facts.idle);
+    } catch { return false; }
+  }
+
+  async execute(request: SourceMutationGuardRequest): Promise<SourceIndexTransactionResult> {
+    let binding: Binding | undefined;
+    try { binding = this.#bindings.get(bindingKey(request.cwd, request.rawSessionId)); }
+    catch { return rejected(request, "mutation-guard-unavailable"); }
+    if (!binding || !this.#validRequest(request)) return rejected(request, binding ? "mutation-guard-request-invalid" : "mutation-guard-unavailable");
+    const recheck = (): boolean => {
+      try {
+        const facts = binding!.facts();
+        return Boolean(facts && facts.taskState === "active" && facts.idle
+          && facts.taskId === request.identity.taskId && facts.taskRunId === request.identity.taskRunId
+          && facts.taskRevision === request.expectedTaskRevision && facts.controlRevision === request.expectedControlRevision
+          && this.#pathsAllowed(binding!, facts, request.authority));
+      } catch { return false; }
+    };
+    if (!recheck()) return rejected(request, "mutation-guard-precondition-stale");
+    return executeGuardedSourceIndexTransaction({ authority: request.authority,
+      expectedIndexPreimage: request.expectedIndexPreimage, expectedWorkspacePreimage: request.expectedWorkspacePreimage,
+      selectedHunkRefs: request.selectedHunkRefs, recheck });
+  }
+
+  async executeRevert(request: SourceRevertGuardRequest): Promise<SourceIndexTransactionResult> {
+    let binding: Binding | undefined;
+    try { binding = this.#bindings.get(bindingKey(request.cwd, request.rawSessionId)); }
+    catch { return revertRejected(request, "mutation-guard-unavailable"); }
+    if (!binding || !this.#validRevertRequest(request)) return revertRejected(request, binding ? "mutation-guard-request-invalid" : "mutation-guard-unavailable");
+    const recheck = (): boolean => {
+      try {
+        const facts = binding!.facts(), target = request.authority.target;
+        return Boolean(facts && facts.taskState === "active" && facts.idle && Date.now() <= Date.parse(target.expiresAt)
+          && facts.taskId === request.identity.taskId && facts.taskRunId === request.identity.taskRunId
+          && facts.taskRevision === request.expectedTaskRevision && facts.controlRevision === request.expectedControlRevision
+          && this.#pathsAllowed(binding!, facts, { repoRoot: request.authority.repoRoot, repoPaths: [request.authority.repoPath] }));
+      } catch { return false; }
+    };
+    if (!recheck()) return revertRejected(request, "mutation-guard-precondition-stale");
+    return executeGuardedSourceWorktreeRevert({ authority: request.authority, expectedIndexPreimage: request.expectedIndexPreimage,
+      expectedWorkspacePreimage: request.expectedWorkspacePreimage, recheck });
+  }
+
+  #validRequest(request: SourceMutationGuardRequest): boolean {
+    try { validateSourceMutationTarget(request.authority.target); }
+    catch { return false; }
+    const target = request.authority.target;
+    return REF.test(request.identity.projectRef) && REF.test(request.identity.runtimeInstanceId) && REF.test(request.identity.sessionRef)
+      && REF.test(request.identity.taskId) && REF.test(request.identity.taskRunId)
+      && REVISION.test(request.expectedTaskRevision) && REVISION.test(request.expectedControlRevision)
+      && DIGEST.test(request.expectedIndexPreimage) && WORKSPACE.test(request.expectedWorkspacePreimage)
+      && target.taskRevision === request.expectedTaskRevision && target.indexPreimage === request.expectedIndexPreimage
+      && target.workspacePreimage === request.expectedWorkspacePreimage
+      && Array.isArray(request.selectedHunkRefs) && request.selectedHunkRefs.length <= 128
+      && new Set(request.selectedHunkRefs).size === request.selectedHunkRefs.length
+      && request.selectedHunkRefs.every((hunkRef) => REF.test(hunkRef) && target.hunkRefs.includes(hunkRef))
+      && JSON.stringify(request.selectedHunkRefs) === JSON.stringify(target.hunkRefs.filter((hunkRef) => request.selectedHunkRefs.includes(hunkRef)))
+      && (request.selectedHunkRefs.length === 0 || Boolean(request.authority.patchAuthority && target.status === "M"
+        && target.oldPath === null && request.authority.repoPaths.length === 1))
+      && (request.action === "source.stage" && target.view === "working-tree" && target.effect === "copy-worktree-to-index"
+        || request.action === "source.unstage" && target.view === "staged" && target.effect === "restore-index-from-head");
+  }
+
+  #validRevertRequest(request: SourceRevertGuardRequest): boolean {
+    try { validateSourceRevertTarget(request.authority.target); } catch { return false; }
+    const target = request.authority.target;
+    return request.action === "source.revert" && REF.test(request.identity.projectRef) && REF.test(request.identity.runtimeInstanceId)
+      && REF.test(request.identity.sessionRef) && REF.test(request.identity.taskId) && REF.test(request.identity.taskRunId)
+      && REVISION.test(request.expectedTaskRevision) && REVISION.test(request.expectedControlRevision)
+      && DIGEST.test(request.expectedIndexPreimage) && WORKSPACE.test(request.expectedWorkspacePreimage)
+      && REF.test(request.previewRef) && DIGEST.test(request.confirmedPreviewDigest)
+      && request.previewRef === target.previewRef && request.confirmedPreviewDigest === target.confirmedPreviewDigest
+      && target.taskRevision === request.expectedTaskRevision && target.indexPreimage === request.expectedIndexPreimage
+      && target.workspacePreimage === request.expectedWorkspacePreimage && target.view === "working-tree"
+      && target.status === "M" && target.oldPath === null && target.effect === "restore-worktree-from-index"
+      && request.authority.repoPath === target.path && request.authority.patchAuthority.hunks.length >= 1
+      && target.hunkRefs.every((hunkRef) => request.authority.patchAuthority.hunks.some((hunk) => hunk.hunkRef === hunkRef));
+  }
+
+  #pathsAllowed(binding: Binding, facts: SourceMutationGuardFacts, authority: Pick<SourceMutationAuthority, "repoRoot" | "repoPaths">): boolean {
+    const projectRoot = binding.cwd;
+    let repoRoot: string;
+    try { repoRoot = fs.realpathSync.native(authority.repoRoot); }
+    catch { return false; }
+    if (!authority.repoPaths.length || authority.repoPaths.length > 2) return false;
+    return authority.repoPaths.every((repoPath) => {
+      if (!repoPath || path.isAbsolute(repoPath) || repoPath.includes("\0")) return false;
+      const absolute = path.resolve(repoRoot, repoPath);
+      if (!inside(repoRoot, absolute) || !inside(projectRoot, absolute)) return false;
+      const relative = path.relative(projectRoot, absolute).split(path.sep).join("/");
+      return Boolean(relative && relative !== "." && !facts.isProtectedPath(relative));
+    });
+  }
+}
+
+const BROKER_KEY = Symbol.for("piagent.webui.source-mutation-guard.v1");
+const root = globalThis as typeof globalThis & { [BROKER_KEY]?: PiSourceMutationGuard };
+export const piSourceMutationGuard = root[BROKER_KEY] ??= new PiSourceMutationGuard();

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

@@ -0,0 +1,105 @@
+import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+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 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 {
+  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 } : {}) };
+}
+async function runGit(repoRoot: string, args: string[], input: Buffer, timeoutMs: number): Promise<void> {
+  const filterArgs = await localFilterDisableArgs(repoRoot, timeoutMs);
+  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];
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn("git", argv, { cwd: repoRoot, env: environment(), 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?.();
+    child.once("error", () => { clearTimeout(timer); if (!settled) { settled = true; reject(new Error("git-revert-start-failed")); } });
+    child.once("close", (code) => { clearTimeout(timer); if (settled) return; settled = true;
+      if (code === 0 && stderr <= 64 * 1024) resolve(); else reject(new Error("git-revert-failed")); });
+  });
+}
+async function gitDirectory(repoRoot: string): Promise<string> {
+  const candidate = (await runReadOnlyGit(repoRoot, ["rev-parse", "--absolute-git-dir"], { maxBytes: 16 * 1024 })).toString("utf8").trim();
+  const resolved = fs.realpathSync.native(candidate), stat = fs.lstatSync(resolved);
+  if (!path.isAbsolute(candidate) || !stat.isDirectory() || stat.isSymbolicLink()) throw new Error("git-directory-invalid");
+  return resolved;
+}
+async function restoreWholeFile(authority: SourceRevertAuthority, recheck: () => Promise<boolean>): Promise<void> {
+  const bytes = await runReadOnlyGit(authority.repoRoot, ["cat-file", "blob", authority.indexObject], { maxBytes: 16 * 1024 * 1024 });
+  const target = path.resolve(authority.repoRoot, authority.repoPath), parent = fs.realpathSync.native(path.dirname(target));
+  if (parent !== path.dirname(target) || !target.startsWith(`${authority.repoRoot}${path.sep}`)) throw new Error("revert-target-unsafe");
+  const current = fs.lstatSync(target); if (!current.isFile() || current.isSymbolicLink()) throw new Error("revert-target-unsafe");
+  const temporary = path.join(parent, `.${path.basename(target)}.piagent-revert.${process.pid}.${randomBytes(8).toString("hex")}`);
+  const descriptor = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW ?? 0), 0o600);
+  try { fs.writeFileSync(descriptor, bytes); fs.fsyncSync(descriptor); fs.fchmodSync(descriptor, authority.indexMode === "100755" ? 0o755 : 0o644); }
+  finally { fs.closeSync(descriptor); }
+  try { if (!await recheck()) throw new Error("revert-preimage-stale"); fs.renameSync(temporary, target); }
+  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> {
+  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);
+}
+
+export async function executeGuardedSourceWorktreeRevert(options: { authority: SourceRevertAuthority; expectedIndexPreimage: string;
+  expectedWorkspacePreimage: string; recheck(): boolean; timeoutMs?: number }): Promise<SourceIndexTransactionResult> {
+  const before = { beforeIndexPreimage: options.expectedIndexPreimage, beforeWorkspacePreimage: options.expectedWorkspacePreimage };
+  let lockPath = "", ownsLock = false, committed = false;
+  try {
+    const gitDir = await gitDirectory(options.authority.repoRoot), lockName = createHash("sha256").update(options.authority.repoPath).digest("hex");
+    lockPath = path.join(gitDir, `piagent-webui-worktree-${lockName}.lock`);
+    const descriptor = fs.openSync(lockPath, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY | (fs.constants.O_NOFOLLOW ?? 0), 0o600);
+    fs.closeSync(descriptor); ownsLock = true;
+    const lockedIndex = await collectIndexPreimage(options.authority.repoRoot);
+    const lockedWorkspace = collectSelectedWorkspacePreimage(options.authority.repoRoot, [options.authority.repoPath]);
+    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;
+    if (options.authority.target.hunkRefs.length) {
+      if (!await finalRecheck()) 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)));
+    } else await restoreWholeFile(options.authority, finalRecheck);
+    committed = true;
+    const afterIndexPreimage = await collectIndexPreimage(options.authority.repoRoot);
+    const afterWorkspacePreimage = collectSelectedWorkspacePreimage(options.authority.repoRoot, [options.authority.repoPath]);
+    if (afterIndexPreimage !== options.expectedIndexPreimage || afterWorkspacePreimage === options.expectedWorkspacePreimage)
+      return result({ state: "uncertain", reasonCode: "mutation-postcondition-unknown", ...before, afterIndexPreimage, afterWorkspacePreimage });
+    if (options.authority.target.hunkRefs.length) {
+      const snapshot = await collectGitStatusForPaths(options.authority.repoRoot, [options.authority.repoPath]);
+      const record = snapshot.records.find((item) => item.path.value === options.authority.repoPath);
+      if (record) {
+        const remaining = await collectExactGitPatchAuthority({ snapshot, record, view: "unstaged", fileRef: options.authority.target.fileRef });
+        if (remaining?.hunks.some((hunk) => options.authority.target.hunkRefs.includes(hunk.hunkRef)))
+          return result({ state: "uncertain", reasonCode: "mutation-postcondition-unknown", ...before, afterIndexPreimage, afterWorkspacePreimage });
+      }
+    }
+    return result({ state: "settled", reasonCode: null, ...before, afterIndexPreimage, afterWorkspacePreimage });
+  } catch (error) {
+    const reasonCode = (error as NodeJS.ErrnoException).code === "EEXIST" ? "worktree-revert-locked"
+      : committed ? "mutation-postcondition-unknown" : "worktree-revert-failed";
+    return result({ state: committed ? "uncertain" : "rejected", reasonCode, ...before, afterIndexPreimage: null, afterWorkspacePreimage: null });
+  } finally { if (ownsLock) try { fs.rmSync(lockPath, { force: true }); } catch {} }
+}