@piagent/platform 1.37.1 → 1.38.1

package/packages/piagent-webui/server/checkpoint-controller.ts

@@ -0,0 +1,87 @@
+import type { CheckpointCommand, CheckpointReceipt, CheckpointState } from '../contracts/generated/checkpoint-v1.ts';
+import { CHECKPOINT_VERSION, checkpointSha, parseCheckpointCommand, sameCheckpointValue as same } from './checkpoint-command.ts';
+
+export type CheckpointFacts = Omit<CheckpointState, 'schemaVersion' | 'version' | 'messageType'> & { writable: boolean };
+export type CheckpointRestoreResult = { result: string; completed: string[]; files: string[]; conflicts?: string[]; stoppedAt?: string | null };
+type Options = {
+  facts(): Promise<CheckpointFacts> | CheckpointFacts;
+  history(): CheckpointReceipt[];
+  append(receipt: CheckpointReceipt): void | Promise<void>;
+  restore(target: string, expected: { digest: string; revision: string; tree: string }, identity: CheckpointState['identity']): Promise<CheckpointRestoreResult>;
+  now?(): Date;
+};
+
+export class CheckpointController {
+  #options: Options;
+  #tail: Promise<unknown> = Promise.resolve();
+  #pending = 0;
+  constructor(options: Options) { this.#options = options; }
+  async state(): Promise<CheckpointState> {
+    const { writable: _writable, ...facts } = await this.#options.facts();
+    return { schemaVersion: 1, version: CHECKPOINT_VERSION, messageType: 'state', ...facts };
+  }
+  execute(value: unknown): Promise<CheckpointReceipt> {
+    const command = parseCheckpointCommand(value);
+    if (this.#pending >= 128) return Promise.reject(Error('checkpoint-command-capacity'));
+    this.#pending++;
+    const run = this.#tail.then(() => this.#execute(command));
+    this.#tail = run.catch(() => undefined);
+    return run.finally(() => { this.#pending--; });
+  }
+  #now() { return this.#options.now?.() ?? new Date(); }
+  #expired(command: CheckpointCommand) {
+    const now = this.#now().getTime(), requested = Date.parse(command.requestedAt), expires = Date.parse(command.expiresAt);
+    return expires <= now || requested > now + 5000 || expires <= requested || expires - requested > 120000;
+  }
+  async #execute(command: CheckpointCommand): Promise<CheckpointReceipt> {
+    const facts = await this.#options.facts(), key = checkpointSha(command.idempotencyKey);
+    const previous = [...this.#options.history()].reverse().find(receipt => receipt.idempotencyKeyDigest === key);
+    const receipt: CheckpointReceipt = { schemaVersion: 1, version: CHECKPOINT_VERSION, messageType: 'receipt', commandId: command.commandId,
+      idempotencyKeyDigest: key, action: command.action, actionDigest: command.actionDigest, identity: facts.identity,
+      phase: 'rejected', resultCode: 'unavailable', requestedAt: command.requestedAt, settledAt: this.#now().toISOString(),
+      observedRevisionsBefore: facts.revisions, observedRevisionsAfter: facts.revisions, deduplicated: false,
+      targetId: command.payload.targetId, completed: [], files: [], conflicts: [], stoppedAt: null };
+    const reject = (resultCode: CheckpointReceipt['resultCode']): CheckpointReceipt => ({ ...receipt, resultCode });
+    if (previous && same(command.identity, previous.identity) && facts.identity.projectRef === command.identity.projectRef
+      && facts.identity.sessionRef === command.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 refusal = (current: CheckpointFacts): CheckpointReceipt['resultCode'] | null => {
+      if (!same(command.identity, current.identity)) return 'identity-mismatch';
+      if (this.#expired(command)) return 'expired';
+      if (!current.available) return 'unavailable';
+      if (!current.writable) return 'read-only';
+      if (current.agentRunning) return 'busy';
+      if (!same(command.expectedRevisions, current.revisions)) return 'stale-revision';
+      return null;
+    };
+    const denied = refusal(facts);
+    if (denied) { const result = reject(denied); await this.#options.append(result); return result; }
+    // Publication precedes dispatch. Lost completion remains non-replayable.
+    const pending: CheckpointReceipt = { ...receipt, phase: 'uncertain', resultCode: 'effect-unknown' };
+    await this.#options.append(pending);
+    let settled = pending;
+    try {
+      const deniedNow = refusal(await this.#options.facts());
+      if (deniedNow) settled = reject(deniedNow);
+      else {
+        const result = await this.#options.restore(command.payload.targetId, {
+          digest: command.payload.previewDigest, revision: command.expectedRevisions.checkpointRevision, tree: command.payload.expectedTree,
+        }, command.identity);
+        const after = await this.#options.facts();
+        const code = result.result === 'done' ? 'restored' : result.result === 'refused' ? 'conflict'
+          : result.result === 'stale' ? 'stale-revision' : result.result === 'busy' ? 'busy' : result.result === 'read-only' ? 'read-only'
+          : ['unavailable', 'failed', 'none'].includes(result.result) ? 'unavailable' : 'effect-unknown';
+        settled = { ...receipt, phase: code === 'effect-unknown' ? 'uncertain' : result.completed.length || code === 'restored' ? 'settled' : 'rejected',
+          resultCode: code, observedRevisionsAfter: after.revisions, completed: result.completed,
+          files: result.files, conflicts: result.conflicts ?? [], stoppedAt: result.stoppedAt ?? null };
+      }
+    } catch { settled = pending; }
+    settled = { ...settled, settledAt: this.#now().toISOString() };
+    try { await this.#options.append(settled); } catch { return pending; }
+    return settled;
+  }
+}

package/packages/piagent-webui/server/checkpoint-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 CheckpointRoutes = {
+  state(sessionRef: string): unknown | Promise<unknown>;
+  preview(sessionRef: string, target: 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 routeCheckpoint(context: Context, handler?: CheckpointRoutes): 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})\/checkpoints(?:\/([a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}))?$/.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-checkpoint-query"); return true; }
+  if (!["GET", "POST"].includes(request.method ?? "") || match[2] && request.method !== "GET") { 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;
+    }
+    try { command = JSON.parse((await requestBody(request, 8192)).toString("utf8")); }
+    catch (error) { errorResponse(response, (error as Error).message === "body-limit" ? 413 : 400, "invalid-checkpoint-command"); return true; }
+    if ((command as { identity?: { sessionRef?: unknown } } | null)?.identity?.sessionRef !== match[1]) {
+      errorResponse(response, 400, "checkpoint-session-mismatch"); return true;
+    }
+  }
+  if (!handler) { errorResponse(response, 503, "checkpoint-unavailable"); return true; }
+  try { jsonResponse(response, 200, request.method === "GET" ? (match[2] ? await handler.preview(match[1], match[2]) : await handler.state(match[1])) : await handler.execute(match[1], command)); }
+  catch (error) { errorResponse(response, (error as Error).message === "invalid-checkpoint-command" ? 400 : 503, "checkpoint-unavailable"); }
+  return true;
+}

package/packages/piagent-webui/server/control-command-digest.ts

@@ -0,0 +1,5 @@
+import { reviewDigest } from "../../piagent-core/runtime/inspection/review-state-contract.ts";
+
+export function controlActionDigest(command: { action: unknown; identity: unknown; expectedRevisions: unknown; payload: unknown }): string {
+  return reviewDigest({ action: command.action, identity: command.identity, expectedRevisions: command.expectedRevisions, payload: command.payload });
+}

package/packages/piagent-webui/server/core-inspection-provider.ts

@@ -8,23 +8,7 @@ import { readTerminalDeliveryReceipt, terminalDeliverySessionEntries } from "./t
 
 const CORE_ROOT = "../../piagent-core";
 const SOURCE_AUTHORITY_ALIGNED = Symbol("piagent-source-authority-aligned");
-const STABLE_IDENTITY_FIELDS = ["projectRef", "runtimeInstanceId", "sessionRef", "taskId", "taskRunId"] as const;
-
-function stableIdentityMatches(left: Record<string, any> | null | undefined, right: Record<string, any> | null | undefined): boolean {
-  return Boolean(left && right && STABLE_IDENTITY_FIELDS.every((field) => left[field] === right[field]));
-}
-
-function sourceBinding(snapshot: Record<string, any>) {
-  return { sourceProjectionRevision: snapshot.sourceChanges.projectionRevision,
-    taskViewRevision: snapshot.sourceChanges.task.revision, workspaceRevision: snapshot.sourceChanges.workingTree.revision,
-    indexRevision: snapshot.sourceChanges.staged.revision };
-}
-
-function sourceDocumentMatches(document: Record<string, any> | null | undefined, snapshot: Record<string, any>): boolean {
-  const binding = sourceBinding(snapshot);
-  return Boolean(document && stableIdentityMatches(document.identity, snapshot.identity)
-    && Object.entries(binding).every(([field, value]) => document.snapshotBinding?.[field] === value));
-}
+import { STABLE_IDENTITY_FIELDS, stableIdentityMatches, sourceBinding, sourceDocumentMatches } from "./source-projection-binding.ts";
 
 type RuntimeEvent = { eventCursor: string; [key: string]: unknown };
 type EventReplay = {
@@ -42,8 +26,8 @@ type EventStore = {
 };
 
 async function loadCoreInspection() {
-  const [{ collectFileDiff }, { buildWebUiInspectionProjection }, { matchesProtectedPath }, reviewProjection, reviewStore, mutationProjection, revertProjection, openProjection, commitSummaryProjection, taskIndexProjection, taskTimelineProjection, recoveryHistoryProjection, handoffHistoryProjection, subagentTreeProjection, releaseMonitorProjection, documentWorkspaceProjection] = await Promise.all([
-    import(`${CORE_ROOT}/runtime/inspection/diff-projection.ts`),
+  const [{ collectSessionFileDiff: collectFileDiff }, { buildWebUiInspectionProjection }, { matchesProtectedPath }, reviewProjection, reviewStore, mutationProjection, revertProjection, openProjection, commitSummaryProjection, taskIndexProjection, taskTimelineProjection, recoveryHistoryProjection, handoffHistoryProjection, subagentTreeProjection, releaseMonitorProjection, documentWorkspaceProjection] = await Promise.all([
+    import(`${CORE_ROOT}/runtime/inspection/session-diff-projection.ts`),
     import(`${CORE_ROOT}/runtime/inspection/webui-snapshot.ts`),
     import(`${CORE_ROOT}/extensions/policy-core.js`),
     import(`${CORE_ROOT}/runtime/inspection/review-state-projection.ts`),
@@ -87,6 +71,8 @@ export type CoreInspectionInput = {
   approvalProjection?: () => { revision: string | null; summary: Record<string, unknown> };
   approvalDetail?: (approvalRef: string) => unknown | null;
   sourceMutationGuardAvailable?: () => boolean;
+  sourceSessionControlRevision?: () => string | null;
+  sourceSessionObservation?: (path: string) => unknown;
   sourceOpenAvailable?: () => boolean;
   lifecycleControl?: () => { state: "active" | "pause-requested" | "paused" | "terminal" | "unknown"; controlRevision: string | null;
     dispatchBlocked: boolean; currentPhase: string; pauseEpoch: number; actions: { stop: boolean; pause: boolean; resume: boolean } };
@@ -218,6 +204,9 @@ export class CoreInspectionProvider implements WebUiReadModelProvider {
         } };
       }
     }
+    if (value.snapshot.identity.taskId === null && value.snapshot.identity.taskRunId === null && this.#input.sourceSessionControlRevision) {
+      value.snapshot.revision.controlRevision = this.#input.sourceSessionControlRevision();
+    }
     projectApprovalState(value.snapshot, this.#input.approvalProjection?.());
     if (sourceIdentityAligned) {
       const binding = sourceBinding(value.snapshot);
@@ -312,7 +301,7 @@ export class CoreInspectionProvider implements WebUiReadModelProvider {
     const { collectFileDiff, matchesProtectedPath } = await loadCoreInspection();
     const protectedPaths = this.#input.protectedPaths?.() ?? [];
     const value = await collectFileDiff({
-      cwd: this.#input.cwd, identity, sourceView: source, fileRef,
+      cwd: this.#input.cwd, identity, sourceView: source, fileRef, sessionObservation: this.#input.sourceSessionObservation,
       precondition: { expectedViewRevision: source.viewRevision, expectedFileRevision: file.fileRevision,
         expectedBaseDigest: file.baseDigest ?? null, expectedCurrentDigest: file.currentDigest ?? null },
       taskRevision: projection.snapshot.revision.taskRevision,
@@ -379,14 +368,19 @@ export class CoreInspectionProvider implements WebUiReadModelProvider {
     const projection = await this.#projection(), snapshot = projection.snapshot;
     this.#requireSourceAuthority(projection, ["working-tree", ...(projection.sourceViews.task ? ["task" as const] : [])]);
     const identity = { ...snapshot.identity, agentOperationId: null, toolCallId: null };
-    if (!identity.taskId || !identity.taskRunId || !snapshot.revision.taskRevision || !snapshot.revision.workspaceRevision || !snapshot.revision.indexRevision)
+    const sessionBound = identity.taskId === null && identity.taskRunId === null && snapshot.revision.taskRevision === null
+      && !!this.#input.sourceSessionObservation;
+    if ((!sessionBound && (!identity.taskId || !identity.taskRunId || !snapshot.revision.taskRevision))
+      || !snapshot.revision.workspaceRevision || !snapshot.revision.indexRevision)
       throw new ReadModelNotFound();
     const source = projection.sourceViews.workingTree, taskView = projection.sourceViews.task ?? null;
-    if (!source?.files.some((file: any) => file.fileRef === fileRef)) throw new ReadModelNotFound();
+    const file = source?.files.find((file: any) => file.fileRef === fileRef);
+    if (!file) throw new ReadModelNotFound();
     const diff = await this.diff("working-tree", fileRef) as any;
     const { collectSourceRevertPreview, matchesProtectedPath } = await loadCoreInspection();
     const protectedPaths = this.#input.protectedPaths?.() ?? [];
     return collectSourceRevertPreview({ cwd: this.#input.cwd, identity, sourceView: source, taskView, diff,
+      sessionObservation: sessionBound && file.pathDisplay === "exact-safe" ? this.#input.sourceSessionObservation?.(file.path) : undefined,
       taskRevision: snapshot.revision.taskRevision, workspaceRevision: snapshot.revision.workspaceRevision,
       indexRevision: snapshot.revision.indexRevision, selectedHunkRefs: hunkRef ? [hunkRef] : [],
       confirmationKey: this.#sourceRevertConfirmationKey,

package/packages/piagent-webui/server/gateway-websocket.ts

@@ -1,3 +1,4 @@
+import { TerminalWebSocketStream, type TerminalStreamPort } from "./terminal-websocket-stream.ts";
 import type { IncomingMessage, Server } from "node:http";
 import { WebSocket, WebSocketServer } from "ws";
 
@@ -5,7 +6,7 @@ import type { SessionAuthority } from "./session-auth.ts";
 
 const FRAME_LIMIT = 70_000;
 const CLIENT_LIMIT = 8;
-const BACKPRESSURE_LIMIT = 512 * 1024;
+const BACKPRESSURE_LIMIT = 512 * 1024, TERMINAL_BACKLOG = 128 * 1024;
 const REF = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
 const REQUEST_ID = /^[A-Za-z0-9_-]{16,96}$/;
 
@@ -13,9 +14,10 @@ type GatewayProtocolEvent = {
   sequence: number;
   [key: string]: unknown;
 };
-export type GatewayRequest = { requestId: string; method: "gateway.health" | "sessions.list" | "sessions.get" | "sessions.command"; params: Record<string, unknown> };
+export type GatewayRequest = { requestId: string; method: "gateway.health" | "sessions.list" | "sessions.get" | "sessions.command" | "terminals.state" | "terminals.command"; params: Record<string, unknown> };
 export type GatewayProtocolHandler = {
   capabilities(): unknown;
+  terminalEvents?: TerminalStreamPort;
   execute(request: GatewayRequest): Promise<unknown>;
   events: {
     readonly stateVersion: number;
@@ -44,12 +46,18 @@ function parseConnect(value: unknown): { lastEventSequence: number | null } | nu
 function parseRequest(value: unknown): GatewayRequest | null {
   if (!record(value) || !exactKeys(value, ["schemaVersion", "version", "messageType", "requestId", "method", "params"]) || value.schemaVersion !== 1
     || value.version !== "piagent-gateway-protocol-v1" || value.messageType !== "request" || typeof value.requestId !== "string"
-    || !REQUEST_ID.test(value.requestId) || !["gateway.health", "sessions.list", "sessions.get", "sessions.command"].includes(String(value.method))
+    || !REQUEST_ID.test(value.requestId) || !["gateway.health", "sessions.list", "sessions.get", "sessions.command", "terminals.state", "terminals.command"].includes(String(value.method))
     || !record(value.params)) return null;
   const params = value.params;
   if (value.method === "gateway.health" && !exactKeys(params, [])) return null;
   if (value.method === "sessions.get" && (!exactKeys(params, ["sessionRef"]) || typeof params.sessionRef !== "string" || !REF.test(params.sessionRef))) return null;
   if (value.method === "sessions.command" && (!exactKeys(params, ["command"]) || !record(params.command))) return null;
+  if (value.method === "terminals.state" || value.method === "terminals.command") {
+    if (typeof params.csrfToken !== "string" || !/^[A-Za-z0-9_-]{16,128}$/.test(params.csrfToken)) return null;
+    if (value.method === "terminals.state" && (!exactKeys(params, ["sessionRef", "csrfToken"])
+      || typeof params.sessionRef !== "string" || !REF.test(params.sessionRef))) return null;
+    if (value.method === "terminals.command" && (!exactKeys(params, ["command", "csrfToken"]) || !record(params.command))) return null;
+  }
   if (value.method === "sessions.list") {
     if (!exactKeys(params, ["cursor", "limit", "filter", "query", "projectRef"]) || !nullableRef(params.cursor) || !nullableRef(params.projectRef)
       || !Number.isInteger(params.limit) || Number(params.limit) < 1 || Number(params.limit) > 200
@@ -100,12 +108,22 @@ export function attachGatewayWebSocket(options: {
     webSockets.handleUpgrade(request, socket, head, (client) => webSockets.emit("connection", client, request));
   };
   options.server.on("upgrade", upgrade);
-  webSockets.on("connection", (socket) => {
+  webSockets.on("connection", (socket, upgradeRequest: IncomingMessage) => {
+    const terminalStream = options.protocol.terminalEvents ? new TerminalWebSocketStream({ port: options.protocol.terminalEvents,
+      authorized: csrf => Boolean(options.authority.authorizeMutationToken(upgradeRequest, csrf)),
+      // Live terminal output yields to the conversation: while the socket is
+      // behind it is skipped (the terminal keeps its replay buffer) rather
+      // than closing the socket the chat also uses.
+      send: message => { if (message.messageType === "output" && !message.replay && socket.bufferedAmount > TERMINAL_BACKLOG) return; send(socket, message); },
+      close: reason => socket.close(1008, reason) }) : null;
+    let queued = 0;
     sockets.add(socket); let connected = false, unsubscribe: (() => void) | null = null, chain = Promise.resolve();
     const timeout = setTimeout(() => socket.close(1008, "connect-timeout"), 5_000);
     socket.on("message", (data, binary) => {
       if (binary) { socket.close(1003, "text-only"); return; }
+      if (++queued > 128) { socket.close(1013, "request-backpressure"); return; }
       chain = chain.then(async () => {
+        if (socket.readyState !== WebSocket.OPEN) return;
         let value: unknown;
         try { value = JSON.parse(data.toString()); } catch { socket.close(1007, "invalid-json"); return; }
         if (!connected) {
@@ -128,11 +146,21 @@ export function attachGatewayWebSocket(options: {
         }
         const request = parseRequest(value);
         if (!request) { socket.close(1008, "invalid-request"); return; }
-        try { send(socket, response(request, options.protocol.events.stateVersion, await options.protocol.execute(request))); }
-        catch (error) { send(socket, errorResponse(request, options.protocol.events.stateVersion, error)); }
-      }).catch(() => socket.close(1011, "gateway-failure"));
+        let replay: ReturnType<TerminalWebSocketStream["begin"]> | undefined;
+        try {
+          if (request.method.startsWith("terminals.") && !options.authority.authorizeMutationToken(upgradeRequest, request.params.csrfToken))
+            throw Object.assign(new Error("terminal-csrf-required"), { code: "terminal-csrf-required" });
+          if (request.method === "terminals.state") replay = terminalStream?.begin(String(request.params.sessionRef), String(request.params.csrfToken));
+          const result = await options.protocol.execute(request);
+          if (request.method.startsWith("terminals.") && !options.authority.authorizeMutationToken(upgradeRequest, request.params.csrfToken))
+            throw Object.assign(new Error("terminal-csrf-required"), { code: "terminal-csrf-required" });
+          const reply = () => send(socket, response(request, options.protocol.events.stateVersion, result));
+          if (replay) replay.finish(reply); else reply();
+        }
+        catch (error) { replay?.abort(); send(socket, errorResponse(request, options.protocol.events.stateVersion, error)); }
+      }).catch(() => socket.close(1011, "gateway-failure")).finally(() => { queued--; });
     });
-    socket.once("close", () => { clearTimeout(timeout); unsubscribe?.(); sockets.delete(socket); });
+    socket.once("close", () => { clearTimeout(timeout); unsubscribe?.(); terminalStream?.stop(); sockets.delete(socket); });
     socket.once("error", () => socket.terminate());
   });
   return { close: async () => {

package/packages/piagent-webui/server/loopback-server.ts

@@ -1,8 +1,11 @@
+import { routeSessionSourceRevert, type SessionSourceRevertRoutes } from "./session-source-revert-routes.ts";
 import http, { type ServerResponse } from "node:http";
 import { randomBytes } from "node:crypto";
 
 import { errorResponse, applySecurityHeaders, jsonResponse, requestBody } from "./http-security.ts";
 import { routeMemberRequest, type UpdateRoutes } from "./member-routes.ts";
+import { routeWorkspaceWrite, type WorkspaceWriteRoutes } from "./workspace-write-routes.ts";
+import { routeCheckpoint, type CheckpointRoutes } from "./checkpoint-routes.ts";
 import { ReadModelNotFound, type WebUiReadModelProvider } from "./read-model-provider.ts";
 import { routeReadOnlyRequest } from "./read-only-router.ts";
 import { SessionAuthority } from "./session-auth.ts";
@@ -49,6 +52,9 @@ export async function startLoopbackServer(options: {
   readSessionLiveState?: () => unknown | Promise<unknown>;
   readSessionCreationOptions?: () => unknown | Promise<unknown>;
   readSessionModel?: (sessionRef: string) => WebUiReadModelProvider | Promise<WebUiReadModelProvider>;
+  workspaceWrite?: WorkspaceWriteRoutes;
+  checkpoints?: CheckpointRoutes;
+  sessionSourceRevert?: SessionSourceRevertRoutes;
   executeSessionAttachment?: (sessionRef: string, command: unknown) => unknown | Promise<unknown>;
   readSessionConnections?: (sessionRef: string) => unknown | Promise<unknown>;
   executeSessionConnection?: (command: unknown) => unknown | Promise<unknown>;
@@ -303,6 +309,9 @@ export async function startLoopbackServer(options: {
 
     // The main agent's questions to the member, a project's Git branches, and
     // Piagent's own updates.
+    if (await routeSessionSourceRevert({ request, response, url, origin, requestOrigin, auth, now, consumeControl }, options.sessionSourceRevert)) return;
+    if (await routeWorkspaceWrite({ request, response, url, origin, requestOrigin, auth, now, consumeControl }, options.workspaceWrite)) return;
+    if (await routeCheckpoint({ request, response, url, origin, requestOrigin, auth, now, consumeControl }, options.checkpoints)) return;
     if (await routeMemberRequest({ request, response, url, origin, requestOrigin, auth, now, consumeControl }, options)) return;
 
     if (request.method === "POST" && url.pathname.startsWith("/api/v1/approvals/") && url.pathname.endsWith("/decision") && options.executeApproval) {

package/packages/piagent-webui/server/read-model-provider.ts

@@ -1,3 +1,5 @@
+import type { WorkspaceRead } from "./workspace-read-routes.ts";
+
 export type SourceView = "task" | "working-tree" | "staged";
 export type StreamEvent = { cursor: string; value: unknown };
 export type StreamReplay = {
@@ -9,6 +11,7 @@ export type StreamReplay = {
 };
 
 export type WebUiReadModelProvider = {
+  workspace?: WorkspaceRead;
   snapshot(): unknown | Promise<unknown>;
   sourceChanges(view: SourceView): unknown | Promise<unknown>;
   diff(view: SourceView, fileRef: string): unknown | Promise<unknown>;

package/packages/piagent-webui/server/read-only-router.ts

@@ -1,3 +1,4 @@
+import { routeWorkspaceRead } from "./workspace-read-routes.ts";
 import type { WebUiReadModelProvider, SourceView } from "./read-model-provider.ts";
 
 const OPAQUE_REF = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
@@ -5,6 +6,8 @@ const OPAQUE_REF = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
 export type ReadRouteResult = { handled: false } | { handled: true; status: number; value: unknown };
 
 export async function routeReadOnlyRequest(url: URL, provider: WebUiReadModelProvider): Promise<ReadRouteResult> {
+  const workspace = await routeWorkspaceRead(url, provider.workspace?.bind(provider));
+  if (workspace.handled) return workspace;
   if (url.pathname === "/api/v1/snapshot" && !url.search) return { handled: true, status: 200, value: await provider.snapshot() };
   if (url.pathname === "/api/v1/activity" && !url.search) return { handled: true, status: 200, value: await provider.activity() };
   if (url.pathname === "/api/v1/tasks" && !url.search) return { handled: true, status: 200, value: await provider.taskIndex() };

package/packages/piagent-webui/server/session-auth.ts

@@ -93,8 +93,11 @@ export class SessionAuthority {
   }
 
   authorizeMutation(request: IncomingMessage, now = Date.now()): BrowserSession | null {
+    return this.authorizeMutationToken(request, request.headers["x-piagent-csrf"], now);
+  }
+
+  authorizeMutationToken(request: IncomingMessage, csrf: unknown, now = Date.now()): BrowserSession | null {
     const session = this.authenticate(request, now);
-    const csrf = request.headers["x-piagent-csrf"];
     return session && typeof csrf === "string" && equal(csrf, session.csrf) ? session : null;
   }
 

package/packages/piagent-webui/server/session-source-revert-routes.ts

@@ -0,0 +1,54 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { SessionAuthority } from "./session-auth.ts";
+import { errorResponse, jsonResponse, requestBody } from "./http-security.ts";
+
+export type SessionSourceRevertRoutes = {
+  sources?(sessionRef: string): unknown | Promise<unknown>;
+  diff?(sessionRef: string, fileRef: string): unknown | Promise<unknown>;
+  preview(sessionRef: string, fileRef: string, hunkRef: string | null): 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 };
+const REF = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
+export async function routeSessionSourceRevert(context: Context, handler?: SessionSourceRevertRoutes): Promise<boolean> {
+  const { request, response, url, auth, requestOrigin, origin, now, consumeControl } = context;
+  const review = /^\/api\/v1\/sessions\/([A-Za-z0-9][A-Za-z0-9._~-]{0,159})\/source-review(?:\/([A-Za-z0-9][A-Za-z0-9._~-]{0,159}))?$/.exec(url.pathname);
+  if (review) {
+    if (!auth.authenticate(request)) { errorResponse(response, 401, "authentication-required"); return true; }
+    if (request.method !== "GET") { errorResponse(response, 405, "method-not-allowed"); return true; }
+    if (url.search) { errorResponse(response, 400, "invalid-source-review-query"); return true; }
+    try {
+      const read = review[2] ? handler?.diff : handler?.sources;
+      if (!read) throw new Error("unavailable");
+      jsonResponse(response, 200, await read(review[1], review[2]));
+    } catch { errorResponse(response, 503, "source-review-unavailable"); }
+    return true;
+  }
+  const match = /^\/api\/v1\/sessions\/([A-Za-z0-9][A-Za-z0-9._~-]{0,159})\/source-reverts(?:\/([A-Za-z0-9][A-Za-z0-9._~-]{0,159}))?$/.exec(url.pathname);
+  if (!match) return false;
+  if (!auth.authenticate(request)) { errorResponse(response, 401, "authentication-required"); return true; }
+  const reading = request.method === "GET" && !!match[2], writing = request.method === "POST" && !match[2];
+  if (!reading && !writing) { errorResponse(response, 405, "method-not-allowed"); return true; }
+  const hunkRef = url.searchParams.get("hunkRef");
+  if (writing && url.search || reading && ([...url.searchParams.keys()].some(key => key !== "hunkRef")
+    || url.searchParams.getAll("hunkRef").length > 1 || hunkRef !== null && !REF.test(hunkRef))) {
+    errorResponse(response, 400, "invalid-source-revert-query"); return true;
+  }
+  let command: unknown;
+  if (writing) {
+    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;
+    }
+    try { command = JSON.parse((await requestBody(request, 70_000)).toString("utf8")); }
+    catch (error) { errorResponse(response, (error as Error).message === "body-limit" ? 413 : 400, "invalid-source-revert-command"); return true; }
+  }
+  if (!handler) { errorResponse(response, 503, "source-revert-unavailable"); return true; }
+  try { jsonResponse(response, 200, reading ? await handler.preview(match[1], match[2], hunkRef) : await handler.execute(match[1], command)); }
+  catch { errorResponse(response, 503, "source-revert-unavailable"); }
+  return true;
+}

package/packages/piagent-webui/server/source-projection-binding.ts

@@ -0,0 +1,18 @@
+export const STABLE_IDENTITY_FIELDS = ["projectRef", "runtimeInstanceId", "sessionRef", "taskId", "taskRunId"] as const;
+
+export function stableIdentityMatches(left: Record<string, any> | null | undefined, right: Record<string, any> | null | undefined): boolean {
+  return Boolean(left && right && STABLE_IDENTITY_FIELDS.every((field) => left[field] === right[field]));
+}
+
+export function sourceBinding(snapshot: Record<string, any>) {
+  return { sourceProjectionRevision: snapshot.sourceChanges.projectionRevision,
+    taskViewRevision: snapshot.sourceChanges.task.revision, workspaceRevision: snapshot.sourceChanges.workingTree.revision,
+    indexRevision: snapshot.sourceChanges.staged.revision };
+}
+
+export function sourceDocumentMatches(document: Record<string, any> | null | undefined, snapshot: Record<string, any>): boolean {
+  const binding = sourceBinding(snapshot);
+  return Boolean(document && stableIdentityMatches(document.identity, snapshot.identity)
+    && Object.entries(binding).every(([field, value]) => document.snapshotBinding?.[field] === value));
+}
+