@piagent/platform 1.37.0 → 1.38.1

package/packages/piagent-webui/server/source-revert-controller.ts

@@ -0,0 +1,225 @@
+import { createHash } from "node:crypto";
+
+import type { SourceMutationAppendOptions, SourceMutationEvidenceRecord } from "../../piagent-core/runtime/inspection/source-action-contract.ts";
+import { canonicalReviewValue, reviewDigest } from "../../piagent-core/runtime/inspection/review-state-contract.ts";
+import type { SourceRevertAuthority, SourceRevertProjection, SourceRevertTarget } from "../../piagent-core/runtime/inspection/source-action-contract.ts";
+import type { SourceIndexTransactionResult } from "../../piagent-core/runtime/inspection/source-action-contract.ts";
+import { controlActionDigest } from "./control-command-digest.ts";
+import type { BridgeIdentity, BridgeRevisions, BridgeSnapshot } from "../../piagent-core/runtime/inspection/session-identity.ts";
+type RevertSessionBinding = { snapshot(): BridgeSnapshot };
+
+const REF = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/, PUBLIC_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}$/, IDEMPOTENCY = /^[A-Za-z0-9._~-]{32,128}$/;
+const REVISION_KEYS = ["runtimeRevision", "taskRevision", "controlRevision", "workspaceRevision", "indexRevision", "approvalRevision", "sessionOptionRevision", "queueRevision"];
+type RevertCommand = { schemaVersion: 1; version: "piagent-webui-control-v1"; messageType: "command"; commandId: string; idempotencyKey: string;
+  requestedAt: string; expiresAt: string; capabilityScope: "reviewActions"; action: "source.revert"; actionDigest: string; identity: BridgeIdentity;
+  expectedRevisions: BridgeRevisions & { workspacePreimage: string; indexPreimage: string; patchPreimage: string };
+  payload: { fileRef: string; hunkRefs: string[]; previewRef: string; confirmedPreviewDigest: string; contentDigest: string } };
+type RevertMutate<Authority> = (input: { identity: { projectRef: string; runtimeInstanceId: string; sessionRef: string; taskId: string | null; taskRunId: string | null };
+  action: "source.revert"; expectedTaskRevision: string | null; expectedControlRevision: string; expectedIndexPreimage: string;
+  expectedWorkspacePreimage: string; previewRef: string; confirmedPreviewDigest: string;
+  authority: Authority }) => Promise<SourceIndexTransactionResult>;
+export type SourceRevertReceipt = { schemaVersion: 1; version: "piagent-webui-control-v1"; messageType: "receipt"; commandId: string;
+  idempotencyKeyDigest: string; action: "source.revert"; actionDigest: string; identity: BridgeIdentity; phase: "settled" | "rejected" | "uncertain";
+  resultCode: "reverted" | "effect-unknown" | "stale-revision" | "identity-mismatch" | "capability-unavailable" | "idempotency-payload-mismatch"
+    | "expired" | "invalid-command" | "resync-required" | "terminal-task"; requestedAt: string; settledAt: string;
+  observedRevisionsBefore: BridgeRevisions; observedRevisionsAfter: BridgeRevisions; deduplicated: boolean; auditRef: string | null;
+  settlementEvidenceRef: string | null; error: { code: string; message: string; retryable: boolean } | null };
+
+function sha(value: string): string { return `sha256:${createHash("sha256").update(value).digest("hex")}`; }
+function same(left: unknown, right: unknown): boolean { return canonicalReviewValue(left) === canonicalReviewValue(right); }
+function exactKeys(value: unknown, keys: string[]): boolean { return Boolean(value && typeof value === "object" && !Array.isArray(value)
+  && same(Object.keys(value as object).sort(), [...keys].sort())); }
+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 wireIdentity(value: BridgeIdentity): BridgeIdentity { return { projectRef: value.projectRef, runtimeInstanceId: value.runtimeInstanceId,
+  sessionRef: value.sessionRef, taskId: value.taskId, taskRunId: value.taskRunId, agentOperationId: null, toolCallId: null }; }
+function wireRevisions(value: Record<string, any>): BridgeRevisions { return { runtimeRevision: value.runtimeRevision, taskRevision: value.taskRevision,
+  controlRevision: value.controlRevision, workspaceRevision: value.workspaceRevision, indexRevision: value.indexRevision,
+  approvalRevision: value.approvalRevision, sessionOptionRevision: value.sessionOptionRevision, queueRevision: value.queueRevision }; }
+function replayIdentityDisposition(record: Pick<SourceRevertEvidenceRecord, "projectRef" | "runtimeInstanceId" | "sessionRef" | "taskId" | "taskRunId">,
+  identity: BridgeIdentity): "task-identity-mismatch" | "runtime-or-session-replaced" | null {
+  if (record.taskId !== identity.taskId || record.taskRunId !== identity.taskRunId) return "task-identity-mismatch";
+  if (record.projectRef !== identity.projectRef || record.runtimeInstanceId !== identity.runtimeInstanceId || record.sessionRef !== identity.sessionRef)
+    return "runtime-or-session-replaced";
+  return null;
+}
+function receipt(record: SourceRevertEvidenceRecord, deduplicated: boolean): SourceRevertReceipt {
+  const identity = { projectRef: record.projectRef, runtimeInstanceId: record.runtimeInstanceId, sessionRef: record.sessionRef,
+    taskId: record.taskId, taskRunId: record.taskRunId, agentOperationId: null, toolCallId: null } as BridgeIdentity;
+  const before = wireRevisions(record.observedRevisionsBefore), after = wireRevisions(record.observedRevisionsAfter ?? record.observedRevisionsBefore);
+  if (record.phase === "settled") return { schemaVersion: 1, version: "piagent-webui-control-v1", messageType: "receipt", commandId: record.commandId,
+    idempotencyKeyDigest: record.idempotencyKeyDigest, action: "source.revert", actionDigest: record.actionDigest, identity, phase: "settled", resultCode: "reverted",
+    requestedAt: record.requestedAt, settledAt: record.recordedAt, observedRevisionsBefore: before, observedRevisionsAfter: after, deduplicated,
+    auditRef: record.evidenceRef, settlementEvidenceRef: record.evidenceRef, error: null };
+  if (record.phase === "rejected") {
+    const stale = ["mutation-preimage-stale", "mutation-guard-precondition-stale"].includes(record.failureCode ?? "");
+    return { schemaVersion: 1, version: "piagent-webui-control-v1", messageType: "receipt", commandId: record.commandId,
+      idempotencyKeyDigest: record.idempotencyKeyDigest, action: "source.revert", actionDigest: record.actionDigest, identity, phase: "rejected",
+      resultCode: stale ? "stale-revision" : "capability-unavailable", requestedAt: record.requestedAt, settledAt: record.recordedAt,
+      observedRevisionsBefore: before, observedRevisionsAfter: after, deduplicated, auditRef: record.evidenceRef, settlementEvidenceRef: null,
+      error: { code: record.failureCode ?? "source-revert-rejected", message: "The Pi guard rejected the confirmed source revert before commit.", retryable: true } };
+  }
+  return { schemaVersion: 1, version: "piagent-webui-control-v1", messageType: "receipt", commandId: record.commandId,
+    idempotencyKeyDigest: record.idempotencyKeyDigest, action: "source.revert", actionDigest: record.actionDigest, identity, phase: "uncertain",
+    resultCode: "effect-unknown", requestedAt: record.requestedAt, settledAt: record.recordedAt, observedRevisionsBefore: before,
+    observedRevisionsAfter: after, deduplicated, auditRef: record.phase === "uncertain" ? record.evidenceRef : null,
+    settlementEvidenceRef: null, error: { code: "source-revert-effect-unknown", message: "The worktree effect could not be confirmed. Inspect the source tabs.", retryable: false } };
+}
+
+export type SourceRevertEvidenceRecord = Omit<SourceMutationEvidenceRecord, "taskId" | "taskRunId"> & { taskId: string | null; taskRunId: string | null };
+export type SourceRevertEvidenceAppend = Omit<SourceMutationAppendOptions, "taskId" | "taskRunId"> & { taskId: string | null; taskRunId: string | null };
+export type SourceRevertEvidenceStore = {
+  read(projectRoot: string, taskRunId: string | null, sessionRef: string): { records: SourceRevertEvidenceRecord[]; corruptions: string[] };
+  append(options: SourceRevertEvidenceAppend): SourceRevertEvidenceRecord;
+};
+
+export class SourceRevertController<Authority = SourceRevertAuthority> {
+  readonly #evidence: SourceRevertEvidenceStore; readonly #allowSessionReverts: boolean;
+  readonly #bridge: RevertSessionBinding; readonly #projectRoot: string;
+  readonly #resolve: (fileRef: string, hunkRefs: string[]) => Promise<{ projection: SourceRevertProjection; authority: Authority | null }>;
+  readonly #revisions: () => Promise<Record<string, string | null>>;
+  readonly #mutate: RevertMutate<Authority>;
+  readonly #now: () => Date; #serial: Promise<unknown> = Promise.resolve();
+  constructor(options: { allowSessionReverts?: boolean; evidence: SourceRevertEvidenceStore; bridge: RevertSessionBinding; projectRoot: string;
+    resolve(fileRef: string, hunkRefs: string[]): Promise<{ projection: SourceRevertProjection; authority: Authority | null }>;
+    revisions(): Promise<Record<string, string | null>>; mutate: RevertMutate<Authority>; now?: () => Date }) {
+    this.#allowSessionReverts = options.allowSessionReverts === true; this.#evidence = options.evidence; this.#bridge = options.bridge; this.#projectRoot = options.projectRoot; this.#resolve = options.resolve;
+    this.#revisions = options.revisions; this.#mutate = options.mutate; this.#now = options.now ?? (() => new Date());
+  }
+  execute(value: unknown): Promise<SourceRevertReceipt> {
+    const run = this.#serial.then(() => this.#execute(value), () => this.#execute(value)); this.#serial = run.catch(() => undefined); return run;
+  }
+  async #execute(value: unknown): Promise<SourceRevertReceipt> {
+    const command = value as RevertCommand, snapshot = this.#bridge.snapshot(), invalid = this.#validate(value);
+    if (snapshot.state !== "ready" || !snapshot.identity || !snapshot.revisions) return this.#reject(command, "resync-required", "revert-binding-unavailable", true);
+    if (invalid) return this.#reject(command, "invalid-command", invalid, false);
+    const identity = wireIdentity(snapshot.identity), bridgeRevisions = wireRevisions(snapshot.revisions);
+    const sessionBound = this.#allowSessionReverts && identity.taskId === null && identity.taskRunId === null && bridgeRevisions.taskRevision === null;
+    if (!sessionBound && (!identity.taskId || !identity.taskRunId || !bridgeRevisions.taskRevision)) return this.#reject(command, "capability-unavailable", "active-task-required", false);
+    if (snapshot.taskState === "terminal") return this.#reject(command, "terminal-task", "task-terminal", false);
+    if (snapshot.liveness !== "idle") return this.#reject(command, "capability-unavailable", "agent-not-idle", true);
+    const evidence = this.#evidence.read(this.#projectRoot, identity.taskRunId, identity.sessionRef);
+    if (evidence.corruptions.length) return this.#reject(command, "resync-required", "mutation-evidence-corrupt", false);
+    const keyDigest = sha(command.idempotencyKey), prior = evidence.records.filter((record) => record.commandId === command.commandId || record.idempotencyKeyDigest === keyDigest);
+    if (prior.length) {
+      if (prior.some((record) => record.commandId !== command.commandId || record.idempotencyKeyDigest !== keyDigest || record.actionDigest !== command.actionDigest
+        || record.action !== command.action)) return this.#reject(command, "idempotency-payload-mismatch", "idempotency-payload-mismatch", false);
+      const dispositions = prior.map((record) => replayIdentityDisposition(record, identity)).filter(Boolean);
+      if (dispositions.length) return this.#reject(command, "identity-mismatch",
+        dispositions.includes("task-identity-mismatch") ? "task-identity-mismatch" : "runtime-or-session-replaced", false);
+      return receipt(prior.at(-1)!, true);
+    }
+    const now = this.#now().getTime();
+    if (Date.parse(command.requestedAt) > now + 30_000) return this.#reject(command, "invalid-command", "requested-at-in-future", false);
+    if (now > Date.parse(command.expiresAt)) return this.#reject(command, "expired", "command-expired", false);
+    if (!same(command.identity, identity)) return this.#reject(command, "identity-mismatch", "identity-mismatch", false);
+    if (command.expectedRevisions.runtimeRevision !== bridgeRevisions.runtimeRevision || command.expectedRevisions.taskRevision !== bridgeRevisions.taskRevision
+      || command.expectedRevisions.controlRevision !== bridgeRevisions.controlRevision) return this.#reject(command, "stale-revision", "stale-task-control-revision", true);
+    let resolved: { projection: SourceRevertProjection; authority: Authority | null };
+    try { resolved = await this.#resolve(command.payload.fileRef, command.payload.hunkRefs); }
+    catch { return this.#reject(command, "capability-unavailable", "revert-preview-unavailable", true); }
+    const rebound = this.#bridge.snapshot();
+    if (rebound.state !== "ready" || !rebound.identity || !rebound.revisions)
+      return this.#reject(command, "resync-required", "revert-binding-unavailable-after-preview", true);
+    const reboundIdentity = wireIdentity(rebound.identity), reboundRevisions = wireRevisions(rebound.revisions);
+    if (!same(reboundIdentity, identity)) {
+      const taskChanged = reboundIdentity.taskId !== identity.taskId || reboundIdentity.taskRunId !== identity.taskRunId;
+      return this.#reject(command, "identity-mismatch", taskChanged ? "task-identity-mismatch" : "runtime-or-session-replaced", false);
+    }
+    if (rebound.taskState === "terminal") return this.#reject(command, "terminal-task", "task-terminal-after-preview", false);
+    if (rebound.liveness !== "idle") return this.#reject(command, "capability-unavailable", "agent-not-idle-after-preview", true);
+    if (command.expectedRevisions.runtimeRevision !== reboundRevisions.runtimeRevision
+      || command.expectedRevisions.taskRevision !== reboundRevisions.taskRevision
+      || command.expectedRevisions.controlRevision !== reboundRevisions.controlRevision)
+      return this.#reject(command, "stale-revision", "stale-task-control-revision-after-preview", true);
+    if (!resolved.authority || resolved.projection.state !== "ready" || !resolved.projection.target)
+      return this.#reject(command, "capability-unavailable", resolved.projection.reasonCode ?? "revert-preview-unavailable", true);
+    const target = resolved.projection.target;
+    if (!this.#matches(command, target) || this.#now().getTime() > Date.parse(target.expiresAt))
+      return this.#reject(command, "stale-revision", "revert-preview-stale", true);
+    const before = { ...bridgeRevisions, workspaceRevision: target.workspaceRevision, indexRevision: target.indexRevision };
+    let requested: SourceRevertEvidenceRecord;
+    try { requested = this.#evidence.append({ projectRoot: this.#projectRoot, projectRef: identity.projectRef, runtimeInstanceId: identity.runtimeInstanceId,
+      sessionRef: identity.sessionRef, taskId: identity.taskId, taskRunId: identity.taskRunId, commandId: command.commandId, idempotencyKeyDigest: keyDigest,
+      actionDigest: command.actionDigest, action: "source.revert", target, selectedHunkRefs: [...command.payload.hunkRefs], phase: "requested",
+      resultCode: "mutation-requested", failureCode: null, requestedAt: command.requestedAt, recordedAt: this.#now().toISOString(),
+      beforeIndexPreimage: target.indexPreimage, afterIndexPreimage: null, beforeWorkspacePreimage: target.workspacePreimage,
+      afterWorkspacePreimage: null, observedRevisionsBefore: before, observedRevisionsAfter: null }); }
+    catch { return this.#reject(command, "capability-unavailable", "mutation-evidence-unavailable", false); }
+    let effect: SourceIndexTransactionResult;
+    try { effect = await this.#mutate({ identity: { projectRef: identity.projectRef, runtimeInstanceId: identity.runtimeInstanceId,
+      sessionRef: identity.sessionRef, taskId: identity.taskId, taskRunId: identity.taskRunId }, action: "source.revert",
+      expectedTaskRevision: target.taskRevision, expectedControlRevision: bridgeRevisions.controlRevision!, expectedIndexPreimage: target.indexPreimage,
+      expectedWorkspacePreimage: target.workspacePreimage, previewRef: target.previewRef, confirmedPreviewDigest: target.confirmedPreviewDigest,
+      authority: resolved.authority }); }
+    catch { effect = { state: "rejected", reasonCode: "mutation-guard-unavailable", beforeIndexPreimage: target.indexPreimage,
+      afterIndexPreimage: null, beforeWorkspacePreimage: target.workspacePreimage, afterWorkspacePreimage: null, executor: "pi-guard", directExecution: false }; }
+    if (effect.executor !== "pi-guard" || effect.directExecution !== false) effect = { ...effect, state: "uncertain", reasonCode: "mutation-executor-untrusted",
+      afterIndexPreimage: null, afterWorkspacePreimage: null, executor: "pi-guard", directExecution: false };
+    let after: BridgeRevisions; try { after = wireRevisions(await this.#revisions()); } catch { after = before; }
+    const phase = effect.state, resultCode = effect.state === "settled" ? "reverted" : effect.state === "rejected" ? "mutation-rejected" : "effect-unknown";
+    try { const terminal = this.#evidence.append({ projectRoot: this.#projectRoot, projectRef: identity.projectRef,
+      runtimeInstanceId: identity.runtimeInstanceId, sessionRef: identity.sessionRef, taskId: identity.taskId, taskRunId: identity.taskRunId,
+      commandId: command.commandId, idempotencyKeyDigest: keyDigest, actionDigest: command.actionDigest, action: "source.revert", target,
+      selectedHunkRefs: [...command.payload.hunkRefs], phase, resultCode, failureCode: effect.reasonCode, requestedAt: command.requestedAt,
+      recordedAt: this.#now().toISOString(), beforeIndexPreimage: target.indexPreimage, afterIndexPreimage: effect.afterIndexPreimage,
+      beforeWorkspacePreimage: target.workspacePreimage, afterWorkspacePreimage: effect.afterWorkspacePreimage,
+      observedRevisionsBefore: before, observedRevisionsAfter: after }); return receipt(terminal, false); }
+    catch { return receipt(requested, false); }
+  }
+  #matches(command: RevertCommand, target: SourceRevertTarget): boolean {
+    return command.payload.fileRef === target.fileRef && same(command.payload.hunkRefs, target.hunkRefs) && command.payload.previewRef === target.previewRef
+      && command.payload.confirmedPreviewDigest === target.confirmedPreviewDigest && command.payload.contentDigest === target.contentDigest
+      && command.expectedRevisions.taskRevision === target.taskRevision && command.expectedRevisions.workspaceRevision === target.workspaceRevision
+      && command.expectedRevisions.indexRevision === target.indexRevision && command.expectedRevisions.workspacePreimage === target.workspacePreimage
+      && command.expectedRevisions.indexPreimage === target.indexPreimage && command.expectedRevisions.patchPreimage === target.patchPreimage;
+  }
+  #validate(value: unknown): string | null {
+    const command = value as RevertCommand;
+    if (!exactKeys(command, ["schemaVersion", "version", "messageType", "commandId", "idempotencyKey", "requestedAt", "expiresAt", "capabilityScope", "action", "actionDigest", "identity", "expectedRevisions", "payload"])
+      || command.schemaVersion !== 1 || command.version !== "piagent-webui-control-v1" || command.messageType !== "command" || command.capabilityScope !== "reviewActions"
+      || command.action !== "source.revert" || !REF.test(command.commandId) || !IDEMPOTENCY.test(command.idempotencyKey) || !timestamp(command.requestedAt)
+      || !timestamp(command.expiresAt) || Date.parse(command.requestedAt) > Date.parse(command.expiresAt) || Date.parse(command.expiresAt) - Date.parse(command.requestedAt) > 300_000)
+      return "invalid-command-metadata";
+    const sessionBound = this.#allowSessionReverts && command.identity?.taskId === null && command.identity?.taskRunId === null
+      && command.expectedRevisions?.taskRevision === null;
+    if (!exactKeys(command.identity, ["projectRef", "runtimeInstanceId", "sessionRef", "taskId", "taskRunId", "agentOperationId", "toolCallId"])
+      || ![command.identity.projectRef, command.identity.runtimeInstanceId, command.identity.sessionRef].every((item) => REF.test(item))
+      || (!sessionBound && ![command.identity.taskId, command.identity.taskRunId].every((item) => typeof item === "string" && PUBLIC_REF.test(item)))
+      || command.identity.agentOperationId !== null || command.identity.toolCallId !== null) return "invalid-command-identity";
+    if (!exactKeys(command.expectedRevisions, [...REVISION_KEYS, "workspacePreimage", "indexPreimage", "patchPreimage"])
+      || !REVISION.test(command.expectedRevisions.runtimeRevision) || (!sessionBound && !REVISION.test(command.expectedRevisions.taskRevision ?? ""))
+      || !REVISION.test(command.expectedRevisions.controlRevision ?? "")
+      || !REVISION.test(command.expectedRevisions.workspaceRevision ?? "") || !REVISION.test(command.expectedRevisions.indexRevision ?? "")
+      || [command.expectedRevisions.approvalRevision, command.expectedRevisions.sessionOptionRevision, command.expectedRevisions.queueRevision]
+        .some((item) => item !== null && !REVISION.test(String(item)))
+      || !WORKSPACE.test(command.expectedRevisions.workspacePreimage) || !DIGEST.test(command.expectedRevisions.indexPreimage)
+      || !DIGEST.test(command.expectedRevisions.patchPreimage)) return "invalid-revert-authority";
+    if (!exactKeys(command.payload, ["fileRef", "hunkRefs", "previewRef", "confirmedPreviewDigest", "contentDigest"])
+      || !REF.test(command.payload.fileRef) || !REF.test(command.payload.previewRef) || !Array.isArray(command.payload.hunkRefs)
+      || command.payload.hunkRefs.length > 1 || new Set(command.payload.hunkRefs).size !== command.payload.hunkRefs.length
+      || command.payload.hunkRefs.some((item) => !REF.test(item)) || !DIGEST.test(command.payload.confirmedPreviewDigest)
+      || !DIGEST.test(command.payload.contentDigest)) return "invalid-revert-payload";
+    if (!DIGEST.test(command.actionDigest) || command.actionDigest !== controlActionDigest(command)) return "action-digest-mismatch";
+    return null;
+  }
+  #reject(command: RevertCommand, resultCode: SourceRevertReceipt["resultCode"], code: string, retryable: boolean): SourceRevertReceipt {
+    const snapshot = this.#bridge.snapshot(), at = this.#now().toISOString(), observed = snapshot.identity ? wireIdentity(snapshot.identity) : null;
+    const identity = observed && this.#allowSessionReverts ? observed : observed ? { ...observed, taskId: observed.taskId ?? "task.unavailable", taskRunId: observed.taskRunId ?? "task-run.unavailable" }
+      : { projectRef: "project.unavailable", runtimeInstanceId: "runtime.unavailable", sessionRef: "session.unavailable", taskId: "task.unavailable",
+        taskRunId: "task-run.unavailable", agentOperationId: null, toolCallId: null } as BridgeIdentity;
+    const revisions = snapshot.revisions ? wireRevisions(snapshot.revisions) : { runtimeRevision: "runtime.unavailable", taskRevision: null, controlRevision: null,
+      workspaceRevision: null, indexRevision: null, approvalRevision: null, sessionOptionRevision: null, queueRevision: null };
+    return { schemaVersion: 1, version: "piagent-webui-control-v1", messageType: "receipt",
+      commandId: typeof command?.commandId === "string" && REF.test(command.commandId) ? command.commandId : `revert-rejected.${reviewDigest(command ?? null).slice(7)}`,
+      idempotencyKeyDigest: sha(typeof command?.idempotencyKey === "string" ? command.idempotencyKey : canonicalReviewValue(command ?? null)), action: "source.revert",
+      actionDigest: typeof command?.actionDigest === "string" && DIGEST.test(command.actionDigest) ? command.actionDigest : sha(code), identity,
+      phase: "rejected", resultCode, requestedAt: timestamp(command?.requestedAt) ? command.requestedAt : at, settledAt: at,
+      observedRevisionsBefore: revisions, observedRevisionsAfter: revisions, deduplicated: false, auditRef: null, settlementEvidenceRef: null,
+      error: { code, message: "The confirmed exact source revert could not be completed.", retryable } };
+  }
+}

