@piagent/platform 1.37.1 → 1.38.2

package/packages/piagent-core/runtime/inspection/session-mutation-observer.ts

@@ -0,0 +1,125 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { inspectWorkspaceFile, type WorkspacePolicy } from "../../extensions/workspace-inspection.ts";
+import { expectedModelMutationProof } from "../quality/model-mutation-proof.ts";
+
+type FileImage = { content: string; digest: string };
+export type SessionMutationObservation = {
+  path: string; baseline: FileImage; currentDigest: string; toolCallId: string; evidenceRef: string;
+};
+type Pending = { toolName: string; files: Map<string, { before: FileImage; expected: string[] }> };
+type Session = { pending: Map<string, Pending>; files: Map<string, SessionMutationObservation> };
+const MAX_SESSIONS = 64, MAX_FILES = 32, MAX_PENDING = 8, MAX_BYTES = 256 * 1024;
+const hash = (value: string) => createHash("sha256").update(value).digest("hex");
+
+// This observation proves the exact tool result, not authorship of every line
+// in the file. A member edit breaks the chain and becomes the next baseline.
+export class SessionMutationObserver {
+  readonly #sessions = new Map<string, Session>();
+  #key(cwd: string, sessionId: string) { return `${path.resolve(cwd)}\0${sessionId}`; }
+  #session(cwd: string, sessionId: string): Session {
+    const key = this.#key(cwd, sessionId);
+    let state = this.#sessions.get(key);
+    if (!state) {
+      state = { pending: new Map(), files: new Map() }; this.#sessions.set(key, state);
+      while (this.#sessions.size > MAX_SESSIONS) this.#sessions.delete(this.#sessions.keys().next().value!);
+    }
+    return state;
+  }
+  #trim(): void {
+    let bytes = 0;
+    for (const state of [...this.#sessions.values()].reverse()) {
+      for (const item of state.files.values()) bytes += Buffer.byteLength(item.baseline.content);
+      for (const pending of state.pending.values()) for (const item of pending.files.values()) bytes += Buffer.byteLength(item.before.content);
+    }
+    while (bytes > 8 * 1024 * 1024 && this.#sessions.size) {
+      const key = this.#sessions.keys().next().value!, state = this.#sessions.get(key)!;
+      for (const item of state.files.values()) bytes -= Buffer.byteLength(item.baseline.content);
+      for (const pending of state.pending.values()) for (const item of pending.files.values()) bytes -= Buffer.byteLength(item.before.content);
+      this.#sessions.delete(key);
+    }
+  }
+  #read(cwd: string, file: string, policy: WorkspacePolicy, allowAbsent = false): FileImage | null {
+    try {
+      const value = inspectWorkspaceFile(cwd, file, policy);
+      if (value.protected || value.content === null || !value.digest || Buffer.byteLength(value.content) > MAX_BYTES) return null;
+      return { content: value.content, digest: value.digest };
+    } catch (error) {
+      return allowAbsent && (error as NodeJS.ErrnoException).code === "ENOENT" ? { content: "", digest: "absent" } : null;
+    }
+  }
+  begin(cwd: string, sessionId: string, toolCallId: string, toolName: string,
+    input: Record<string, unknown>, targets: string[], policy: WorkspacePolicy): void {
+    const state = this.#session(cwd, sessionId);
+    state.pending.delete(toolCallId);
+    if (!["write", "edit", "apply_patch"].includes(toolName) || targets.length > MAX_FILES) return;
+    const before = new Map<string, FileImage>();
+    for (const target of new Set(targets)) {
+      const file = path.relative(cwd, path.resolve(cwd, target)).split(path.sep).join("/");
+      const image = this.#read(cwd, file, policy, true);
+      // Only validated paths may enter the legacy exact-replacement prover.
+      if (image) before.set(file, image);
+    }
+    const proof = expectedModelMutationProof(cwd, toolName, input, [...before.keys()], (_root, file) => this.#read(cwd, file, policy) ?? undefined);
+    const files: Pending["files"] = new Map();
+    for (const [file, image] of before) {
+      const expected = proof.expectedContentDigests[file];
+      if (expected?.length && this.#read(cwd, file, policy, true)?.digest === image.digest
+        && (!proof.preContentDigests[file] || proof.preContentDigests[file] === image.digest)) {
+        files.set(file, { before: image, expected });
+      } else state.files.delete(file);
+    }
+    if (files.size) state.pending.set(toolCallId, { toolName, files });
+    while (state.pending.size > MAX_PENDING) state.pending.delete(state.pending.keys().next().value!);
+    this.#trim();
+  }
+  finish(cwd: string, sessionId: string, toolCallId: string, toolName: string, successful: boolean, policy: WorkspacePolicy): void {
+    const state = this.#sessions.get(this.#key(cwd, sessionId)), pending = state?.pending.get(toolCallId);
+    if (!state || !pending) return;
+    state.pending.delete(toolCallId);
+    for (const [file, candidate] of pending.files) {
+      const current = successful && toolName === pending.toolName ? this.#read(cwd, file, policy) : null;
+      const previous = state.files.get(file); state.files.delete(file);
+      if (!current || current.digest === candidate.before.digest || !candidate.expected.includes(current.digest)) continue;
+      const baseline = previous?.currentDigest === candidate.before.digest ? previous.baseline : candidate.before;
+      if (baseline.digest === current.digest) continue;
+      const evidenceRef = `session-mutation.${hash(JSON.stringify([sessionId, toolCallId, file, baseline.digest, current.digest]))}`;
+      state.files.set(file, { path: file, baseline, currentDigest: current.digest, toolCallId, evidenceRef });
+    }
+    while (state.files.size > MAX_FILES) state.files.delete(state.files.keys().next().value!);
+    this.#trim();
+  }
+  // Called only with the digest of bytes committed by the guarded executor.
+  reverted(cwd: string, sessionId: string, file: string, beforeDigest: string, committedDigest: string, policy: WorkspacePolicy): void {
+    const state = this.#sessions.get(this.#key(cwd, sessionId)), prior = state?.files.get(file);
+    if (!state || !prior) return;
+    state.files.delete(file);
+    const current = this.#read(cwd, file, policy);
+    if (prior.currentDigest !== beforeDigest || current?.digest !== committedDigest || current.digest === prior.baseline.digest) return;
+    state.files.set(file, { ...prior, currentDigest: current.digest,
+      evidenceRef: `session-mutation.${hash(JSON.stringify([prior.evidenceRef, "revert", current.digest]))}` });
+  }
+  current(cwd: string, sessionId: string, file: string, policy: WorkspacePolicy): SessionMutationObservation | null {
+    const state = this.#sessions.get(this.#key(cwd, sessionId)), observation = state?.files.get(file);
+    if (!observation) return null;
+    if (this.#read(cwd, file, policy)?.digest !== observation.currentDigest) { state!.files.delete(file); return null; }
+    return structuredClone(observation);
+  }
+  // Only the trusted runtime may restore this between sandbox invocations.
+  // Revalidate the path policy and live digest before the next tool starts.
+  restore(cwd: string, sessionId: string, file: string, value: unknown, policy: WorkspacePolicy): void {
+    const item = value as SessionMutationObservation | null;
+    if (!item || item.path !== file || typeof item.baseline?.content !== "string"
+      || Buffer.byteLength(item.baseline.content) > MAX_BYTES
+      || (item.baseline.digest === "absent" ? item.baseline.content !== "" : hash(item.baseline.content) !== item.baseline.digest)
+      || !/^[a-f0-9]{64}$/.test(item.currentDigest) || typeof item.toolCallId !== "string" || item.toolCallId.length > 256
+      || !/^session-mutation\.[a-f0-9]{64}$/.test(item.evidenceRef)
+      || this.#read(cwd, file, policy)?.digest !== item.currentDigest) return;
+    this.#session(cwd, sessionId).files.set(file, structuredClone(item)); this.#trim();
+  }
+  clear(cwd: string, sessionId: string): void { this.#sessions.delete(this.#key(cwd, sessionId)); }
+}
+
+const KEY = Symbol.for("piagent.session-mutation-observer.v1");
+const shared = globalThis as typeof globalThis & { [KEY]?: SessionMutationObserver };
+export const sessionMutationObserver = shared[KEY] ??= new SessionMutationObserver();

package/packages/piagent-core/runtime/inspection/source-action-contract.ts

@@ -0,0 +1,123 @@
+// Shared source-action data without filesystem or runtime dependencies.
+
+export type WebUiIdentity = {
+  projectRef: string;
+  runtimeInstanceId: string;
+  sessionRef: string;
+  taskId: string | null;
+  taskRunId: string | null;
+  agentOperationId: string | null;
+  toolCallId: string | null;
+};
+
+export type ExactGitPatchAuthority = { header: Buffer; hunks: Array<{ hunkRef: string; bytes: Buffer }> };
+
+export type SourceRevertTarget = {
+  view: "working-tree"; repoRef: string; fileRef: string; diffRef: string; status: "M"; path: string; oldPath: null;
+  effect: "restore-worktree-from-index"; taskRevision: string | null; workspaceRevision: string; indexRevision: string;
+  viewRevision: string; fileRevision: string; workspacePreimage: string; indexPreimage: string; patchPreimage: string;
+  contentDigest: string; hunkRefs: string[]; previewRef: string; confirmedPreviewDigest: string; expiresAt: string;
+  summary: { files: 1; hunks: number; additionsDiscarded: number; deletionsRestored: number;
+    effect: "discard-unstaged-keep-index"; recovery: "not-guaranteed" };
+};
+export type SourceRevertProjection = {
+  schemaVersion: 1; version: "piagent-webui-source-revert-v1"; generatedAt: string; identity: WebUiIdentity;
+  action: "source.revert"; state: "ready" | "unavailable"; target: SourceRevertTarget | null;
+  preview: { basis: "index-to-working-tree"; hunks: RevertPreviewHunk[]; truncated: false } | null; reasonCode: string | null;
+  health: { state: "ok" | "unavailable" | "error"; reasonCode: string | null; message: string | null };
+};
+export type RevertPreviewLine = { kind: "added" | "deleted" | "context" | "meta"; marker: "+" | "-" | " " | "\\"; text: string };
+export type RevertPreviewHunk = { hunkRef: string; header: string; lines: RevertPreviewLine[] };
+export type SourceRevertAuthority = {
+  repoRoot: string; repoPath: string; indexObject: string; indexMode: "100644" | "100755";
+  target: SourceRevertTarget; patchAuthority: ExactGitPatchAuthority;
+};
+
+export type SourceMutationAction = "source.stage" | "source.unstage";
+export type SourceMutationTarget = {
+  view: "working-tree" | "staged";
+  repoRef: string;
+  fileRef: string;
+  diffRef: string;
+  status: "A" | "M" | "D" | "R" | "U";
+  path: string;
+  oldPath: string | null;
+  effect: "copy-worktree-to-index" | "restore-index-from-head";
+  taskRevision: string;
+  workspaceRevision: string;
+  indexRevision: string;
+  viewRevision: string;
+  fileRevision: string;
+  workspacePreimage: string;
+  indexPreimage: string;
+  patchPreimage: string;
+  contentDigest: string;
+  hunkRefs: string[];
+};
+export type SourceMutationProjection = {
+  schemaVersion: 1;
+  version: "piagent-webui-source-mutation-v1";
+  generatedAt: string;
+  identity: WebUiIdentity;
+  action: SourceMutationAction;
+  state: "ready" | "unavailable";
+  target: SourceMutationTarget | null;
+  reasonCode: string | null;
+  health: { state: "ok" | "unavailable" | "error"; reasonCode: string | null; message: string | null };
+};
+export type SourceMutationAuthority = {
+  repoRoot: string;
+  repoPaths: string[];
+  headOid: string | null;
+  indexStatus: string;
+  worktreeStatus: string;
+  target: SourceMutationTarget;
+  patchAuthority: ExactGitPatchAuthority | null;
+};
+
+export const SOURCE_MUTATION_EVIDENCE_VERSION = "piagent-webui-source-mutation-evidence-v1";
+
+export type SourceMutationEvidenceRecord = {
+  schemaVersion: 1;
+  version: typeof SOURCE_MUTATION_EVIDENCE_VERSION;
+  recordId: string;
+  evidenceRef: string;
+  sequence: number;
+  phase: "requested" | "settled" | "rejected" | "uncertain";
+  resultCode: "mutation-requested" | "staged" | "unstaged" | "reverted" | "mutation-rejected" | "effect-unknown";
+  failureCode: string | null;
+  projectRef: string;
+  runtimeInstanceId: string;
+  sessionRef: string;
+  taskId: string;
+  taskRunId: string;
+  commandId: string;
+  idempotencyKeyDigest: string;
+  actionDigest: string;
+  action: SourceMutationAction | "source.revert";
+  target: SourceMutationTarget | SourceRevertTarget;
+  selectedHunkRefs: string[];
+  requestedAt: string;
+  recordedAt: string;
+  retentionUntil: string;
+  beforeIndexPreimage: string;
+  afterIndexPreimage: string | null;
+  beforeWorkspacePreimage: string;
+  afterWorkspacePreimage: string | null;
+  observedRevisionsBefore: Record<string, string | null>;
+  observedRevisionsAfter: Record<string, string | null> | null;
+  integrityDigest: string;
+};
+
+export type SourceMutationAppendOptions = Omit<SourceMutationEvidenceRecord, "schemaVersion" | "version" | "recordId" | "evidenceRef" | "sequence" | "retentionUntil" | "integrityDigest"> & { projectRoot: string };
+
+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;
+};

package/packages/piagent-core/runtime/inspection/source-change-projection.ts

@@ -1,3 +1,6 @@
+import type { WebUiIdentity } from "./source-action-contract.ts";
+export type { WebUiIdentity } from "./source-action-contract.ts";
+
 import { createHash } from "node:crypto";
 import path from "node:path";
 import {
@@ -15,15 +18,6 @@ import { sourceInspectionPlan } from "./source-inspection-plan.ts";
 const DEFAULT_PAGE_LIMIT = 300;
 const MAX_PAGE_LIMIT = 2_000;
 const MAX_TEXT_BYTES = 4 * 1024 * 1024;
-export type WebUiIdentity = {
-  projectRef: string;
-  runtimeInstanceId: string;
-  sessionRef: string;
-  taskId: string | null;
-  taskRunId: string | null;
-  agentOperationId: string | null;
-  toolCallId: string | null;
-};
 export type SourceProjectionOptions = {
   cwd: string;
   identity: WebUiIdentity;

package/packages/piagent-core/runtime/inspection/source-mutation-projection.ts

@@ -1,3 +1,6 @@
+import type { SourceMutationAction, SourceMutationTarget, SourceMutationProjection, SourceMutationAuthority } from "./source-action-contract.ts";
+export type { SourceMutationAction, SourceMutationTarget, SourceMutationProjection, SourceMutationAuthority } from "./source-action-contract.ts";
+
 import { createHash } from "node:crypto";
 
 import { runReadOnlyGit } from "./git-status-adapter.ts";
@@ -7,47 +10,6 @@ import { collectSelectedSourceFileState, type SourceChangeDocument, type SourceP
 import type { DiffDocument } from "./diff-projection.ts";
 import { hashWorkspaceFile, inspectWorkspaceEntry } from "./workspace-file-reader.ts";
 
-export type SourceMutationAction = "source.stage" | "source.unstage";
-export type SourceMutationTarget = {
-  view: "working-tree" | "staged";
-  repoRef: string;
-  fileRef: string;
-  diffRef: string;
-  status: "A" | "M" | "D" | "R" | "U";
-  path: string;
-  oldPath: string | null;
-  effect: "copy-worktree-to-index" | "restore-index-from-head";
-  taskRevision: string;
-  workspaceRevision: string;
-  indexRevision: string;
-  viewRevision: string;
-  fileRevision: string;
-  workspacePreimage: string;
-  indexPreimage: string;
-  patchPreimage: string;
-  contentDigest: string;
-  hunkRefs: string[];
-};
-export type SourceMutationProjection = {
-  schemaVersion: 1;
-  version: "piagent-webui-source-mutation-v1";
-  generatedAt: string;
-  identity: WebUiIdentity;
-  action: SourceMutationAction;
-  state: "ready" | "unavailable";
-  target: SourceMutationTarget | null;
-  reasonCode: string | null;
-  health: { state: "ok" | "unavailable" | "error"; reasonCode: string | null; message: string | null };
-};
-export type SourceMutationAuthority = {
-  repoRoot: string;
-  repoPaths: string[];
-  headOid: string | null;
-  indexStatus: string;
-  worktreeStatus: string;
-  target: SourceMutationTarget;
-  patchAuthority: ExactGitPatchAuthority | null;
-};
 const REF = /^[A-Za-z0-9][A-Za-z0-9._:@~-]{0,159}$/, REVISION = /^[A-Za-z0-9][A-Za-z0-9._:~-]{0,159}$/,
   DIGEST = /^sha256:[a-f0-9]{64}$/, WORKSPACE = /^wt-content-v2:[a-f0-9]{64}$/,
   SAFE_PATH = /^(?!\/)(?![A-Za-z]:)(?!.*(?:^|\/)\.\.(?:\/|$))[^\u0000-\u001F\u007F\\]{1,1024}$/;

package/packages/piagent-core/runtime/inspection/source-mutation-store.ts

@@ -1,3 +1,8 @@
+import type { SourceMutationEvidenceRecord, SourceMutationAppendOptions } from "./source-action-contract.ts";
+export type { SourceMutationEvidenceRecord, SourceMutationAppendOptions } from "./source-action-contract.ts";
+import { SOURCE_MUTATION_EVIDENCE_VERSION } from "./source-action-contract.ts";
+export { SOURCE_MUTATION_EVIDENCE_VERSION } from "./source-action-contract.ts";
+
 import { createHash, randomBytes } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
@@ -12,41 +17,6 @@ const MAX_RECORDS = 4_000, MAX_RECORD_BYTES = 96 * 1024;
 const REF = /^[A-Za-z0-9][A-Za-z0-9._:@~-]{0,159}$/, DIGEST = /^sha256:[a-f0-9]{64}$/;
 const REVISION = /^[A-Za-z0-9][A-Za-z0-9._:~-]{0,159}$/, REVISION_KEYS = ["runtimeRevision", "taskRevision", "controlRevision",
   "workspaceRevision", "indexRevision", "approvalRevision", "sessionOptionRevision", "queueRevision"];
-export const SOURCE_MUTATION_EVIDENCE_VERSION = "piagent-webui-source-mutation-evidence-v1";
-
-export type SourceMutationEvidenceRecord = {
-  schemaVersion: 1;
-  version: typeof SOURCE_MUTATION_EVIDENCE_VERSION;
-  recordId: string;
-  evidenceRef: string;
-  sequence: number;
-  phase: "requested" | "settled" | "rejected" | "uncertain";
-  resultCode: "mutation-requested" | "staged" | "unstaged" | "reverted" | "mutation-rejected" | "effect-unknown";
-  failureCode: string | null;
-  projectRef: string;
-  runtimeInstanceId: string;
-  sessionRef: string;
-  taskId: string;
-  taskRunId: string;
-  commandId: string;
-  idempotencyKeyDigest: string;
-  actionDigest: string;
-  action: SourceMutationAction | "source.revert";
-  target: SourceMutationTarget | SourceRevertTarget;
-  selectedHunkRefs: string[];
-  requestedAt: string;
-  recordedAt: string;
-  retentionUntil: string;
-  beforeIndexPreimage: string;
-  afterIndexPreimage: string | null;
-  beforeWorkspacePreimage: string;
-  afterWorkspacePreimage: string | null;
-  observedRevisionsBefore: Record<string, string | null>;
-  observedRevisionsAfter: Record<string, string | null> | null;
-  integrityDigest: string;
-};
-
-type AppendOptions = Omit<SourceMutationEvidenceRecord, "schemaVersion" | "version" | "recordId" | "evidenceRef" | "sequence" | "retentionUntil" | "integrityDigest"> & { projectRoot: string };
 
 function sha(value: string): string { return createHash("sha256").update(value).digest("hex"); }
 function evidenceDigest(value: unknown): string { return `sha256:${sha(canonicalReviewValue(value))}`; }
@@ -132,7 +102,7 @@ export function readSourceMutationEvidence(projectRoot: string, taskRunId: strin
   return { records: corruptions.length ? [] : records.sort((left, right) => left.sequence - right.sequence), corruptions };
 }
 
-export function appendSourceMutationEvidence(options: AppendOptions): SourceMutationEvidenceRecord {
+export function appendSourceMutationEvidence(options: SourceMutationAppendOptions): SourceMutationEvidenceRecord {
   const manifest = readTaskBaselineManifest(options.projectRoot, options.taskRunId);
   if (!manifest || manifest.taskId !== options.taskId || manifest.captureState !== "current"
     || taskBaselineRetentionState(manifest, new Date(options.recordedAt)) !== "active") throw new Error("mutation-baseline-unavailable");

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

@@ -1,8 +1,14 @@
+import { readWorkspaceFile } from "./workspace-file-reader.ts";
+import { sessionAuthoredHunkRefs } from "./session-hunk-provenance.ts";
+import type { SessionMutationObservation } from "./session-mutation-observer.ts";
+import type { SourceRevertTarget, SourceRevertProjection, SourceRevertAuthority, RevertPreviewHunk, RevertPreviewLine } from "./source-action-contract.ts";
+export type { SourceRevertTarget, SourceRevertProjection, SourceRevertAuthority, RevertPreviewHunk, RevertPreviewLine } from "./source-action-contract.ts";
+
 import { createHmac } from "node:crypto";
 
 import { canonicalReviewValue } from "./review-state-contract.ts";
 import { collectExactGitPatchAuthority, type DiffDocument, type ExactGitPatchAuthority } from "./diff-projection.ts";
-import { deriveReviewTarget } from "./review-state-projection.ts";
+import { deriveSourceDiffTarget } from "./review-state-projection.ts";
 import { collectSelectedSourceFileState, type SourceChangeDocument, type SourceProjectionOptions, type WebUiIdentity } from "./source-change-projection.ts";
 import { collectIndexPreimage, collectSelectedWorkspacePreimage } from "./source-mutation-projection.ts";
 
@@ -10,29 +16,9 @@ const REF = /^[A-Za-z0-9][A-Za-z0-9._:@~-]{0,159}$/, REVISION = /^[A-Za-z0-9][A-
   DIGEST = /^sha256:[a-f0-9]{64}$/, WORKSPACE = /^wt-content-v2:[a-f0-9]{64}$/,
   SAFE_PATH = /^(?!\/)(?![A-Za-z]:)(?!.*(?:^|\/)\.\.(?:\/|$))[^\u0000-\u001F\u007F\\]{1,1024}$/;
 
-export type SourceRevertTarget = {
-  view: "working-tree"; repoRef: string; fileRef: string; diffRef: string; status: "M"; path: string; oldPath: null;
-  effect: "restore-worktree-from-index"; taskRevision: string; workspaceRevision: string; indexRevision: string;
-  viewRevision: string; fileRevision: string; workspacePreimage: string; indexPreimage: string; patchPreimage: string;
-  contentDigest: string; hunkRefs: string[]; previewRef: string; confirmedPreviewDigest: string; expiresAt: string;
-  summary: { files: 1; hunks: number; additionsDiscarded: number; deletionsRestored: number;
-    effect: "discard-unstaged-keep-index"; recovery: "not-guaranteed" };
-};
-export type SourceRevertProjection = {
-  schemaVersion: 1; version: "piagent-webui-source-revert-v1"; generatedAt: string; identity: WebUiIdentity;
-  action: "source.revert"; state: "ready" | "unavailable"; target: SourceRevertTarget | null;
-  preview: { basis: "index-to-working-tree"; hunks: RevertPreviewHunk[]; truncated: false } | null; reasonCode: string | null;
-  health: { state: "ok" | "unavailable" | "error"; reasonCode: string | null; message: string | null };
-};
-type RevertPreviewLine = { kind: "added" | "deleted" | "context" | "meta"; marker: "+" | "-" | " " | "\\"; text: string };
-type RevertPreviewHunk = { hunkRef: string; header: string; lines: RevertPreviewLine[] };
-export type SourceRevertAuthority = {
-  repoRoot: string; repoPath: string; indexObject: string; indexMode: "100644" | "100755";
-  target: SourceRevertTarget; patchAuthority: ExactGitPatchAuthority;
-};
 type CollectOptions = {
   cwd: string; identity: WebUiIdentity; sourceView: SourceChangeDocument; taskView: SourceChangeDocument | null; diff: DiffDocument;
-  taskRevision: string; workspaceRevision: string; indexRevision: string; selectedHunkRefs?: string[]; generatedAt?: string;
+  taskRevision: string | null; sessionObservation?: SessionMutationObservation; workspaceRevision: string; indexRevision: string; selectedHunkRefs?: string[]; generatedAt?: string;
   confirmationKey: Buffer;
   isProtectedPath?: SourceProjectionOptions["isProtectedPath"]; guardAvailable?: boolean; timeoutMs?: number; maxGitBytes?: number;
 };
@@ -69,7 +55,8 @@ export function validateSourceRevertTarget(value: unknown): SourceRevertTarget {
   if (canonicalReviewValue(Object.keys(target).sort()) !== canonicalReviewValue(keys.sort()) || target.view !== "working-tree" || target.status !== "M"
     || target.oldPath !== null || target.effect !== "restore-worktree-from-index" || !SAFE_PATH.test(target.path)
     || ![target.repoRef, target.fileRef, target.diffRef, target.previewRef].every((item) => REF.test(item))
-    || ![target.taskRevision, target.workspaceRevision, target.indexRevision, target.viewRevision, target.fileRevision].every((item) => REVISION.test(item))
+    || (target.taskRevision !== null && !REVISION.test(target.taskRevision))
+    || ![target.workspaceRevision, target.indexRevision, target.viewRevision, target.fileRevision].every((item) => REVISION.test(item))
     || !WORKSPACE.test(target.workspacePreimage) || ![target.indexPreimage, target.patchPreimage, target.contentDigest, target.confirmedPreviewDigest].every((item) => DIGEST.test(item))
     || !Array.isArray(target.hunkRefs) || target.hunkRefs.length > 1 || new Set(target.hunkRefs).size !== target.hunkRefs.length
     || target.hunkRefs.some((item) => !REF.test(item)) || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(target.expiresAt)
@@ -82,20 +69,23 @@ export function validateSourceRevertTarget(value: unknown): SourceRevertTarget {
 
 export async function collectSourceRevertPreview(options: CollectOptions): Promise<{ projection: SourceRevertProjection; authority: SourceRevertAuthority | null }> {
   const selectedHunkRefs = options.selectedHunkRefs ?? [];
+  const sessionBound = options.identity.taskId === null && options.identity.taskRunId === null && options.taskRevision === null;
+  const bindingAvailable = sessionBound ? !!options.sessionObservation : !!options.identity.taskId && !!options.identity.taskRunId && !!options.taskRevision;
   if (!Buffer.isBuffer(options.confirmationKey) || options.confirmationKey.length < 32) return unavailable(options, "revert-confirmation-authority-unavailable");
   if (options.guardAvailable !== true) return unavailable(options, "mutation-guard-unavailable");
-  if (options.sourceView.view !== "working-tree" || options.sourceView.availability.state !== "current" || !options.identity.taskId || !options.identity.taskRunId
-    || !options.taskRevision || !options.workspaceRevision || !options.indexRevision || selectedHunkRefs.length > 1 || new Set(selectedHunkRefs).size !== selectedHunkRefs.length)
+  if (options.sourceView.view !== "working-tree" || options.sourceView.availability.state !== "current" || !bindingAvailable
+    || !options.workspaceRevision || !options.indexRevision || selectedHunkRefs.length > 1 || new Set(selectedHunkRefs).size !== selectedHunkRefs.length)
     return unavailable(options, "revert-authority-unavailable");
   const file = options.sourceView.files.find((candidate: any) => candidate.fileRef === (options.diff as any).file?.fileRef) as Record<string, any> | undefined;
   if (!file || file.status !== "M" || file.git?.worktreeStatus !== "M" || file.oldPath !== null || file.pathDisplay !== "exact-safe"
     || file.content?.kind !== "text" || file.content?.access !== "available") return unavailable(options, "revert-target-unavailable");
   const taskFile = options.taskView?.files.find((candidate: any) => candidate.path === file.path && candidate.currentDigest === file.currentDigest) as Record<string, any> | undefined;
-  if (!taskFile || taskFile.provenance?.classification !== "runtime-observed-agent" || taskFile.provenance?.evidence !== "exact"
-    || !Array.isArray(taskFile.provenance?.mutationEvidenceRefs) || taskFile.provenance.mutationEvidenceRefs.length === 0)
+  if (!sessionBound && (!taskFile || taskFile.provenance?.classification !== "runtime-observed-agent" || taskFile.provenance?.evidence !== "exact"
+    || !Array.isArray(taskFile.provenance?.mutationEvidenceRefs) || taskFile.provenance.mutationEvidenceRefs.length === 0))
     return unavailable(options, "revert-provenance-unavailable");
-  const review = deriveReviewTarget({ diff: options.diff, taskId: options.identity.taskId, taskRunId: options.identity.taskRunId,
-    taskRevision: options.taskRevision, workspaceRevision: options.workspaceRevision, indexRevision: options.indexRevision });
+  const review = deriveSourceDiffTarget({ diff: options.diff, taskId: options.identity.taskId, taskRunId: options.identity.taskRunId,
+    taskRevision: options.taskRevision, workspaceRevision: options.workspaceRevision, indexRevision: options.indexRevision,
+    ...(sessionBound ? { sessionIdentity: options.identity } : {}) });
   if (!review || review.view !== "working-tree" || review.fileRef !== file.fileRef || (options.diff as any).truncation?.truncated !== false
     || (options.diff as any).redaction?.applied !== false) return unavailable(options, "revert-preview-incomplete");
   const selected = await collectSelectedSourceFileState({ cwd: options.cwd, identity: options.identity, taskRevision: options.taskRevision,
@@ -108,6 +98,8 @@ export async function collectSourceRevertPreview(options: CollectOptions): Promi
   const repoPath = selected.record.path.value;
   if (!repoPath || options.isProtectedPath?.(selected.snapshot.repoRoot, repoPath) === true) return unavailable(options, "protected-path");
   try {
+    const initialWorkspacePreimage = collectSelectedWorkspacePreimage(selected.snapshot.repoRoot, [repoPath]);
+    const initialIndexPreimage = await collectIndexPreimage(selected.snapshot.repoRoot, options.timeoutMs, options.maxGitBytes);
     const patchAuthority = await collectExactGitPatchAuthority({ snapshot: selected.snapshot, record: selected.record, view: "unstaged",
       fileRef: String(file.fileRef), timeoutMs: options.timeoutMs, maxBytes: options.maxGitBytes });
     if (!patchAuthority || patchAuthority.hunks.length === 0 || patchAuthority.hunks.length > 128
@@ -115,14 +107,28 @@ export async function collectSourceRevertPreview(options: CollectOptions): Promi
     const selectedAuthorityHunks = patchAuthority.hunks.filter((hunk) => selectedHunkRefs.length === 0 || selectedHunkRefs.includes(hunk.hunkRef));
     const selectedRefs = selectedAuthorityHunks.map((hunk) => hunk.hunkRef);
     if (selectedHunkRefs.length && canonicalReviewValue(selectedRefs) !== canonicalReviewValue(selectedHunkRefs)) return unavailable(options, "revert-hunk-unavailable");
+    if (sessionBound) {
+      const observation = options.sessionObservation!;
+      if (observation.path !== file.path) return unavailable(options, "revert-provenance-unavailable");
+      const current = readWorkspaceFile(selected.snapshot.repoRoot, repoPath, 256 * 1024).toString("utf8");
+      const authored = sessionAuthoredHunkRefs(observation, current, patchAuthority);
+      if (selectedRefs.some(ref => !authored.includes(ref))) return unavailable(options, "revert-provenance-unavailable");
+    }
     const previewHunks = selectedAuthorityHunks.map(previewHunk);
     if (previewHunks.some((hunk) => !hunk) || previewHunks.reduce((count, hunk) => count + (hunk?.lines.length ?? 0), 0) > 5_000)
       return unavailable(options, "revert-preview-incomplete");
     const exactPreviewHunks = previewHunks as RevertPreviewHunk[];
     const workspacePreimage = collectSelectedWorkspacePreimage(selected.snapshot.repoRoot, [repoPath]);
     const indexPreimage = await collectIndexPreimage(selected.snapshot.repoRoot, options.timeoutMs, options.maxGitBytes);
+    const finalSelected = await collectSelectedSourceFileState({ cwd: options.cwd, identity: options.identity, taskRevision: options.taskRevision,
+      generatedAt: options.generatedAt, isProtectedPath: options.isProtectedPath, timeoutMs: options.timeoutMs, maxGitBytes: options.maxGitBytes },
+      "working-tree", file.fileRef, String(file.basisRef), [file.path]);
+    if (!finalSelected || finalSelected.file.fileRevision !== file.fileRevision
+      || workspacePreimage !== initialWorkspacePreimage || indexPreimage !== initialIndexPreimage
+      || collectSelectedWorkspacePreimage(selected.snapshot.repoRoot, [repoPath]) !== workspacePreimage)
+      return unavailable(options, "revert-target-stale");
     const generatedAt = options.generatedAt ?? new Date().toISOString(), expiresAt = new Date(Date.parse(generatedAt) + 5 * 60_000).toISOString();
-    const confirmation = { projectRef: options.identity.projectRef, sessionRef: options.identity.sessionRef, taskRunId: options.identity.taskRunId,
+    const confirmation = { projectRef: options.identity.projectRef, runtimeInstanceId: options.identity.runtimeInstanceId, sessionRef: options.identity.sessionRef, taskRunId: options.identity.taskRunId,
       fileRef: file.fileRef, hunkRefs: selectedHunkRefs, taskRevision: options.taskRevision, workspaceRevision: options.workspaceRevision,
       indexRevision: options.indexRevision, viewRevision: review.viewRevision, fileRevision: review.fileRevision,
       workspacePreimage, indexPreimage, patchPreimage: review.patchPreimage, contentDigest: review.contentDigest };

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

@@ -8,19 +8,20 @@ export type TextDiffResult = {
   reasonCode: string | null;
 };
 
-function lines(content: Buffer): string[] | null {
+function lines(content: Buffer, preserveLineEndings: boolean): string[] | null {
   if (content.includes(0)) return null;
   const text = content.toString("utf8");
   if (Buffer.from(text, "utf8").compare(content) !== 0) return null;
   if (!text) return [];
+  if (preserveLineEndings) return text.match(/[^\n]*\n|[^\n]+$/g) ?? [];
   const result = text.split("\n");
   if (text.endsWith("\n")) result.pop();
   return result.map((line) => line.endsWith("\r") ? line.slice(0, -1) : line);
 }
 
-export function diffTextBuffers(base: Buffer, current: Buffer, maxCells = 4_000_000): TextDiffResult {
-  const before = lines(base);
-  const after = lines(current);
+export function diffTextBuffers(base: Buffer, current: Buffer, maxCells = 4_000_000, preserveLineEndings = false): TextDiffResult {
+  const before = lines(base, preserveLineEndings);
+  const after = lines(current, preserveLineEndings);
   if (!before || !after) return { operations: [], additions: 0, deletions: 0, exact: false, reasonCode: "binary-content" };
   const cells = (before.length + 1) * (after.length + 1);
   if (!Number.isSafeInteger(cells) || cells > maxCells) {

package/packages/piagent-core/runtime/inspection/workspace-worker.ts

@@ -0,0 +1,79 @@
+import { createManagedSourceRevert, type ManagedSourceContext } from "./managed-source-revert.ts";
+import path from "node:path";
+import { SessionMutationObserver } from "./session-mutation-observer.ts";
+import { writeWorkspaceFile, WorkspaceWriteError, type WorkspaceWriteInput } from "../../extensions/workspace-write.ts";
+import { searchWorkspace } from "../../extensions/workspace-search.ts";
+import { loadProjectContextIndexPolicy } from "../../extensions/workspace-policy.js";
+import { inspectWorkspaceFile, inspectWorkspaceTree, inspectWorkspacePaths } from "../../extensions/workspace-inspection.ts";
+import { inspectWorkspaceEntry } from "../../security/workspace-file-reader.ts";
+import { managedCheckpointOperation } from "../checkpoints/checkpoint-worker.ts";
+
+// Bundled with its policy assets under managed/dist. The worker runs only
+// after the tool boundary has entered the conversation's sandbox.
+export async function inspectManagedWorkspace(cwd: string, assets: string, request: unknown, readOnly = false) {
+  const input = request as { kind?: unknown; path?: unknown; payload?: unknown } | null;
+  if (input?.kind === "checkpoint") return managedCheckpointOperation(cwd, () => managedWorkspacePolicy(cwd, assets, readOnly), request);
+  const writing = input?.kind === "write", state = input?.kind === "write-state";
+  if (!input || (!writing && !state && (!["tree", "file", "paths", "search"].includes(String(input.kind)) || typeof input.path !== "string"))
+    || Object.keys(input).some(key => key !== "kind" && key !== (writing ? "payload" : state ? "kind" : "path"))) throw new Error("workspace-request-invalid");
+  const context = managedWorkspacePolicy(cwd, assets, readOnly);
+  if (state) return { writable: !context.readOnly };
+  if (writing) {
+    try { return { state: "saved", ...writeWorkspaceFile(cwd, input.payload as WorkspaceWriteInput, context) }; }
+    catch (error) {
+      if (error instanceof WorkspaceWriteError) return { state: "rejected", code: error.code, currentDigest: error.currentDigest };
+      throw error;
+    }
+  }
+  const relative = input.path as string;
+  return input.kind === "search" ? await searchWorkspace(cwd, relative, context) : input.kind === "paths" ? await inspectWorkspacePaths(cwd, relative, context) : input.kind === "tree" ? inspectWorkspaceTree(cwd, relative, context) : inspectWorkspaceFile(cwd, relative, context);
+}
+
+function managedWorkspacePolicy(cwd: string, assets: string, readOnly: boolean) {
+  try {
+    const stat = inspectWorkspaceEntry(cwd, ".pi/piagent-profile.json");
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1_048_576) throw new Error("workspace-policy-unavailable");
+  } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+  const { policy, profile } = loadProjectContextIndexPolicy(assets, cwd);
+  return { policy, profile, readOnly: readOnly || profile.permissionProfile === "read-only" };
+}
+
+export function beginManagedMutationObservation(cwd: string, assets: string, request: {
+  toolName: string; args: Record<string, unknown>; sessionId: string; toolCallId: string; prior: unknown;
+}, readOnly: boolean) {
+  const observer = new SessionMutationObserver();
+  if (!["edit", "write"].includes(request.toolName) || typeof request.args.path !== "string") return () => null;
+  const file = path.relative(cwd, path.resolve(cwd, request.args.path)).split(path.sep).join("/");
+  const policy = managedWorkspacePolicy(cwd, assets, readOnly);
+  observer.restore(cwd, request.sessionId, file, request.prior, policy);
+  observer.begin(cwd, request.sessionId, request.toolCallId, request.toolName, request.args, [file], policy);
+  return () => {
+    // Profile changes during execution must also take effect before disclosure.
+    const currentPolicy = managedWorkspacePolicy(cwd, assets, readOnly);
+    observer.finish(cwd, request.sessionId, request.toolCallId, request.toolName, true, currentPolicy);
+    return observer.current(cwd, request.sessionId, file, currentPolicy);
+  };
+}
+
+export function managedSourceRevert(cwd: string, assets: string, context: Omit<ManagedSourceContext, "cwd" | "policy">, readOnly: boolean) {
+  return createManagedSourceRevert({ ...context, cwd, policy: () => managedWorkspacePolicy(cwd, assets, readOnly) });
+}
+
+// Only tool-worker supplies this context, separately from model/browser args.
+export async function inspectManagedSource(cwd: string, assets: string, request: any, trusted: any, readOnly: boolean) {
+  if (!trusted || !/^[a-f0-9]{64}$/.test(trusted.confirmationKey) || !Array.isArray(trusted.observations)
+    || trusted.observations.length > 32) throw new Error("source-boundary-authority-required");
+  const observations = new Map<string, unknown>(trusted.observations);
+  const adapter = managedSourceRevert(cwd, assets, { identity: trusted.identity, rawSessionId: trusted.rawSessionId,
+    controlRevision: trusted.controlRevision, confirmationKey: Buffer.from(trusted.confirmationKey, "hex"),
+    idle: () => true, observation: file => observations.get(file) }, readOnly);
+  if (request?.kind === "diff" && typeof request.fileRef === "string") return { result: await adapter.diff(request.fileRef) };
+  if (request?.kind === "sources") return { result: await adapter.sources() };
+  if (request?.kind === "preview" && typeof request.fileRef === "string" && Array.isArray(request.hunkRefs))
+    return { result: await adapter.preview(request.fileRef, request.hunkRefs) };
+  if (request?.kind === "execute") {
+    const result = await adapter.execute(request.target);
+    return { result, sourceObservation: { path: request.target.path, observation: adapter.observation(request.target.path) } };
+  }
+  throw new Error("source-request-invalid");
+}

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

@@ -1,3 +1,6 @@
+import type { SourceIndexTransactionResult } from "../inspection/source-action-contract.ts";
+export type { SourceIndexTransactionResult } from "../inspection/source-action-contract.ts";
+
 import { spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import fs from "node:fs";
@@ -14,16 +17,6 @@ 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 };