@piagent/platform 1.6.0 → 1.7.1

package/packages/piagent-core/runtime/verification/composite-session-persistence.ts

@@ -0,0 +1,175 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+
+const MAX_SESSION_BYTES = 64 * 1024 * 1024;
+const MAX_SESSION_ENTRIES = 50_000;
+const ID = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
+const HASH = /^[a-f0-9]{64}$/;
+const CORRELATION_TYPE = "piagent-webui-message-correlation";
+export const COMPOSITE_DELIVERY_CONFIRMATION_TYPE = "piagent-composite-terminal-delivery-v1";
+const persistedCapabilities = new WeakMap<object, PersistedObservation>();
+const deliveryCapabilities = new WeakMap<object, DeliveryObservation>();
+const sha = (value: string | Buffer) => createHash("sha256").update(value).digest("hex");
+
+type PersistedObservation = { file: string; cwd: string; sessionId: string; entryId: string;
+  digest: string; byteLength: number; bytes: string; entry: any; fileDigest: string };
+type DeliveryObservation = PersistedObservation & { operationRef: string; messageRequestId: string;
+  idempotencyKey: string; confirmationEntryId: string; confirmationDigest: string; fileDigest: string };
+
+function assistantText(message: any): string {
+  if (typeof message?.content === "string") return message.content;
+  if (!Array.isArray(message?.content)) return "";
+  return message.content.filter((item: any) => item?.type === "text" && typeof item.text === "string")
+    .map((item: any) => item.text).join("\n");
+}
+
+function canonicalLine(line: Buffer): any {
+  if (!line.length) throw new Error("native-session-empty-record");
+  const text = new TextDecoder("utf-8", { fatal: true }).decode(line), value = JSON.parse(text);
+  if (!Buffer.from(JSON.stringify(value)).equals(line)) throw new Error("native-session-noncanonical-record");
+  return value;
+}
+
+function sessionSnapshot(file: string, cwd: string, sessionId: string) {
+  if (!path.isAbsolute(file) || path.normalize(file) !== file || fs.realpathSync.native(file) !== file)
+    throw new Error("native-session-path-invalid");
+  const descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+  try {
+    fs.fsyncSync(descriptor);
+    const before = fs.fstatSync(descriptor, { bigint: true });
+    if (!before.isFile() || before.nlink !== 1n || before.uid !== BigInt(process.getuid?.() ?? Number(before.uid))
+      || before.size < 1n || before.size > BigInt(MAX_SESSION_BYTES)) throw new Error("native-session-file-unsafe");
+    const source = fs.readFileSync(descriptor), after = fs.fstatSync(descriptor, { bigint: true });
+    const atPath = fs.lstatSync(file, { bigint: true });
+    const fields = ["dev", "ino", "mode", "nlink", "uid", "size", "mtimeNs", "ctimeNs"];
+    if (source.length !== Number(before.size) || source.at(-1) !== 10 || atPath.isSymbolicLink()
+      || fields.some(field => before[field] !== after[field] || after[field] !== atPath[field]))
+      throw new Error("native-session-file-changed");
+    const lines: Buffer[] = []; let start = 0;
+    for (let index = 0; index < source.length; index += 1) if (source[index] === 10) {
+      lines.push(source.subarray(start, index)); start = index + 1;
+    }
+    if (lines.length < 2 || lines.length > MAX_SESSION_ENTRIES + 1) throw new Error("native-session-entry-bound");
+    const [header, ...entries] = lines.map(canonicalLine);
+    const headerKeys = Object.keys(header ?? {});
+    if (header?.type !== "session" || header.version !== 3 || header.id !== sessionId
+      || header.cwd !== cwd || !Number.isFinite(Date.parse(header.timestamp))
+      || headerKeys.some(key => !["type", "version", "id", "timestamp", "cwd", "parentSession"].includes(key)))
+      throw new Error("native-session-header-invalid");
+    const ids = new Set<string>();
+    for (const entry of entries) {
+      if (!entry || typeof entry !== "object" || Array.isArray(entry) || !ID.test(entry.id)
+        || ids.has(entry.id) || !Number.isFinite(Date.parse(entry.timestamp))
+        || typeof entry.type !== "string" || entry.parentId !== null && !ids.has(entry.parentId))
+        throw new Error("native-session-chain-invalid");
+      ids.add(entry.id);
+    }
+    return { header, entries, all: [header, ...entries], fileDigest: sha(source) };
+  } finally { fs.closeSync(descriptor); }
+}
+
+function stableManager(manager: any, snapshot: ReturnType<typeof sessionSnapshot>): any[] {
+  if (!manager || manager.isPersisted?.() !== true || typeof manager.getEntries !== "function"
+    || typeof manager.getBranch !== "function" || typeof manager.getEntry !== "function")
+    throw new Error("native-session-manager-unavailable");
+  const first = manager.getEntries(), firstText = JSON.stringify(first);
+  if (firstText !== JSON.stringify(snapshot.entries) || firstText !== JSON.stringify(manager.getEntries()))
+    throw new Error("native-session-memory-disk-mismatch");
+  return first;
+}
+
+export function capturePersistedAssistantResponse(input: { cwd: string; sessionId: string; manager: any;
+  message: any; expectedText: string }): object {
+  if (!path.isAbsolute(input.cwd) || fs.realpathSync.native(input.cwd) !== input.cwd
+    || !ID.test(input.sessionId) || input.message?.role !== "assistant" || typeof input.expectedText !== "string"
+    || !(input.expectedText as any).isWellFormed() || Buffer.byteLength(input.expectedText) > 65_536
+    || assistantText(input.message) !== input.expectedText) throw new Error("native-response-input-invalid");
+  const file = input.manager?.getSessionFile?.();
+  if (typeof file !== "string") throw new Error("native-session-file-unavailable");
+  const snapshot = sessionSnapshot(file, input.cwd, input.sessionId), memory = stableManager(input.manager, snapshot);
+  const matches = memory.filter((entry: any) => entry?.type === "message" && entry.message === input.message);
+  if (matches.length !== 1) throw new Error("native-response-object-identity-mismatch");
+  const entry = matches[0], branch = input.manager.getBranch();
+  if (branch.filter((candidate: any) => candidate === entry).length !== 1 || branch.at(-1) !== entry
+    || input.manager.getLeafId?.() !== entry.id || input.manager.getEntry(entry.id) !== entry
+    || snapshot.entries.at(-1)?.id !== entry.id || !isDeepStrictEqual(snapshot.entries.at(-1), entry))
+    throw new Error("native-response-branch-identity-mismatch");
+  const observation: PersistedObservation = { file, cwd: input.cwd, sessionId: input.sessionId, entryId: entry.id,
+    digest: sha(input.expectedText), byteLength: Buffer.byteLength(input.expectedText), bytes: input.expectedText,
+    entry: structuredClone(entry), fileDigest: snapshot.fileDigest };
+  const capability = Object.freeze({ version: "native-persisted-response-capability-v1", entryId: entry.id,
+    digest: observation.digest, byteLength: observation.byteLength });
+  persistedCapabilities.set(capability, observation); return capability;
+}
+
+export function persistedAssistantResponseObservation(capability: object): Readonly<PersistedObservation> {
+  const value = persistedCapabilities.get(capability);
+  if (!value) throw new Error("untrusted-native-response-capability");
+  return Object.freeze({ ...value, entry: structuredClone(value.entry) });
+}
+
+function correlation(entry: any) {
+  const data = entry?.data;
+  return entry?.type === "custom" && entry.customType === CORRELATION_TYPE && data?.schemaVersion === 1
+    && ID.test(data.messageRequestId) && ID.test(data.operationRef)
+    ? { messageRequestId: data.messageRequestId, operationRef: data.operationRef } : null;
+}
+
+export function commitCompositeWebUiDelivery(input: { response: object; manager: any; taskRunId: string;
+  operationRef: string; messageRequestId: string; idempotencyKey: string }): object {
+  const response = persistedCapabilities.get(input.response);
+  if (!response || !ID.test(input.taskRunId) || !ID.test(input.operationRef) || !ID.test(input.messageRequestId)
+    || !HASH.test(input.idempotencyKey)) throw new Error("composite-delivery-input-invalid");
+  const before = sessionSnapshot(response.file, response.cwd, response.sessionId), memory = stableManager(input.manager, before);
+  const branch = input.manager.getBranch(), responseIndex = branch.findIndex((entry: any) => entry?.id === response.entryId);
+  const matching = branch.map((entry: any, index: number) => ({ entry, index, value: correlation(entry) }))
+    .filter(item => item.value?.operationRef === input.operationRef && item.value?.messageRequestId === input.messageRequestId);
+  const globalMatches = memory.filter((entry: any) => { const value = correlation(entry); return value?.operationRef === input.operationRef
+    && value?.messageRequestId === input.messageRequestId; });
+  if (responseIndex < 0 || matching.length !== 1 || globalMatches.length !== 1
+    || matching[0].index >= responseIndex || branch.slice(matching[0].index + 1, responseIndex)
+      .filter((entry: any) => entry?.type === "message" && entry.message?.role === "user").length !== 1)
+    throw new Error("composite-delivery-correlation-mismatch");
+  const data = { schemaVersion: 1, taskRunId: input.taskRunId, sessionId: response.sessionId,
+    responseEntryId: response.entryId, responseDigest: response.digest, responseByteLength: response.byteLength,
+    operationRef: input.operationRef, messageRequestId: input.messageRequestId, idempotencyKey: input.idempotencyKey };
+  const existing = branch.filter((entry: any) => entry?.type === "custom"
+    && entry.customType === COMPOSITE_DELIVERY_CONFIRMATION_TYPE && entry.data?.idempotencyKey === input.idempotencyKey);
+  if (existing.length === 1) {
+    const confirmation = existing[0], disk = before.entries.find((entry: any) => entry?.id === confirmation.id);
+    if (branch.at(-1) !== confirmation || !isDeepStrictEqual(confirmation.data, data)
+      || !isDeepStrictEqual(confirmation, disk)) throw new Error("composite-delivery-replay-mismatch");
+    const observation: DeliveryObservation = { ...response, operationRef: input.operationRef,
+      messageRequestId: input.messageRequestId, idempotencyKey: input.idempotencyKey,
+      confirmationEntryId: confirmation.id, confirmationDigest: sha(JSON.stringify(confirmation)), fileDigest: before.fileDigest };
+    const capability = Object.freeze({ version: "native-webui-delivery-capability-v1",
+      confirmationEntryId: confirmation.id, responseEntryId: response.entryId, idempotencyKey: input.idempotencyKey });
+    deliveryCapabilities.set(capability, observation); return capability;
+  }
+  if (existing.length || branch.at(-1)?.id !== response.entryId) throw new Error("composite-delivery-replay-mismatch");
+  if (typeof input.manager.appendCustomEntry !== "function") throw new Error("composite-delivery-append-unavailable");
+  const confirmationEntryId = input.manager.appendCustomEntry(COMPOSITE_DELIVERY_CONFIRMATION_TYPE, data);
+  if (!ID.test(confirmationEntryId)) throw new Error("composite-delivery-entry-invalid");
+  const after = sessionSnapshot(response.file, response.cwd, response.sessionId), current = stableManager(input.manager, after);
+  const confirmation = current.at(-1), disk = after.entries.at(-1);
+  if (input.manager.getLeafId?.() !== confirmationEntryId || confirmation?.id !== confirmationEntryId
+    || confirmation?.type !== "custom" || confirmation.customType !== COMPOSITE_DELIVERY_CONFIRMATION_TYPE
+    || !isDeepStrictEqual(confirmation.data, data) || !isDeepStrictEqual(confirmation, disk)
+    || after.entries.filter((entry: any) => entry?.customType === COMPOSITE_DELIVERY_CONFIRMATION_TYPE
+      && entry.data?.idempotencyKey === input.idempotencyKey).length !== 1)
+    throw new Error("composite-delivery-not-persisted");
+  const observation: DeliveryObservation = { ...response, operationRef: input.operationRef,
+    messageRequestId: input.messageRequestId, idempotencyKey: input.idempotencyKey,
+    confirmationEntryId, confirmationDigest: sha(JSON.stringify(confirmation)), fileDigest: after.fileDigest };
+  const capability = Object.freeze({ version: "native-webui-delivery-capability-v1", confirmationEntryId,
+    responseEntryId: response.entryId, idempotencyKey: input.idempotencyKey });
+  deliveryCapabilities.set(capability, observation); return capability;
+}
+
+export function webUiDeliveryObservation(capability: object): Readonly<DeliveryObservation> {
+  const value = deliveryCapabilities.get(capability);
+  if (!value) throw new Error("untrusted-native-delivery-capability");
+  return Object.freeze({ ...value, entry: structuredClone(value.entry) });
+}

