@piagent/platform 1.37.1 → 1.38.1

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

@@ -1,212 +1,18 @@
-import { createHash } from "node:crypto";
+import type { SourceRevertAuthority } from "../../piagent-core/runtime/inspection/source-action-contract.ts";
+import { appendSourceMutationEvidence, readSourceMutationEvidence } from "../../piagent-core/runtime/inspection/source-mutation-store.ts";
+import { SourceRevertController as SharedSourceRevertController } from "../server/source-revert-controller.ts";
 
-import { appendSourceMutationEvidence, readSourceMutationEvidence, type SourceMutationEvidenceRecord } from "../../piagent-core/runtime/inspection/source-mutation-store.ts";
-import { canonicalReviewValue, reviewDigest } from "../../piagent-core/runtime/inspection/review-state-contract.ts";
-import type { SourceRevertAuthority, SourceRevertProjection, SourceRevertTarget } from "../../piagent-core/runtime/inspection/source-revert-projection.ts";
-import type { SourceIndexTransactionResult } from "../../piagent-core/runtime/policy/source-index-transaction.ts";
-import { controlActionDigest, type BridgeIdentity, type BridgeRevisions, type SameSessionPiBridge } from "./same-session-bridge.ts";
+export type { SourceRevertReceipt } from "../server/source-revert-controller.ts";
 