package/packages/piagent-webui/server/terminal-command.ts

@@ -0,0 +1,35 @@
+import type { TerminalCommand } from "../contracts/generated/terminal-v1.ts";
+import { controlActionDigest } from "./control-command-digest.ts";
+const REF = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
+const REVISION = /^[A-Za-z0-9][A-Za-z0-9._:~-]{0,159}$/;
+const record = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
+const exact = (value: unknown, keys: string[]): value is Record<string, unknown> => record(value)
+  && Object.keys(value).length === keys.length && Object.keys(value).every(key => keys.includes(key));
+const ref = (value: unknown) => typeof value === "string" && REF.test(value);
+const date = (value: unknown) => typeof value === "string" && value.length <= 64 && Number.isFinite(Date.parse(value));
+const dimensions = (value: Record<string, unknown>) => Number.isInteger(value.cols) && Number(value.cols) >= 2 && Number(value.cols) <= 500
+  && Number.isInteger(value.rows) && Number(value.rows) >= 1 && Number(value.rows) <= 200;
+export function parseTerminalCommand(value: unknown): TerminalCommand {
+  const invalid = () => { throw new Error("terminal-command-invalid"); };
+  if (!exact(value, ["schemaVersion", "version", "messageType", "commandId", "idempotencyKey", "requestedAt", "expiresAt", "action", "actionDigest", "identity", "expectedRevisions", "payload"])) return invalid();
+  if (value.schemaVersion !== 1 || value.version !== "piagent-terminal-v1" || value.messageType !== "command"
+    || value.action !== "terminal.command" || !ref(value.commandId) || !ref(value.idempotencyKey)
+    || !date(value.requestedAt) || !date(value.expiresAt)
+    || !exact(value.identity, ["gatewayInstanceRef", "sessionRef", "runtimeInstanceRef"]) || !Object.values(value.identity).every(ref)
+    || !exact(value.expectedRevisions, ["terminalRevision"]) || typeof value.expectedRevisions.terminalRevision !== "string"
+    || !REVISION.test(value.expectedRevisions.terminalRevision) || !record(value.payload)) return invalid();
+  const window = Date.parse(String(value.expiresAt)) - Date.parse(String(value.requestedAt));
+  if (window < 0 || window > 300_000) return invalid();
+  const payload = value.payload;
+  if (payload.kind === "open") { if (!exact(payload, ["kind", "cols", "rows"]) || !dimensions(payload)) return invalid(); }
+  else if (payload.kind === "input") {
+    if (!exact(payload, ["kind", "terminalRef", "data"]) || !ref(payload.terminalRef) || typeof payload.data !== "string"
+      || Buffer.byteLength(payload.data) > 16 * 1024) return invalid();
+  } else if (payload.kind === "resize") {
+    if (!exact(payload, ["kind", "terminalRef", "cols", "rows"]) || !ref(payload.terminalRef) || !dimensions(payload)) return invalid();
+  } else if (payload.kind === "close") { if (!exact(payload, ["kind", "terminalRef"]) || !ref(payload.terminalRef)) return invalid(); }
+  else return invalid();
+  const command = value as unknown as TerminalCommand;
+  if (command.actionDigest !== controlActionDigest(command)) return invalid();
+  return command;
+}