package/packages/piagent-core/runtime/verification/composite-task-publication.ts

@@ -0,0 +1,273 @@
+import { createHash, createHmac, KeyObject, randomUUID, timingSafeEqual } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { types } from "node:util";
+
+import type { TaskContract } from "../../extensions/guard-types.ts";
+import { durableTaskContractMatches, normalizeTaskContract, taskContractValidationErrors } from "../../extensions/task-state.js";
+import { isCurrentWorkingTreeDigest } from "../../extensions/working-tree-digest.js";
+import { openCompositeAssuranceJournal } from "./runtime-assurance-facts.ts";
+
+export const COMPOSITE_TASK_PUBLICATION_VERSION = "composite-task-publication-v1";
+export const COMPOSITE_TERMINAL_TASK_TARGET_VERSION = "composite-terminal-task-target-v1";
+export const COMPOSITE_JOURNAL_PUBLICATION_VERSION = "composite-journal-publication-v1";
+const HASH = /^[a-f0-9]{64}$/;
+const ID = /^[A-Za-z0-9][A-Za-z0-9:._~-]{0,159}$/;
+const MAX_BYTES = 4 * 1024 * 1024;
+const sha = (value: string | Buffer) => createHash("sha256").update(value).digest("hex");
+
+function exact(value: any, fields: string[], label: string) {
+  if (!value || typeof value !== "object" || Array.isArray(value) || types.isProxy(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))
+    || Object.keys(value).length !== fields.length || fields.some(field => !Object.hasOwn(value, field))) {
+    throw new Error(`Invalid ${label}`);
+  }
+  return value;
+}
+
+function freeze<T>(value: T): T {
+  if (value && typeof value === "object" && !Object.isFrozen(value)) {
+    for (const child of Object.values(value as object)) freeze(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+function canonicalTask(value: any, outcome?: "pending" | "completed"): TaskContract {
+  const cloned = structuredClone(value), normalized = normalizeTaskContract(cloned);
+  if (!normalized || taskContractValidationErrors(normalized).length || outcome && normalized.trace.outcome !== outcome) {
+    throw new Error("Composite publication task contract is invalid");
+  }
+  return normalized as TaskContract;
+}
+
+/** updatedAt is storage metadata; every other normalized task byte is publication identity. */
+export function compositeTaskPublicationDigest(value: TaskContract): string {
+  const task = canonicalTask(value), { updatedAt: _updatedAt, ...identity } = task;
+  return sha(JSON.stringify(identity));
+}
+
+function privateDirectory(directory: string, projectRoot: string) {
+  const root = fs.realpathSync.native(projectRoot);
+  if (!path.isAbsolute(directory) || fs.realpathSync.native(directory) !== directory) throw new Error("Publication directory is not canonical");
+  const relative = path.relative(root, directory), stat = fs.lstatSync(directory);
+  if (!relative || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative))
+    || !stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== process.getuid() || (stat.mode & 0o077) !== 0) {
+    throw new Error("Publication directory is not private host state");
+  }
+  return root;
+}
+
+function key32(key: unknown): asserts key is KeyObject {
+  if (!(key instanceof KeyObject) || key.type !== "secret" || key.symmetricKeySize !== 32) throw new TypeError("Expected host 256-bit secret key");
+}
+
+function validateEntry(value: any, terminalTaskDigest: string) {
+  exact(value, ["version", "criterionId", "criterionHash", "contextDigest", "journalFile", "preAggregateHead", "aggregate"],
+    "composite journal publication");
+  exact(value.aggregate, ["idempotencyKey", "assessmentDigest", "taskPublicationDigest"], "composite aggregate publication");
+  if (value.version !== COMPOSITE_JOURNAL_PUBLICATION_VERSION || !ID.test(value.criterionId) || !HASH.test(value.criterionHash)
+    || !HASH.test(value.contextDigest) || !/^composite-[a-f0-9]{64}\.jsonl$/.test(value.journalFile)
+    || !HASH.test(value.preAggregateHead) || !HASH.test(value.aggregate.idempotencyKey)
+    || !HASH.test(value.aggregate.assessmentDigest) || value.aggregate.taskPublicationDigest !== terminalTaskDigest) {
+    throw new Error("Composite journal publication identity is invalid");
+  }
+  return value;
+}
+
+function validatePayload(value: any, projectRoot: string) {
+  exact(value, ["version", "projectId", "taskRunId", "sessionId", "operatorRequestDigest", "pendingTaskDigest",
+    "terminalTaskDigest", "workingTreeDigest", "terminalTask", "entries"], "composite task publication");
+  const task = canonicalTask(value.terminalTask, "completed");
+  if (value.version !== COMPOSITE_TASK_PUBLICATION_VERSION || value.projectId !== sha(fs.realpathSync.native(projectRoot))
+    || value.taskRunId !== task.taskRunId || value.sessionId !== task.sessionId
+    || value.operatorRequestDigest !== task.operatorRequestDigest || !ID.test(value.taskRunId) || !ID.test(value.sessionId)
+    || !/^operator-request-v1:[a-f0-9]{64}$/.test(value.operatorRequestDigest) || !HASH.test(value.pendingTaskDigest)
+    || value.terminalTaskDigest !== compositeTaskPublicationDigest(task) || !isCurrentWorkingTreeDigest(value.workingTreeDigest)
+    || !Array.isArray(value.entries) || value.entries.length < 1 || value.entries.length > 12) {
+    throw new Error("Composite task publication target is invalid");
+  }
+  const ids = new Set<string>();
+  for (const entry of value.entries) {
+    validateEntry(entry, value.terminalTaskDigest);
+    if (ids.has(entry.criterionId)) throw new Error("Duplicate composite publication criterion");
+    ids.add(entry.criterionId);
+  }
+  value.terminalTask = task;
+  return value;
+}
+
+type JournalStatus = "pre-aggregate" | "aggregate-settled" | "task-completed";
+
+export function openCompositeTaskPublicationStore({ key, directory, projectRoot }: {
+  key: KeyObject; directory: string; projectRoot: string }) {
+  key32(key); privateDirectory(directory, projectRoot);
+  const records = new WeakSet<object>();
+  const fileFor = (taskRunId: string, sessionId: string) => path.join(directory,
+    `composite-publication-${sha(`${taskRunId}\0${sessionId}`)}.json`);
+  const signature = (file: string, text: string) => createHmac("sha256", key)
+    .update(`${COMPOSITE_TASK_PUBLICATION_VERSION}\0${file}\0${text}`).digest("hex");
+
+  function readFile(file: string) {
+    if (!fs.existsSync(file)) return null;
+    const atPath = fs.lstatSync(file, { bigint: true });
+    if (!atPath.isFile() || atPath.isSymbolicLink() || atPath.nlink !== 1n || atPath.uid !== BigInt(process.getuid())
+      || (atPath.mode & 0o077n) !== 0n || atPath.size < 1n || atPath.size > BigInt(MAX_BYTES)) {
+      throw new Error("Composite publication file is unsafe");
+    }
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    try {
+      const before = fs.fstatSync(fd, { bigint: true }), bytes = fs.readFileSync(fd), after = fs.fstatSync(fd, { bigint: true });
+      const fields = ["dev", "ino", "mode", "nlink", "uid", "size", "mtimeNs", "ctimeNs"];
+      if (bytes.length !== Number(before.size) || fields.some(field => before[field] !== after[field] || after[field] !== atPath[field])) {
+        throw new Error("Composite publication changed during read");
+      }
+      const envelope = exact(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)),
+        ["payload", "signature"], "composite publication envelope");
+      if (!Buffer.from(JSON.stringify(envelope)).equals(bytes) || !HASH.test(envelope.signature)) throw new Error("Composite publication is noncanonical");
+      const text = JSON.stringify(envelope.payload), expected = signature(file, text);
+      if (!timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(envelope.signature, "hex"))) {
+        throw new Error("Composite publication signature is invalid");
+      }
+      const record = freeze(validatePayload(envelope.payload, projectRoot)); records.add(record); return record;
+    } finally { fs.closeSync(fd); }
+  }
+
+  function read(taskRunId: string, sessionId: string) {
+    if (!ID.test(taskRunId) || !ID.test(sessionId)) throw new TypeError("Invalid composite publication task identity");
+    return readFile(fileFor(taskRunId, sessionId));
+  }
+
+  function trusted(record: any) {
+    if (!record || !records.has(record)) throw new Error("Untrusted composite task publication");
+    const current = readFile(fileFor(record.taskRunId, record.sessionId));
+    if (!current || JSON.stringify(current) !== JSON.stringify(record)) throw new Error("Composite task publication changed");
+    return current;
+  }
+
+  function journalStatus(entry: any): JournalStatus {
+    const filePath = path.join(directory, entry.journalFile);
+    const journal = openCompositeAssuranceJournal({ filePath, projectRoot, key, contextDigest: entry.contextDigest });
+    try {
+      const head = journal.head(), events = journal.events();
+      if (head === entry.preAggregateHead) return "pre-aggregate";
+      const first = events.findIndex((event: any) => event.previous === entry.preAggregateHead);
+      if (first < 0) throw new Error("Composite publication journal does not extend its prepared head");
+      const tail = events.slice(first);
+      if (tail.length < 1 || tail.length > 2 || tail[0].kind !== "aggregate-settled"
+        || JSON.stringify(tail[0].data) !== JSON.stringify(entry.aggregate)) {
+        throw new Error("Composite publication aggregate journal mismatch");
+      }
+      if (tail.length === 1) return "aggregate-settled";
+      if (tail[1].kind !== "task-completed" || JSON.stringify(tail[1].data) !== JSON.stringify(entry.aggregate)) {
+        throw new Error("Composite publication completion journal mismatch");
+      }
+      return "task-completed";
+    } finally { journal.close(); }
+  }
+
+  function appendCompletion(entry: any) {
+    const filePath = path.join(directory, entry.journalFile);
+    const journal = openCompositeAssuranceJournal({ filePath, projectRoot, key, contextDigest: entry.contextDigest });
+    try { journal.append("task-completed", entry.aggregate); } finally { journal.close(); }
+  }
+
+  function appendAggregate(entry: any) {
+    const filePath = path.join(directory, entry.journalFile);
+    const journal = openCompositeAssuranceJournal({ filePath, projectRoot, key, contextDigest: entry.contextDigest });
+    try {
+      if (journal.head() !== entry.preAggregateHead) throw new Error("Composite aggregate recovery head changed");
+      journal.append("aggregate-settled", entry.aggregate);
+    } finally { journal.close(); }
+  }
+
+  function inspect(record: any) {
+    const current = trusted(record);
+    const statuses = current.entries.map((entry: any) => ({ criterionId: entry.criterionId, status: journalStatus(entry) }));
+    return freeze({ statuses, allSettled: statuses.every(item => item.status !== "pre-aggregate"),
+      allCompleted: statuses.every(item => item.status === "task-completed") });
+  }
+
+  function prepare({ pendingTask, terminalTask, workingTreeDigest, entries }: any) {
+    const pending = canonicalTask(pendingTask, "pending"), terminal = canonicalTask(terminalTask, "completed");
+    if (pending.taskRunId !== terminal.taskRunId || pending.sessionId !== terminal.sessionId
+      || pending.operatorRequestDigest !== terminal.operatorRequestDigest || !isCurrentWorkingTreeDigest(workingTreeDigest)) {
+      throw new Error("Composite publication pending and terminal tasks do not match");
+    }
+    const payload = validatePayload({ version: COMPOSITE_TASK_PUBLICATION_VERSION,
+      projectId: sha(fs.realpathSync.native(projectRoot)), taskRunId: terminal.taskRunId, sessionId: terminal.sessionId,
+      operatorRequestDigest: terminal.operatorRequestDigest, pendingTaskDigest: compositeTaskPublicationDigest(pending),
+      terminalTaskDigest: compositeTaskPublicationDigest(terminal), workingTreeDigest, terminalTask: terminal,
+      entries: structuredClone(entries) }, projectRoot);
+    const file = fileFor(payload.taskRunId, payload.sessionId), text = JSON.stringify(payload);
+    const envelope = Buffer.from(JSON.stringify({ payload, signature: signature(file, text) }));
+    if (envelope.length > MAX_BYTES) throw new Error("Composite publication exceeds byte bound");
+    const existing = readFile(file);
+    if (existing) {
+      if (JSON.stringify(existing) !== JSON.stringify(payload)) throw new Error("Different composite publication already exists");
+      return existing;
+    }
+    for (const entry of payload.entries) if (journalStatus(entry) !== "pre-aggregate") {
+      throw new Error("Aggregate exists without its durable task publication intent");
+    }
+    const temporary = path.join(directory, `.${path.basename(file)}.${process.pid}.${randomUUID()}.tmp`);
+    const fd = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL
+      | fs.constants.O_NOFOLLOW, 0o600);
+    try {
+      try {
+        for (let offset = 0; offset < envelope.length;) {
+          const written = fs.writeSync(fd, envelope, offset, envelope.length - offset);
+          if (written < 1) throw new Error("Composite publication write was incomplete");
+          offset += written;
+        }
+        fs.fsyncSync(fd);
+      } finally { fs.closeSync(fd); }
+      fs.renameSync(temporary, file); fs.chmodSync(file, 0o600);
+      const parent = fs.openSync(directory, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+      try { fs.fsyncSync(parent); } finally { fs.closeSync(parent); }
+    } catch (error) { try { fs.unlinkSync(temporary); } catch {} throw error; }
+    const observed = readFile(file);
+    if (!observed || JSON.stringify(observed) !== JSON.stringify(payload)) throw new Error("Composite publication readback failed");
+    return observed;
+  }
+
+  function settle(record: any) {
+    const current = trusted(record);
+    for (const entry of current.entries) if (journalStatus(entry) === "pre-aggregate") appendAggregate(entry);
+    const result = inspect(current);
+    if (!result.allSettled) throw new Error("Composite aggregate settlement recovery is incomplete");
+    return result;
+  }
+
+  function complete(record: any) {
+    const current = trusted(record);
+    const before = inspect(current);
+    if (!before.allSettled) throw new Error("Composite task cannot complete before every aggregate");
+    for (const entry of current.entries) if (journalStatus(entry) === "aggregate-settled") appendCompletion(entry);
+    const result = inspect(current);
+    if (!result.allCompleted) throw new Error("Composite task completion recovery is incomplete");
+    return result;
+  }
+
+  return Object.freeze({ version: COMPOSITE_TASK_PUBLICATION_VERSION, read, prepare, inspect, settle, complete });
+}
+
+export function recoverCompositeTaskPublication({ store, record, task, currentWorkingTreeDigest,
+  expectedCriteria, cwd, writeTask }: any): TaskContract {
+  if (!store || store.version !== COMPOSITE_TASK_PUBLICATION_VERSION || !Array.isArray(expectedCriteria)
+    || typeof writeTask !== "function" || record.operatorRequestDigest !== task.operatorRequestDigest
+    || record.workingTreeDigest !== currentWorkingTreeDigest) throw new Error("Composite publication recovery binding changed");
+  const expected = expectedCriteria.map((item: any) => `${item.criterionId}\0${item.criterionHash}`).sort();
+  const actual = record.entries.map((item: any) => `${item.criterionId}\0${item.criterionHash}`).sort();
+  if (JSON.stringify(expected) !== JSON.stringify(actual)) throw new Error("Composite publication criteria changed");
+  let completed = canonicalTask(task);
+  if (completed.trace.outcome === "pending") {
+    if (compositeTaskPublicationDigest(completed) !== record.pendingTaskDigest) throw new Error("Composite pending task changed before recovery");
+  } else if (completed.trace.outcome !== "completed" || compositeTaskPublicationDigest(completed) !== record.terminalTaskDigest) {
+    throw new Error("Composite terminal task does not match its publication");
+  }
+  store.settle(record);
+  if (completed.trace.outcome === "pending") completed = writeTask(cwd, record.terminalTask);
+  if (!durableTaskContractMatches(cwd, completed)) throw new Error("Recovered terminal task is not durable");
+  store.complete(record); return completed;
+}

