@piagent/platform 1.3.0 → 1.4.0

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

@@ -0,0 +1,168 @@
+import { createHash, randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { ensurePrivateStateDirectory, resolveLocalStatePath } from "../../extensions/local-state-path.js";
+import { canonicalReviewValue } from "./review-state-contract.ts";
+import { validateSourceMutationTarget, type SourceMutationAction, type SourceMutationTarget } from "./source-mutation-projection.ts";
+import { validateSourceRevertTarget, type SourceRevertTarget } from "./source-revert-projection.ts";
+import { readTaskBaselineManifest, taskBaselineRetentionState } from "./source-evidence-store.ts";
+
+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))}`; }
+function timestamp(value: unknown): value is string {
+  if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value)) return false;
+  const parsed = Date.parse(value); return Number.isFinite(parsed) && new Date(parsed).toISOString() === value;
+}
+function directory(projectRoot: string, taskRunId: string): string {
+  return path.join(projectRoot, ".pi", "piagent-state", "source-evidence", `run-${sha(taskRunId)}`, "source-actions");
+}
+function readPrivate(projectRoot: string, file: string): Buffer {
+  const safe = resolveLocalStatePath(projectRoot, file, { label: "Source mutation evidence", kind: "file" });
+  const descriptor = fs.openSync(safe, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+  try {
+    const stat = fs.fstatSync(descriptor);
+    if (!stat.isFile() || stat.size > MAX_RECORD_BYTES) throw new Error("mutation-record-oversized");
+    return fs.readFileSync(descriptor);
+  } finally { fs.closeSync(descriptor); }
+}
+function publish(projectRoot: string, target: string, bytes: Buffer): void {
+  const parent = ensurePrivateStateDirectory(projectRoot, path.dirname(target), "Source mutation evidence directory");
+  const safeTarget = resolveLocalStatePath(projectRoot, target, { label: "Source mutation evidence" });
+  const temporary = path.join(parent, `${path.basename(target)}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`);
+  const descriptor = fs.openSync(temporary, "wx", 0o600);
+  try { fs.writeFileSync(descriptor, bytes); fs.fsyncSync(descriptor); fs.fchmodSync(descriptor, 0o600); }
+  finally { fs.closeSync(descriptor); }
+  try { fs.linkSync(temporary, safeTarget); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST" || !readPrivate(projectRoot, safeTarget).equals(bytes)) throw error;
+  } finally { fs.rmSync(temporary, { force: true }); }
+}
+
+export function validateSourceMutationEvidence(value: unknown): SourceMutationEvidenceRecord {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("mutation-record-invalid");
+  const record = value as SourceMutationEvidenceRecord;
+  const keys = ["schemaVersion", "version", "recordId", "evidenceRef", "sequence", "phase", "resultCode", "projectRef", "runtimeInstanceId", "sessionRef",
+    "taskId", "taskRunId", "commandId", "idempotencyKeyDigest", "actionDigest", "action", "target", "selectedHunkRefs", "failureCode", "requestedAt", "recordedAt", "retentionUntil",
+    "beforeIndexPreimage", "afterIndexPreimage", "beforeWorkspacePreimage", "afterWorkspacePreimage", "observedRevisionsBefore", "observedRevisionsAfter", "integrityDigest"];
+  if (canonicalReviewValue(Object.keys(record).sort()) !== canonicalReviewValue(keys.sort()) || record.schemaVersion !== 1
+    || record.version !== SOURCE_MUTATION_EVIDENCE_VERSION || ![record.recordId, record.evidenceRef, record.projectRef, record.runtimeInstanceId,
+      record.sessionRef, record.taskId, record.taskRunId, record.commandId].every((item) => REF.test(item))
+    || !Number.isInteger(record.sequence) || record.sequence < 1 || record.sequence > MAX_RECORDS
+    || ![record.idempotencyKeyDigest, record.actionDigest, record.beforeIndexPreimage, record.integrityDigest].every((item) => DIGEST.test(item))
+    || !/^wt-content-v2:[a-f0-9]{64}$/.test(record.beforeWorkspacePreimage)
+    || record.afterIndexPreimage !== null && !DIGEST.test(record.afterIndexPreimage)
+    || record.afterWorkspacePreimage !== null && !/^wt-content-v2:[a-f0-9]{64}$/.test(record.afterWorkspacePreimage)
+    || !Array.isArray(record.selectedHunkRefs) || record.selectedHunkRefs.length > 128
+    || new Set(record.selectedHunkRefs).size !== record.selectedHunkRefs.length
+    || record.selectedHunkRefs.some((item) => !REF.test(item) || !record.target.hunkRefs.includes(item))
+    || ![record.requestedAt, record.recordedAt, record.retentionUntil].every(timestamp)
+    || !(record.failureCode === null || /^[a-z][a-z0-9.-]{0,95}$/.test(record.failureCode))
+    || !["source.stage", "source.unstage", "source.revert"].includes(record.action)) throw new Error("mutation-record-invalid");
+  const settledResult = record.action === "source.stage" ? "staged" : record.action === "source.unstage" ? "unstaged" : "reverted";
+  const phaseResult = { requested: "mutation-requested", settled: settledResult,
+    rejected: "mutation-rejected", uncertain: "effect-unknown" }[record.phase];
+  if (record.resultCode !== phaseResult || record.phase === "requested" && (record.afterIndexPreimage !== null || record.afterWorkspacePreimage !== null)
+    || record.phase === "settled" && (!record.afterIndexPreimage || !record.afterWorkspacePreimage)
+    || ["requested", "settled"].includes(record.phase) !== (record.failureCode === null)) throw new Error("mutation-record-phase-invalid");
+  if (record.action === "source.revert") validateSourceRevertTarget(record.target); else validateSourceMutationTarget(record.target);
+  for (const revisions of [record.observedRevisionsBefore, record.observedRevisionsAfter].filter(Boolean) as Array<Record<string, string | null>>) {
+    if (canonicalReviewValue(Object.keys(revisions).sort()) !== canonicalReviewValue([...REVISION_KEYS].sort())
+      || !REVISION.test(String(revisions.runtimeRevision ?? "")) || REVISION_KEYS.slice(1).some((key) => revisions[key] !== null && !REVISION.test(String(revisions[key]))))
+      throw new Error("mutation-record-revisions-invalid");
+  }
+  if (record.phase === "requested" ? record.observedRevisionsAfter !== null : record.observedRevisionsAfter === null) throw new Error("mutation-record-revisions-invalid");
+  const { integrityDigest, ...payload } = record;
+  if (evidenceDigest(payload) !== integrityDigest) throw new Error("mutation-record-integrity-invalid");
+  return structuredClone(record);
+}
+
+export function readSourceMutationEvidence(projectRoot: string, taskRunId: string): { records: SourceMutationEvidenceRecord[]; corruptions: string[] } {
+  const root = directory(projectRoot, taskRunId);
+  let files: string[];
+  try { files = fs.readdirSync(resolveLocalStatePath(projectRoot, root, { label: "Source mutation evidence", kind: "directory" })).filter((file) => file.endsWith(".json")).sort(); }
+  catch (error) { return (error as NodeJS.ErrnoException).code === "ENOENT" ? { records: [], corruptions: [] } : { records: [], corruptions: ["mutation-evidence-directory-unavailable"] }; }
+  if (files.length > MAX_RECORDS) return { records: [], corruptions: ["mutation-evidence-record-limit"] };
+  const records: SourceMutationEvidenceRecord[] = [], corruptions: string[] = [];
+  for (const file of files) try {
+    const record = validateSourceMutationEvidence(JSON.parse(readPrivate(projectRoot, path.join(root, file)).toString("utf8")));
+    if (file !== `${record.recordId}.json` || record.taskRunId !== taskRunId) throw new Error("mutation-record-identity-invalid");
+    records.push(record);
+  } catch { corruptions.push(`mutation.${sha(file)}`); }
+  return { records: corruptions.length ? [] : records.sort((left, right) => left.sequence - right.sequence), corruptions };
+}
+
+export function appendSourceMutationEvidence(options: AppendOptions): 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");
+  const existing = readSourceMutationEvidence(options.projectRoot, options.taskRunId);
+  if (existing.corruptions.length || existing.records.length >= MAX_RECORDS) throw new Error("mutation-evidence-unavailable");
+  const identity = evidenceDigest({ commandId: options.commandId, actionDigest: options.actionDigest, phase: options.phase });
+  const recordId = `mutation.${identity.slice(7)}`;
+  const duplicate = existing.records.find((record) => record.recordId === recordId);
+  if (duplicate) {
+    const expected = { phase: options.phase, resultCode: options.resultCode, failureCode: options.failureCode, selectedHunkRefs: options.selectedHunkRefs,
+      commandId: options.commandId, idempotencyKeyDigest: options.idempotencyKeyDigest,
+      actionDigest: options.actionDigest, action: options.action, target: options.target, beforeIndexPreimage: options.beforeIndexPreimage,
+      afterIndexPreimage: options.afterIndexPreimage, beforeWorkspacePreimage: options.beforeWorkspacePreimage,
+      afterWorkspacePreimage: options.afterWorkspacePreimage, observedRevisionsBefore: options.observedRevisionsBefore,
+      observedRevisionsAfter: options.observedRevisionsAfter };
+    const actual = Object.fromEntries(Object.keys(expected).map((key) => [key, (duplicate as any)[key]]));
+    if (canonicalReviewValue(actual) !== canonicalReviewValue(expected)) throw new Error("mutation-evidence-identity-collision");
+    return validateSourceMutationEvidence(duplicate);
+  }
+  const payload = { schemaVersion: 1 as const, version: SOURCE_MUTATION_EVIDENCE_VERSION, recordId, evidenceRef: `mutation-evidence.${identity.slice(7)}`,
+    sequence: (existing.records.at(-1)?.sequence ?? 0) + 1, phase: options.phase, resultCode: options.resultCode, failureCode: options.failureCode,
+    projectRef: options.projectRef, runtimeInstanceId: options.runtimeInstanceId, sessionRef: options.sessionRef, taskId: options.taskId,
+    taskRunId: options.taskRunId, commandId: options.commandId, idempotencyKeyDigest: options.idempotencyKeyDigest, actionDigest: options.actionDigest,
+    action: options.action, target: structuredClone(options.target), selectedHunkRefs: [...options.selectedHunkRefs], requestedAt: options.requestedAt, recordedAt: options.recordedAt,
+    retentionUntil: manifest.retentionUntil, beforeIndexPreimage: options.beforeIndexPreimage, afterIndexPreimage: options.afterIndexPreimage,
+    beforeWorkspacePreimage: options.beforeWorkspacePreimage, afterWorkspacePreimage: options.afterWorkspacePreimage,
+    observedRevisionsBefore: structuredClone(options.observedRevisionsBefore), observedRevisionsAfter: structuredClone(options.observedRevisionsAfter) };
+  const record = validateSourceMutationEvidence({ ...payload, integrityDigest: evidenceDigest(payload) });
+  const bytes = Buffer.from(`${JSON.stringify(record, null, 2)}\n`);
+  if (bytes.length > MAX_RECORD_BYTES) throw new Error("mutation-record-oversized");
+  publish(options.projectRoot, path.join(directory(options.projectRoot, options.taskRunId), `${record.recordId}.json`), bytes);
+  return record;
+}

package/packages/piagent-core/runtime/inspection/source-open-target.ts

@@ -0,0 +1,38 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { collectSelectedSourceFileState, type SourceChangeDocument, type SourceProjectionOptions, type WebUiIdentity } from "./source-change-projection.ts";
+
+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}$/;
+
+export type SourceOpenTarget = { fileRef: string; taskRevision: string; workspaceRevision: string; fileRevision: string; contentDigest: string };
+export type SourceOpenAuthority = { projectRoot: string; repoRoot: string; repoPath: string; absolutePath: string; target: SourceOpenTarget };
+
+function inside(root: string, candidate: string): boolean {
+  const relative = path.relative(root, candidate);
+  return relative === "" || relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+
+export async function resolveSourceOpenTarget(options: { cwd: string; identity: WebUiIdentity; sourceView: SourceChangeDocument;
+  fileRef: string; taskRevision: string; workspaceRevision: string; generatedAt?: string;
+  isProtectedPath?: SourceProjectionOptions["isProtectedPath"]; timeoutMs?: number; maxGitBytes?: number }): Promise<SourceOpenAuthority | null> {
+  if (options.sourceView.view !== "working-tree" || options.sourceView.availability.state !== "current" || !REF.test(options.fileRef)
+    || !REVISION.test(options.taskRevision) || !REVISION.test(options.workspaceRevision)) return null;
+  const file = options.sourceView.files.find((candidate: any) => candidate.fileRef === options.fileRef) as Record<string, any> | undefined;
+  if (!file || file.pathDisplay !== "exact-safe" || file.oldPath !== null || ["D", "R", "C"].includes(String(file.status))
+    || file.content?.access !== "available" || file.content?.kind !== "text" || !DIGEST.test(String(file.currentDigest ?? ""))) return null;
+  const selected = 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", options.fileRef, String(file.basisRef), [file.path]);
+  const selectedContent = selected?.file.content as { access?: unknown; kind?: unknown } | undefined;
+  if (!selected || selected.file.fileRevision !== file.fileRevision || selected.record.kind !== "ordinary" || selected.record.oldPath
+    || selectedContent?.access !== "available" || selectedContent.kind !== "text") return null;
+  const repoPath = selected.record.path.value; if (!repoPath || options.isProtectedPath?.(selected.snapshot.repoRoot, repoPath) === true) return null;
+  const projectRoot = fs.realpathSync.native(options.cwd), repoRoot = fs.realpathSync.native(selected.snapshot.repoRoot);
+  const unresolved = path.resolve(repoRoot, repoPath); if (!inside(projectRoot, unresolved) || !inside(repoRoot, unresolved)) return null;
+  const stat = fs.lstatSync(unresolved); if (!stat.isFile() || stat.isSymbolicLink()) return null;
+  const absolutePath = fs.realpathSync.native(unresolved); if (absolutePath !== unresolved || !inside(projectRoot, absolutePath)) return null;
+  return { projectRoot, repoRoot, repoPath, absolutePath, target: { fileRef: options.fileRef, taskRevision: options.taskRevision,
+    workspaceRevision: options.workspaceRevision, fileRevision: String(file.fileRevision), contentDigest: String(file.currentDigest) } };
+}

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

@@ -0,0 +1,147 @@
+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 { collectSelectedSourceFileState, type SourceChangeDocument, type SourceProjectionOptions, type WebUiIdentity } from "./source-change-projection.ts";
+import { collectIndexPreimage, collectSelectedWorkspacePreimage } from "./source-mutation-projection.ts";
+
+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}$/;
+
+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;
+  confirmationKey: Buffer;
+  isProtectedPath?: SourceProjectionOptions["isProtectedPath"]; guardAvailable?: boolean; timeoutMs?: number; maxGitBytes?: number;
+};
+
+function confirmationDigest(key: Buffer, value: unknown): string {
+  return `sha256:${createHmac("sha256", key).update(canonicalReviewValue(value)).digest("hex")}`;
+}
+function previewHunk(hunk: ExactGitPatchAuthority["hunks"][number]): RevertPreviewHunk | null {
+  const text = hunk.bytes.toString("utf8");
+  if (!Buffer.from(text, "utf8").equals(hunk.bytes)) return null;
+  const raw = text.split("\n"); if (raw.at(-1) === "") raw.pop();
+  const header = raw.shift() ?? ""; if (!/^@@ -\d+(?:,\d+)? \+\d+(?:,\d+)? @@/.test(header) || header.length > 1024) return null;
+  const lines: RevertPreviewLine[] = [];
+  for (const line of raw) {
+    const marker = line.startsWith("+") ? "+" : line.startsWith("-") ? "-" : line.startsWith("\\") ? "\\" : " ";
+    const value = line.slice(1); if (value.length > 16_384 || /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/.test(value)) return null;
+    lines.push({ kind: marker === "+" ? "added" : marker === "-" ? "deleted" : marker === "\\" ? "meta" : "context", marker, text: value });
+  }
+  return { hunkRef: hunk.hunkRef, header, lines };
+}
+function unavailable(options: CollectOptions, reasonCode: string): { projection: SourceRevertProjection; authority: null } {
+  const message = "A confirmed exact Working Tree revert is unavailable";
+  return { projection: { schemaVersion: 1, version: "piagent-webui-source-revert-v1", generatedAt: options.generatedAt ?? new Date().toISOString(),
+    identity: structuredClone(options.identity), action: "source.revert", state: "unavailable", target: null, preview: null, reasonCode,
+    health: { state: "unavailable", reasonCode, message } }, authority: null };
+}
+
+export function validateSourceRevertTarget(value: unknown): SourceRevertTarget {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("source-revert-target-invalid");
+  const target = value as SourceRevertTarget;
+  const keys = ["view", "repoRef", "fileRef", "diffRef", "status", "path", "oldPath", "effect", "taskRevision", "workspaceRevision",
+    "indexRevision", "viewRevision", "fileRevision", "workspacePreimage", "indexPreimage", "patchPreimage", "contentDigest", "hunkRefs",
+    "previewRef", "confirmedPreviewDigest", "expiresAt", "summary"];
+  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))
+    || !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)
+    || !target.summary || target.summary.files !== 1 || !Number.isInteger(target.summary.hunks) || target.summary.hunks < 1 || target.summary.hunks > 128
+    || ![target.summary.additionsDiscarded, target.summary.deletionsRestored].every((item) => Number.isInteger(item) && item >= 0 && item <= 65_536)
+    || target.summary.effect !== "discard-unstaged-keep-index" || target.summary.recovery !== "not-guaranteed") throw new Error("source-revert-target-invalid");
+  const parsed = Date.parse(target.expiresAt); if (!Number.isFinite(parsed) || new Date(parsed).toISOString() !== target.expiresAt) throw new Error("source-revert-target-invalid");
+  return structuredClone(target);
+}
+
+export async function collectSourceRevertPreview(options: CollectOptions): Promise<{ projection: SourceRevertProjection; authority: SourceRevertAuthority | null }> {
+  const selectedHunkRefs = options.selectedHunkRefs ?? [];
+  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)
+    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)
+    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 });
+  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,
+    generatedAt: options.generatedAt, isProtectedPath: options.isProtectedPath, timeoutMs: options.timeoutMs, maxGitBytes: options.maxGitBytes },
+  "working-tree", file.fileRef, String(file.basisRef), [file.path]);
+  if ((selected?.file as Record<string, any> | undefined)?.content?.access === "protected") return unavailable(options, "protected-path");
+  if (!selected || selected.file.fileRevision !== file.fileRevision || selected.record.kind !== "ordinary" || selected.record.oldPath
+    || selected.record.worktreeStatus !== "M" || !selected.record.indexObject || !["100644", "100755"].includes(String(selected.record.indexMode)))
+    return unavailable(options, "revert-target-stale");
+  const repoPath = selected.record.path.value;
+  if (!repoPath || options.isProtectedPath?.(selected.snapshot.repoRoot, repoPath) === true) return unavailable(options, "protected-path");
+  try {
+    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
+      || selectedHunkRefs.some((item) => !patchAuthority.hunks.some((hunk) => hunk.hunkRef === item))) return unavailable(options, "revert-hunk-unavailable");
+    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");
+    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 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,
+      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 };
+    const confirmedPreviewDigest = confirmationDigest(options.confirmationKey,
+      { domain: "piagent-webui-source-revert-preview-v1", confirmation });
+    const target: SourceRevertTarget = { view: "working-tree", repoRef: String(file.repoRef), fileRef: String(file.fileRef), diffRef: review.diffRef,
+      status: "M", path: String(file.path), oldPath: null, effect: "restore-worktree-from-index", taskRevision: options.taskRevision,
+      workspaceRevision: options.workspaceRevision, indexRevision: options.indexRevision, viewRevision: review.viewRevision,
+      fileRevision: review.fileRevision, workspacePreimage, indexPreimage, patchPreimage: review.patchPreimage, contentDigest: review.contentDigest,
+      hunkRefs: [...selectedHunkRefs], previewRef: `revert-preview.${confirmedPreviewDigest.slice(7)}`, confirmedPreviewDigest, expiresAt,
+      summary: { files: 1, hunks: exactPreviewHunks.length,
+        additionsDiscarded: exactPreviewHunks.reduce((count, hunk) => count + hunk.lines.filter((line) => line.kind === "added").length, 0),
+        deletionsRestored: exactPreviewHunks.reduce((count, hunk) => count + hunk.lines.filter((line) => line.kind === "deleted").length, 0),
+        effect: "discard-unstaged-keep-index", recovery: "not-guaranteed" } };
+    validateSourceRevertTarget(target);
+    return { projection: { schemaVersion: 1, version: "piagent-webui-source-revert-v1", generatedAt, identity: structuredClone(options.identity),
+      action: "source.revert", state: "ready", target, preview: { basis: "index-to-working-tree", hunks: exactPreviewHunks, truncated: false },
+      reasonCode: null, health: { state: "ok", reasonCode: null, message: null } },
+    authority: { repoRoot: selected.snapshot.repoRoot, repoPath, indexObject: selected.record.indexObject,
+      indexMode: selected.record.indexMode as "100644" | "100755", target, patchAuthority } };
+  } catch { return unavailable(options, "revert-preimage-unavailable"); }
+}

package/packages/piagent-core/runtime/inspection/task-baseline-start-capture.ts

@@ -0,0 +1,22 @@
+import { captureTaskBaselineManifest } from "./source-evidence-store.ts";
+
+export async function captureTaskStartBaseline(input: {
+  projectRoot: string;
+  taskId: string;
+  taskRunId: string;
+  sessionId: string;
+  capturedAt: string;
+  baselineTreeDigest: string;
+  protectedPaths: string[];
+  matchesProtectedPath: (path: string, patterns: string[]) => unknown;
+}): Promise<void> {
+  await captureTaskBaselineManifest({
+    projectRoot: input.projectRoot,
+    taskId: input.taskId,
+    taskRunId: input.taskRunId,
+    sessionId: input.sessionId,
+    capturedAt: input.capturedAt,
+    baselineTreeDigest: input.baselineTreeDigest,
+    isProtectedProjectPath: (projectPath) => Boolean(input.matchesProtectedPath(projectPath, input.protectedPaths))
+  });
+}

package/packages/piagent-core/runtime/inspection/task-compaction-history.ts

@@ -0,0 +1,160 @@
+import { createHash } from "node:crypto";
+
+import { redactSensitiveText } from "../../extensions/redaction-core.js";
+import { inspectTaskResumeState } from "../recovery/resume-state.ts";
+import { inspectBoundedContextTelemetry } from "./context-telemetry-inspection.ts";
+import { taskRunOpaqueRef } from "./task-run-index.ts";
+
+const MAX_EVENTS = 300;
+const MAX_TELEMETRY = 5_000;
+
+type Task = {
+  taskId: string;
+  taskRunId: string;
+  sessionId: string;
+  [key: string]: any;
+};
+type Identity = {
+  projectRef: string;
+  runtimeInstanceId: string;
+  sessionRef: string;
+  taskId: string;
+  taskRunId: string;
+  agentOperationId: null;
+  toolCallId: null;
+};
+
+function opaque(prefix: string, value: string): string {
+  return `${prefix}.${createHash("sha256").update(`piagent-webui-recovery-history-v1\0${value}`).digest("hex").slice(0, 48)}`;
+}
+
+function display(value: unknown, maximum = 160): string {
+  return redactSensitiveText(String(value ?? "")).text
+    .replace(/[\u0000-\u001f\u007f]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, maximum);
+}
+
+function timestamp(value: unknown): value is string {
+  return typeof value === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value)
+    && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value;
+}
+
+function boundedInteger(value: unknown, maximum = 1_000_000_000): number | null {
+  return Number.isInteger(value) && Number(value) >= 0 ? Math.min(Number(value), maximum) : null;
+}
+
+function recoverySummary(cwd: string, task: Task) {
+  const resume = inspectTaskResumeState(cwd, task as any, task.sessionId);
+  const latestCheckpointRef = resume.latestCheckpoint
+    ? opaque("checkpoint", `${task.taskRunId}\0${resume.latestCheckpoint.checkpointId}`)
+    : null;
+  return {
+    decision: resume.decision,
+    enforcementSafe: resume.enforcementSafe,
+    latestCheckpointRef,
+    verifierState: resume.verifierEvidenceCurrent ? "current" : resume.staleVerifierEvidence ? "stale" : "not-current",
+    invalidatedFileCount: Math.min(100_000, resume.invalidatedVerifierFiles.length),
+    invalidatedFilesKnown: resume.invalidatedVerifierFilesKnown,
+    handoffState: !resume.handoff.exists ? "none" : resume.handoff.valid ? "available" : "invalid",
+    reasonCode: `recovery-${resume.decision}`
+  };
+}
+
+function unavailable(identity: Identity, runRef: string, generatedAt: string, reasonCode = "recovery-history-unavailable") {
+  return {
+    schemaVersion: 1,
+    version: "piagent-webui-recovery-history-v1",
+    generatedAt,
+    identity: structuredClone(identity),
+    runRef,
+    state: "unavailable",
+    historyRevision: null,
+    completeness: "unknown",
+    summary: { contextCompactions: 0, toolResultCompactions: 0, compactedToolResults: 0 },
+    recovery: { decision: "unknown", enforcementSafe: null, latestCheckpointRef: null, verifierState: "unknown",
+      invalidatedFileCount: null, invalidatedFilesKnown: false, handoffState: "unknown", reasonCode },
+    retainedContent: { access: "omitted", exposed: false, reasonCode: "protected-runtime-evidence" },
+    events: [],
+    page: { total: 0, returned: 0, truncated: false },
+    warnings: [],
+    health: { state: "unavailable", reasonCode, message: "Compaction and recovery history is unavailable." }
+  };
+}
+
+export function projectTaskCompactionHistory(input: {
+  cwd: string;
+  task: Task;
+  identity: Identity;
+  generatedAt?: string;
+}): Record<string, any> {
+  const generatedAt = input.generatedAt ?? new Date().toISOString();
+  const runRef = taskRunOpaqueRef(input.task.taskRunId);
+  try {
+    const inspected = inspectBoundedContextTelemetry(input.cwd, { limit: MAX_TELEMETRY });
+    let malformed = inspected.corruptions;
+    const matching = inspected.records.flatMap((record: any, ordinal: number) => {
+      if (record?.taskId !== input.task.taskId || record?.taskRunId !== input.task.taskRunId || record?.sessionId !== input.task.sessionId) return [];
+      if (record.schemaVersion !== 1 || !timestamp(record.recordedAt)) { malformed += 1; return []; }
+      if (record.event === "session_compact") {
+        if (typeof record.willRetry !== "boolean" || typeof record.fromExtension !== "boolean") { malformed += 1; return []; }
+        return [{ ordinal, recordedAt: record.recordedAt, kind: "context-compaction", title: "Context đã được compact",
+          detail: display(record.reason, 180) || null, toolName: null, originalChars: null, originalLines: null, captureCount: null,
+          willRetry: record.willRetry, fromExtension: record.fromExtension }];
+      }
+      if (record.event === "tool_result" && record.compacted === true) {
+        const captureCount = boundedInteger(record.compactedCaptures, 10_000);
+        if (captureCount === null || captureCount < 1) { malformed += 1; return []; }
+        return [{ ordinal, recordedAt: record.recordedAt, kind: "tool-result-compaction", title: "Tool result đã được rút gọn",
+          detail: null, toolName: display(record.toolName, 120) || "tool", originalChars: boundedInteger(record.outputChars),
+          originalLines: boundedInteger(record.outputLines), captureCount, willRetry: null, fromExtension: null }];
+      }
+      return [];
+    });
+    const projected = matching.map((event: any, index: number) => {
+      const fact = { ...event }; delete fact.ordinal;
+      const digest = createHash("sha256").update(JSON.stringify({ taskRunId: input.task.taskRunId, ordinal: event.ordinal, fact })).digest("hex");
+      return { eventRef: opaque("compaction", `${input.task.taskRunId}\0${digest}`), evidenceRef: opaque("telemetry", digest),
+        sequence: index + 1, ...fact };
+    });
+    const events = projected.slice(-MAX_EVENTS);
+    const contextCompactions = projected.filter((event: any) => event.kind === "context-compaction").length;
+    const toolResultCompactions = projected.filter((event: any) => event.kind === "tool-result-compaction").length;
+    const compactedToolResults = projected.reduce((sum: number, event: any) => sum + (event.captureCount ?? 0), 0);
+    const warnings: Array<{ code: string; count: number; message: string }> = [];
+    if (!inspected.exists) warnings.push({ code: "telemetry-missing", count: 1, message: "No bounded compaction telemetry was found for this project." });
+    if (malformed > 0) warnings.push({ code: "telemetry-corrupt", count: malformed, message: `${malformed} telemetry record(s) could not be validated.` });
+    if (inspected.recoverableTailBytes > 0) warnings.push({ code: "telemetry-incomplete-tail", count: inspected.recoverableTailBytes,
+      message: "An incomplete telemetry tail may omit the latest compaction fact." });
+    if (inspected.inputTruncated) warnings.push({ code: "telemetry-input-truncated", count: 1,
+      message: "Older telemetry is outside the bounded inspection window." });
+    if (projected.length > events.length) warnings.push({ code: "history-truncated", count: projected.length - events.length,
+      message: `${projected.length - events.length} older compaction event(s) are outside this bounded page.` });
+    const recovery = recoverySummary(input.cwd, input.task);
+    const completeness = !inspected.exists ? "missing" : malformed || inspected.recoverableTailBytes || inspected.inputTruncated ? "partial" : "complete";
+    const summary = { contextCompactions, toolResultCompactions, compactedToolResults };
+    const historyRevision = `recovery-history.${createHash("sha256").update(JSON.stringify({ events, summary, recovery, completeness })).digest("hex")}`;
+    return {
+      schemaVersion: 1,
+      version: "piagent-webui-recovery-history-v1",
+      generatedAt,
+      identity: structuredClone(input.identity),
+      runRef,
+      state: "ready",
+      historyRevision,
+      completeness,
+      summary,
+      recovery,
+      retainedContent: { access: "omitted", exposed: false, reasonCode: "protected-runtime-evidence" },
+      events,
+      page: { total: projected.length, returned: events.length, truncated: projected.length > events.length },
+      warnings,
+      health: warnings.length
+        ? { state: "degraded", reasonCode: "recovery-history-warning", message: "Some compaction or recovery facts are unavailable or omitted." }
+        : { state: "ok", reasonCode: null, message: null }
+    };
+  } catch {
+    return unavailable(input.identity, runRef, generatedAt);
+  }
+}