package/packages/piagent-webui/server/terminal-websocket-stream.ts

@@ -0,0 +1,56 @@
+import type { TerminalState, TerminalOutput, TerminalExit } from "../contracts/generated/terminal-v1.ts";
+export type TerminalStreamMessage = TerminalState | TerminalOutput | TerminalExit;
+export type TerminalStreamPort = {
+  subscribe(sessionRef: string, listener: (message: TerminalStreamMessage) => void): () => void;
+  replay(sessionRef: string): TerminalOutput[];
+};
+
+// Each socket follows one selected session. PTYs outlive this subscription.
+export class TerminalWebSocketStream {
+  readonly #port: TerminalStreamPort;
+  readonly #authorized: (csrf: string) => boolean;
+  readonly #send: (message: TerminalStreamMessage) => void;
+  readonly #close: (reason: string) => void;
+  #unsubscribe: (() => void) | null = null;
+  #generation = 0;
+  constructor(options: { port: TerminalStreamPort; authorized(csrf: string): boolean;
+    send(message: TerminalStreamMessage): void; close(reason: string): void }) {
+    this.#port = options.port; this.#authorized = options.authorized; this.#send = options.send; this.#close = options.close;
+  }
+  stop() { this.#generation++; this.#unsubscribe?.(); this.#unsubscribe = null; }
+  begin(sessionRef: string, csrf: string) {
+    this.stop();
+    const generation = this.#generation;
+    let pending: TerminalStreamMessage[] = [], bytes = 0, replaying = true;
+    const deliver = (message: TerminalStreamMessage) => {
+      if (generation !== this.#generation) return;
+      if (!this.#authorized(csrf)) { this.stop(); this.#close("terminal-session-expired"); return; }
+      this.#send(message);
+    };
+    this.#unsubscribe = this.#port.subscribe(sessionRef, message => {
+      if (message.identity.sessionRef !== sessionRef || generation !== this.#generation) return;
+      if (!this.#authorized(csrf)) { this.stop(); this.#close("terminal-session-expired"); return; }
+      if (!replaying) { deliver(message); return; }
+      bytes += Buffer.byteLength(JSON.stringify(message));
+      if (bytes > 512 * 1024 || pending.length >= 256) { this.stop(); pending = []; this.#close("terminal-backpressure"); return; }
+      pending.push(message);
+    });
+    return {
+      // Called immediately after the state response, before accepting live data.
+      finish: (ready: () => void) => {
+        if (generation !== this.#generation) return;
+        if (!this.#authorized(csrf)) { this.stop(); this.#close("terminal-session-expired"); return; }
+        const replay = this.#port.replay(sessionRef), seen = new Map<string, number>();
+        ready();
+        for (const message of replay) { seen.set(message.terminalRef, message.sequence); deliver(message); }
+        replaying = false;
+        for (const message of pending) {
+          if (message.messageType === "state" || message.messageType === "exit"
+            || message.sequence > (seen.get(message.terminalRef) ?? -1)) deliver(message);
+        }
+        pending = [];
+      },
+      abort: () => { if (generation === this.#generation) this.stop(); }
+    };
+  }
+}

package/packages/piagent-webui/server/transcript-projection.ts

@@ -62,6 +62,7 @@ export type TranscriptProjectionInput = {
 
 function hash(value: string): string { return createHash("sha256").update(value).digest("hex"); }
 function opaque(prefix: string, value: unknown): string { return `${prefix}.${hash(JSON.stringify(value))}`; }
+export const transcriptMessageRef = (sessionRef: string, entryId: string) => opaque("message", [sessionRef, entryId]);
 function timestamp(value: unknown): string | null {
   const parsed = typeof value === "number" && Number.isFinite(value) ? value : typeof value === "string" ? Date.parse(value) : Number.NaN;
   return Number.isFinite(parsed) ? new Date(parsed).toISOString() : null;
@@ -266,7 +267,7 @@ function item(entry: any, identity: TranscriptIdentity, customReceipt = false):
       textChars: Math.min(1_000_000_000, projected.full.length), digest: `sha256:${hash(projected.full)}`, truncated: projected.truncated,
       redacted: projected.redacted, imageCount: imageCount(entry.message), reasonCode: projected.redacted ? "sensitive-values-redacted" as const : null };
   })();
-  return { messageRef: opaque("message", [identity.sessionRef, entry.id]), parentMessageRef: null, role: itemRole, recordedAt,
+  return { messageRef: transcriptMessageRef(identity.sessionRef, entry.id), parentMessageRef: null, role: itemRole, recordedAt,
     agentOperationId: null, turnIndex: null, content, ...(userProjection.attachments.length ? { attachments: userProjection.attachments } : {}),
     toolCalls: projectedToolCalls };
 }

package/packages/piagent-webui/server/workspace-read-routes.ts

@@ -0,0 +1,32 @@
+import { WorkspaceReadError } from "../../piagent-core/security/workspace-file-reader.ts";
+
+export type WorkspaceRead = (kind: "tree" | "file" | "paths" | "search", path: string) => unknown | Promise<unknown>;
+export type WorkspaceRouteResult = { handled: false } | { handled: true; status: number; value: unknown };
+
+// Authentication and company forwarding belong to the session router. This
+// parser accepts only project-relative paths, including an empty tree root.
+export async function routeWorkspaceRead(url: URL, read?: WorkspaceRead): Promise<WorkspaceRouteResult> {
+  const match = /^\/api\/v1\/workspace\/(tree|file|paths|search)$/.exec(url.pathname);
+  if (!match) return { handled: false };
+  const refused = (status: number, code: string): WorkspaceRouteResult => ({ handled: true, status, value: { error: { code } } });
+  if (!read) return refused(503, "workspace-unavailable");
+  const parameter = ["paths", "search"].includes(match[1]) ? "query" : "path";
+  const relative = url.searchParams.get(parameter) ?? "";
+  if ([...url.searchParams.keys()].some(key => key !== parameter) || url.searchParams.getAll(parameter).length > 1
+    || relative.length > (parameter === "query" ? 512 : 4096) || /[\x00-\x1f\x7f]/.test(relative)
+    || (match[1] !== "search" && (relative.includes("\\") || relative.startsWith("/")))
+    || (match[1] === "search" && !relative.trim())
+    || (parameter === "path" && (relative ? relative.split("/").some(part => !part || part === "." || part === "..") : match[1] !== "tree"))) {
+    return refused(400, "workspace-path-invalid");
+  }
+  try { return { handled: true, status: 200, value: await read(match[1] as "tree" | "file" | "paths" | "search", relative) }; }
+  catch (error) {
+    if (error instanceof WorkspaceReadError) return refused(error.code === "changed-during-read" ? 409 : 400, error.code);
+    const code = (error as NodeJS.ErrnoException)?.code;
+    if (code === "ENOENT") return refused(404, "workspace-path-not-found");
+    if (code === "ELOOP" || code === "EACCES" || code === "EPERM" || (error as Error)?.message === "workspace-path-protected") {
+      return refused(403, "workspace-path-protected");
+    }
+    return refused(503, "workspace-unavailable");
+  }
+}

package/packages/piagent-webui/server/workspace-reader.ts

@@ -0,0 +1,23 @@
+import { searchWorkspace } from "../../piagent-core/extensions/workspace-search.ts";
+import { loadProjectContextIndexPolicy } from "../../piagent-core/extensions/workspace-policy.js";
+import { inspectWorkspaceFile, inspectWorkspaceTree, inspectWorkspacePaths } from "../../piagent-core/extensions/workspace-inspection.ts";
+import { inspectWorkspaceEntry } from "../../piagent-core/security/workspace-file-reader.ts";
+import type { WorkspaceRead } from "./workspace-read-routes.ts";
+
+// Re-read policy on every request; changing a profile must not leave a warm
+// editor with the permissions that happened to exist when it first opened.
+export function personalWorkspaceReader(options: {
+  cwd: string; packageRoot: string; identity(): Record<string, unknown> | Promise<Record<string, unknown>>;
+}): WorkspaceRead {
+  return async (kind, relative) => {
+    try {
+      const stat = inspectWorkspaceEntry(options.cwd, ".pi/piagent-profile.json");
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1_048_576) throw new Error("workspace-policy-unavailable");
+    } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+    const { policy, profile } = loadProjectContextIndexPolicy(options.packageRoot, options.cwd);
+    const context = { policy, profile, readOnly: profile.permissionProfile === "read-only" };
+    const value = kind === "search" ? await searchWorkspace(options.cwd, relative, context) : kind === "paths" ? await inspectWorkspacePaths(options.cwd, relative, context) : kind === "tree" ? inspectWorkspaceTree(options.cwd, relative, context) : inspectWorkspaceFile(options.cwd, relative, context);
+    return { schemaVersion: 1, version: `piagent-webui-workspace-${kind}-v1`, generatedAt: new Date().toISOString(),
+      identity: await options.identity(), ...value };
+  };
+}

package/packages/piagent-webui/server/workspace-write-controller.ts

@@ -0,0 +1,118 @@
+import { createHash } from "node:crypto";
+import { canonicalReviewValue } from "../../piagent-core/runtime/inspection/review-state-contract.ts";
+import { WorkspaceWriteError } from "../../piagent-core/extensions/workspace-write.ts";
+import type { Identity, WorkspaceWriteCommand, WorkspaceWritePayload, WorkspaceWriteReceipt, WorkspaceWriteState } from "../contracts/generated/workspace-write-v1.ts";
+
+const VERSION = "piagent-webui-workspace-write-v1" as const;
+const sha = (value: string) => `sha256:${createHash("sha256").update(value).digest("hex")}`;
+const canonical = canonicalReviewValue;
+const same = (left: unknown, right: unknown) => canonical(left) === canonical(right);
+const keys = (value: unknown, expected: string[]) => !!value && typeof value === "object" && !Array.isArray(value)
+  && same(Object.keys(value).sort(), [...expected].sort());
+const timestamp = (value: unknown): value is string => typeof value === "string" && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value;
+const ref = (value: unknown): value is string => typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/.test(value);
+export function workspaceWriteDigest(command: Pick<WorkspaceWriteCommand, "action" | "identity" | "expectedRevisions" | "payload">): string {
+  return sha(canonical({ action: command.action, identity: command.identity, expectedRevisions: command.expectedRevisions, payload: command.payload }));
+}
+// A write, or a rename (with its destination) or delete of a file whose digest the member saw.
+const payloadKeys = (payload: WorkspaceWritePayload) => keys(payload, ["path", "content", "expectedDigest"])
+  || payload?.operation === "write" && keys(payload, ["path", "content", "expectedDigest", "operation"])
+  || payload?.operation === "delete" && keys(payload, ["path", "content", "expectedDigest", "operation"]) && payload.content === "" && payload.expectedDigest !== "absent"
+  || payload?.operation === "rename" && keys(payload, ["path", "content", "expectedDigest", "operation", "destination"]) && payload.content === ""
+    && payload.expectedDigest !== "absent" && typeof payload.destination === "string" && !!payload.destination && payload.destination.length <= 4096;
+function parse(value: unknown): WorkspaceWriteCommand {
+  const command = value as WorkspaceWriteCommand;
+  if (!keys(value, ["schemaVersion", "version", "messageType", "commandId", "idempotencyKey", "requestedAt", "expiresAt", "action", "actionDigest", "identity", "expectedRevisions", "payload"])
+    || command.schemaVersion !== 1 || command.version !== VERSION || command.messageType !== "command" || command.action !== "workspace.write"
+    || !ref(command.commandId) || typeof command.idempotencyKey !== "string" || !/^[A-Za-z0-9._~-]{32,128}$/.test(command.idempotencyKey)
+    || !timestamp(command.requestedAt) || !timestamp(command.expiresAt)
+    || !keys(command.identity, ["projectRef", "runtimeInstanceId", "sessionRef", "taskId", "taskRunId", "agentOperationId", "toolCallId"])
+    || !keys(command.expectedRevisions, ["workspaceRevision"]) || typeof command.expectedRevisions.workspaceRevision !== "string"
+    || !/^[A-Za-z0-9][A-Za-z0-9._:~-]{0,159}$/.test(command.expectedRevisions.workspaceRevision)
+    || !payloadKeys(command.payload) || typeof command.payload.path !== "string" || !command.payload.path || command.payload.path.length > 4096
+    || typeof command.payload.content !== "string" || Buffer.byteLength(command.payload.content) > 1_048_576
+    || typeof command.payload.expectedDigest !== "string" || !/^(absent|[a-f0-9]{64})$/.test(command.payload.expectedDigest)
+    || command.actionDigest !== workspaceWriteDigest(command)) throw new Error("invalid-workspace-write-command");
+  return command;
+}
+export type WorkspaceWriteFacts = { identity: Identity; writable: boolean; agentRunning: boolean };
+export type WorkspaceWriteAdapterResult = { state: "saved"; digest: string } | { state: "rejected"; code: WorkspaceWriteError["code"]; currentDigest?: string | null };
+type Options = {
+  facts(): WorkspaceWriteFacts | Promise<WorkspaceWriteFacts>;
+  // Gateway persistence owns receipts; successful saves mirror to the session.
+  history(): WorkspaceWriteReceipt[];
+  append(receipt: WorkspaceWriteReceipt): void | Promise<void>;
+  write(payload: WorkspaceWritePayload): WorkspaceWriteAdapterResult | Promise<WorkspaceWriteAdapterResult>;
+  now?(): Date;
+};
+
+export class WorkspaceWriteController {
+  readonly #options: Options;
+  #serial: Promise<unknown> = Promise.resolve();
+  constructor(options: Options) { this.#options = options; }
+  #revision(facts: WorkspaceWriteFacts, history: WorkspaceWriteReceipt[]): string {
+    const last = [...history].reverse().find(receipt => receipt.phase === "settled" && receipt.resultCode === "saved"
+      && receipt.identity.projectRef === facts.identity.projectRef && receipt.identity.sessionRef === facts.identity.sessionRef);
+    return last?.observedRevisionsAfter.workspaceRevision ?? `workspace:${sha(canonical(facts.identity)).slice(7)}`;
+  }
+  async state(): Promise<WorkspaceWriteState> {
+    const facts = await this.#options.facts();
+    return { schemaVersion: 1, version: VERSION, messageType: "state", ...facts,
+      revisions: { workspaceRevision: this.#revision(facts, this.#options.history()) } };
+  }
+  execute(value: unknown): Promise<WorkspaceWriteReceipt> {
+    const command = parse(value);
+    const run = this.#serial.then(() => this.#execute(command));
+    this.#serial = run.catch(() => undefined); return run;
+  }
+  async #execute(command: WorkspaceWriteCommand): Promise<WorkspaceWriteReceipt> {
+    const facts = await this.#options.facts(), history = this.#options.history();
+    const key = sha(command.idempotencyKey), previous = [...history].reverse().find(receipt => receipt.idempotencyKeyDigest === key);
+    const revisions = { workspaceRevision: this.#revision(facts, history) };
+    const now = this.#options.now?.() ?? new Date();
+    const receipt: WorkspaceWriteReceipt = { schemaVersion: 1, version: VERSION, messageType: "receipt", commandId: command.commandId,
+      idempotencyKeyDigest: key, action: command.action, actionDigest: command.actionDigest, identity: facts.identity,
+      phase: "rejected", resultCode: "write-failed", requestedAt: command.requestedAt, settledAt: now.toISOString(),
+      observedRevisionsBefore: revisions, observedRevisionsAfter: revisions, path: command.payload.path, digest: null, currentDigest: null, deduplicated: false };
+    const reject = (resultCode: WorkspaceWriteReceipt["resultCode"]) => ({ ...receipt, resultCode });
+    if (previous && same(command.identity, previous.identity)
+      && command.identity.projectRef === facts.identity.projectRef && command.identity.sessionRef === facts.identity.sessionRef) {
+      if (previous.actionDigest !== command.actionDigest) return reject("idempotency-payload-mismatch");
+      return { ...previous, deduplicated: true };
+    }
+    if (!same(command.identity, facts.identity)) return reject("identity-mismatch");
+    if (previous) return reject("idempotency-payload-mismatch");
+    const refuse = async (code: WorkspaceWriteReceipt["resultCode"]) => { const value = reject(code); await this.#options.append(value); return value; };
+    if (Date.parse(command.expiresAt) < now.getTime() || Date.parse(command.requestedAt) > now.getTime() + 5000
+      || Date.parse(command.expiresAt) <= Date.parse(command.requestedAt) || Date.parse(command.expiresAt) - Date.parse(command.requestedAt) > 120_000) return refuse("expired");
+    if (!facts.writable) return refuse("read-only");
+    if (!same(command.expectedRevisions, revisions)) return refuse("stale-revision");
+    // Persist an uncertain receipt before dispatch. A crash must never replay a
+    // possibly completed write, even when its completion was not recorded.
+    const pending = { ...receipt, phase: "uncertain" as const, resultCode: "effect-unknown" as const };
+    await this.#options.append(pending);
+    let settled: WorkspaceWriteReceipt;
+    try {
+      const current = await this.#options.facts();
+      if (!same(current.identity, facts.identity)) settled = reject("identity-mismatch");
+      else if (!current.writable) settled = reject("read-only");
+      else if (Date.parse(command.expiresAt) < (this.#options.now?.() ?? new Date()).getTime()) settled = reject("expired");
+      else {
+        const result = await this.#options.write(command.payload);
+        settled = result.state === "saved" ? { ...receipt, phase: "settled", resultCode: "saved", digest: result.digest,
+          observedRevisionsAfter: { workspaceRevision: `workspace:${key.slice(7)}` } }
+          : { ...receipt, resultCode: result.code, currentDigest: result.currentDigest ?? null };
+      }
+    } catch (error) {
+      // The live personal guard may be loaded by Pi's TS loader, with a
+      // different Error constructor than native ESM. Validate its bounded code.
+      const failure = error as WorkspaceWriteError | undefined;
+      settled = (error instanceof WorkspaceWriteError || failure?.name === "WorkspaceWriteError")
+        && ["invalid-write", "path-protected", "read-only", "stale-content", "unsafe-path"].includes(failure!.code)
+        ? { ...receipt, resultCode: failure!.code, currentDigest: failure!.currentDigest ?? null } : pending;
+    }
+    settled.settledAt = (this.#options.now?.() ?? new Date()).toISOString();
+    try { await this.#options.append(settled); } catch { return pending; }
+    return settled;
+  }
+}

package/packages/piagent-webui/server/workspace-write-routes.ts

@@ -0,0 +1,38 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { SessionAuthority } from "./session-auth.ts";
+import { errorResponse, jsonResponse, requestBody } from "./http-security.ts";
+
+export type WorkspaceWriteRoutes = {
+  state(sessionRef: string): unknown | Promise<unknown>;
+  execute(sessionRef: string, command: unknown): unknown | Promise<unknown>;
+};
+type Context = { request: IncomingMessage; response: ServerResponse; url: URL; origin: string;
+  requestOrigin: string | undefined; auth: SessionAuthority; now: number; consumeControl(id: string, now: number): boolean };
+export async function routeWorkspaceWrite(context: Context, handler?: WorkspaceWriteRoutes): Promise<boolean> {
+  const { request, response, url, auth, requestOrigin, origin, now, consumeControl } = context;
+  const match = /^\/api\/v1\/sessions\/([A-Za-z0-9][A-Za-z0-9._~-]{0,159})\/workspace\/write$/.exec(url.pathname);
+  if (!match) return false;
+  if (!auth.authenticate(request)) { errorResponse(response, 401, "authentication-required"); return true; }
+  if (url.search) { errorResponse(response, 400, "invalid-workspace-write-query"); return true; }
+  if (!["GET", "POST"].includes(request.method ?? "")) { errorResponse(response, 405, "method-not-allowed"); return true; }
+  let command: unknown;
+  if (request.method === "POST") {
+    if (requestOrigin !== origin) { errorResponse(response, 403, "origin-required"); return true; }
+    const session = auth.authorizeMutation(request);
+    if (!session) { errorResponse(response, 403, "mutation-authority-rejected"); return true; }
+    if (!consumeControl(session.id, now)) { errorResponse(response, 429, "control-rate-limit"); return true; }
+    if (!String(request.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) {
+      errorResponse(response, 415, "content-type"); return true;
+    }
+    // JSON escaping may expand one permitted UTF-8 text byte to six bytes.
+    try { command = JSON.parse((await requestBody(request, 6 * 1_048_576 + 8192)).toString("utf8")); }
+    catch (error) { errorResponse(response, (error as Error).message === "body-limit" ? 413 : 400, "invalid-workspace-write-command"); return true; }
+    if ((command as { identity?: { sessionRef?: unknown } } | null)?.identity?.sessionRef !== match[1]) {
+      errorResponse(response, 400, "workspace-session-mismatch"); return true;
+    }
+  }
+  if (!handler) { errorResponse(response, 503, "workspace-write-unavailable"); return true; }
+  try { jsonResponse(response, 200, request.method === "GET" ? await handler.state(match[1]) : await handler.execute(match[1], command)); }
+  catch (error) { errorResponse(response, (error as Error).message === "invalid-workspace-write-command" ? 400 : 503, "workspace-write-unavailable"); }
+  return true;
+}

package/packages/piagent-webui/shared/terminal-message.ts

@@ -0,0 +1,23 @@
+const object = (value: unknown): value is Record<string, any> => !!value && typeof value === 'object' && !Array.isArray(value);
+const ref = (value: unknown) => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/.test(value);
+const exact = (value: Record<string, any>, keys: string[]) => Object.keys(value).length === keys.length && Object.keys(value).every(key => keys.includes(key));
+export function isTerminalMessage(value: unknown): boolean {
+  if (!object(value) || value.schemaVersion !== 1 || value.version !== 'piagent-terminal-v1' || !object(value.identity)
+    || !exact(value.identity, ['gatewayInstanceRef', 'runtimeInstanceRef', 'sessionRef'])
+    || !['gatewayInstanceRef', 'runtimeInstanceRef', 'sessionRef'].every(key => ref(value.identity[key]))) return false;
+  const base = ['schemaVersion', 'version', 'messageType', 'identity'];
+  if (value.messageType === 'state') return exact(value, [...base, 'revisions', 'available', 'reasonCode', 'terminals'])
+    && object(value.revisions) && exact(value.revisions, ['terminalRevision']) && typeof value.revisions.terminalRevision === 'string'
+    && typeof value.available === 'boolean' && (value.reasonCode === null || typeof value.reasonCode === 'string')
+    && Array.isArray(value.terminals) && value.terminals.length <= 4 && value.terminals.every((tab: unknown) => object(tab)
+      && exact(tab, ['terminalRef', 'number', 'state', 'cols', 'rows', 'sequence', 'exitCode'])
+      && ref(tab.terminalRef) && Number.isSafeInteger(tab.number) && tab.number > 0 && ['running', 'exited'].includes(tab.state)
+      && Number.isSafeInteger(tab.sequence) && tab.sequence >= 0 && Number.isInteger(tab.cols) && tab.cols >= 2 && tab.cols <= 500
+      && Number.isInteger(tab.rows) && tab.rows >= 1 && tab.rows <= 200 && (tab.exitCode === null || Number.isInteger(tab.exitCode)));
+  if (!ref(value.terminalRef) || !Number.isSafeInteger(value.sequence) || value.sequence < 0) return false;
+  if (value.messageType === 'output') return exact(value, [...base, 'terminalRef', 'sequence', 'data', 'replay', 'reset', 'complete', 'truncated'])
+    && typeof value.data === 'string' && value.data.length <= 8192
+    && ['replay', 'reset', 'complete', 'truncated'].every(key => typeof value[key] === 'boolean');
+  return value.messageType === 'exit' && exact(value, [...base, 'terminalRef', 'sequence', 'exitCode', 'signal'])
+    && (value.exitCode === null || Number.isInteger(value.exitCode)) && (value.signal === null || Number.isInteger(value.signal));
+}