package/packages/piagent-core/runtime/verification/exact-verifier-reuse.ts

@@ -0,0 +1,101 @@
+import crypto from "node:crypto";
+
+import type { TaskContract } from "../../extensions/guard-types.ts";
+import { extractShellCommandInput, normalizeShellCommandForPolicy } from "../../extensions/guard-shell-analysis.ts";
+import { commandMatchesVerifyPlan } from "../../extensions/runtime-evidence.js";
+import { passingVerifyCommandsForDigest } from "../../extensions/task-contract-view.js";
+import { captureWorkspaceVerificationSnapshot } from "../../extensions/workspace-verification-snapshot.js";
+
+const SHELL_TOOLS = new Set(["bash", "shell", "exec"]);
+const REUSE_COMMAND = "printf '%s\\n' 'Piagent reused exact verifier evidence for the unchanged working tree; the verifier was not rerun.'";
+
+export type ExactVerifierReuseDecision = {
+  reused: boolean;
+  reasonCode: string;
+  commandDigest: string | null;
+  workingTreeDigest: string | null;
+};
+
+function messageText(message: unknown): string {
+  if (!message || typeof message !== "object") return "";
+  const content = (message as Record<string, any>).content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content.filter((block) => block?.type === "text").map((block) => String(block.text ?? "")).join("\n");
+}
+
+function latestOperatorText(entries: unknown[]): string {
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const entry = entries[index] as Record<string, any> | undefined;
+    if (entry?.type === "message" && entry.message?.role === "user") return messageText(entry.message);
+  }
+  return "";
+}
+
+export function operatorExplicitlyRequestedVerifierExecution(entries: unknown[]): boolean {
+  const value = latestOperatorText(entries).normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase();
+  return /\b(rerun|run again|test again|verify again|one more run|final run|last run)\b/.test(value)
+    || /\b(run|execute)\b[^\n]{0,80}\b(test|tests|verify|verifier|lint|typecheck|build)\b/.test(value)
+    || /\b(chay lai|test lai|verify lai|kiem tra lai|kiem thu lai|lan cuoi|chay (?:mot|1) lan nua)\b/.test(value)
+    || /\b(chay|thuc hien)\b[^\n]{0,80}\b(test|kiem thu|verify|verifier|lint|typecheck|build)\b/.test(value);
+}
+
+export function evaluateExactVerifierReuse(input: {
+  task?: TaskContract;
+  toolName: string;
+  toolInput: Record<string, unknown>;
+  workingTreeDigest: string | null;
+  workspaceRevisionDigest?: string | null;
+  sessionEntries?: unknown[];
+}): ExactVerifierReuseDecision {
+  const no = (reasonCode: string): ExactVerifierReuseDecision => ({ reused: false, reasonCode, commandDigest: null, workingTreeDigest: input.workingTreeDigest });
+  const task = input.task;
+  if (!task || task.trace.outcome !== "pending" || task.changeMode !== "source-change") return no("no-pending-source-task");
+  if (!SHELL_TOOLS.has(input.toolName)) return no("not-shell-tool");
+  if (operatorExplicitlyRequestedVerifierExecution(input.sessionEntries ?? [])) return no("operator-requested-execution");
+  if (Object.hasOwn(input.toolInput, "args") && Array.isArray(input.toolInput.args) && input.toolInput.args.length > 0) return no("shell-args-present");
+  const extracted = extractShellCommandInput(input.toolInput);
+  if (!extracted.command || extracted.reason) return no("shell-command-unavailable");
+  const command = normalizeShellCommandForPolicy(extracted.command);
+  if (!commandMatchesVerifyPlan(command, task.verifyCommands)) return no("not-exact-verifier");
+  const passing = passingVerifyCommandsForDigest(task, input.workingTreeDigest, input.workspaceRevisionDigest);
+  const exactVerifier = task.verifyCommands.find((candidate) => (
+    passing.has(candidate.trim())
+    && commandMatchesVerifyPlan(command, [candidate])
+  ));
+  if (!exactVerifier) return no("current-tree-pass-missing");
+  const field = typeof input.toolInput.command === "string" ? "command" : typeof input.toolInput.cmd === "string" ? "cmd" : null;
+  if (!field) return no("mutable-command-field-missing");
+  input.toolInput[field] = REUSE_COMMAND;
+  return {
+    reused: true,
+    reasonCode: "current-tree-exact-verifier-reused",
+    commandDigest: crypto.createHash("sha256").update(exactVerifier.trim()).digest("hex"),
+    workingTreeDigest: input.workingTreeDigest
+  };
+}
+
+export function reuseCurrentTreeExactVerifier(input: {
+  cwd: string;
+  task?: TaskContract;
+  toolName: string;
+  toolInput: Record<string, unknown>;
+  sessionEntries?: unknown[];
+  getHostProjectVerificationDigest?: (snapshot: ReturnType<typeof captureWorkspaceVerificationSnapshot>, exactCommand: string) => string | null;
+}): ExactVerifierReuseDecision {
+  if (!input.task || !SHELL_TOOLS.has(input.toolName)) {
+    return { reused: false, reasonCode: "not-applicable", commandDigest: null, workingTreeDigest: null };
+  }
+  const extracted = extractShellCommandInput(input.toolInput);
+  const command = extracted.command ? normalizeShellCommandForPolicy(extracted.command) : "";
+  if (!command || !commandMatchesVerifyPlan(command, input.task.verifyCommands)) {
+    return { reused: false, reasonCode: "not-exact-verifier", commandDigest: null, workingTreeDigest: null };
+  }
+  const snapshot = captureWorkspaceVerificationSnapshot(input.cwd);
+  const observedDigest = input.getHostProjectVerificationDigest?.(snapshot, command);
+  if (typeof observedDigest !== "string" || !/^[a-f0-9]{64}$/.test(observedDigest)) {
+    return { reused: false, reasonCode: "host-project-verifier-observation-missing", commandDigest: null, workingTreeDigest: snapshot.digest };
+  }
+  return evaluateExactVerifierReuse({ ...input, workingTreeDigest: snapshot.proofCapable ? snapshot.digest : null,
+    workspaceRevisionDigest: snapshot.workspaceRevisionDigest });
+}

