@piagent/platform 1.37.0 → 1.38.1

package/packages/piagent-core/runtime/checkpoints/turn-checkpoints.mjs

@@ -0,0 +1,167 @@
+import { randomUUID } from 'node:crypto';
+import { checkpointDigest, previewCheckpointRestore } from './restore-preview.mjs';
+
+// Another owner holds this session's history (a second runtime mid-turn, a
+// replaced runtime): the change waits rather than racing it. Any other failure
+// only costs the turn its checkpoint.
+export const checkpointOwnershipError = error =>
+  /checkpoint-(?:turn-owned|store-busy|lock-changed|authority-changed|session-capacity|command-capacity)/.test(String(error?.message ?? error));
+
+// Shared turn history and drift refusal; Git execution is supplied by an adapter.
+export class TurnCheckpointService {
+  #stack = [];
+  #tail = Promise.resolve();
+  #pending = 0;
+  #gap = false;
+  constructor(git, { busy = /** @returns {boolean} */ () => false, history = null,
+    memberEdits = /** @param {number} _since @returns {Set<string>} */ _since => new Set() } = {}) {
+    this.git = git; this.busy = busy; this.history = history; this.memberEdits = memberEdits;
+    this.#stack = history?.load() ?? [];
+  }
+  /** @template T @param {() => Promise<T>} action @returns {Promise<T>} */
+  #serial(action) {
+    if (this.#pending >= 128) return Promise.reject(Error('checkpoint-command-capacity'));
+    this.#pending++;
+    const locked = async () => {
+      // Non-Git projects remain side-effect-free, including checkpoint metadata.
+      if (!this.history || this.git.available && !await this.git.available()) return await action();
+      return await this.history.operation(async () => {
+        // A turn that ran without a checkpoint (the store refused it) ends the
+        // history it would otherwise sit inside.
+        if (this.#gap) { this.#gap = false; await this.#barrier(null); }
+        return await action();
+      });
+    };
+    const operation = this.#tail.then(locked, locked);
+    this.#tail = operation.then(() => {}, () => {});
+    return operation.finally(() => { this.#pending--; });
+  }
+  async close() { await this.history?.close(); }
+  revoke() { this.history?.revoke(); }
+  // A change is about to happen without a checkpoint for its turn.
+  markGap() { this.#stack = []; this.#gap = true; }
+  take(run) {
+    return this.#serial(() => this.#take(run)).catch(error => {
+      if (run && run.checkpoint === undefined && !checkpointOwnershipError(error)) { run.checkpoint = null; run.checkpointError = error; this.markGap(); }
+      throw error;
+    });
+  }
+  finish(run) { return this.#serial(() => this.#finish(run)); }
+  undo() { return this.#serial(() => this.#undo()); }
+  list() { return this.#serial(async () => {
+    this.history?.assertCurrent();
+    return { revision: checkpointDigest(this.#stack), available: this.git.available ? await this.git.available() : true,
+      points: this.#stack.map(({ id, turnRef, at }) => ({ id, turnRef, at })) };
+  }); }
+  preview(targetId) { return this.#serial(() => this.#preview(targetId)); }
+  async #preview(targetId) {
+    this.history?.assertCurrent();
+    const preview = await previewCheckpointRestore(this.git, this.#stack, targetId, this.busy(), this.memberEdits);
+    this.history?.assertCurrent();
+    return preview;
+  }
+  restoreTo(targetId, expected, guard = undefined) { return this.#serial(async () => {
+    guard?.();
+    const preview = await this.#preview(targetId);
+    const completed = [], files = new Set();
+    if (!expected?.digest || !preview.digest || expected.digest !== preview.digest
+      || expected.revision !== preview.revision || expected.tree !== preview.tree)
+      return { result: preview.result === 'busy' ? 'busy' : 'stale', completed, files: [] };
+    // Every step uses the same drift/policy guard as /undo and publishes its
+    // shortened stack. A later refusal never conceals already completed turns.
+    for (const step of preview.steps) {
+      try {
+        if (this.#stack.at(-1)?.id !== step.id) return { result: 'stale', completed, files: [...files] };
+        const undo = await this.#undo(guard);
+        // `files`: what this restore changed; `conflicts`: why it stopped.
+        if (undo.result !== 'done') return { ...undo, completed, files: [...files].sort(), conflicts: undo.result === 'refused' ? undo.files : [], stoppedAt: step.id };
+        completed.push(step.id);
+        for (const file of [...step.restore, ...step.remove]) files.add(file);
+      } catch (error) {
+        // Refused before a file of this step changed: a definite answer.
+        const reason = String(error?.message ?? error), definite = !/checkpoint-partial/.test(reason);
+        const named = /checkpoint-content-changed: (.+)$/.exec(reason)?.[1]?.split(', ') ?? [];
+        if (definite && /checkpoint-content-changed/.test(reason)) return { result: 'refused', completed, files: [...files], conflicts: named, stoppedAt: step.id };
+        if (definite && /checkpoint-(?:read-only|path-protected)/.test(reason)) return { result: 'read-only', completed, files: [...files], stoppedAt: step.id, reason };
+        if (definite && /^(?:Error: )?checkpoint-/.test(reason)) return { result: 'unavailable', completed, files: [...files], stoppedAt: step.id, reason };
+        return { result: 'uncertain', completed, files: [...files], stoppedAt: step.id, reason };
+      }
+    }
+    return { result: preview.conflicts.length ? 'refused' : 'done', completed, files: [...files].sort(),
+      conflicts: preview.conflicts, stoppedAt: preview.stoppedAt };
+  }); }
+  // Before the first change of a run; once per run. A snapshot that fails
+  // never stops the agent's edit: the turn just has no checkpoint, and older
+  // checkpoints are dropped with it, since undoing past an unrecorded turn
+  // would leave its changes in place while claiming an earlier state.
+  async #take(run) {
+    if (!run || run.checkpoint !== undefined) return;
+    run.checkpoint = null;
+    let point = null;
+    try {
+      const before = await this.git.tree();
+      if (before) {
+        point = { id: randomUUID(), turnRef: run.turnRef ?? randomUUID(), before, after: null, at: Date.now() };
+        await this.history?.begin(point);
+        run.checkpoint = point;
+      }
+    } catch (error) {
+      // Another owner: the edit waits and this turn tries again, history intact.
+      if (checkpointOwnershipError(error)) { run.checkpoint = undefined; throw error; }
+      run.checkpointError = error;
+      await this.#barrier(point);
+    }
+  }
+  async #barrier(point) {
+    this.#stack = [];
+    if (!this.history) return;
+    try { if (point) await this.history.abandon(point); } catch { /* the capture is retired on the next operation */ }
+    try { this.#stack = await this.history.save([]); } catch { /* a stale store refuses later restores itself */ }
+  }
+  // When the run ends: the tree after it, kept when the run changed something.
+  async #finish(run) {
+    const point = run?.checkpoint;
+    if (!point || run.checkpointFinished) return;
+    try { point.after = await this.git.tree(); }
+    catch (error) { run.checkpointError = error; run.checkpointFinished = true; await this.#barrier(point); return; }
+    if (point.after && point.after !== point.before) {
+      const next = [...this.#stack, point];
+      this.#stack = this.history ? await this.history.save(next) : next.slice(-64);
+      run.checkpointFinished = true;
+    } else if (point.after) {
+      await this.history?.abandon(point); run.checkpointFinished = true;
+    }
+  }
+  // Puts back what the last turn changed: { result, restored, removed, files }
+  // for the WebUI note (phase "undo") and `text`, the sentence for the member.
+  async #undo(guard = undefined) {
+    guard?.();
+    const answer = (undo, text) => ({ ...undo, text });
+    if (this.busy()) return answer({ result: 'busy', restored: 0, removed: 0, files: [] }, 'Đang có một lượt chạy: chờ nó xong (hoặc dừng nó) rồi /undo.');
+    const point = this.#stack.at(-1);
+    if (!point) return answer({ result: 'none', restored: 0, removed: 0, files: [] }, 'Không có lượt nào để hoàn tác trong cuộc trò chuyện này (chỉ áp dụng cho project là git repository; checkpoint có từ khi mở cuộc trò chuyện).');
+    await this.history?.prepare();
+    const now = await this.git.tree();
+    if (!now) return answer({ result: 'failed', restored: 0, removed: 0, files: [] }, 'Không đọc được trạng thái hiện tại của project; không hoàn tác.');
+    const since = new Set((await this.git.changed(point.after, now)).map(f => f.path));
+    // A file already back as it was before the turn (an undo that stopped
+    // midway) is done, not a conflict: only the rest is put back.
+    const differs = new Set((await this.git.changed(point.before, now)).map(f => f.path));
+    const turn = (await this.git.changed(point.before, point.after)).filter(f => differs.has(f.path));
+    // A file the member saved after the turn began is theirs, even when the
+    // turn's snapshots captured it: refuse rather than put it back.
+    const edited = this.memberEdits(point.at);
+    const touched = turn.filter(f => since.has(f.path) || edited.has(f.path)).map(f => f.path);
+    if (touched.length) return answer({ result: 'refused', restored: 0, removed: 0, files: touched.slice(0, 5) },
+      `Không hoàn tác: ${touched.length} file lượt trước đã sửa lại thay đổi sau đó (${touched.slice(0, 5).join(', ')}${touched.length > 5 ? ', …' : ''}). Hoàn tác sẽ ghi đè thay đổi đó.`);
+    const restore = turn.filter(f => f.status !== 'A').map(f => f.path), remove = turn.filter(f => f.status === 'A').map(f => f.path);
+    if (this.busy()) return answer({ result: 'busy', restored: 0, removed: 0, files: [] }, 'Đang có một lượt chạy: chờ nó xong (hoặc dừng nó) rồi /undo.');
+    this.history?.assertCurrent();
+    guard?.();
+    if (restore.length || remove.length) await this.git.restore(point.before, restore, remove, now, guard);
+    const next = this.#stack.slice(0, -1);
+    this.#stack = this.history ? await this.history.save(next) : next;
+    return answer({ result: 'done', restored: restore.length, removed: remove.length, files: [...restore, ...remove].slice(0, 5), more: this.#stack.length > 0 },
+      `Đã hoàn tác lượt trước: ${restore.length} file trả về như trước lượt đó, ${remove.length} file lượt đó tạo đã xoá.${this.#stack.length ? ' /undo lần nữa để hoàn tác lượt trước nữa.' : ''} Commit tạo trong lượt đó (nếu có) vẫn giữ nguyên.`);
+  }
+}

package/packages/piagent-core/runtime/hooks/session-hooks.ts

@@ -24,7 +24,7 @@ type SessionHookDependencies = {
     event: string
   ) => TaskContract | undefined;
   onTurnEnd?: (ctx: ExtensionContext) => void;
-  onAgentSettled?: (ctx: ExtensionContext) => void;
+  onAgentSettled?: (ctx: ExtensionContext) => void | Promise<void>;
   beforeShutdown?: (ctx: ExtensionContext) => void | Promise<void>;
 };
 
@@ -102,7 +102,7 @@ export function registerSessionHooks(pi: ExtensionAPI, dependencies: SessionHook
       taskRunId: task?.taskRunId,
       taskOutcome: task?.trace.outcome
     });
-    dependencies.onAgentSettled?.(ctx);
+    await dependencies.onAgentSettled?.(ctx);
   });
 
   pi.on("session_compact", async (event, ctx) => {
@@ -115,19 +115,22 @@ export function registerSessionHooks(pi: ExtensionAPI, dependencies: SessionHook
   });
 
   pi.on("session_shutdown", async (event, ctx) => {
-    await dependencies.beforeShutdown?.(ctx);
-    flushObservedTaskContext(
-      pi,
-      ctx,
-      state.qualifiedTaskContext(ctx),
-      maxManifestFiles,
-      "context_observed_before_shutdown"
-    );
-    telemetry(ctx, {
-      event: "session_shutdown",
-      reason: event.reason,
-      targetSessionFile: event.targetSessionFile ? path.basename(event.targetSessionFile) : undefined
-    });
-    state.clearSession(ctx);
+    try { await dependencies.beforeShutdown?.(ctx); }
+    finally {
+      try {
+        flushObservedTaskContext(
+          pi,
+          ctx,
+          state.qualifiedTaskContext(ctx),
+          maxManifestFiles,
+          "context_observed_before_shutdown"
+        );
+        telemetry(ctx, {
+          event: "session_shutdown",
+          reason: event.reason,
+          targetSessionFile: event.targetSessionFile ? path.basename(event.targetSessionFile) : undefined
+        });
+      } finally { state.clearSession(ctx); }
+    }
   });
 }