-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 = (input: { identity: { projectRef: string; runtimeInstanceId: string; sessionRef: string; taskId: string; taskRunId: string };
-  action: "source.revert"; expectedTaskRevision: string; expectedControlRevision: string; expectedIndexPreimage: string;
-  expectedWorkspacePreimage: string; previewRef: string; confirmedPreviewDigest: string;
-  authority: SourceRevertAuthority }) => 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<SourceMutationEvidenceRecord, "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: SourceMutationEvidenceRecord, 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 class SourceRevertController {
-  readonly #bridge: SameSessionPiBridge; readonly #projectRoot: string;
-  readonly #resolve: (fileRef: string, hunkRefs: string[]) => Promise<{ projection: SourceRevertProjection; authority: SourceRevertAuthority | null }>;
-  readonly #revisions: () => Promise<Record<string, string | null>>;
-  readonly #mutate: RevertMutate;
-  readonly #now: () => Date; #serial: Promise<unknown> = Promise.resolve();
-  constructor(options: { bridge: SameSessionPiBridge; projectRoot: string;
-    resolve(fileRef: string, hunkRefs: string[]): Promise<{ projection: SourceRevertProjection; authority: SourceRevertAuthority | null }>;
-    revisions(): Promise<Record<string, string | null>>; mutate: RevertMutate; now?: () => Date }) {
-    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);
-    if (!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 = readSourceMutationEvidence(this.#projectRoot, identity.taskRunId);
-    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: SourceRevertAuthority | 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: SourceMutationEvidenceRecord;
-    try { requested = appendSourceMutationEvidence({ 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 = appendSourceMutationEvidence({ 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";
-    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))
-      || ![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) || !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 ? { ...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 } };
+// The legacy extension retains its task evidence store; Gateway supplies its own binding.
+export class SourceRevertController extends SharedSourceRevertController {
+  constructor(options: Omit<ConstructorParameters<typeof SharedSourceRevertController<SourceRevertAuthority>>[0], "evidence" | "allowSessionReverts">) {
+    super({ ...options, allowSessionReverts: false, evidence: {
+      read: (root, run) => run ? readSourceMutationEvidence(root, run) : { records: [], corruptions: ["active-task-required"] },
+      append: value => {
+        if (!value.taskId || !value.taskRunId) throw new Error("active-task-required");
+        return appendSourceMutationEvidence({ ...value, taskId: value.taskId, taskRunId: value.taskRunId });
+      }
+    } });
   }
 }

package/packages/piagent-webui/gateway/checkpoint-sessions.ts

@@ -0,0 +1,99 @@
+import { checkpointAuthority } from '../../piagent-core/runtime/checkpoints/checkpoint-authority.ts';
+import { workspaceWriteAuthority } from '../../piagent-core/runtime/policy/workspace-write-authority.ts';
+import { CheckpointController } from '../server/checkpoint-controller.ts';
+import { CHECKPOINT_VERSION, sameCheckpointValue } from '../server/checkpoint-command.ts';
+import type { CheckpointPreview } from '../contracts/generated/checkpoint-v1.ts';
+import type { SessionRuntimeSupervisor } from './session-runtime-supervisor.ts';
+import { sessionRefForPath, projectRefForCwd } from './session-catalog.ts';
+import { CheckpointReceiptStore } from './checkpoint-store.ts';
+import { transcriptMessageRef } from '../server/transcript-projection.ts';
+import { webUiSessionRef } from '../../piagent-core/runtime/inspection/webui-snapshot.ts';
+import type { CheckpointPort } from '../../piagent-core/runtime/checkpoints/checkpoint-authority.ts';
+
+export type ManagedCheckpointRuntime = { current(): boolean; writable(): Promise<boolean>; port: CheckpointPort };
+
+type Options = { root: string; key: Buffer; gatewayInstanceRef: string; managed: boolean;
+  runtimes: Pick<SessionRuntimeSupervisor, 'listSessions' | 'acquire' | 'liveSessionManager' | 'ownership' | 'currentOperation'>;
+  managedCheckpoint?(id: string): ManagedCheckpointRuntime;
+  changed(sessionRef: string): void };
+
+export class CheckpointSessions {
+  #options: Options;
+  #store: CheckpointReceiptStore;
+  #controllers = new Map<string, CheckpointController>();
+  constructor(options: Options) { this.#options = options; this.#store = new CheckpointReceiptStore(options.root, options.key); }
+  async #live(sessionRef: string) {
+    const { runtimes, key, gatewayInstanceRef } = this.#options;
+    if (this.#options.managed && !this.#options.managedCheckpoint) throw Error('checkpoint-company-boundary-required');
+    const matches = (await runtimes.listSessions()).filter(info => sessionRefForPath(key, info.path) === sessionRef);
+    if (matches.length !== 1) throw Error('checkpoint-session-unavailable');
+    const info = matches[0]!, lease = await runtimes.acquire(sessionRef), manager = runtimes.liveSessionManager(sessionRef);
+    if (!manager || !lease.runtimeInstanceRef || manager.getSessionId() !== info.id) throw Error('checkpoint-session-unavailable');
+    const managed = this.#options.managed ? this.#options.managedCheckpoint!(info.id) : null;
+    const port = managed ? { ...managed.port, current: managed.current } : checkpointAuthority.resolve(info.cwd, info.id);
+    const assertCurrent = () => {
+      const ownership = runtimes.ownership(sessionRef);
+      if (!port.current() || runtimes.liveSessionManager(sessionRef) !== manager || manager.getSessionId() !== info.id
+        || ownership.state !== 'gateway-owned' || ownership.owner.continuity !== 'exact'
+        || ownership.owner.gatewayInstanceRef !== gatewayInstanceRef || ownership.owner.runtimeInstanceRef !== lease.runtimeInstanceRef
+        || ownership.owner.ownerEpoch !== lease.ownerEpoch) throw Error('checkpoint-runtime-replaced');
+      if (!managed && manager.buildSessionContext().model?.provider === 'agent_watch_managed') throw Error('checkpoint-company-boundary-required');
+    };
+    assertCurrent();
+    const identity = { projectRef: projectRefForCwd(key, info.cwd), sessionRef, runtimeInstanceId: lease.runtimeInstanceRef,
+      taskId: null, taskRunId: null, agentOperationId: null, toolCallId: null };
+    const writable = async () => {
+      assertCurrent();
+      const value = managed ? await managed.writable() : workspaceWriteAuthority.writable(info.cwd, info.id);
+      assertCurrent(); return value;
+    };
+    return { info, port, assertCurrent, identity, writable, managed: !!managed };
+  }
+  async #facts(sessionRef: string) {
+    const binding = await this.#live(sessionRef), listed = await binding.port.list();
+    binding.assertCurrent();
+    return { identity: binding.identity, revisions: { checkpointRevision: listed.revision },
+      points: listed.points.map(point => ({ ...point, turnRef: transcriptMessageRef(webUiSessionRef(binding.info.id), point.turnRef) })),
+      available: listed.available, agentRunning: Boolean(this.#options.runtimes.currentOperation(sessionRef)),
+      writable: await binding.writable() };
+  }
+  #controller(sessionRef: string) {
+    let controller = this.#controllers.get(sessionRef);
+    if (!controller) {
+      if (this.#controllers.size >= 1024) throw Error('checkpoint-session-capacity');
+      controller = new CheckpointController({
+        facts: () => this.#facts(sessionRef), history: () => this.#store.history(sessionRef),
+        append: receipt => {
+          this.#store.append(sessionRef, receipt);
+          if (receipt.phase === 'settled' || receipt.phase === 'uncertain') this.#options.changed(sessionRef);
+        },
+        restore: async (target, expected, identity) => {
+          const binding = await this.#live(sessionRef);
+          if (!sameCheckpointValue(identity, binding.identity)) throw Error('checkpoint-runtime-replaced');
+          if (!await binding.writable()) throw Error('checkpoint-read-only');
+          const guard = () => {
+            binding.assertCurrent();
+            if (this.#options.runtimes.currentOperation(sessionRef)) throw Error('checkpoint-session-busy');
+            if (!binding.managed && !workspaceWriteAuthority.writable(binding.info.cwd, binding.info.id)) throw Error('checkpoint-read-only');
+          };
+          guard();
+          return await binding.port.restoreTo(target, expected, guard);
+        },
+      });
+      this.#controllers.set(sessionRef, controller);
+    }
+    return controller;
+  }
+  state(sessionRef: string) { return this.#controller(sessionRef).state(); }
+  execute(sessionRef: string, command: unknown) { return this.#controller(sessionRef).execute(command); }
+  async preview(sessionRef: string, target: string): Promise<CheckpointPreview> {
+    if (!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(target)) throw Error('invalid-checkpoint-target');
+    const binding = await this.#live(sessionRef), preview = await binding.port.preview(target);
+    binding.assertCurrent();
+    return { schemaVersion: 1, version: CHECKPOINT_VERSION, messageType: 'preview', identity: binding.identity,
+      revisions: { checkpointRevision: preview.revision }, targetId: target, result: preview.result as CheckpointPreview['result'],
+      previewDigest: preview.digest, tree: preview.tree,
+      steps: preview.steps.map(step => ({ ...step, turnRef: transcriptMessageRef(webUiSessionRef(binding.info.id), step.turnRef) })), files: preview.files,
+      conflicts: preview.conflicts, stoppedAt: preview.stoppedAt };
+  }
+}

package/packages/piagent-webui/gateway/checkpoint-store.ts

@@ -0,0 +1,6 @@
+import type { CheckpointReceipt } from '../contracts/generated/checkpoint-v1.ts';
+import { SignedSessionJournal } from './signed-session-journal.ts';
+
+export class CheckpointReceiptStore extends SignedSessionJournal<CheckpointReceipt> {
+  constructor(root: string, key: Buffer) { super(root, key, 'checkpoint-receipts'); }
+}

package/packages/piagent-webui/gateway/company-relay.ts

@@ -1,5 +1,6 @@
 import { createHash, randomBytes } from "node:crypto";
 import { WebSocket } from "ws";
+import { CompanyTerminalRelay } from "./company-terminal-relay.ts";
 
 import type { Catalog, SessionRow } from "../contracts/generated/session-catalog-v1.ts";
 import { webUiModelRef } from "../../piagent-core/runtime/inspection/webui-snapshot.ts";
@@ -41,6 +42,7 @@ const timedOut = (error: unknown) => error instanceof Error && (error.name === "
 const failure = (error: unknown, fallback: string) => error instanceof Error && /^[a-z][a-z0-9:._-]{2,95}$/.test(error.message) ? error.message : fallback;
 
 export class CompanyRelay {
+  readonly terminals: CompanyTerminalRelay;
   readonly #connector: CompanyConnector;
   readonly #events: GatewayEventStore;
   readonly #hubProject: (cwd: string) => string;
@@ -70,6 +72,8 @@ export class CompanyRelay {
     this.#connector = options.connector; this.#events = options.events;
     this.#hubProject = options.hubProject; this.#folder = options.folder;
     this.#readTimeoutMs = options.readTimeoutMs ?? READ_TIMEOUT_MS; this.#answerTimeoutMs = options.answerTimeoutMs ?? ANSWER_TIMEOUT_MS;
+    this.terminals = new CompanyTerminalRelay({ owns: ref => this.owns(ref),
+      link: async () => { const link = await this.#ready(); return this.#bootstrap(link.socket); } });
   }
 
   status(): CompanyStatus {
@@ -123,6 +127,7 @@ export class CompanyRelay {
 
   close(): void {
     this.#closed = true;
+    this.terminals.close();
     if (this.#retry) clearTimeout(this.#retry);
     this.#ws?.terminate();
   }

package/packages/piagent-webui/gateway/company-terminal-cache.ts

@@ -0,0 +1,54 @@
+import type { TerminalState, TerminalOutput, TerminalSummary } from '../contracts/generated/terminal-v1.ts';
+import type { TerminalStreamMessage } from '../server/terminal-websocket-stream.ts';
+import { TerminalOutputBuffer } from './terminal-output-buffer.ts';
+
+const identityKey = (value: TerminalState['identity']) => JSON.stringify([value.gatewayInstanceRef, value.runtimeInstanceRef, value.sessionRef]);
+type Entry = { buffer: TerminalOutputBuffer; sequence: number; truncated: boolean };
+// The relay keeps only the same bounded, redacted replay the company Gateway
+// provides. Live bytes never enter the durable event stream or browser storage.
+export class CompanyTerminalCache {
+  state: TerminalState | null = null;
+  readonly #tabs = new Map<string, Entry>();
+  accept(message: TerminalStreamMessage) {
+    if (message.messageType === 'state') {
+      if (this.state && identityKey(this.state.identity) !== identityKey(message.identity)) this.#tabs.clear();
+      this.state = message;
+      for (const ref of this.#tabs.keys()) if (!(message.terminals as readonly TerminalSummary[]).some(tab => tab.terminalRef === ref)) this.#tabs.delete(ref);
+      return;
+    }
+    if (!this.state || identityKey(this.state.identity) !== identityKey(message.identity)) throw Error('company-terminal-identity-changed');
+    let entry = this.#tabs.get(message.terminalRef);
+    if (!entry) {
+      if (this.#tabs.size >= 4) throw Error('company-terminal-capacity');
+      entry = { buffer: new TerminalOutputBuffer(), sequence: 0, truncated: false }; this.#tabs.set(message.terminalRef, entry);
+    }
+    if (message.messageType === 'output') {
+      if (message.replay && message.reset) { entry.buffer = new TerminalOutputBuffer(); entry.truncated = message.truncated; }
+      else if (!message.replay && message.sequence <= entry.sequence) return;
+      entry.buffer.append(message.data);
+    }
+    entry.sequence = message.sequence;
+  }
+  disconnected() {
+    if (!this.state) return null;
+    this.state = { ...this.state, available: false, reasonCode: 'company-terminal-disconnected' };
+    return this.state;
+  }
+  replay(): TerminalOutput[] {
+    if (!this.state) return [];
+    const { identity } = this.state;
+    return (this.state.terminals as readonly TerminalSummary[]).flatMap(tab => {
+      const entry = this.#tabs.get(tab.terminalRef), snapshot = entry?.buffer.snapshot() ?? { text: '', truncated: false };
+      const parts: string[] = [];
+      for (let start = 0; start < snapshot.text.length;) {
+        let end = Math.min(start + 8192, snapshot.text.length);
+        if (end < snapshot.text.length && /[\uD800-\uDBFF]/.test(snapshot.text[end - 1]!)) end--;
+        parts.push(snapshot.text.slice(start, end)); start = end;
+      }
+      if (!parts.length) parts.push('');
+      return parts.map((data, index): TerminalOutput => ({ schemaVersion: 1, version: 'piagent-terminal-v1', messageType: 'output', identity,
+        terminalRef: tab.terminalRef, sequence: entry?.sequence ?? tab.sequence, data, replay: true,
+        reset: index === 0, complete: index === parts.length - 1, truncated: snapshot.truncated || Boolean(entry?.truncated) }));
+    });
+  }
+}

package/packages/piagent-webui/gateway/company-terminal-channel.ts

@@ -0,0 +1,117 @@
+import { randomUUID } from 'node:crypto';
+import { WebSocket } from 'ws';
+import type { TerminalCommand, TerminalReceipt, TerminalState, TerminalSummary } from '../contracts/generated/terminal-v1.ts';
+import type { TerminalStreamMessage } from '../server/terminal-websocket-stream.ts';
+import { isTerminalMessage } from '../shared/terminal-message.ts';
+import { CompanyTerminalCache } from './company-terminal-cache.ts';
+
+export type CompanyTerminalLink = { origin: string; cookie: string; csrf: string };
+type Pending = { method: string; resolve(value: unknown): void; reject(error: Error): void; timer: NodeJS.Timeout;
+  replay?: Map<string, number>; result?: TerminalState };
+
+export class CompanyTerminalChannel {
+  readonly cache = new CompanyTerminalCache();
+  readonly #socket: WebSocket;
+  readonly #ref: string;
+  readonly #csrf: string;
+  readonly #emit: (message: TerminalStreamMessage) => void;
+  readonly #pending = new Map<string, Pending>();
+  readonly ready: Promise<void>;
+  #read: Promise<TerminalState> | null = null;
+  #closed = false;
+  get closed() { return this.#closed; }
+  constructor(ref: string, link: CompanyTerminalLink, emit: (message: TerminalStreamMessage) => void, disconnected: () => void) {
+    if (!/^http:\/\/127\.0\.0\.1:\d{1,5}$/.test(link.origin)) throw Error('company-gateway-invalid');
+    this.#ref = ref; this.#csrf = link.csrf; this.#emit = emit;
+    const ws = this.#socket = new WebSocket(`${link.origin.replace('http:', 'ws:')}/api/v1/gateway`, 'piagent.gateway.v1',
+      { headers: { Origin: link.origin, Cookie: link.cookie }, maxPayload: 70_000, perMessageDeflate: false });
+    this.ready = new Promise((resolve, reject) => {
+      let hello = false;
+      const timer = setTimeout(() => { reject(Error('company-terminal-connect-timeout')); ws.terminate(); }, 5000);
+      ws.on('open', () => ws.send(JSON.stringify({ schemaVersion: 1, version: 'piagent-gateway-protocol-v1', messageType: 'connect',
+        clientRef: 'dashboard-company-terminal', minimumProtocol: 1, maximumProtocol: 1, lastEventSequence: null, catalogRevision: null })));
+      ws.on('message', data => {
+        try {
+          const frame = JSON.parse(String(data));
+          if (!hello && frame.version === 'piagent-gateway-protocol-v1' && frame.messageType === 'hello') {
+            hello = true; clearTimeout(timer); resolve(); return;
+          }
+          if (!hello) throw Error();
+          this.#message(frame);
+        } catch { ws.close(1008, 'company-terminal-protocol-invalid'); }
+      });
+      ws.on('error', () => {});
+      ws.once('close', () => {
+        clearTimeout(timer); this.#closed = true;
+        reject(Error('company-terminal-disconnected'));
+        for (const pending of this.#pending.values()) { clearTimeout(pending.timer); pending.reject(Error('company-terminal-disconnected')); }
+        this.#pending.clear();
+        const state = this.cache.disconnected(); if (state) this.#emit(state);
+        disconnected();
+      });
+    });
+  }
+  #message(frame: any) {
+    if (frame.version === 'piagent-gateway-protocol-v1') {
+      if (frame.messageType !== 'response') return; // General session events are owned by CompanyRelay.
+      const pending = this.#pending.get(frame.requestId); if (!pending) return;
+      if (frame.method !== pending.method) throw Error();
+      if (frame.ok !== true) {
+        clearTimeout(pending.timer); this.#pending.delete(frame.requestId);
+        pending.reject(Error('company-terminal-request-rejected')); return;
+      }
+      if (pending.method === 'terminals.state') {
+        if (!isTerminalMessage(frame.result) || frame.result.messageType !== 'state' || frame.result.identity.sessionRef !== this.#ref) throw Error();
+        const state = frame.result as TerminalState; this.cache.accept(state); this.#emit(state);
+        pending.result = state; pending.replay = new Map((state.terminals as readonly TerminalSummary[]).map(tab => [tab.terminalRef, tab.sequence]));
+        if (pending.replay.size) return;
+      }
+      clearTimeout(pending.timer); this.#pending.delete(frame.requestId); pending.resolve(frame.result); return;
+    }
+    if (!isTerminalMessage(frame) || frame.identity.sessionRef !== this.#ref) throw Error();
+    const message = frame as TerminalStreamMessage;
+    this.cache.accept(message); this.#emit(message);
+    if (message.messageType === 'output' && message.replay && message.complete) {
+      for (const [id, pending] of this.#pending) if (pending.replay?.get(message.terminalRef) === message.sequence) {
+        pending.replay.delete(message.terminalRef);
+        if (!pending.replay.size) {
+          clearTimeout(pending.timer); this.#pending.delete(id); pending.resolve(this.cache.state ?? pending.result);
+        }
+      }
+    }
+  }
+  async #request(method: string, params: Record<string, unknown>): Promise<unknown> {
+    await this.ready;
+    if (this.#closed || this.#socket.readyState !== WebSocket.OPEN) throw Error('company-terminal-disconnected');
+    if (this.#pending.size >= 64 || this.#socket.bufferedAmount > 512 * 1024) throw Error('company-terminal-capacity');
+    const requestId = `terminal_${randomUUID().replaceAll('-', '')}`;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.#pending.delete(requestId); reject(Error('company-terminal-response-timeout')); this.#socket.terminate();
+      }, 15000);
+      this.#pending.set(requestId, { method, resolve, reject, timer });
+      this.#socket.send(JSON.stringify({ schemaVersion: 1, version: 'piagent-gateway-protocol-v1', messageType: 'request',
+        requestId, method, params: { ...params, csrfToken: this.#csrf } }), error => { if (error) this.#socket.terminate(); });
+    });
+  }
+  state(): Promise<TerminalState> {
+    this.#read ??= (this.#request('terminals.state', { sessionRef: this.#ref }) as Promise<TerminalState>).finally(() => { this.#read = null; });
+    return this.#read;
+  }
+  async execute(command: TerminalCommand): Promise<TerminalReceipt> {
+    if (command.identity.sessionRef !== this.#ref) throw Error('company-terminal-session-mismatch');
+    const value = await this.#request('terminals.command', { command }) as TerminalReceipt;
+    if (!value || value.schemaVersion !== 1 || value.version !== command.version || value.messageType !== 'receipt'
+      || value.commandId !== command.commandId || value.idempotencyKey !== command.idempotencyKey || value.actionDigest !== command.actionDigest
+      || value.action !== command.action || !value.identity || !Object.entries(command.identity).every(([key, item]) => (value.identity as any)[key] === item)
+      || !value.observedRevisions || typeof value.observedRevisions.terminalRevision !== 'string'
+      || !['settled', 'rejected', 'uncertain'].includes(value.phase) || typeof value.deduplicated !== 'boolean'
+      || !(value.terminalRef === null || typeof value.terminalRef === 'string') || !(value.reasonCode === null || typeof value.reasonCode === 'string'))
+      throw Error('company-terminal-receipt-invalid');
+    // Project only contract fields; an accidental upstream private field cannot travel to the browser.
+    return { schemaVersion: 1, version: value.version, messageType: 'receipt', commandId: value.commandId, idempotencyKey: value.idempotencyKey,
+      action: value.action, actionDigest: value.actionDigest, identity: command.identity, observedRevisions: { terminalRevision: value.observedRevisions.terminalRevision },
+      phase: value.phase, terminalRef: value.terminalRef, reasonCode: value.reasonCode, deduplicated: value.deduplicated };
+  }
+  close() { this.#closed = true; this.#socket.terminate(); }
+}

package/packages/piagent-webui/gateway/company-terminal-relay.ts

@@ -0,0 +1,75 @@
+import type { TerminalOutput, TerminalState } from '../contracts/generated/terminal-v1.ts';
+import type { TerminalStreamMessage } from '../server/terminal-websocket-stream.ts';
+import { parseTerminalCommand } from '../server/terminal-command.ts';
+import { CompanyTerminalChannel, type CompanyTerminalLink } from './company-terminal-channel.ts';
+
+type Entry = { listeners: Set<(message: TerminalStreamMessage) => void>; channel: CompanyTerminalChannel | null;
+  connecting: Promise<CompanyTerminalChannel> | null; retry: NodeJS.Timeout | null; idle: NodeJS.Timeout | null };
+
+export class CompanyTerminalRelay {
+  readonly #link: () => Promise<CompanyTerminalLink>;
+  readonly #owns: (ref: string) => boolean;
+  readonly #entries = new Map<string, Entry>();
+  #closed = false;
+  constructor(options: { link(): Promise<CompanyTerminalLink>; owns(ref: string): boolean }) { this.#link = options.link; this.#owns = options.owns; }
+  #entry(ref: string): Entry {
+    if (this.#closed || !this.#owns(ref)) throw Error('company-terminal-session-unavailable');
+    let entry = this.#entries.get(ref);
+    if (!entry) {
+      if (this.#entries.size >= 32) throw Error('company-terminal-capacity');
+      entry = { listeners: new Set(), channel: null, connecting: null, retry: null, idle: null }; this.#entries.set(ref, entry);
+    }
+    if (entry.idle) clearTimeout(entry.idle);
+    const current = entry;
+    entry.idle = setTimeout(() => { if (!current.listeners.size) this.#remove(ref, current); }, 30000); entry.idle.unref();
+    return entry;
+  }
+  #retry(ref: string, entry: Entry) {
+    if (this.#closed || this.#entries.get(ref) !== entry || !entry.listeners.size || entry.retry) return;
+    entry.retry = setTimeout(() => {
+      entry.retry = null;
+      void this.state(ref).catch(() => this.#retry(ref, entry));
+    }, 3000); entry.retry.unref();
+  }
+  async #channel(ref: string, entry: Entry): Promise<CompanyTerminalChannel> {
+    if (entry.channel && !entry.channel.closed) { await entry.channel.ready; return entry.channel; }
+    entry.connecting ??= (async () => {
+      const link = await this.#link();
+      if (this.#closed || this.#entries.get(ref) !== entry || !this.#owns(ref)) throw Error('company-terminal-session-unavailable');
+      const channel = new CompanyTerminalChannel(ref, link, message => {
+        if (this.#entries.get(ref) !== entry || entry.channel !== channel) return;
+        for (const listener of entry.listeners) try { listener(message); } catch { /* browser stream owns its backpressure */ }
+      }, () => { if (entry.channel === channel) this.#retry(ref, entry); });
+      entry.channel = channel; await channel.ready;
+      if (entry.retry) { clearTimeout(entry.retry); entry.retry = null; }
+      return channel;
+    })().finally(() => { entry.connecting = null; });
+    return entry.connecting;
+  }
+  async state(ref: string): Promise<TerminalState> {
+    const entry = this.#entry(ref);
+    return (await this.#channel(ref, entry)).state();
+  }
+  async execute(value: unknown) {
+    const command = parseTerminalCommand(value), ref = command.identity.sessionRef, entry = this.#entry(ref);
+    const channel = await this.#channel(ref, entry);
+    if (!channel.cache.state) await channel.state();
+    // Exactly one dispatch. Only an explicit client retry may send this command again.
+    return channel.execute(command);
+  }
+  subscribe(ref: string, listener: (message: TerminalStreamMessage) => void) {
+    const entry = this.#entry(ref);
+    if (entry.listeners.size >= 32) throw Error('company-terminal-subscription-capacity');
+    entry.listeners.add(listener);
+    return () => { entry.listeners.delete(listener); if (!entry.listeners.size) this.#remove(ref, entry); };
+  }
+  replay(ref: string): TerminalOutput[] { return this.#entries.get(ref)?.channel?.cache.replay() ?? []; }
+  #remove(ref: string, entry: Entry) {
+    if (this.#entries.get(ref) !== entry) return;
+    this.#entries.delete(ref);
+    if (entry.retry) clearTimeout(entry.retry);
+    if (entry.idle) clearTimeout(entry.idle);
+    entry.channel?.close();
+  }
+  close() { this.#closed = true; for (const [ref, entry] of this.#entries) this.#remove(ref, entry); }
+}