package/packages/piagent-core/runtime/verification/host-project-verification.ts

@@ -0,0 +1,71 @@
+import { createHash } from "node:crypto";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { TaskContract } from "../../extensions/guard-types.ts";
+import { toolResultFingerprint } from "../../extensions/context-engine.js";
+import { claimedExitMatchesObserved, hashEvidenceCommand, observedBashResultFromToolResultEvent } from "../../extensions/runtime-evidence.js";
+import { meaningfulVerificationCommands } from "../../extensions/verification-intelligence.js";
+import { captureWorkspaceVerificationSnapshot } from "../../extensions/workspace-verification-snapshot.js";
+import type { ShellVerificationSnapshots } from "./shell-verification-snapshots.ts";
+
+export const HOST_PROJECT_VERIFICATION_VERSION = "host-project-verification-v1";
+type Snapshot = ReturnType<typeof captureWorkspaceVerificationSnapshot>;
+type ToolEvent = { toolCallId?: string; toolName: string; input?: unknown; details?: unknown; isError?: boolean };
+const hash = (value: unknown): string => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+
+function taskBinding(task: TaskContract): string {
+  return hash([task.taskId, task.taskRunId, task.sessionId, task.operatorRequestDigest ?? null,
+    task.verifyCommands, task.acceptanceReceipt?.promptHash ?? null,
+    task.acceptanceReceipt?.criteria.map(({ id, hash: criterionHash }) => [id, criterionHash]) ?? []]);
+}
+
+/** Host-only live observations, never reconstructed from task JSON or stdout. */
+export class HostProjectVerification {
+  readonly #invocations: ShellVerificationSnapshots;
+  readonly #latest = new Map<string, { taskBinding: string; digest: string; revision: string } | null>();
+  constructor(invocations: ShellVerificationSnapshots) { this.#invocations = invocations; }
+  #prefix(ctx: ExtensionContext): string { return `${ctx.cwd}\0${ctx.sessionManager.getSessionId()}\0`; }
+  #key(ctx: ExtensionContext, task: TaskContract, commandHash: string): string { return `${this.#prefix(ctx)}${task.taskRunId}\0${commandHash}`; }
+
+  observe(ctx: ExtensionContext, task: TaskContract | undefined, event: ToolEvent, before: Snapshot | undefined, after: Snapshot | undefined): void {
+    if (!task || !["pending", "completed"].includes(task.trace.outcome) || task.sessionId !== ctx.sessionManager.getSessionId()) return;
+    const observed = observedBashResultFromToolResultEvent(event, ctx.cwd);
+    if (!observed?.commandHash || !meaningfulVerificationCommands(task.verifyCommands).some((command) => hashEvidenceCommand(command) === observed.commandHash)) return;
+    const callId = event.toolCallId ?? toolResultFingerprint(event.toolName, event.input, []).key;
+    const issued = this.#invocations.claimObservation(ctx, event.toolName, event.input, callId, task.taskRunId, before);
+    const key = this.#key(ctx, task, observed.commandHash);
+    // Every new result replaces the previous result, including unavailable,
+    // unmatched, contradictory, or failed observations. No timestamp selection.
+    this.#latest.set(key, task.trace.outcome === "pending" && issued && before?.proofCapable && after?.proofCapable
+      && before.digest === after.digest && before.workspaceRevisionDigest === after.workspaceRevisionDigest
+      && claimedExitMatchesObserved(0, { ...observed, isError: event.isError }) && event.isError !== true
+      ? { taskBinding: taskBinding(task), digest: after.digest, revision: after.workspaceRevisionDigest! } : null);
+    while (this.#latest.size > 500) this.#latest.delete(this.#latest.keys().next().value as string);
+  }
+
+  currentDigest(ctx: ExtensionContext, task: TaskContract, current: Snapshot, exactCommand?: string, { completedProjection = false } = {}): string | null {
+    // A completed task may display an existing live observation, but cannot
+    // create one or reserve a new independent execution. New tool results
+    // invalidate it even after completion; JSON alone never restores it.
+    if ((task.trace.outcome !== "pending" && !(completedProjection && task.trace.outcome === "completed"))
+      || task.sessionId !== ctx.sessionManager.getSessionId() || !current.proofCapable) return null;
+    if (this.#invocations.hasPending(ctx, task.taskRunId)) return null;
+    const commands = meaningfulVerificationCommands(task.verifyCommands);
+    if (commands.length === 0 || commands.length !== task.verifyCommands.length) return null;
+    const selected = exactCommand === undefined ? commands : commands.filter((command) => hashEvidenceCommand(command) === hashEvidenceCommand(exactCommand));
+    if (selected.length === 0) return null;
+    const binding = taskBinding(task), commandHashes = selected.map(hashEvidenceCommand);
+    if (commandHashes.some((command) => !command)) return null;
+    for (const command of commandHashes) {
+      const entry = this.#latest.get(this.#key(ctx, task, command));
+      if (!entry || entry.taskBinding !== binding || entry.digest !== current.digest || entry.revision !== current.workspaceRevisionDigest) return null;
+    }
+    // Equivalent newly observed passing checks can reuse the same independent
+    // evidence. Availability comes from live state, not from this public hash.
+    return hash([HOST_PROJECT_VERIFICATION_VERSION, ctx.cwd, binding, current.digest, current.workspaceRevisionDigest, commandHashes]);
+  }
+
+  clear(ctx: ExtensionContext): void {
+    const prefix = this.#prefix(ctx);
+    for (const key of this.#latest.keys()) if (key.startsWith(prefix)) this.#latest.delete(key);
+  }
+}