@piagent/platform 1.3.0 → 1.4.0

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

@@ -0,0 +1,315 @@
+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 { workingTreeSnapshot } from "../../extensions/task-state.js";
+import { workingTreeEvidenceDigest } from "../../extensions/working-tree-digest.js";
+import { collectGitStatus, type GitStatusRecord, type GitStatusSnapshot } from "./git-status-adapter.ts";
+import { collectSourceChangeViews, sourceFileRef, type WebUiIdentity } from "./source-change-projection.ts";
+import {
+  TASK_BASELINE_MANIFEST_VERSION,
+  taskBaselineManifestDigest,
+  validateTaskBaselineManifest,
+  type TaskBaselineEntry,
+  type TaskBaselineManifest,
+  type TaskBaselineRoot
+} from "./source-evidence-contract.ts";
+import { inspectWorkspaceEntry, readWorkspaceFile, readWorkspaceLink } from "./workspace-file-reader.ts";
+
+const DEFAULT_MAX_ENTRIES = 2_000;
+const DEFAULT_MAX_FILE_BYTES = 4 * 1024 * 1024;
+const DEFAULT_MAX_TOTAL_BYTES = 64 * 1024 * 1024;
+const DEFAULT_RETENTION_MS = 30 * 24 * 60 * 60 * 1_000;
+
+export type BaselineCaptureOptions = {
+  projectRoot: string;
+  taskId: string;
+  taskRunId: string;
+  sessionId: string;
+  capturedAt: string;
+  baselineTreeDigest: string;
+  isProtectedProjectPath?: (projectPath: string) => boolean;
+  maxEntries?: number;
+  maxFileBytes?: number;
+  maxTotalBytes?: number;
+  retentionMs?: number;
+};
+
+type EvidenceRoot = { cwd: string; projectPath: string };
+type Candidate = { record: GitStatusRecord; repoPath: string | null; absent: boolean };
+
+function hash(value: string | Buffer): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function digest(value: string | Buffer): string {
+  return `sha256:${hash(value)}`;
+}
+
+function bounded(value: number | undefined, fallback: number, minimum: number, maximum: number): number {
+  return Number.isInteger(value) ? Math.max(minimum, Math.min(maximum, value as number)) : fallback;
+}
+
+function runDirectory(projectRoot: string, taskRunId: string): string {
+  return path.join(projectRoot, ".pi", "piagent-state", "source-evidence", `run-${hash(taskRunId)}`);
+}
+
+export function taskBaselineManifestPath(projectRoot: string, taskRunId: string): string {
+  return path.join(runDirectory(projectRoot, taskRunId), "manifest.json");
+}
+
+function blobPath(projectRoot: string, taskRunId: string, contentRef: string): string {
+  if (!/^sha256:[a-f0-9]{64}$/.test(contentRef)) throw new Error("Invalid baseline content ref");
+  return path.join(runDirectory(projectRoot, taskRunId), "blobs", contentRef.slice(7));
+}
+
+function readPrivateFile(projectRoot: string, file: string, maxBytes: number): Buffer {
+  const safe = resolveLocalStatePath(projectRoot, file, { label: "Source 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 > maxBytes) throw new Error("Source evidence file is oversized or not regular");
+    return fs.readFileSync(descriptor);
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
+
+function publishPrivateFile(projectRoot: string, target: string, content: Buffer): void {
+  const parent = ensurePrivateStateDirectory(projectRoot, path.dirname(target), "Source evidence directory");
+  const safeTarget = resolveLocalStatePath(projectRoot, target, { label: "Source evidence" });
+  const temporary = path.join(parent, `${path.basename(safeTarget)}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`);
+  const descriptor = fs.openSync(temporary, "wx", 0o600);
+  try {
+    fs.writeFileSync(descriptor, content);
+    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") throw error;
+    const existing = readPrivateFile(projectRoot, safeTarget, Math.max(1024, content.length));
+    if (!existing.equals(content)) throw new Error("Existing source evidence does not match the captured bytes");
+  } finally {
+    fs.rmSync(temporary, { force: true });
+  }
+  try { fs.chmodSync(parent, 0o700); fs.chmodSync(safeTarget, 0o600); } catch {}
+}
+
+function writeBlob(projectRoot: string, taskRunId: string, content: Buffer): string {
+  const contentRef = digest(content);
+  publishPrivateFile(projectRoot, blobPath(projectRoot, taskRunId, contentRef), content);
+  return contentRef;
+}
+
+async function discoverEvidenceRoots(projectRoot: string): Promise<EvidenceRoot[]> {
+  const absolute = fs.realpathSync.native(projectRoot);
+  try {
+    await collectGitStatus(absolute);
+    return [{ cwd: absolute, projectPath: "." }];
+  } catch {
+    const roots: EvidenceRoot[] = [];
+    for (const entry of fs.readdirSync(absolute, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name.startsWith(".") || entry.name === "node_modules") continue;
+      const child = path.join(absolute, entry.name);
+      try {
+        if (fs.lstatSync(child).isSymbolicLink()) continue;
+        const status = await collectGitStatus(child);
+        if (status.repoRoot !== fs.realpathSync.native(child)) continue;
+        roots.push({ cwd: status.repoRoot, projectPath: entry.name });
+      } catch {}
+    }
+    return roots.sort((left, right) => left.projectPath.localeCompare(right.projectPath, "en"));
+  }
+}
+
+function projectPath(root: EvidenceRoot, repoPath: string): string {
+  return root.projectPath === "." ? repoPath : `${root.projectPath}/${repoPath}`;
+}
+
+function entryMode(record: GitStatusRecord, absent: boolean): string {
+  if (absent) return "000000";
+  const mode = record.worktreeMode === "000000" ? record.indexMode : record.worktreeMode;
+  return /^[0-7]{6}$/.test(mode ?? "") ? mode as string : "000000";
+}
+
+function candidates(snapshot: GitStatusSnapshot): Candidate[] {
+  const selected = new Map<string, Candidate>();
+  for (const record of snapshot.records) {
+    if (record.kind === "ignored") continue;
+    const paths = [record.path.value, record.oldPath?.value].filter((value): value is string => Boolean(value));
+    if (paths.some((value) => value === ".pi/piagent-state" || value.startsWith(".pi/piagent-state/"))) continue;
+    if (record.oldPath?.value) selected.set(record.oldPath.value, { record, repoPath: record.oldPath.value, absent: true });
+    if (record.path.value) selected.set(record.path.value, { record, repoPath: record.path.value, absent: record.worktreeMode === "000000" && record.kind !== "untracked" });
+    else selected.set(`unavailable:${record.path.digest}`, { record, repoPath: null, absent: false });
+  }
+  return [...selected.values()].sort((left, right) => Buffer.compare(Buffer.from(left.repoPath ?? left.record.path.digest), Buffer.from(right.repoPath ?? right.record.path.digest)));
+}
+
+function unavailableEntry(candidate: Candidate, snapshot: GitStatusSnapshot, reasonCode: string): TaskBaselineEntry {
+  const raw = candidate.repoPath ? Buffer.from(candidate.repoPath, "utf8") : null;
+  const pathDigest = candidate.repoPath ? digest(raw as Buffer) : candidate.record.path.digest;
+  return {
+    pathRef: `path.${hash(`${snapshot.repoDigest}\0${pathDigest}`)}`,
+    pathDigest,
+    repoPathBase64: raw?.toString("base64url") ?? null,
+    state: "unavailable",
+    reasonCode,
+    contentRef: null,
+    byteLength: 0,
+    mode: entryMode(candidate.record, candidate.absent),
+    headObject: candidate.record.headObject && !/^0+$/.test(candidate.record.headObject) ? candidate.record.headObject : null,
+    indexObject: candidate.record.indexObject && !/^0+$/.test(candidate.record.indexObject) ? candidate.record.indexObject : null
+  };
+}
+
+function captureEntry(
+  options: BaselineCaptureOptions,
+  root: EvidenceRoot,
+  snapshot: GitStatusSnapshot,
+  candidate: Candidate,
+  quota: { captured: number; refs: Set<string>; maxFile: number; maxTotal: number }
+): TaskBaselineEntry {
+  if (!candidate.repoPath) return unavailableEntry(candidate, snapshot, "path-unavailable");
+  const base = unavailableEntry(candidate, snapshot, "capture-unavailable");
+  const encoded = Buffer.from(candidate.repoPath, "utf8").toString("base64url");
+  const exact = (state: TaskBaselineEntry["state"], contentRef: string | null, byteLength: number): TaskBaselineEntry => ({ ...base, repoPathBase64: encoded, state, reasonCode: null, contentRef, byteLength });
+  if (options.isProtectedProjectPath?.(projectPath(root, candidate.repoPath))) {
+    return { ...base, repoPathBase64: encoded, state: "protected", reasonCode: "protected-path" };
+  }
+  if (candidate.absent) return exact("absent", null, 0);
+  if (base.mode === "160000" || candidate.record.submodule?.startsWith("S")) return exact("submodule", null, 0);
+  try {
+    const stat = inspectWorkspaceEntry(snapshot.repoRoot, candidate.repoPath);
+    let content: Buffer;
+    let state: "blob" | "symlink";
+    if (stat.isSymbolicLink()) {
+      content = Buffer.from(readWorkspaceLink(snapshot.repoRoot, candidate.repoPath), "utf8");
+      state = "symlink";
+    } else if (stat.isFile()) {
+      if (stat.size > quota.maxFile) return { ...base, repoPathBase64: encoded, state: "oversized", reasonCode: "file-size-limit", byteLength: Math.min(stat.size, 16 * 1024 * 1024) };
+      content = readWorkspaceFile(snapshot.repoRoot, candidate.repoPath, quota.maxFile);
+      state = "blob";
+    } else return { ...base, repoPathBase64: encoded, reasonCode: "unsupported-file-type" };
+    const contentRef = digest(content);
+    const additional = quota.refs.has(contentRef) ? 0 : content.length;
+    if (quota.captured + additional > quota.maxTotal) return { ...base, repoPathBase64: encoded, reasonCode: "task-byte-quota" };
+    writeBlob(options.projectRoot, options.taskRunId, content);
+    quota.refs.add(contentRef);
+    quota.captured += additional;
+    return exact(state, contentRef, content.length);
+  } catch {
+    return { ...base, repoPathBase64: encoded, reasonCode: "content-read-failed" };
+  }
+}
+
+function identity(options: BaselineCaptureOptions): WebUiIdentity {
+  return { projectRef: "baseline-capture", runtimeInstanceId: "baseline-capture", sessionRef: "baseline-capture", taskId: options.taskId, taskRunId: options.taskRunId, agentOperationId: null, toolCallId: null };
+}
+
+async function captureRoot(options: BaselineCaptureOptions, root: EvidenceRoot, quota: { captured: number; refs: Set<string>; maxFile: number; maxTotal: number }, maxEntries: number): Promise<TaskBaselineRoot> {
+  const snapshot = await collectGitStatus(root.cwd);
+  const projected = await collectSourceChangeViews({ cwd: root.cwd, identity: identity(options), generatedAt: options.capturedAt, pageLimit: 2000 });
+  const basis = projected.workingTree.bases[0] as Record<string, any>;
+  const all = candidates(snapshot);
+  const limited = all.slice(0, maxEntries);
+  const entries = limited.map((candidate) => captureEntry(options, root, snapshot, candidate, quota));
+  const bad = entries.find((entry) => ["protected", "oversized", "unavailable"].includes(entry.state));
+  const state = all.length > limited.length || bad ? "unavailable" : "current";
+  const reasonCode = all.length > limited.length ? "entry-limit" : bad?.reasonCode ?? null;
+  return {
+    repoRef: String(basis.repoRef),
+    projectPath: root.projectPath,
+    headState: snapshot.headState,
+    headOid: snapshot.headOid,
+    workspaceRevision: String(basis.workspaceRevision),
+    indexRevision: String(basis.indexRevision),
+    state,
+    reasonCode,
+    entries
+  };
+}
+
+export async function captureTaskBaselineManifest(options: BaselineCaptureOptions): Promise<TaskBaselineManifest> {
+  const existing = readTaskBaselineManifest(options.projectRoot, options.taskRunId);
+  if (existing) {
+    if (existing.taskId !== options.taskId || existing.baselineTreeDigest !== options.baselineTreeDigest) throw new Error("Task baseline manifest identity collision");
+    return existing;
+  }
+  if (workingTreeEvidenceDigest(workingTreeSnapshot(options.projectRoot)) !== options.baselineTreeDigest) {
+    throw new Error("Workspace changed before Task Baseline Manifest capture");
+  }
+  const maxEntries = bounded(options.maxEntries, DEFAULT_MAX_ENTRIES, 1, DEFAULT_MAX_ENTRIES);
+  const maxFileBytes = bounded(options.maxFileBytes, DEFAULT_MAX_FILE_BYTES, 1024, 16 * 1024 * 1024);
+  const maxTotalBytes = bounded(options.maxTotalBytes, DEFAULT_MAX_TOTAL_BYTES, 1024 * 1024, 256 * 1024 * 1024);
+  const retentionMs = bounded(options.retentionMs, DEFAULT_RETENTION_MS, 60_000, 365 * 24 * 60 * 60 * 1000);
+  const roots = await discoverEvidenceRoots(options.projectRoot);
+  if (roots.length === 0 || roots.length > 32) throw new Error("Task baseline capture requires between one and 32 Git roots");
+  const quota = { captured: 0, refs: new Set<string>(), maxFile: maxFileBytes, maxTotal: maxTotalBytes };
+  let remaining = maxEntries;
+  const capturedRoots: TaskBaselineRoot[] = [];
+  for (const root of roots) {
+    const captured = await captureRoot(options, root, quota, remaining);
+    capturedRoots.push(captured);
+    remaining = Math.max(0, remaining - captured.entries.length);
+  }
+  const badRoot = capturedRoots.find((root) => root.state !== "current");
+  const payload: Omit<TaskBaselineManifest, "integrityDigest"> = {
+    schemaVersion: 1,
+    version: TASK_BASELINE_MANIFEST_VERSION,
+    taskId: options.taskId,
+    taskRunId: options.taskRunId,
+    sessionIdentityHash: digest(options.sessionId),
+    capturedAt: options.capturedAt,
+    retentionUntil: new Date(Date.parse(options.capturedAt) + retentionMs).toISOString(),
+    baselineDigestAlgorithm: "wt-content-v2",
+    baselineTreeDigest: options.baselineTreeDigest,
+    captureState: badRoot ? "unavailable" : "current",
+    reasonCode: badRoot?.reasonCode ?? null,
+    limits: { maxEntries, maxFileBytes, maxTotalBytes, capturedBytes: quota.captured },
+    roots: capturedRoots
+  };
+  if (workingTreeEvidenceDigest(workingTreeSnapshot(options.projectRoot)) !== options.baselineTreeDigest) {
+    throw new Error("Workspace changed during Task Baseline Manifest capture");
+  }
+  const manifest = validateTaskBaselineManifest({ ...payload, integrityDigest: taskBaselineManifestDigest(payload) });
+  publishPrivateFile(options.projectRoot, taskBaselineManifestPath(options.projectRoot, options.taskRunId), Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`));
+  return manifest;
+}
+
+export function readTaskBaselineManifest(projectRoot: string, taskRunId: string): TaskBaselineManifest | undefined {
+  const file = taskBaselineManifestPath(projectRoot, taskRunId);
+  try {
+    return validateTaskBaselineManifest(JSON.parse(readPrivateFile(projectRoot, file, 8 * 1024 * 1024).toString("utf8")));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+export function readTaskBaselineBlob(projectRoot: string, taskRunId: string, contentRef: string, maxBytes = DEFAULT_MAX_FILE_BYTES): Buffer {
+  const content = readPrivateFile(projectRoot, blobPath(projectRoot, taskRunId, contentRef), bounded(maxBytes, DEFAULT_MAX_FILE_BYTES, 1024, 16 * 1024 * 1024));
+  if (digest(content) !== contentRef) throw new Error("Task baseline blob integrity mismatch");
+  return content;
+}
+
+export function taskBaselineManifestRef(manifest: TaskBaselineManifest): string {
+  return `baseline.${manifest.integrityDigest.slice(7)}`;
+}
+
+export function taskBaselineRetentionState(
+  manifest: TaskBaselineManifest,
+  at = new Date()
+): "active" | "expired" {
+  return at.getTime() < Date.parse(manifest.retentionUntil) ? "active" : "expired";
+}
+
+export function decodeBaselineRepoPath(entry: TaskBaselineEntry): string | null {
+  if (entry.repoPathBase64 === null) return null;
+  const value = Buffer.from(entry.repoPathBase64, "base64url").toString("utf8");
+  return value && !path.posix.isAbsolute(value) && !value.split("/").includes("..") ? value : null;
+}

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

@@ -0,0 +1,70 @@
+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 { readTaskBaselineManifest, taskBaselineRetentionState } from "./source-evidence-store.ts";
+
+const REF = /^[A-Za-z0-9][A-Za-z0-9._:@~-]{0,159}$/, DIGEST = /^sha256:[a-f0-9]{64}$/,
+  REVISION = /^[A-Za-z0-9][A-Za-z0-9._:~-]{0,159}$/, MAX_RECORDS = 2_000, MAX_BYTES = 32 * 1024;
+export const SOURCE_HANDOFF_EVIDENCE_VERSION = "piagent-webui-source-handoff-v1";
+
+export type SourceHandoffRecord = { schemaVersion: 1; version: typeof SOURCE_HANDOFF_EVIDENCE_VERSION; recordId: string; evidenceRef: string;
+  sequence: number; phase: "requested" | "settled" | "rejected" | "uncertain"; resultCode: "handoff-requested" | "opened" | "handoff-rejected" | "effect-unknown";
+  failureCode: string | null; projectRef: string; runtimeInstanceId: string; sessionRef: string; taskId: string; taskRunId: string;
+  commandId: string; idempotencyKeyDigest: string; actionDigest: string; fileRef: string; line: number | null; column: number | null;
+  taskRevision: string; workspaceRevision: string; contentDigest: string; requestedAt: string; recordedAt: string; retentionUntil: string; integrityDigest: string };
+type Append = Omit<SourceHandoffRecord, "schemaVersion" | "version" | "recordId" | "evidenceRef" | "sequence" | "retentionUntil" | "integrityDigest"> & { projectRoot: string };
+
+function sha(value: string): string { return createHash("sha256").update(value).digest("hex"); }
+function digest(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(root: string, run: string): string { return path.join(root, ".pi", "piagent-state", "source-evidence", `run-${sha(run)}`, "handoffs"); }
+function readPrivate(root: string, file: string): Buffer { const safe = resolveLocalStatePath(root, file, { label: "Source handoff 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_BYTES) throw new Error("source-handoff-record-invalid"); return fs.readFileSync(descriptor); } finally { fs.closeSync(descriptor); } }
+function publish(root: string, target: string, bytes: Buffer): void { const parent = ensurePrivateStateDirectory(root, path.dirname(target), "Source handoff evidence directory");
+  const safe = resolveLocalStatePath(root, target, { label: "Source handoff evidence" }), temporary = path.join(parent, `.${path.basename(target)}.${process.pid}.${randomBytes(8).toString("hex")}`);
+  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, safe); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST" || !readPrivate(root, safe).equals(bytes)) throw error; }
+  finally { fs.rmSync(temporary, { force: true }); } }
+
+export function validateSourceHandoffRecord(value: unknown): SourceHandoffRecord {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("source-handoff-record-invalid"); const record = value as SourceHandoffRecord;
+  const keys = ["schemaVersion", "version", "recordId", "evidenceRef", "sequence", "phase", "resultCode", "failureCode", "projectRef", "runtimeInstanceId",
+    "sessionRef", "taskId", "taskRunId", "commandId", "idempotencyKeyDigest", "actionDigest", "fileRef", "line", "column", "taskRevision",
+    "workspaceRevision", "contentDigest", "requestedAt", "recordedAt", "retentionUntil", "integrityDigest"];
+  if (canonicalReviewValue(Object.keys(record).sort()) !== canonicalReviewValue(keys.sort()) || record.schemaVersion !== 1 || record.version !== SOURCE_HANDOFF_EVIDENCE_VERSION
+    || ![record.recordId, record.evidenceRef, record.projectRef, record.runtimeInstanceId, record.sessionRef, record.taskId, record.taskRunId, record.commandId, record.fileRef].every((item) => REF.test(item))
+    || ![record.idempotencyKeyDigest, record.actionDigest, record.contentDigest, record.integrityDigest].every((item) => DIGEST.test(item))
+    || ![record.taskRevision, record.workspaceRevision].every((item) => REVISION.test(item)) || ![record.requestedAt, record.recordedAt, record.retentionUntil].every(timestamp)
+    || !Number.isInteger(record.sequence) || record.sequence < 1 || record.sequence > MAX_RECORDS || record.line !== null && (!Number.isInteger(record.line) || record.line < 1 || record.line > 100_000_000)
+    || record.column !== null && (!Number.isInteger(record.column) || record.column < 1 || record.column > 1_000_000) || record.column !== null && record.line === null
+    || !(record.failureCode === null || /^[a-z][a-z0-9.-]{0,95}$/.test(record.failureCode))) throw new Error("source-handoff-record-invalid");
+  const expected = { requested: "handoff-requested", settled: "opened", rejected: "handoff-rejected", uncertain: "effect-unknown" }[record.phase];
+  if (record.resultCode !== expected || ["requested", "settled"].includes(record.phase) !== (record.failureCode === null)) throw new Error("source-handoff-record-invalid");
+  const { integrityDigest, ...payload } = record; if (digest(payload) !== integrityDigest) throw new Error("source-handoff-record-invalid"); return structuredClone(record);
+}
+
+export function readSourceHandoffEvidence(root: string, run: string): { records: SourceHandoffRecord[]; corruptions: string[] } {
+  let files: string[]; const folder = directory(root, run); try { files = fs.readdirSync(resolveLocalStatePath(root, folder, { label: "Source handoff evidence", kind: "directory" })).filter((file) => file.endsWith(".json")).sort(); }
+  catch (error) { return (error as NodeJS.ErrnoException).code === "ENOENT" ? { records: [], corruptions: [] } : { records: [], corruptions: ["source-handoff-evidence-unavailable"] }; }
+  if (files.length > MAX_RECORDS) return { records: [], corruptions: ["source-handoff-record-limit"] }; const records: SourceHandoffRecord[] = [], corruptions: string[] = [];
+  for (const file of files) try { const record = validateSourceHandoffRecord(JSON.parse(readPrivate(root, path.join(folder, file)).toString("utf8")));
+    if (file !== `${record.recordId}.json` || record.taskRunId !== run) throw new Error("source-handoff-identity-invalid"); records.push(record); }
+  catch { corruptions.push(`handoff.${sha(file)}`); } return { records: corruptions.length ? [] : records.sort((a, b) => a.sequence - b.sequence), corruptions };
+}
+
+export function appendSourceHandoffEvidence(options: Append): SourceHandoffRecord {
+  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("source-handoff-baseline-unavailable");
+  const existing = readSourceHandoffEvidence(options.projectRoot, options.taskRunId); if (existing.corruptions.length || existing.records.length >= MAX_RECORDS) throw new Error("source-handoff-evidence-unavailable");
+  const identity = digest({ commandId: options.commandId, actionDigest: options.actionDigest, phase: options.phase }), recordId = `handoff.${identity.slice(7)}`;
+  const old = existing.records.find((record) => record.recordId === recordId); if (old) return old;
+  const payload = { schemaVersion: 1 as const, version: SOURCE_HANDOFF_EVIDENCE_VERSION, recordId, evidenceRef: `handoff-evidence.${identity.slice(7)}`,
+    sequence: (existing.records.at(-1)?.sequence ?? 0) + 1, retentionUntil: manifest.retentionUntil, ...Object.fromEntries(Object.entries(options).filter(([key]) => key !== "projectRoot")) } as Omit<SourceHandoffRecord, "integrityDigest">;
+  const record = validateSourceHandoffRecord({ ...payload, integrityDigest: digest(payload) }), bytes = Buffer.from(`${JSON.stringify(record)}\n`);
+  if (bytes.length > MAX_BYTES) throw new Error("source-handoff-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-inspection-plan.ts

@@ -0,0 +1,34 @@
+import type { GitStatusRecord, GitStatusSnapshot } from "./git-status-adapter.ts";
+
+type ProtectedPathCheck = (repoRoot: string, repoPath: string) => boolean;
+
+export type SourceInspectionPlan = {
+  objectIds: string[];
+  workingTreePaths: string[];
+  stagedPaths: string[];
+};
+
+function visible(record: GitStatusRecord): boolean {
+  const paths = [record.path.value, record.oldPath?.value].filter((value): value is string => Boolean(value));
+  return paths.length > 0 && !paths.some((repoPath) => repoPath === ".pi/piagent-state" || repoPath.startsWith(".pi/piagent-state/"));
+}
+
+export function sourceInspectionPlan(
+  snapshot: GitStatusSnapshot,
+  isProtectedPath?: ProtectedPathCheck
+): SourceInspectionPlan {
+  const safeRecords = snapshot.records.filter((record) => {
+    const repoPath = record.path.value;
+    const oldPath = record.oldPath?.value;
+    return visible(record)
+      && isProtectedPath?.(snapshot.repoRoot, repoPath as string) !== true
+      && (!oldPath || isProtectedPath?.(snapshot.repoRoot, oldPath) !== true);
+  });
+  const objectIds = [...new Set(safeRecords.flatMap((record) =>
+    [record.headObject, record.indexObject].filter((value): value is string => Boolean(value) && !/^0+$/.test(value))
+  ))];
+  const paths = [...new Set(safeRecords.flatMap((record) =>
+    [record.path.value, record.oldPath?.value].filter((value): value is string => Boolean(value))
+  ))];
+  return { objectIds, workingTreePaths: paths, stagedPaths: paths };
+}

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

@@ -0,0 +1,164 @@
+import { createHash } from "node:crypto";
+
+import { runReadOnlyGit } from "./git-status-adapter.ts";
+import { collectExactGitPatchAuthority, 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 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}$/;
+
+type CollectOptions = {
+  cwd: string;
+  identity: WebUiIdentity;
+  action: SourceMutationAction;
+  sourceView: SourceChangeDocument;
+  diff: DiffDocument;
+  taskRevision: string;
+  workspaceRevision: string;
+  indexRevision: string | null;
+  generatedAt?: string;
+  isProtectedPath?: SourceProjectionOptions["isProtectedPath"];
+  guardAvailable?: boolean;
+  timeoutMs?: number;
+  maxGitBytes?: number;
+};
+
+function sha(value: string | Buffer): string { return createHash("sha256").update(value).digest("hex"); }
+function digest(value: string | Buffer): string { return `sha256:${sha(value)}`; }
+function unavailable(options: CollectOptions, reasonCode: string): { projection: SourceMutationProjection; authority: null } {
+  const message = "The exact selected-file Git mutation preview is unavailable";
+  return { projection: { schemaVersion: 1, version: "piagent-webui-source-mutation-v1", generatedAt: options.generatedAt ?? new Date().toISOString(),
+    identity: structuredClone(options.identity), action: options.action, state: "unavailable", target: null, reasonCode,
+    health: { state: "unavailable", reasonCode, message } }, authority: null };
+}
+
+export function validateSourceMutationTarget(value: unknown): SourceMutationTarget {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("mutation-target-invalid");
+  const target = value as SourceMutationTarget, keys = ["view", "repoRef", "fileRef", "diffRef", "status", "path", "oldPath", "effect",
+    "taskRevision", "workspaceRevision", "indexRevision", "viewRevision", "fileRevision", "workspacePreimage", "indexPreimage", "patchPreimage", "contentDigest", "hunkRefs"];
+  if (JSON.stringify(Object.keys(target).sort()) !== JSON.stringify(keys.sort()) || !["working-tree", "staged"].includes(target.view)
+    || ![target.repoRef, target.fileRef, target.diffRef].every((item) => REF.test(item)) || !["A", "M", "D", "R", "U"].includes(target.status)
+    || !SAFE_PATH.test(target.path) || target.oldPath !== null && !SAFE_PATH.test(target.oldPath)
+    || ![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].every((item) => DIGEST.test(item))
+    || target.patchPreimage !== target.contentDigest || !Array.isArray(target.hunkRefs) || target.hunkRefs.length > 128
+    || new Set(target.hunkRefs).size !== target.hunkRefs.length || target.hunkRefs.some((item) => !REF.test(item))
+    || target.view === "working-tree" && target.effect !== "copy-worktree-to-index"
+    || target.view === "staged" && target.effect !== "restore-index-from-head") throw new Error("mutation-target-invalid");
+  return structuredClone(target);
+}
+
+export function collectSelectedWorkspacePreimage(repoRoot: string, repoPaths: string[]): string {
+  const entries = [...new Set(repoPaths)].sort().map((repoPath) => {
+    try {
+      const stat = inspectWorkspaceEntry(repoRoot, repoPath);
+      if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("unsupported-workspace-entry");
+      return [repoPath, `sha256:${hashWorkspaceFile(repoRoot, repoPath)}`];
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return [repoPath, null];
+      throw error;
+    }
+  });
+  const material = JSON.stringify({ schemaVersion: 1, entries });
+  return `wt-content-v2:${sha(`piagent-webui-selected-workspace\0${material}`)}`;
+}
+
+export async function collectIndexPreimage(repoRoot: string, timeoutMs?: number, maxGitBytes?: number): Promise<string> {
+  const index = await runReadOnlyGit(repoRoot, ["ls-files", "--stage", "-z"], { timeoutMs, maxBytes: maxGitBytes ?? 64 * 1024 * 1024 });
+  return digest(`piagent-webui-index-v1\0${index.toString("base64")}`);
+}
+
+export async function collectSourceMutationPreview(options: CollectOptions): Promise<{ projection: SourceMutationProjection; authority: SourceMutationAuthority | null }> {
+  const expectedView = options.action === "source.stage" ? "working-tree" : "staged";
+  if (options.guardAvailable !== true) return unavailable(options, "mutation-guard-unavailable");
+  if (options.sourceView.view !== expectedView || options.sourceView.availability.state !== "current" || !options.indexRevision
+    || !options.identity.taskId || !options.identity.taskRunId || !options.taskRevision || !options.workspaceRevision) return unavailable(options, "mutation-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.pathDisplay !== "exact-safe" || file.status === "C" || !["A", "M", "D", "R", "U"].includes(file.status)
+    || file.content?.kind !== "text" || file.content?.access !== "available") return unavailable(options, "mutation-target-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 !== expectedView || review.fileRef !== file.fileRef) return unavailable(options, "mutation-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 },
+  expectedView, file.fileRef, String(file.basisRef), [file.oldPath, file.path].filter((value): value is string => typeof value === "string"));
+  if (!selected || selected.file.fileRevision !== file.fileRevision || selected.file.pathDisplay !== "exact-safe") return unavailable(options, "mutation-target-stale");
+  if (options.action === "source.stage" && selected.record.kind !== "untracked" && [".", "!", "?"].includes(selected.record.worktreeStatus))
+    return unavailable(options, "no-unstaged-change");
+  if (options.action === "source.unstage" && [".", "!", "?"].includes(selected.record.indexStatus)) return unavailable(options, "no-staged-change");
+  const repoPaths = [selected.record.oldPath?.value, selected.record.path.value].filter((value): value is string => Boolean(value));
+  if (!repoPaths.length || repoPaths.some((repoPath) => options.isProtectedPath?.(selected.snapshot.repoRoot, repoPath) === true)) return unavailable(options, "protected-path");
+  const core = { view: expectedView, repoRef: String(file.repoRef), fileRef: String(file.fileRef), status: String(file.status), path: String(file.path),
+    oldPath: typeof file.oldPath === "string" ? file.oldPath : null, viewRevision: review.viewRevision, fileRevision: review.fileRevision,
+    baseDigest: review.baseDigest, currentDigest: review.currentDigest };
+  let workspacePreimage: string, indexPreimage: string, patchAuthority: ExactGitPatchAuthority | null = null;
+  try {
+    workspacePreimage = collectSelectedWorkspacePreimage(selected.snapshot.repoRoot, repoPaths);
+    indexPreimage = await collectIndexPreimage(selected.snapshot.repoRoot, options.timeoutMs, options.maxGitBytes);
+    const projectedHunkRefs = (options.diff.hunks as Array<Record<string, unknown>>).map((hunk) => String(hunk.hunkRef));
+    if (selected.record.kind === "ordinary" && !selected.record.oldPath && core.status === "M" && projectedHunkRefs.length > 0
+      && (options.diff as any).truncation?.truncated === false && (options.diff as any).redaction?.applied === false) {
+      const exact = await collectExactGitPatchAuthority({ snapshot: selected.snapshot, record: selected.record,
+        view: options.action === "source.stage" ? "unstaged" : "staged",
+        fileRef: core.fileRef, timeoutMs: options.timeoutMs, maxBytes: options.maxGitBytes });
+      if (exact && exact.hunks.every((hunk) => projectedHunkRefs.includes(hunk.hunkRef))) patchAuthority = exact;
+    }
+  } catch { return unavailable(options, "mutation-preimage-unavailable"); }
+  const target: SourceMutationTarget = { view: expectedView, repoRef: core.repoRef, fileRef: core.fileRef, diffRef: review.diffRef,
+    status: core.status as SourceMutationTarget["status"], path: core.path, oldPath: core.oldPath,
+    effect: options.action === "source.stage" ? "copy-worktree-to-index" : "restore-index-from-head", taskRevision: options.taskRevision,
+    workspaceRevision: options.workspaceRevision, indexRevision: options.indexRevision, viewRevision: review.viewRevision, fileRevision: review.fileRevision,
+    workspacePreimage, indexPreimage, patchPreimage: review.patchPreimage, contentDigest: review.contentDigest,
+    hunkRefs: patchAuthority?.hunks.map((hunk) => hunk.hunkRef) ?? [] };
+  validateSourceMutationTarget(target);
+  return { projection: { schemaVersion: 1, version: "piagent-webui-source-mutation-v1", generatedAt: options.generatedAt ?? new Date().toISOString(),
+    identity: structuredClone(options.identity), action: options.action, state: "ready", target, reasonCode: null,
+    health: { state: "ok", reasonCode: null, message: null } },
+  authority: { repoRoot: selected.snapshot.repoRoot, repoPaths, headOid: selected.snapshot.headOid,
+    indexStatus: selected.record.indexStatus, worktreeStatus: selected.record.worktreeStatus, target, patchAuthority } };
+}