package/packages/piagent-core/runtime/hooks/session-start-hook.ts

@@ -319,6 +319,9 @@ export function registerSessionStartHook(pi: ExtensionAPI, dependencies: Session
     if (permissionProfile.mode === "trusted-full-access") {
       ctx.ui.notify("Piagent permission profile trusted-full-access is active; protected paths, secret redaction, and destructive/external confirmations remain enforced.", "warning");
     }
+    if (permissionProfile.mode === "bypass") {
+      ctx.ui.notify("Piagent bypass is active: no confirmation, protected-path or policy gate applies in this personal session. Output redaction and /undo checkpoints remain.", "warning");
+    }
     const mcpNotice = dependencies.mcpReadinessNotice(ctx.cwd);
     if (mcpNotice) ctx.ui.notify(mcpNotice, "warning");
     const updateNotice = dependencies.updateAvailabilityNotice();

package/packages/piagent-core/runtime/hooks/tool-call-hook.ts

@@ -18,7 +18,7 @@ type ToolCallHookDependencies = {
   beforeAuthorize?: (event: ToolCallEvent, ctx: ExtensionContext) => Promise<ToolCallDecision> | ToolCallDecision;
   authorize: (event: ToolCallEvent, ctx: ExtensionContext) => Promise<ToolCallDecision> | ToolCallDecision;
   reviewBudgetDecision?: (event: ToolCallEvent, ctx: ExtensionContext) => ToolCallDecision;
-  beforeStart?: (event: ToolCallEvent, ctx: ExtensionContext) => ToolCallDecision;
+  beforeStart?: (event: ToolCallEvent, ctx: ExtensionContext) => Promise<ToolCallDecision> | ToolCallDecision;
   afterDecision?: (
     event: ToolCallEvent,
     ctx: ExtensionContext,
@@ -74,7 +74,7 @@ export function registerToolCallHook(pi: ExtensionAPI, dependencies: ToolCallHoo
     const decision = authorizationDecision && typeof authorizationDecision === "object" && authorizationDecision.block
       ? authorizationDecision
       : dependencies.reviewBudgetDecision?.(resolvedEvent, ctx);
-    const startDecision = !(decision && typeof decision === "object" && decision.block) ? dependencies.beforeStart?.(resolvedEvent, ctx) : undefined;
+    const startDecision = !(decision && typeof decision === "object" && decision.block) ? await dependencies.beforeStart?.(resolvedEvent, ctx) : undefined;
     const finalDecision = startDecision && typeof startDecision === "object" && startDecision.block ? startDecision : decision;
     // Every refusal leaves through here, so this is where it is answered. A
     // remedy attached at the 29 sites that build one is a remedy the next site

package/packages/piagent-core/runtime/inspection/diff-projection.ts

@@ -1,3 +1,5 @@
+import type { ExactGitPatchAuthority } from "./source-action-contract.ts";
+export type { ExactGitPatchAuthority } from "./source-action-contract.ts";
 import { createHash } from "node:crypto";
 import os from "node:os";
 import { collectGitStatus, runReadOnlyGit, type GitStatusRecord, type GitStatusSnapshot } from "./git-status-adapter.ts";
@@ -363,7 +365,6 @@ async function patchForUnstagedRecord(snapshot: GitStatusSnapshot, record: GitSt
     `--unified=${contextLines}`, "--", ...paths], { timeoutMs, maxBytes });
 }
 
-export type ExactGitPatchAuthority = { header: Buffer; hunks: Array<{ hunkRef: string; bytes: Buffer }> };
 type ExactGitPatchOptions = {
   snapshot: GitStatusSnapshot; record: GitStatusRecord; view: "unstaged" | "staged"; fileRef: string;
   contextLines?: number; timeoutMs?: number; maxBytes?: number; maxHunks?: number;

package/packages/piagent-core/runtime/inspection/managed-source-revert.ts

@@ -0,0 +1,90 @@
+import path from "node:path";
+import { inspectWorkspaceFile, workspacePathFlags, type WorkspacePolicy } from "../../extensions/workspace-inspection.ts";
+import { redactSensitiveText } from "../../extensions/redaction-core.js";
+import { PiSourceMutationGuard } from "../policy/source-mutation-guard.ts";
+import { collectSourceChangeViews } from "./source-change-projection.ts";
+import { collectSessionFileDiff } from "./session-diff-projection.ts";
+import { collectSourceRevertPreview, validateSourceRevertTarget } from "./source-revert-projection.ts";
+import { SessionMutationObserver } from "./session-mutation-observer.ts";
+import { sessionAuthoredHunkRefs } from "./session-hunk-provenance.ts";
+import { canonicalReviewValue } from "./review-state-contract.ts";
+import type { SourceRevertTarget, WebUiIdentity } from "./source-action-contract.ts";
+
+// Construct only inside the sandbox. Identity, observations and confirmation key
+// come from the owning runtime; the browser supplies only a selected target.
+export type ManagedSourceContext = {
+  cwd: string; rawSessionId: string; identity: WebUiIdentity; confirmationKey: Buffer;
+  controlRevision: string; idle(): boolean; policy(): WorkspacePolicy;
+  observation(file: string): unknown;
+};
+export function createManagedSourceRevert(context: ManagedSourceContext) {
+  const { cwd, identity } = context;
+  if (identity.taskId !== null || identity.taskRunId !== null) throw new Error("source-session-binding-required");
+  const relative = (root: string, file: string) => path.relative(cwd, path.resolve(root, file)).split(path.sep).join("/");
+  const blocked = (root: string, file: string, writing = true) => {
+    const name = relative(root, file);
+    if (!name || name === ".." || name.startsWith("../") || path.isAbsolute(name)) return true;
+    const flags = workspacePathFlags(name, context.policy());
+    return flags.protected || writing && flags.readOnly;
+  };
+  const observer = new SessionMutationObserver(), loaded = new Set<string>();
+  const observation = (file: string) => {
+    const policy = context.policy();
+    if (!loaded.has(file)) { observer.restore(cwd, context.rawSessionId, file, context.observation(file), policy); loaded.add(file); }
+    return observer.current(cwd, context.rawSessionId, file, policy);
+  };
+  const readBlocked = (root: string, file: string) => blocked(root, file, false);
+  const sources = () => collectSourceChangeViews({ cwd, identity, taskRevision: null, isProtectedPath: readBlocked });
+  const detail = async (fileRef: string) => {
+    const views = await sources(), source = views.workingTree;
+    const file = source.files.find(item => item.fileRef === fileRef);
+    if (!file) throw new Error("source-file-unavailable");
+    const diff = await collectSessionFileDiff({ cwd, identity, sourceView: source, fileRef, taskRevision: null, sessionObservation: observation,
+      isProtectedPath: readBlocked, redactLine: redactSensitiveText, revalidationMode: "selected-file",
+      selectedRepoPaths: file.pathDisplay === "exact-safe" ? [String(file.path)] : undefined,
+      precondition: { expectedViewRevision: source.viewRevision, expectedFileRevision: String(file.fileRevision),
+        expectedBaseDigest: file.baseDigest as string | null, expectedCurrentDigest: file.currentDigest as string | null } });
+    return { views, source, file, diff };
+  };
+  const resolve = async (fileRef: string, hunkRefs: string[]) => {
+    const { views, source, file, diff } = await detail(fileRef);
+    return collectSourceRevertPreview({ cwd, identity, sourceView: source, taskView: null, diff, taskRevision: null,
+      workspaceRevision: source.viewRevision, indexRevision: views.staged.viewRevision, selectedHunkRefs: hunkRefs,
+      sessionObservation: file.pathDisplay === "exact-safe" ? observation(String(file.path)) ?? undefined : undefined,
+      confirmationKey: context.confirmationKey, guardAvailable: context.idle() && context.policy().readOnly !== true,
+      isProtectedPath: blocked });
+  };
+  return {
+    sources, observation,
+    async diff(fileRef: string) { return (await detail(fileRef)).diff; },
+    async preview(fileRef: string, hunkRefs: string[]) { return (await resolve(fileRef, hunkRefs)).projection; },
+    async execute(value: unknown) {
+      const target: SourceRevertTarget = validateSourceRevertTarget(value);
+      if (Date.now() > Date.parse(target.expiresAt)) throw new Error("source-revert-preview-expired");
+      const { authority } = await resolve(target.fileRef, target.hunkRefs);
+      // The time window is checked separately; every content and identity binding
+      // must match the newly constructed, keyed preview before execution.
+      if (!authority || canonicalReviewValue({ ...authority.target, expiresAt: target.expiresAt }) !== canonicalReviewValue(target))
+        throw new Error("source-revert-preview-stale");
+      authority.target.expiresAt = target.expiresAt;
+      const guard = new PiSourceMutationGuard();
+      const unbind = guard.bind({ cwd, rawSessionId: context.rawSessionId, guardInstanceId: identity.runtimeInstanceId,
+        facts: () => ({ taskId: null, taskRunId: null, taskRevision: null, taskState: "none", sessionBound: true,
+          writable: context.policy().readOnly !== true, idle: context.idle(), controlRevision: context.controlRevision,
+          sessionObservation: observation,
+          sessionReverted: (candidate, before, committed) => observer.reverted(cwd, context.rawSessionId,
+            relative(candidate.repoRoot, candidate.repoPath), before, committed, context.policy()),
+          isProtectedPath: file => blocked(cwd, file), sessionHunkRefs: candidate => {
+            const file = relative(candidate.repoRoot, candidate.repoPath), observed = observation(file);
+            const current = inspectWorkspaceFile(cwd, file, context.policy());
+            return observed && current.content !== null ? sessionAuthoredHunkRefs(observed, current.content, candidate.patchAuthority) : [];
+          } }) });
+      try {
+        return await guard.executeRevert({ cwd, rawSessionId: context.rawSessionId, identity, action: "source.revert",
+          expectedTaskRevision: null, expectedControlRevision: context.controlRevision,
+          expectedIndexPreimage: target.indexPreimage, expectedWorkspacePreimage: target.workspacePreimage,
+          previewRef: target.previewRef, confirmedPreviewDigest: target.confirmedPreviewDigest, authority });
+      } finally { unbind(); }
+    }
+  };
+}

package/packages/piagent-core/runtime/inspection/review-state-projection.ts

@@ -16,16 +16,16 @@ export type ReviewStateProjection = {
   health: { state: "ok" | "degraded" | "unavailable" | "error"; reasonCode: string | null; message: string | null };
 };
 
-type DeriveReviewTargetOptions = {
+type DeriveReviewTargetOptions<Revision extends string | null = string> = {
   diff: DiffDocument;
-  taskId: string;
-  taskRunId: string;
-  taskRevision: string;
+  taskId: string | null;
+  taskRunId: string | null;
+  taskRevision: Revision;
   workspaceRevision: string;
   indexRevision: string | null;
 };
 
-function targetCore(options: DeriveReviewTargetOptions): Omit<ReviewTarget, "diffRef" | "patchPreimage" | "contentDigest"> & { basisRef: string } {
+function targetCore<Revision extends string | null>(options: DeriveReviewTargetOptions<Revision>): Omit<ReviewTarget, "taskRevision" | "diffRef" | "patchPreimage" | "contentDigest"> & { taskRevision: Revision; basisRef: string } {
   const diff = options.diff as Record<string, any>, file = diff.file as Record<string, any>, observed = diff.observed as Record<string, any>;
   return {
     view: diff.view as ReviewView, fileRef: String(file.fileRef), taskRevision: options.taskRevision,
@@ -36,19 +36,30 @@ function targetCore(options: DeriveReviewTargetOptions): Omit<ReviewTarget, "dif
   };
 }
 
-export function deriveReviewTarget(options: DeriveReviewTargetOptions): ReviewTarget | null {
+export function deriveSourceDiffTarget<Revision extends string | null>(options: DeriveReviewTargetOptions<Revision> & {
+  sessionIdentity?: Pick<WebUiIdentity, "projectRef" | "runtimeInstanceId" | "sessionRef">;
+}): (Omit<ReviewTarget, "taskRevision"> & { taskRevision: Revision }) | null {
   const diff = options.diff as Record<string, any>;
-  if (!options.taskId || !options.taskRunId || !options.taskRevision || !options.workspaceRevision
+  const binding = options.sessionIdentity;
+  const session = binding ? { projectRef: binding.projectRef, runtimeInstanceId: binding.runtimeInstanceId, sessionRef: binding.sessionRef } : undefined;
+  const sessionBound = session && options.taskId === null && options.taskRunId === null && options.taskRevision === null
+    && ["projectRef", "runtimeInstanceId", "sessionRef"].every(key => typeof session[key] === "string" && session[key] === diff.identity?.[key])
+    && diff.identity?.taskId === null && diff.identity?.taskRunId === null;
+  if ((!sessionBound && (!options.taskId || !options.taskRunId || !options.taskRevision)) || !options.workspaceRevision
     || diff.availability?.state !== "current" || diff.fallback?.kind !== "none"
     || diff.truncation?.truncated !== false || diff.redaction?.applied !== false || diff.redaction?.truncated !== false
     || diff.file?.status === "C" || diff.file?.content?.kind !== "text" || diff.file?.content?.access !== "available") return null;
-  const core = targetCore(options), preimage = reviewDigest({ schemaVersion: 1, taskId: options.taskId, taskRunId: options.taskRunId, ...core });
+  const core = targetCore(options), preimage = reviewDigest({ schemaVersion: 1, taskId: options.taskId, taskRunId: options.taskRunId, ...(sessionBound ? { sessionIdentity: session } : {}), ...core });
   return { view: core.view, fileRef: core.fileRef, diffRef: `diff.${preimage.slice("sha256:".length)}`, taskRevision: core.taskRevision,
     workspaceRevision: core.workspaceRevision, indexRevision: core.indexRevision, viewRevision: core.viewRevision,
     fileRevision: core.fileRevision, baseDigest: core.baseDigest, currentDigest: core.currentDigest,
     patchPreimage: preimage, contentDigest: preimage };
 }
 
+export function deriveReviewTarget(options: DeriveReviewTargetOptions): ReviewTarget | null {
+  return deriveSourceDiffTarget(options);
+}
+
 function sameTarget(left: ReviewTarget, right: ReviewTarget): boolean {
   return canonicalReviewValue(left) === canonicalReviewValue(right);
 }

package/packages/piagent-core/runtime/inspection/session-diff-projection.ts

@@ -0,0 +1,47 @@
+import { createHash } from "node:crypto";
+import { collectExactGitPatchAuthority, collectFileDiff, type FileDiffOptions } from "./diff-projection.ts";
+import { collectSelectedSourceFileState } from "./source-change-projection.ts";
+import { readWorkspaceFile } from "./workspace-file-reader.ts";
+import { sessionAuthoredHunkRefs } from "./session-hunk-provenance.ts";
+import type { SessionMutationObservation } from "./session-mutation-observer.ts";
+
+// Attribution is per hunk. A mixed file never inherits whole-file authorship
+// merely because an observed agent edit exists somewhere in it.
+export async function collectSessionFileDiff(options: FileDiffOptions & {
+  sessionObservation?(file: string): SessionMutationObservation | null | undefined;
+}) {
+  const diff = await collectFileDiff(options), result = { ...diff, agentHunkRefs: [] as string[] };
+  if (options.sourceView.view !== "working-tree" || diff.availability.state !== "current"
+    || (diff.truncation as any)?.truncated !== false || (diff.redaction as any)?.applied !== false) return result;
+  const file = options.sourceView.files.find(item => item.fileRef === options.fileRef);
+  if (!file || file.pathDisplay !== "exact-safe" || typeof file.path !== "string") return result;
+  try {
+    const observation = options.sessionObservation?.(file.path);
+    if (!observation) return result;
+    const sourceOptions = { cwd: options.cwd, identity: options.identity, taskRevision: options.taskRevision,
+      isProtectedPath: options.isProtectedPath, timeoutMs: options.timeoutMs, maxGitBytes: options.maxBytes };
+    const selected = await collectSelectedSourceFileState(sourceOptions, "working-tree", options.fileRef, String(file.basisRef), [file.path]);
+    if (!selected || selected.file.fileRevision !== file.fileRevision || !selected.record.path.value
+      || options.isProtectedPath?.(selected.snapshot.repoRoot, selected.record.path.value)) return result;
+    const bytes = readWorkspaceFile(selected.snapshot.repoRoot, selected.record.path.value, 256 * 1024);
+    const current = bytes.toString("utf8"), currentDigest = createHash("sha256").update(bytes).digest("hex");
+    if (!Buffer.from(current).equals(bytes) || (diff.file as { currentDigest?: string }).currentDigest !== `sha256:${currentDigest}`) return result;
+    let authored: string[];
+    if (selected.record.kind === "untracked") {
+      // A witnessed creation proves the complete new file for display only.
+      // It does not mint a Git patch authority or enable file deletion.
+      authored = observation.baseline.digest === "absent" && observation.baseline.content === ""
+        && observation.currentDigest === currentDigest ? diff.hunks.map(hunk => String(hunk.hunkRef)) : [];
+    } else {
+      const patch = await collectExactGitPatchAuthority({ snapshot: selected.snapshot, record: selected.record, view: "unstaged",
+        fileRef: options.fileRef, timeoutMs: options.timeoutMs, maxBytes: options.maxBytes });
+      if (!patch) return result;
+      authored = sessionAuthoredHunkRefs(observation, current, patch);
+    }
+    const final = await collectSelectedSourceFileState(sourceOptions, "working-tree", options.fileRef, String(file.basisRef), [file.path]);
+    if (!final || final.file.fileRevision !== selected.file.fileRevision
+      || options.isProtectedPath?.(selected.snapshot.repoRoot, selected.record.path.value)) return result;
+    const visible = new Set(diff.hunks.map(hunk => hunk.hunkRef));
+    return { ...result, agentHunkRefs: authored.filter(ref => visible.has(ref)) };
+  } catch { return result; }
+}

package/packages/piagent-core/runtime/inspection/session-hunk-provenance.ts

@@ -0,0 +1,56 @@
+import { createHash } from "node:crypto";
+import { diffTextBuffers, type TextDiffOperation } from "./text-diff.ts";
+import type { ExactGitPatchAuthority } from "./source-action-contract.ts";
+import type { SessionMutationObservation } from "./session-mutation-observer.ts";
+
+type ChangeBlock = { at: number; added: string[]; deleted: string[] };
+const digest = (text: string) => createHash("sha256").update(text).digest("hex");
+function blocks(operations: TextDiffOperation[], start = 1): ChangeBlock[] {
+  const result: ChangeBlock[] = [];
+  let current = start, block: ChangeBlock | null = null;
+  for (const operation of operations) {
+    if (operation.kind === "context") { block = null; current++; continue; }
+    if (!block) { block = { at: current, added: [], deleted: [] }; result.push(block); }
+    if (operation.kind === "added") { block.added.push(operation.text); current++; }
+    else block.deleted.push(operation.text);
+  }
+  return result;
+}
+function patchBlocks(bytes: Buffer): ChangeBlock[] | null {
+  const text = bytes.toString("utf8");
+  if (!Buffer.from(text).equals(bytes) || !text.endsWith("\n")) return null;
+  const lines = text.slice(0, -1).split("\n"), header = lines.shift();
+  const match = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@.*$/.exec(header ?? "");
+  if (!match) return null;
+  const operations: TextDiffOperation[] = [];
+  for (const line of lines) {
+    const marker = line[0];
+    if (line === "\") {
+      const previous = operations.at(-1);
+      if (!previous?.text.endsWith("\n")) return null;
+      previous.text = previous.text.slice(0, -1);
+      continue;
+    }
+    if (![" ", "+", "-"].includes(marker)) return null;
+    operations.push({ kind: marker === " " ? "context" : marker === "+" ? "added" : "deleted", text: line.slice(1) + "\n" });
+  }
+  if (operations.filter(item => item.kind !== "added").length !== Number(match[2] ?? 1)
+    || operations.filter(item => item.kind !== "deleted").length !== Number(match[4] ?? 1)) return null;
+  return blocks(operations, Math.max(1, Number(match[3]) + (Number(match[4] ?? 1) === 0 ? 1 : 0)));
+}
+
+// Index hunks may contain member edits that predate this session. Only grant
+// a hunk when every changed block is an exact delta from the observed baseline.
+export function sessionAuthoredHunkRefs(observation: SessionMutationObservation, current: string,
+  patch: ExactGitPatchAuthority): string[] {
+  const baseline = observation.baseline;
+  if (digest(current) !== observation.currentDigest
+    || (baseline.digest === "absent" ? baseline.content !== "" : digest(baseline.content) !== baseline.digest)) return [];
+  const delta = diffTextBuffers(Buffer.from(baseline.content), Buffer.from(current), undefined, true);
+  if (!delta.exact) return [];
+  const proven = new Set(blocks(delta.operations).map(block => JSON.stringify(block)));
+  return patch.hunks.filter(hunk => {
+    const changes = patchBlocks(hunk.bytes);
+    return changes !== null && changes.length > 0 && changes.every(block => proven.has(JSON.stringify(block)));
+  }).map(hunk => hunk.hunkRef);
+}